Graceful Degradation & Rate Limit Bypass com Redis em Sistemas Distribuídos

Introdução

Este é um case técnico baseado em um cenário real de integração com a API do Google Sheets, focado em resolver problemas de escassez de quota e alta taxa de erros.

No cenário original, requisições diretas de carga estouravam rapidamente o limite do ecossistema do Google (300 requisições/minuto), gerando falhas em cadeia (HTTP 429 - Too Many Requests). Para solucionar o gargalo, foi construído um mock em Go (sheets-mock-api) reproduzindo fielmente os limites reais e implementado o padrão de Graceful Degradation com Redis na aplicação principal em Laravel (main-service-api).

• Escopo: Sistemas Distribuídos / Rate Limiting & Tolerância a Falhas / Caching.
• Linguagens e Stack: PHP (Laravel), Go (sheets-mock-api), Redis, Docker Compose, k6 (Grafana) para testes de carga.
• Impacto de Negócio: A taxa de erro despencou de 78.3% para 0%, o throughput de requisições sustentado pela aplicação subiu de forma expressiva e as chamadas reais à API externa caíram acima de 95%, respeitando rigorosamente a quota do provedor (300 req/min).

Código Fonte e Relatórios de Carga: Repositório completo no GitHub contendo os serviços, scripts do k6 e instruções do Docker Compose: 🔗 php-graceful-degradation-rate-limit

O Problema

O ponto de partida (branch: feature/01-direct-api-unstable) do case é o cenário sem proteção de resiliência: o k6 dispara requisições de carga contra o main-service-api (Laravel), que por sua vez consulta diretamente o sheets-mock-api (Go) para cada requisição recebida.

O sheets-mock-api implementa um algoritmo rigoroso de Rate Limiting via Leaky/Token Bucket calibrado para 300 requisições por minuto (5 req/s em média), espelhando os limites reais de cota de escrita/leitura da API de planilhas do Google.

Quando a taxa de requisições do main-service-api excede esse teto, a API externa passa a responder imediatamente com HTTP 429 Too Many Requests. Sem uma camada de tratamento ou degradação graciosa, o main-service-api repassa esses erros para os clientes finais.

Durante os primeiros 160s, o sistema opera normalmente com 100% de sucesso, mas assim que o tráfego atinge o pico em t=180s, o limite de 300 req/min do Google Sheets é esgotado, colapsando a integração e gerando 100% de erro (HTTP 429 / 502) na janela. Mesmo com recuperações temporárias do Token Bucket com a queda de tráfego, o acúmulo de requisições provoca novos gargalos (como em t=240s), totalizando 160 falhas (12,7% de erro global).

A Arquitetura da Solução

Situação Inicial:

Arquitetura Final:

O main-service-api contabiliza continuamente as chamadas enviadas à API externa dentro de janelas móveis de 1 minuto. Enquanto o consumo se mantém igual ou abaixo de 50% da cota (até 150 req/min), a aplicação opera em Modo Direto, repassando leituras e gravações de forma síncrona ao sheets-mock-api sem a necessidade de passar por camadas intermediárias.

A inteligência da arquitetura entra em ação no momento em que a cota cruza o gatilho de 50%. A partir dessa marca, o sistema ativa automaticamente o modo de Graceful Degradation, alterando o fluxo de execução para proteger a quota externa sem comprometer a experiência do usuário.

Nas operações de leitura, o serviço interrompe as chamadas HTTP à API Go e passa a consultar o snapshot mantido em cache no Redis, combinando-o em tempo real com as alterações pendentes para entregar o dado perfeitamente atualizado de forma instantânea. Já nas gravações, em vez de arriscar o esgotamento do limite de 300 req/min com escritas síncronas, a mutação é registrada em uma fila de deltas (delta queue) no Redis e refletida imediatamente no cache de leitura local.

Com essa separação, assim que a janela móvel reseta e o consumo de cota retorna a níveis seguros (< 50%), um worker em segundo plano entra em cena para drenar assincronamente a fila de deltas, persistindo todas as gravações acumuladas na API do Google Sheets de forma cadenciada e sem gerar novos picos de requisição.

Evolução

Análise de Decisão

Informações detalhada sobre as principais decisões deste case:

Implementação Prática

Contador Atômico e Verificação de Cota

• Trecho: main-service-api/app/Services/GoogleSheetsQuotaService.php
• Branch: feature/02-redis-quota-counter

Em vez de resetar a contagem em minutos cheios (o que pode gerar picos nas bordas da janela), o GoogleSheetsQuotaService implementa um algoritmo de Sliding Window de 60 segundos segundo a segundo. Cada segundo gera uma chave individual no Redis com TTL de 60s, e o consumo total é calculado somando as chaves do intervalo atual de 60 segundos via MGET.

public function registerRequest(): int
{
	$now = time();
	$key = self::KEY_PREFIX . $now;

	$current = Redis::incr($key);
	if ($current === 1) {
		Redis::expire($key, self::TTL_SECONDS);
	}

	return $this->getQuotaConsumed();
}

...

public function isDegraded(?int $consumed = null): bool
{
	$consumed = $consumed ?? $this->getQuotaConsumed();
	return $consumed > $this->getThreshold();
}

Injeção de Observabilidade via Middleware

• Trecho: main-service-api/app/Http/Middleware/QuotaTrackerMiddleware.php
• Branch: feature/02-redis-quota-counter

O middleware intercepta a requisição, consulta o GoogleSheetsQuotaService para identificar se atingimos o limite de 50% da cota e injeta headers de controle de estado na resposta enviada ao cliente/k6.

public function handle(Request $request, Closure $next): Response
{
	$consumed = $this->quotaService->registerRequest();
	$isDegraded = $this->quotaService->isDegraded($consumed);

	$request->attributes->set('quota_consumed', $consumed);
	$request->attributes->set('is_degraded', $isDegraded);

	$response = $next($request);

	$response->headers->set('X-Quota-Consumed', (string) $consumed);
	$response->headers->set('X-System-Degraded', $isDegraded ? 'true' : 'false');

	return $response;
}

Orquestração de Leitura e Interceptação com Mesclagem de Deltas

• Trecho: main-service-api/app/Services/GoogleSheetsService.php
• Branch: feature/03-graceful-read-degradation

O GoogleSheetsServiceconsulta o GoogleSheetsQuotaService para avaliar o estado da cota em tempo real e decide se fará uma busca síncrona direta na API Go do Google Sheets ou se ativará o fluxo de Graceful Degradation combinando a última cópia válida (snapshot) com as alterações pendentes retidas no buffer local.

public function getRows(string $sheet = 'orders'): array
{
	$isDegraded = $this->quotaService->isDegraded();

	if ($isDegraded) {
		return $this->getDegradedMergedRows($sheet);
	}

	return $this->getDirectRows($sheet);
}

Worker de Drenagem Assíncrona e Sincronização em Retaguarda

Trecho: main-service-api/app/Console/Commands/DrainQuotaBufferCommand.php Branch: feature/04-delta-queue-async-worker

O DrainQuotaBufferCommand atua como um worker de segundo plano (long-running process) responsável por monitorar continuamente o consumo de cota no Redis. Ele garante a drenagem cadenciada e segura da fila atômica de escrita (sheets_write_buffer) para a API do Google Sheets somente quando a cota se estabiliza no nível seguro ($\le 150\text{ req/min}$).

public function handle(GoogleSheetsQuotaService $quotaService, GoogleSheetsService $sheetsService): int
{
	$sheet = $this->option('sheet');
	$loop = $this->option('loop');
	$sleep = (int) $this->option('sleep');

	$this->info("Iniciando Worker de Drenagem Assíncrona para a folha [{$sheet}]...");

	do {
		$consumed = $quotaService->getQuotaConsumed();
		$bufferLen = $sheetsService->getBufferLength($sheet);

		if ($consumed <= 150 && $bufferLen > 0) {
			$this->info("Cota Normalizada ({$consumed} req/min). Drenando {$bufferLen} itens pendentes do buffer...");
			
			$drained = $sheetsService->drainBuffer($sheet, 20);
			
			$this->info("Drenados {$drained} itens do buffer com sucesso.");
		}

		if ($loop) {
			sleep($sleep);
		}
	} while ($loop);

	return Command::SUCCESS;
}

Métricas, Resultados e Lições Aprendidas

Pontos observados

• Preservação Rígida da Cota (Rate-Limit): O limite de requisições da API do Google Sheets não foi estourado em nenhum momento, pois a ativação do modo degradado interrompeu as chamadas externas síncronas assim que o consumo atingiu a margem de segurança.
• Consistência Total dos Dados: As informações mantiveram-se perfeitamente atualizadas e coerentes para o usuário, já que todas as mutações/alterações registradas no buffer foram mescladas em tempo real com o snapshot do Redis durante as consultas.
• Taxa de Erro Zero (100% de Sucesso): Não houve falhas ou interrupções no fluxo, garantindo 100% de sucesso no processamento de todas as requisições enviadas e eliminando completamente erros do tipo HTTP 429 e HTTP 502.
• Sobretaxa de Recursos Computacionais: Apesar de o aumento de CPU e memória ter sido moderado na simulação (dadas as proporções do teste de carga), a execução do modo degradado exige maior processamento e retenção de dados em memória do que o fluxo direto.
• Importância do Gatilho Dinâmico e Escalabilidade: As métricas evidenciam a importância de o modo degradado não ficar ativo o tempo todo, entrando em cena exclusivamente nos momentos de pico de tráfego. Além disso, em cenários de alta carga sustentada, o ambiente precisará ser escalado horizontalmente/verticalmente para suportar o consumo adicional de recursos.

O código completo, com os quatro branches, os READMEs congelados de cada etapa e os relatórios brutos de cada execução, está em:

• https://github.com/marcelo3macedo/php-graceful-degradation-rate-limit