Laravel Fuse

Failures are tracked in fixed-size time buckets (tumbling windows). The circuit only evaluates the failure rate once a window has gathered min_requests attempts. For low-volume services, you should increase the window size to ensure enough samples accumulate before the bucket rolls over.

'reports' => [
    'min_requests' => 10,
    'window' => 600,   // 10 minutes
],

You can define a peak_hours_threshold in your service configuration. During the specified peak_hours_start and peak_hours_end, Fuse will use this higher threshold to be more tolerant of failures, maximizing successful transactions during busy periods.

'stripe' => [
    'threshold' => 40,              // Off-peak: more sensitive (40%)
    'peak_hours_threshold' => 60,   // Peak hours: more tolerant (60%)
    'peak_hours_start' => 9,        // 9 AM
    'peak_hours_end' => 17,         // 5 PM
],

Fuse provides a real-time monitoring dashboard to view the state of all circuit breakers.

1. Enable via .env: Set FUSE_STATUS_PAGE_ENABLED=true.
2. Access: The page is available at /fuse by default, but you can change this using FUSE_STATUS_PAGE_PREFIX.
3. Authorization: Access is protected by the viewFuse gate. You must define this gate in your AppServiceProvider to control who can view the dashboard.

FUSE_STATUS_PAGE_ENABLED=true
FUSE_STATUS_PAGE_PREFIX=fuse

// app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Gate;

Gate::define('viewFuse', function ($user = null) {
    return $user?->isAdmin();
});

To use Laravel Fuse, ensure your environment meets the following requirements:

• PHP: 8.3+
• Laravel: 11+
• Cache Driver: Redis is highly recommended for production environments. Using the file cache driver may lead to race conditions during recovery probing.

Install the package via Composer and publish the configuration file to your Laravel application.

composer require harris21/laravel-fuse

php artisan vendor:publish --tag=fuse-config

Laravel Fuse automatically defines a viewFuse authorization gate if one does not already exist. By default, this gate returns true only when the application environment is set to local.

If you want to restrict or expand who can access Fuse-related features (like dashboards or views), you should define your own viewFuse gate in your AuthServiceProvider to override this default behavior.

The status page behavior is controlled via the config/fuse.php file. Key options include:

• enabled: Boolean to toggle the dashboard.
• prefix: The URL path prefix (e.g., fuse).
• middleware: An array of custom middleware to apply to the status page routes (replaces default middleware).
• polling_interval: The frontend refresh interval in seconds (default is 2).

// config/fuse.php

'status_page' => [
    'enabled' => env('FUSE_STATUS_PAGE_ENABLED', false),
    'prefix' => env('FUSE_STATUS_PAGE_PREFIX', 'fuse'),
    'middleware' => [],          // Custom middleware (replaces default)
    'polling_interval' => 2,    // Frontend refresh interval in seconds
],

To protect a queue job, add CircuitBreakerMiddleware to the job's middleware() method. You must provide a service name (e.g., 'stripe') and an optional release value (seconds to delay the job if the circuit is open).

use Harris21//Fuse\Middleware\CircuitBreakerMiddleware;

class ChargeCustomer implements ShouldQueue
{
    public $tries = 0;           // Unlimited releases
    public $maxExceptions = 3;   // Only real failures count

    public function middleware(): array
    {
        return [new CircuitBreakerMiddleware('stripe', release: 20)];
    }

    public function handle(): void
    {
        // Your payment logic
        Stripe::charges()->create([...]);
    }
}

Fuse dispatches Laravel events whenever a circuit breaker changes state. You can create listeners to trigger alerts (e.g., Slack, PagerDuty) or log critical failures when a service goes down.

Available event classes:

• Harris21\Fuse\Events\CircuitBreakerOpened
• Harris21\Fuse\Events\CircuitBreakerHalfOpen
• Harris21\Fuse\Events\CircuitBreakerClosed

use Harris21//Fuse\Events\CircuitBreakerOpened;
use Illuminate\Support\Facades\Log;

class AlertOnCircuitOpen
{
    public function handle(CircuitBreakerOpened $event): void
    {
        Log::critical("Circuit breaker opened for {$event->service}", [
            'failure_rate' => $event->failureRate,
            'attempts' => $event->attempts,
            'failures' => $event->failures,
        ]);
    }
}