← Volver al blog

Circuit Breaker con Redis en Laravel: protegiendo APIs externas de fallos en cascada

2026-07-22

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:

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:

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:

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.