Circuit Breaker con Redis en Laravel: protegiendo APIs externas de fallos en cascada
Introducción: el problema de las dependencias externas
Cuando tu aplicación Laravel depende de APIs externas, un solo punto de fallo puede desencadenar un colapso total. Imaginá este escenario: tu e-commerce consulta un servicio de pagos que empieza a responder con latencia de 30 segundos en lugar de 200ms. Sin protección, cada request de tu aplicación se bloquea esperando, consumiendo workers, conexiones de base de datos y memoria hasta que todo el sistema colapsa.
Este patrón de fallo en cascada es uno de los más destructivos en sistemas distribuidos. La solución no es evitar las dependencias externas, sino contener los fallos mediante el patrón Circuit Breaker (interruptor de circuito).
¿Qué es el Circuit Breaker?
El Circuit Breaker es un patrón de diseño que monitorea las llamadas a servicios externos y, al detectar un umbral de fallos, "abre el circuito" para rechazar rápidamente nuevas llamadas durante un período de recuperación. Tiene tres estados:
- Closed (cerrado): Todo funciona normalmente, las llamadas transcurren sin interferencia.
- Open (abierto): Se detectaron demasiados fallos. Las llamadas se rechazan inmediatamente sin intentar el servicio externo.
- Half-Open (semi-abierto): Tras el tiempo de espera, se permite una llamada de prueba para verificar si el servicio se recuperó.
La clave está en que Redis actúa como el cerebro distribuido del circuit breaker, permitiendo que múltiples instancias de tu aplicación compartan el mismo estado de forma coordinada.
Arquitectura de la implementación
Para construir un Circuit Breaker robusto en Laravel necesitamos varios componentes que trabajen en conjunto:
- Un contador atómico de fallos en Redis
- Un timestamp del primer fallo para la ventana de tiempo
- Un flag de estado del circuito
- Un timestamp de cuándo se abrió el circuito
- Lógica de transición entre estados
Redis brinda las operaciones atómicas necesarias (INCR, EXPIRE, SETNX) para que múltiples workers simultáneos no corrompan el estado.
Implementación del Circuit Breaker
Creemos una clase CircuitBreaker que encapsule toda la lógica. La ubicación recomendada es app/Services/Resilience/CircuitBreaker.php.
<?php
namespace App\Services\Resilience;
use Illuminate\Support\Facades\Redis;
use Psr\Log\LoggerInterface;
class CircuitBreaker
{
private string $serviceName;
private int $failureThreshold;
private int $timeoutSeconds;
private int $halfOpenMaxAttempts;
private LoggerInterface $logger;
public function __construct(
string $serviceName,
int $failureThreshold = 5,
int $timeoutSeconds = 60,
int $halfOpenMaxAttempts = 1
) {
$this->serviceName = $serviceName;
$this->failureThreshold = $failureThreshold;
$this->timeoutSeconds = $timeoutSeconds;
$this->halfOpenMaxAttempts = $halfOpenMaxAttempts;
$this->logger = app(LoggerInterface::class);
}
private function key(string $suffix): string
{
return "circuit_breaker:{$this->serviceName}:{$suffix}";
}
public function isOpen(): bool
{
$state = Redis::get($this->key('state'));
if ($state === 'open') {
$openedAt = (int) Redis::get($this->key('opened_at'));
if ((time() - $openedAt) >= $this->timeoutSeconds) {
$this->moveToHalfOpen();
return false;
}
return true;
}
return false;
}
private function moveToHalfOpen(): void
{
Redis::setex($this->key('state'), $this->timeoutSeconds, 'half_open');
Redis::setex($this->key('half_open_attempts'), $this->timeoutSeconds, 0);
$this->logger->info("Circuit breaker [{$this->serviceName}] moved to HALF_OPEN");
}
public function canAttempt(): bool
{
if ($this->isOpen()) {
return false;
}
$state = Redis::get($this->key('state'));
if ($state === 'half_open') {
$attempts = (int) Redis::get($this->key('half_open_attempts'));
if ($attempts >= $this->halfOpenMaxAttempts) {
return false;
}
Redis::incr($this->key('half_open_attempts'));
}
return true;
}
public function recordSuccess(): void
{
$state = Redis::get($this->key('state'));
if ($state === 'half_open' || $state === 'open') {
$this->moveToClosed();
}
Redis::del([
$this->key('failures'),
$this->key('first_failure_at'),
]);
}
private function moveToClosed(): void
{
Redis::del([
$this->key('state'),
$this->key('opened_at'),
$this->key('half_open_attempts'),
]);
$this->logger->info("Circuit breaker [{$this->serviceName}] moved to CLOSED");
}
public function recordFailure(): void
{
$failures = Redis::incr($this->key('failures'));
if ($failures === 1) {
Redis::expire($this->key('failures'), $this->timeoutSeconds * 2);
Redis::setex($this->key('first_failure_at'), $this->timeoutSeconds * 2, time());
}
$state = Redis::get($this->key('state'));
if ($state === 'half_open') {
$this->moveToOpen();
return;
}
if ($failures >= $this->failureThreshold) {
$this->moveToOpen();
}
}
private function moveToOpen(): void
{
Redis::setex($this->key('state'), $this->timeoutSeconds * 2, 'open');
Redis::setex($this->key('opened_at'), $this->timeoutSeconds * 2, time());
$this->logger->warning("Circuit breaker [{$this->serviceName}] moved to OPEN");
}
}
Esta implementación utiliza INCR atómico de Redis para contar fallos sin condiciones de carrera. Las claves tienen TTL para evitar acumulación de datos en Redis.
Wiring en Laravel: Service Provider
Para inyectar el Circuit Breaker en cualquier servicio, registramos bindings en un provider.
<?php
namespace App\Providers;
use App\Services\Resilience\CircuitBreaker;
use Illuminate\Support\ServiceProvider;
class ResilienceServiceProvider extends ServiceProvider
{
public function register(): void
{
$this->app->singleton(
'circuit_breaker.payment_gateway',
fn () => new CircuitBreaker('payment_gateway', failureThreshold: 3, timeoutSeconds: 30)
);
$this->app->singleton(
'circuit_breaker.shipping_api',
fn () => new CircuitBreaker('shipping_api', failureThreshold: 5, timeoutSeconds: 60)
);
}
}
Los thresholds deben variar según la criticidad del servicio. Una pasarela de pagos tolera menos fallos que un servicio de recomendaciones.
Integración con un servicio externo
Construyamos el cliente HTTP que utiliza el Circuit Breaker. Usamos el HTTP Client de Laravel con timeouts agresivos.
<?php
namespace App\Services\Payment;
use App\Services\Resilience\CircuitBreaker;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;
use Throwable;
class PaymentGatewayClient
{
private CircuitBreaker $circuitBreaker;
private string $baseUrl;
public function __construct()
{
$this->circuitBreaker = app('circuit_breaker.payment_gateway');
$this->baseUrl = config('services.payment.base_url');
}
public function charge(array $payload): array
{
if (!$this->circuitBreaker->canAttempt()) {
Log::warning('Payment gateway circuit breaker is OPEN, rejecting request');
throw new CircuitBreakerOpenException(
'Payment service temporarily unavailable. Please retry later.'
);
}
try {
$response = Http::withHeaders([
'Authorization' => 'Bearer ' . config('services.payment.key'),
'Content-Type' => 'application/json',
])
->timeout(3)
->connectTimeout(2)
->post("{$this->baseUrl}/charges", $payload);
if ($response->failed()) {
$this->handleFailure($response->status());
}
$this->circuitBreaker->recordSuccess();
return $response->json();
} catch (Throwable $e) {
$this->circuitBreaker->recordFailure();
throw $e;
}
}
private function handleFailure(int $statusCode): void
{
$this->circuitBreaker->recordFailure();
match (true) {
$statusCode >= 500 => throw new PaymentGatewayServerException(
"Payment gateway server error: {$statusCode}"
),
$statusCode === 429 => throw new PaymentGatewayRateLimitException(
'Payment gateway rate limit exceeded'
),
default => throw new PaymentGatewayClientException(
"Payment gateway client error: {$statusCode}"
),
};
}
}
Notá las distinciones importantes: timeout(3) para la respuesta completa y connectTimeout(2) para el handshake TCP. Sin estos, una conexión lenta podría bloquear tu worker por el tiempo máximo de ejecución de PHP.
Manejo de errores y fallback strategies
Cuando el circuito está abierto, necesitás estrategias de degradación elegante. No todas las operaciones admiten fallback, pero muchas sí.
<?php
namespace App\Services\Payment;
use App\Models\PaymentAttempt;
use Illuminate\Support\Facades\Queue;
class PaymentService
{
private PaymentGatewayClient $gateway;
private RetryQueueService $retryQueue;
public function processPayment(array $data): PaymentResult
{
try {
$charge = $this->gateway->charge($data);
return new PaymentResult(
success: true,
transactionId: $charge['id']
);
} catch (CircuitBreakerOpenException $e) {
$this->scheduleRetry($data);
return new PaymentResult(
success: false,
queuedForRetry: true,
message: 'Payment queued due to service unavailability'
);
} catch (PaymentGatewayServerException $e) {
$this->scheduleRetry($data);
return new PaymentResult(
success: false,
queuedForRetry: true,
message: 'Payment queued for retry'
);
} catch (PaymentGatewayClientException $e) {
return new PaymentResult(
success: false,
finalFailure: true,
message: 'Invalid payment details'
);
}
}
private function scheduleRetry(array $data): void
{
PaymentAttempt::create([
'payload' => $data,
'status' => 'pending_retry',
'retry_at' => now()->addMinutes(5),
]);
Queue::later(
now()->addMinutes(5),
new ProcessRetryPayment($data)
);
}
}
Esta estrategia de graceful degradation asegura que el usuario reciba feedback inmediato mientras el sistema recupera la operación en segundo plano.
Monitoreo y observabilidad
Un Circuit Breaker sin métricas es ciego. Exponemos métricas para Prometheus o cualquier监控系统.
<?php
namespace App\Services\Resilience;
use Illuminate\Support\Facades\Redis;
class CircuitBreakerMetrics
{
private string $serviceName;
public function __construct(string $serviceName)
{
$this->serviceName = $serviceName;
}
public function getState(): ?string
{
return Redis::get("circuit_breaker:{$this->serviceName}:state") ?? 'closed';
}
public function getFailureCount(): int
{
return (int) Redis::get("circuit_breaker:{$this->serviceName}:failures");
}
public function getTimeUntilRetry(): ?int
{
$ttl = Redis::ttl("circuit_breaker:{$this->serviceName}:state");
return $ttl > 0 ? $ttl : null;
}
public function exposeForScraping(): array
{
return [
'circuit_breaker_state' => match ($this->getState()) {
'closed' => 0,
'half_open' => 1,
'open' => 2,
default => 0,
},
'circuit_breaker_failures' => $this->getFailureCount(),
'circuit_breaker_retry_after' => $this->getTimeUntilRetry() ?? 0,
];
}
}
Testing del Circuit Breaker
Los tests de integración deben verificar las transiciones de estado. Usamos Redis real en tests para validar la concurrencia.
<?php
namespace Tests\Integration\Resilience;
use App\Services\Resilience\CircuitBreaker;
use Illuminate\Support\Facades\Redis;
use Tests\TestCase;
class CircuitBreakerTest extends TestCase
{
protected function setUp(): void
{
parent::setUp();
Redis::flushdb();
}
public function test_circuit_opens_after_threshold_failures(): void
{
$cb = new CircuitBreaker('test_service', failureThreshold: 3);
$this->assertFalse($cb->isOpen());
$cb->recordFailure();
$cb->recordFailure();
$this->assertFalse($cb->isOpen());
$cb->recordFailure();
$this->assertTrue($cb->isOpen());
}
public function test_half_open_allows_limited_attempts(): void
{
$cb = new CircuitBreaker('test_service', failureThreshold: 1, timeoutSeconds: 0);
$cb->recordFailure();
$this->assertTrue($cb->isOpen()); // Triggers moveToHalfOpen due to timeout=0
$this->assertTrue($cb->canAttempt());
$this->assertFalse($cb->canAttempt()); // Second attempt blocked
}
public function test_success_in_half_open_closes_circuit(): void
{
$cb = new CircuitBreaker('test_service', failureThreshold: 1, timeoutSeconds: 0);
$cb->recordFailure();
$cb->isOpen(); // Transition to half-open
$cb->recordSuccess();
$this->assertFalse($cb->isOpen());
}
}
Configuración de Redis para producción
En producción, configurá Redis con persistencia adecuada y monitoreo de memoria. El Circuit Breaker genera claves con TTL, pero un Redis mal configurado puede evictar otras claves valiosas.
'redis' => [
'circuit_breaker' => [
'url' => env('REDIS_CIRCUIT_URL'),
'host' => env('REDIS_CIRCUIT_HOST', '127.0.0.1'),
'password' => env('REDIS_CIRCUIT_PASSWORD'),
'port' => env('REDIS_CIRCUIT_PORT', '6379'),
'database' => env('REDIS_CIRCUIT_DB', 2),
'read_timeout' => 1.0,
'connect_timeout' => 1.0,
],
],
Usar una database separada facilita el monitoreo y evita interferencias. Los timeouts de conexión a Redis son críticos: si Redis está lento, no querés que el Circuit Breaker mismo cause bloqueos.
Consideraciones avanzadas
Para sistemas de alta escala, considerá estas extensiones:
- Failure differentiation: Distinguir timeouts (posiblemente recuperables) de errores 4xx (no recuperables). Solo los fallos recuperables deben abrir el circuito.
- Sliding window: Reemplazar el contador simple por una ventana deslizante temporal para evitar que fallos espaciados no se detecten.
- Adaptive timeout: Ajustar dinámicamente el timeout basado en percentiles históricos de latencia.
- Request shedding: Cuando el circuito está half-open, usar token bucket para controlar cuántas requests de prueba se permiten.
Conclusión
El Circuit Breaker con Redis transforma fallos de APIs externas de catastróficos a manejables. La implementación que presentamos da prioridad a la simplicidad sin sacrificar robustez: operaciones atómicas de Redis, TTLs para limpieza automática, y transiciones de estado bien definidas.
La clave del éxito está en los detalles: timeouts agresivos en HTTP, estrategias de fallback deliberadas, y métricas que permitan ajustar los thresholds. Integrá este patrón desde el día uno en cada integración externa. Tu sistema de producción, tus usuarios y tu pagina de guardia te lo agradecerán.