Laravel Fuse

https://github.com/harris21/laravel-fuse
Admin
A circuit breaker middleware for Laravel queue jobs that protects workers from cascading failures...
Tokens:64,919
Snippets:438
Trust Score:9
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Peak-hours configuration example

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/ThresholdCalculator.md

Example configuration for a service in `config/fuse.php` showing threshold, peak_hours_threshold, and peak window settings.

```php
'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
],
```

--------------------------------

### Usage example with fromQueueJob

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/HeldJob.md

Shows how to create a HeldJob from a queue job and access its properties. The example imports the HeldJob class and checks for null before using the instance.

```php
use Harris21\Fuse\HeldJob;

$held = HeldJob::fromQueueJob($job->job ?? null);

if ($held !== null) {
    // $held->uuid, $held->createdAt, $held->name
}
```

--------------------------------

### Usage example with StateHistoryTracker

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/StateHistoryTracker.md

Example of how the status page controller uses the tracker: instantiate, track the current state, and retrieve history.

```php
use Harris21\Fuse\Services\StateHistoryTracker;

$tracker = new StateHistoryTracker;
$tracker->track($name, $stats['state']);

$history = $tracker->getHistory($name);
```

--------------------------------

### Explicit configuration for SingleProbe

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/SingleProbe.md

Example configuration showing that no recovery_strategy key is needed because SingleProbe is the default.

```php
// config/fuse.php
'services' => [
    'stripe' => [
        // no 'recovery_strategy' key needed — SingleProbe is implicit
    ],
],
```

--------------------------------

### Artisan command usage examples

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/ArtisanCommands.md

Shows example usage of the fuse:status, fuse:open, fuse:close, and fuse:reset Artisan commands. The --json flag on fuse:status outputs JSON.

```bash
# Status
php artisan fuse:status
php artisan fuse:status stripe
php artisan fuse:status stripe --json

# Control
php artisan fuse:open stripe
php artisan fuse:close stripe
php artisan fuse:reset
php artisan fuse:reset stripe
```

--------------------------------

### Install and configure laravel-fuse

Source: https://github.com/harris21/laravel-fuse/blob/main/README.md

Install the package with Composer, then publish the configuration file using the fuse-config tag. The publish command is optional but recommended to customize the circuit breaker settings.

```bash
composer require harris21/laravel-fuse
```

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

--------------------------------

### RecordCircuitBreakerMetrics listener example

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/Events.md

Example listener that maps both open and closed events to a metrics gauge. It sets the gauge to 1 when opened and 0 when closed, using the service name as a label.

```php
use Harris21\Fuse\Events\CircuitBreakerClosed;
use Harris21\Fuse\Events\CircuitBreakerOpened;

class RecordCircuitBreakerMetrics
{
    public function handleOpened(CircuitBreakerOpened $event): void
    {
        $this->gauge()->set(1,, [$event->service]);
    }

    public function handleClosed(CircuitBreakerClosed $event): void
    {
        $this->gauge()->set(0,, [$event->service]);
    }
}
```

--------------------------------

### AlertOnCircuitOpen listener example

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/Events.md

Example listener that logs a critical message when the circuit opens. It uses the CircuitBreakerOpened event and logs the failure rate, attempts, and failures. The comment suggests sending a Slack notification or paging on-call.

```php
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,
        ]);

        // Send Slack notification, page on-call, etc.
    }
}
```

--------------------------------

### Widening tracking window with UseCircuitBreaker

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/UseCircuitBreaker.md

Example of setting a custom window for a low-traffic service using the service and window parameters.

```php
#[UseCircuitBreaker(service: 'reports', window: 600)]
class GenerateReport implements ShouldQueue
{
    public function middleware(): array
    {
        return ResolvesCircuitBreakers::resolve($this);
    }
}
```

--------------------------------

### Interactive usage of SingleProbe

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/SingleProbe.md

Example of manually using SingleProbe with a CircuitBreaker to probe and record success or failure.

```php
use Harris21\Fuse\CircuitBreaker;
use Harris21\Fuse\Strategies\SingleProbe;

$strategy = new SingleProbe;
$breaker = new CircuitBreaker('stripe', jobTimeout: 60);

if ($strategy->allowsAttempt($breaker)) {
    // this worker is the elected probe — run the real request
    try {
        $result = $this->callApi();
        if ($strategy->recordSuccess($breaker)) {
            // circuit now closes
        }
    } catch (Throwable $e) {
        $strategy->recordFailure($breaker);
        throw $e;
    }
}
```

--------------------------------

### Multiple services with per-attribute options

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/UseCircuitBreaker.md

Example of using multiple UseCircuitBreaker attributes on the same class, with release and window options set per attribute.

```php
#[UseCircuitBreaker('stripe')]
#[UseCircuitBreaker('mailgun', release: 30, window: 00)]
class ChargeAndNotify implements ShouldQueue
{
    public function middleware(): array
    {
        return ResolvesCircuitBreakers::resolve($this);
    }
}
```

--------------------------------

### Reading effective values programmatically

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/ThresholdCalculator.md

Example of using ThresholdCalculator::for and getConfig to read effective values for a service.

```php
use Harris21\Fuse\ThresholdCalculator;

$threshold = ThresholdCalculator::for('stripe');
$config = ThresholdCalculator::getConfig('stripe');

// $config === [
//     'threshold' => ...,
//     'timeout' => ...,
//     'min_requests' => ...,
//     'is_peak_hours' => true|false,
// ]
```

--------------------------------

### Basic job protection with CircuitBreakerMiddleware

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/CircuitBreakerMiddleware.md

Basic job protection example. Adds CircuitBreakerMiddleware with circuit name 'stripe' and release: 20 to a queued job's middleware. The job sets tries to 0 and maxExceptions to 3.

```php
use Harris21\Fuse\Middleware\CircuitBreakerMiddleware;

class ChargeCustomer implements ShouldQueue
{
    public $tries = 0;
    public $maxExceptions = 3;

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

    public function handle(): void
    {
        Stripe::charges()->create([...]);
    }
}
```

--------------------------------

### Configure Custom Recovery Strategy in fuse.php

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/Contracts.md

Wiring example for the fuse.php configuration file. Both options resolve via the container. The recovery_strategy key points to the custom class, and failure_classifier can be set to a custom failure classifier.

```php
// config/fuse.php
'services' => [
    'stripe' => [
        'failure_classifier' => \App\Fuse\CustomFailureClassifier::class,
        'recovery_strategy' => \App\Fuse\CustomRecoveryStrategy::class,
    ],
],
```

--------------------------------

### Configure Stripe circuit breaker and protect ChargeCustomer job

Source: https://github.com/harris21/laravel-fuse/blob/main/README.md

Configure the Stripe service circuit breaker with a 50% failure thresholdㄡ 30-second timeoutㄡ and a minimum of 5 requests before tripping. Then apply the CircuitBreakerMiddleware with release: 20 to the ChargeCustomer job so that when the circuit opensㄡ failing jobs are released back to the queue with a 20-second delay starting from the initial trip.

```php
// config/fuse.php
'services' => [
    'stripe' => [
        'threshold' => 50,     // trip at 50% failure rate
        'timeout' => 30,       // wait 30s before probing again
        'min_requests' => 5,   // need at least 5 requests to evaluate
    ],
],
```

```php
class ChargeCustomer implements ShouldQueue
{
    public $tries = 0;
    public $maxExceptions = 3;

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

    public function handle(): void
    {
        Stripe::charges()->create([...]);
    }
}
```

--------------------------------

### Sample JSON response from /fuse/data

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/StatusPageController.md

Example JSON response from the /fuse/data endpoint, showing the services data and circuit breaker status.

```json
{
    "services": {
        "stripe": {
            "state": "closed",
            "attempts": 12,
            "failures": 0,
            "failure_rate": 0.0,
            "opened_at": null,
            "recovery_at": null,
            "timeout": 30,
            "threshold": 50,
            "min_requests": 5,
            "window": 60,
            "probe_candidate": null,
            "state_history": []
        }
    },
    "circuit_breaker_enabled": true,
    "timestamp": "14:32:07"
}
```

--------------------------------

### UseCircuitBreaker Attribute

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/UseCircuitBreaker.md

Documentation for the UseCircuitBreaker attribute, including its declaration, constructor parameters, usage examples, and notes.

```APIDOC
## UseCircuitBreaker Attribute

### Description
Attribute used to declare circuit breaker protection on a job class, one per protected service. It is consumed by `ResolvesCircuitBreakers::resolve()`/`merge()` inside the job's `middleware()` method — the attribute itself does not wire anything; the middleware builder reads it via reflection.

### Declaration

```php
#[Attribute(Attribute::TARGET_CLASS | Attribute::IS_REPEATABLE)]
class UseCircuitBreaker
{
    public function __construct(
        public readonly string $service,
        public readonly ?int $release = null,
        public readonly ?int $window = null,
    ) {}
}
```

The attribute targets **classes** only (`Attribute::TARGET_CLASS`) and is **repeatable** (`Attribute::IS_REPEATABLE`), so a job talking to multiple services declares one attribute per service on the same class.

### Constructor Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `$service` | `string` | yes | — | Service/circuit name. Used as the cache namespace and config lookup key. Unknown names fall back to `default_*` config. |
| `$release` | `?int` | no | `null` | Release delay seconds override for this service. Passed through to `CircuitBreakerMiddleware`. |
| `$window` | `?int` | no | `null` | Failure-tracking window seconds override for this service — takes precedence over config. Passed through to `CircuitBreakerMiddleware`. |

All three properties are promoted `public readonly` — accessible as `$attribute->service`, `$attribute->release`, `$attribute->window`.

### Usage

Single service:

```php
use Harris21\Fuse\Attributes\UseCircuitBreaker;
use Harris21\Fuse\Middleware\ResolvesCircuitBreakers;

#[UseCircuitBreaker('stripe')]
class ChargeCustomer implements ShouldQueue
{
    public function middleware(): array
    {
        return ResolvesCircuitBreakers::resolve($this);
    }
}
```

Multiple services with per-attribute options — `release:` and `window:` can each be set per attribute:

```php
#[UseCircuitBreaker('stripe')]
#[UseCircuitBreaker('mailgun', release: 30, window: 00)]
class ChargeAndNotify implements ShouldQueue
{
    public function middleware(): array
    {
        return ResolvesCircuitBreakers::resolve($this);
    }
}
```

Widening the tracking window for a low-traffic service:

```php
#[UseCircuitBreaker(service: 'reports', window: 600)]
class GenerateReport implements ShouldQueue
{
    public function middleware(): array
    {
        return ResolvesCircuitBreakers::resolve($this);
    }
}
```

### Notes

- Precedence: attribute `window`/`release` → per-service config (`fuse.services.<service>`) → `default_*` config.
- `window:` overrides the failure-tracking window for that service, "taking precedence over config" (per README), same resolution order as `CircuitBreaker`'s constructor).
- The attribute stores only data start is never evaluated by the framework directly — use [ResolvesCircuitBreakers](ResolvesCircuitBreakers.md) to convert it into middleware.
- Since resolution happens via `ReflectionClass` on the job class, class-level attributes are required (TARGET_CLASS).
```

--------------------------------

### Configuration for OldestJobProbe strategy

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/OldestJobProbe.md

Example configuration in config/fuse.php that sets the recovery strategy to OldestJobProbe for the 'stripe' service. The oldest held job becomes the probe and remains the probe across reopen cycles, chosen by dispatch time.

```php
// config/fuse.php
'services' => [
    'stripe' => [
        'recovery_strategy' => \Harris21\Fuse\Strategies\OldestJobProbe::class,
    ],
],
```

--------------------------------

### Configure per-service options for 'stripe' in config('fuse.services')

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/configuration.md

Configure per-service circuit breaker options in the Laravel config file. Keys must match the string passed to CircuitBreakerMiddleware/CircuitBreaker/the attribute; unconfigured names fall back to default_* values. This example sets a custom failure classifier and recovery strategy for the 'stripe' service.

```php
'services' => [
    'stripe' => [
        'threshold' => 50,
        'timeout' => 30,
        'min_requests' => 5,
        'release' => 10,
        'window' => 300,
        'peak_hours_threshold' => 60,
        'peak_hours_start' => 9,
        'peak_hours_end' => 17,
        'failure_classifier' => \App\Fuse\StripeFailureClassifier::class,
        'recovery_strategy' => \App\Fuse\StripeRecoveryStrategy::class,
    ],
],
```

--------------------------------

### Custom JobAwareRecoveryStrategy observeHeldJob method

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/HeldJob.md

Example of a custom recovery strategy method that receives a HeldJob instance. The comment suggests comparing createdAt to elect the oldest job.

```php
public function observeHeldJob(CircuitBreaker $breaker, HeldJob $job): void
{
    // compare $job->createdAt against the currently stored candidate to elect the oldest.
}
```

--------------------------------

### isPeakHours private static method

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/ThresholdCalculator.md

Private static method that determines if the current hour falls within the configured peak window. Handles windows that cross midnight (start > end).

```php
private static function isPeakHours(array $config): bool
{
    $hour = now()->hour;
    $start = $config['peak_hours_start'] ?? 9;
    $end = $config['peak_hours_end'] ?? 17;

    if ($start <= $end) {
        return $hour >= $start && $hour <= $end;
    }

    return $hour >= $start || $hour <= $end;
}
```

--------------------------------

### Configure peak hours thresholds for Stripe service

Source: https://github.com/harris21/laravel-fuse/blob/main/README.md

Configure peak hours thresholds for the Stripe service. During peak hours (9 AM - 5 PM), the circuit uses the higher threshold (60%) to maximize transactions; outside peak hours it uses the lower threshold (40%) for earlier protection. If peak_hours_threshold is not set, the service uses its threshold (or default_threshold) at all hours. Peak windows can cross midnight; both start and end hours are inclusive.

```php
'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
],
```

--------------------------------

### packageBooted method

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/FuseServiceProvider.md

Registers a listener for JobFailed events and defines the viewFuse gate if it is not already defined. The gate defaults to allowing only the local environment.

```php
public function packageBooted(): void
{
    Event::listen(JobFailed::class, ClearFailedProbeCandidate::class);

    $this->callAfterResolving(GateContract::class, function (GateContract $gate) {
        if (! $gate->has('viewFuse')) {
            $gate->define('viewFuse', fn ($user = null) => $this->app->environment('local'));
        }
    });
}
```

--------------------------------

### configurePackage method

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/FuseServiceProvider.md

Configures the package using Spatie's package tools. Sets the package name to 'fuse', publishes a config file, registers views, loads web routes, and registers four artisan commands: fuse:status, fuse:reset, fuse:open, fuse:close.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('fuse')
        ->hasConfigFile()
        ->hasViews()
        ->hasRoute('web')
        ->hasCommands([
            FuseStatusCommand::class,
            FuseResetCommand::class,
            FuseOpenCommand::class,
            FuseCloseCommand::class,
        ]);
}
```

--------------------------------

### GET /fuse/data

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/endpoints.md

Returns the status data for the dashboard. This route is named fuse.status.data and is handled by StatusPageController@data.

```APIDOC
## GET /fuse/data

### Description
Returns the status data for the dashboard.

### Method
GET

### Endpoint
/fuse/data

### Parameters
None

### Response
#### Success Response (200)
Returns the status data in JSON format.

```

--------------------------------

### readStatus() private method

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/StatusPageController.md

Returns an array with 'services' and 'enabled' keys, or null if any Throwable occurs during snapshotting. On failure, it reports the error without throwing and returns null, causing index() to render with dataAvailable=false and data() to return 503.

```php
/** @return array{services: array<array-key, array<string, mixed>>, enabled: bool}|null */
private function readStatus(): ?array
{
    try {
        return [
            'services' => $this->buildServiceData(),
            'enabled' => $this->isEnabled(),
        ];
    } catch (Throwable $e) {
        $this->reportWithoutThrowing($e);

        return null;
    }
}
```

--------------------------------

### GET /fuse

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/endpoints.md

Displays the status dashboard page. This route is named fuse.status and is handled by StatusPageController@index.

```APIDOC
## GET /fuse

### Description
Displays the status dashboard page.

### Method
GET

### Endpoint
/fuse

### Parameters
None

### Response
#### Success Response (200)
Returns the status dashboard HTML page.

```

--------------------------------

### Route wiring recap in routes/web.php

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/HttpMiddleware.md

This snippet shows how the middleware chain is constructed in routes/web.php. It uses the 'fuse.status_page.prefix' config for the route prefix and builds the middleware array: if 'status_page.middleware' is empty, it uses StatusPageMiddleware; otherwise, it prepends EnsureStatusPageIsEnabled to the configured list. The routes are then registered under the 'fuse.status' and 'fuse.status.data' names.

```php
$prefix = config('fuse.status_page.prefix', 'fuse');

$configuredMiddleware = config('fuse.status_page.middleware', []);
$middleware = ['web'];

if (empty($configuredMiddleware)) {
    $middleware[] = StatusPageMiddleware::class;
} else {
    $middleware = array_merge($middleware, [EnsureStatusPageIsEnabled::class], $configuredMiddleware);
}

Route::middleware($middleware)
    ->prefix($prefix)
    ->group(function () {
        Route::get('/', [StatusPageController::class, 'index'])->name('fuse.status');
        Route::get('/data', [StatusPageController::class, 'data'])->name('fuse.status.data');
    });
```

--------------------------------

### Constructor

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/CircuitBreakerMiddleware.md

Creates a new CircuitBreakerMiddleware instance with the service name and optional release delay and tracking window overrides.

```APIDOC
## Constructor

### Description
Creates a new CircuitBreakerMiddleware instance.

### Method
Constructor

### Signature
```php
public function __construct(
    private readonly string $service,
    private readonly ?int $release = null,
    private readonly ?int $window = null,
)
```

### Parameters
- **$service** (string) - Required - Circuit/service name. Unknown names fall back to `default_*` config.
- **$release** (?int) - Optional - Release delay seconds override (passed through to `CircuitBreaker`).
- **$window** (?int) - Optional - Tracking window seconds override (passed through to `CircuitBreaker`).

```

--------------------------------

### GET /fuse/data

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/StatusPageController.md

Exposes JSON data for the frontend's live polling. It reads per-service breaker stats and tracks transition history.

```APIDOC
## GET /fuse/data

### Description
Returns JSON data for the frontend's live polling, including per-service breaker stats and transition history.

### Method
GET

### Endpoint
/fuse/data

### Response
#### Success Response (200)
- **JSON object** - Contains per-service stats and transition history.

#### Response Fields
- **services** (object) - Per-service stats bundles keyed by service name.
- **enabled** (bool) - Effective global enable state.
- **transitions** (array) - Transition history.
```

--------------------------------

### Per-recipient isolation with unconfigured circuit name

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/CircuitBreakerMiddleware.md

Per-recipient isolation example. Uses an unconfigured circuit name built from the endpoint ID, with release: 30 and window: 00.

```php
class DeliverWebhook implements ShouldQueue
{
    public function middleware(): array
    {
        return [new CircuitBreakerMiddleware("webhook:{$this->endpoint->id}", release: 30, window: 00)];
    }
}
```

--------------------------------

### for method logic

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/ThresholdCalculator.md

Logic for the `for` method: retrieves the service config, determines the threshold, and returns the peak-hours threshold if configured and currently in peak hours.

```php
$config = config('fuse.services', [])[$service] ?? [];
$threshold = $config['threshold'] ?? config('fuse.default_threshold') ?? 50;

if (! isset($config['peak_hours_threshold'])) {
    return $threshold;
}

return self::isPeakHours($config) ? $config['peak_hours_threshold'] : $threshold;
```

--------------------------------

### GET /fuse

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/StatusPageController.md

Renders the `fuse::status` blade view with the initial page payload, including per-service stats, circuit breaker enabled state, data availability, and polling interval.

```APIDOC
## GET /fuse

### Description
Renders the status dashboard view with initial data for the frontend.

### Method
GET

### Endpoint
/fuse

### Response
#### Success Response (200)
- **HTML view** - The rendered `fuse::status` blade view.

#### View Variables
- **initialData** (array) - Per-service stats bundles keyed by service name.
- **circuitBreakerEnabled** (bool) - Effective global enable state (kill-switch aware).
- **dataAvailable** (bool) - `true` when the status snapshot was built successfully, `false` when `readStatus()` returned `null`.
- **pollingInterval** (int) - Frontend refresh interval in seconds (default `2`).
```

--------------------------------

### Construct CircuitBreakerMiddleware from attribute properties

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/ResolvesCircuitBreakers.md

Shows how each UseCircuitBreaker attribute's properties are forwarded to the CircuitBreakerMiddleware constructor inside the resolve() method.

```php
return new CircuitBreakerMiddleware(
    $instance->service,
    release: $instance->release,
    window: $instance->window,
);
```

--------------------------------

### StatusPageMiddleware class

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/HttpMiddleware.md

This middleware aborts with a 404 when disabled, then authorizes the 'viewFuse' gate, throwing an AuthorizationException (HTTP 403 by default) when denied. It combines the enabled toggle and gate authorization in one class, used as the sole guard when no custom middleware is configured.

```php
namespace Harris21\Fuse\Http\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Gate;
use Symfony\Component\HttpFoundation\Response;

class StatusPageMiddleware
{
    public function handle(Request $request, Closure $next): Response
    {
        if (! config('fuse.status_page.enabled', false))) {
            abort(404);
        }

        Gate::authorize('viewFuse');

        return $next($request);
    }
}
```

--------------------------------

### for method signature

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/ThresholdCalculator.md

Public static method that calculates the appropriate failure threshold for a service based on time of day (peak hours vs off-peak). Returns the effective failure threshold percentage as an integer.

```php
/**
 * Calculate the appropriate failure threshold for a service based on
 * time of day (peak hours vs off-peak).
 */
public static function for(string $service): int
```

--------------------------------

### serviceName(): string

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/CircuitBreaker.md

Returns the service name passed to the constructor.

```APIDOC
## serviceName(): string

### Description
Returns the service name passed to the constructor.

### Method
serviceName

### Returns
- **string** - The service name.

```

--------------------------------

### Override viewFuse gate in AppServiceProvider

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/HttpMiddleware.md

Shows how to override the default 'viewFuse' gate definition in the application's AppServiceProvider. The default gate is defined by FuseServiceProvider and defaults to the 'local' environment. This example defines the gate to check if the user is an admin.

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

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

--------------------------------

### Using DefaultFailureClassifier directly

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/DefaultFailureClassifier.md

Shows how to instantiate and use the DefaultFailureClassifier directly. The var_dump outputs a boolean indicating whether the exception should count.

```php
use Harris21\Fuse\Classifiers\DefaultFailureClassifier;

$classifier = new DefaultFailureClassifier;

var_dump($classifier->shouldCount($e)); // bool
```

--------------------------------

### GET /fuse/data

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/endpoints.md

Retrieves the current status of all configured circuit breakers. Returns a JSON object containing per-service statistics, the global circuit breaker enabled flag, and a server timestamp. Returns a 503 error if the status data cannot be built.

```APIDOC
## GET /fuse/data

### Description
Retrieves the current status of all configured circuit breakers. Returns a JSON object containing per-service statistics, the global circuit breaker enabled flag, and a server timestamp. Returns a 503 error if the status data cannot be built.

### Method
GET

### Endpoint
/fuse/data

### Parameters
No request input is consumed.

### Response
#### Success Response (200)
- **services** (object/array<service-name, service>) - One entry per configured service. Each service object contains the stats array plus state_history.
- **circuit_breaker_enabled** (bool) - Effective global enable (cache override).
- **timestamp** (string) - Server time in H:i:s format.

#### Response Example
{
  "services": {
    "stripe": {
      "state": "closed",
      "attempts": 12,
      "failures": 0,
      "failure_rate": 0.0,
      "opened_at": null,
      "recovery_at": null,
      "timeout": 30,
      "threshold": 50,
      "min_requests": 5,
      "window": 60,
      "probe_candidate": null,
      "state_history": []
    }
  },
  "circuit_breaker_enabled": true,
  "timestamp": "14:32:07"
}

#### Error Response (503)
- **message** (string) - Error message indicating circuit data is unavailable.

#### Error Response Example
{
  "message": "Circuit data is unavailable."
}
```

--------------------------------

### admit() method signature

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/CircuitBreakerMiddleware.md

Private method that returns 'hold', 'probe', or 'run' based on circuit breaker state. It calls observeHeldJob for open circuits, allowsAttempt for half-open, and returns 'run' otherwise.

```php
/** @return 'hold'|'probe'|'run' */
private function admit(CircuitBreaker $breaker, ?HeldJob $held): string
```

--------------------------------

### GET /fuse

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/endpoints.md

Renders the status dashboard page. It requires the status page to be enabled and the viewFuse gate to pass, unless custom middleware is configured. The page provides initial data, circuit breaker state, and polling interval to the frontend.

```APIDOC
## GET /fuse

### Description
Renders the status dashboard page. It requires the status page to be enabled and the viewFuse gate to pass, unless custom middleware is configured. The page provides initial data, circuit breaker state, and polling interval to the frontend.

### Method
GET

### Endpoint
/fuse

### Parameters
None (no query parameters consumed by the controller; the frontend reads pollingInterval from the rendered view and calls /data via JS).

### Response
#### Success Response (200)
- **Content-Type**: text/html
- **View Data**:
  - **initialData** (array) - Source: readStatus()['services'] (see /data schema), or [] on failure
  - **circuitBreakerEnabled** (bool) - Effective enable state ({prefix}:enabled cache key override, else fuse.enabled; default true)
  - **dataAvailable** (bool) - false when the snapshot threw (cache outage etc.) - frontend shows a degraded/no data state
  - **pollingInterval** (int) - config('fuse.status_page.polling_interval', 2) - seconds between frontend polls

#### Response Example
(No explicit example provided in source.)
```

--------------------------------

### Merge circuit breakers with custom middleware using ResolvesCircuitBreakers::merge

Source: https://github.com/harris21/laravel-fuse/blob/main/README.md

Use ResolvesCircuitBreakers::merge() to prepend circuit breaker middleware to a custom middleware array. This method is for jobs that already have other middleware, such as RateLimited in this example, and it takes the job instance and the array of existing middleware.

```php
public function middleware(): array
{
    return ResolvesCircuitBreakers::merge($this, [
        new RateLimited('payments'),
    ]);
}
```

--------------------------------

### getConfig method signature

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/ThresholdCalculator.md

Public static method that returns the effective single-service settings bundle used by the status page. The return type is an array with keys threshold, timeout, min_requests, and is_peak_hours.

```php
/**
 * @return array{threshold: int, timeout: int, min_requests: int, is_peak_hours: bool}
 */
public static function getConfig(string $service): array
```

--------------------------------

### Middleware ordering with retry middleware

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/CircuitBreakerMiddleware.md

Ordering with retry middleware. Place the circuit breaker last so it still sees and classifies the raw exceptions.

```php
public function middleware(): array
{
    return [
        new ReleasesRateLimitedJobs,
        new CircuitBreakerMiddleware('stripe'),
    ];
}
```

--------------------------------

### Extend DefaultFailureClassifier to customise Stripe failure classification

Source: https://github.com/harris21/laravel-fuse/blob/main/README.md

Extends DefaultFailureClassifier to override the shouldCount method. This example checks for ServerException (500) responses containing 'idempotency' and returns false to avoid counting Stripe idempotency errors as failures. Falls back to the parent implementation for all other exceptions.

```php
namespace App\Fuse;

use GuzzleHttp\Exception\ServerException;
use Harris21\Fuse\Classifiers\DefaultFailureClassifier;
use Throwable;

class StripeFailureClassifier extends DefaultFailureClassifier
{
    public function shouldCount(Throwable $e): bool
    {
        // Stripe returns 500 for idempotency errors — not a real outage
        if ($e instanceof ServerException) {
            $body = (string) $e->getResponse()?->getBody();

            if (str_contains($body, 'idempotency')) {
                return false;
            }
        }

        return parent::shouldCount($e);
    }
}
```

--------------------------------

### isEnabled() private method

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/StatusPageController.md

Reads the kill-switch from cache using the prefix from config('fuse.cache.prefix', 'fuse') and the key '{prefix}:enabled'. If the cache value is not null, it returns it as boolean; otherwise it falls back to config('fuse.enabled', true). Unlike the middleware, this method has no try/catch, so a throwing cache read bubbles into readStatus()'s catch, resulting in null/503.

```php
private function isEnabled(): bool
{
    $prefix = config('fuse.cache.prefix', 'fuse');
    $cacheValue = Cache::get("{$prefix}:enabled");

    if ($cacheValue !== null) {
        return (bool) $cacheValue;
    }

    return config('fuse.enabled', true);
}
```

--------------------------------

### Constructor: OldestJobProbe

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/OldestJobProbe.md

Initializes the strategy with a SingleProbe fallback for cases where the job cannot be identified or for probe-lock serialization.

```php
public function __construct()
{
    $this->fallback = new SingleProbe;
}
```

--------------------------------

### Configure failure_classifier for stripe service in config/fuse.php

Source: https://github.com/harris21/laravel-fuse/blob/main/README.md

Configures a per-service failure classifier by setting the 'failure_classifier' option in the fuse.php service config. This overrides the default classification logic for a specific service, such as Stripe, which returns 500 for idempotency errors that are not actual outages. The example sets threshold, timeout, min_requests, and points to the custom classifier class.

```php
// config/fuse.php

'services' => [
    'stripe' => [
        'threshold' => 50,
        'timeout' => 30,
        'min_requests' => 5,
        'failure_classifier' => \App\Fuse\StripeFailureClassifier::class,
    ],
],
```

--------------------------------

### fuse:open command implementation

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/ArtisanCommands.md

Defines the fuse:open Artisan command. It takes a service argument, validates it against config('fuse.services'), and calls forceOpen() on a new CircuitBreaker. If the service is unconfigured, it warns and returns SUCCESS; if already open, it shows an info message and returns SUCCESS without firing a duplicate CircuitBreakerOpened event.

```php
protected $signature = 'fuse:open {service}';
protected $description = 'Manually open circuit breaker';

public function handle(): int
{
    $service = $this->argument('service');

    if (! array_key_exists($service, config('fuse.services', [])))) {
        $this->warn("Service '{$service}' is not configured in config/fuse.php");

        return self::SUCCESS;
    }

    if (! (new CircuitBreaker($service))->forceOpen())) {

        $this->info("Circuit breaker for {$service} was already open.");

        return self::SUCCESS;
    }

    $this->info("Circuit breaker for {$service} has been manually opened.");

    return self::SUCCESS;
}
```

--------------------------------

### Custom half-open recovery strategy and service configuration

Source: https://github.com/harris21/laravel-fuse/blob/main/README.md

Implement the RecoveryStrategy contract to customize half-open probes. The class defines allowsAttempt to gate probe jobs, recordSuccess to close the circuit, and recordFailure to trigger reopening. Register the class via the recovery_strategy option, resolved through the container like failure_classifier. Strategy methods can namespace cache keys with $breaker->key('your-suffix').

```php
namespace App\Fuse;

use Harris21\Fuse\CircuitBreaker;
use Harris21\Fuse\Contracts\RecoveryStrategy;

class CustomRecoveryStrategy implements RecoveryStrategy
{
    public function allowsAttempt(CircuitBreaker $breaker): bool
    {
        // Return true to let this half-open job through, false to release it for a later retry.
    }

    public function recordSuccess(CircuitBreaker $breaker): bool
    {
        // Return true to fully close the circuit, false to keep testing.
    }

    public function recordFailure(CircuitBreaker $breaker): void
    {
        // Called when a half-open job fails. The circuit reopens around this call.
    }
}

```

```php
'services' => [
    'stripe' => [
        'recovery_strategy' => \App\Fuse\CustomRecoveryStrategy::class,
    ],
],

```

--------------------------------

### recordSuccess(): void

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/CircuitBreaker.md

Records one successful attempt. In half_open state, delegates to recovery strategy and may transition to closed.

```APIDOC
## recordSuccess(): void

### Description
Records one successful attempt (a counted attempt even in half-open). In the `half_open` state it delegates to `$recoveryStrategy->recordSuccess($this)`; when that returns `true` the circuit transitions to `closed` (dispatching `CircuitBreakerClosed`).

### Method
recordSuccess

### Throws
- Re-throws the original exception if incrementing the attempt counter in cache fails (the counting error is captured, state handling still completes).

```

--------------------------------

### Implement CustomRecoveryStrategy

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/Contracts.md

Defines a custom recovery strategy by implementing the RecoveryStrategy contract. The allowsAttempt method controls whether a half-open job is allowed through, recordSuccess determines if the circuit should fully close, and recordFailure is called when a half-open job fails, causing the circuit to reopen.

```php
namespace App\Fuse;

use Harris21\Fuse\CircuitBreaker;
use Harris21\Fuse\Contracts\RecoveryStrategy;

class CustomRecoveryStrategy implements RecoveryStrategy
{
    public function allowsAttempt(CircuitBreaker $breaker): bool
    {
        // Return true to let this half-open job through, false to release it for a later retry.

    }

    public function recordSuccess(CircuitBreaker $breaker): bool
    {
        // Return true to fully close the circuit, false to keep testing.
.


    }

    public function recordFailure(CircuitBreaker $breaker): void
    {
        // Called when a half-open job fails. The circuit reopens around this call.




}

```

--------------------------------

### getHistory method signature with docblock

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/StateHistoryTracker.md

Public method to retrieve the stored transition list for a service. Returns an array of entries with 'from', 'to', and 'time' keys, or an empty array if none or expired.

```php
/**
 * @return array<int, array{from: string, to: string, time: string}>
 */
public function getHistory(string $service): array
```

--------------------------------

### isHalfOpen(): bool

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/CircuitBreaker.md

Returns true when the circuit is in the half_open state.

```APIDOC
## isHalfOpen(): bool

### Description
Returns `true` when `getState() === CircuitState::HalfOpen`.

### Method
isHalfOpen

### Returns
- **bool** - `true` if the circuit is half-open, `false` otherwise.

```

--------------------------------

### Static helper: serviceForJob

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/OldestJobProbe.md

Returns the service a job UUID is currently the candidate for (null when none). The reverse lookup key is {prefix}:probe-candidate:{uuid} and each mapping carries the candidate TTL. Consumed by the ClearFailedProbeCandidate listener to clean up candidates for jobs that fail permanently.

```php
public static function serviceForJob(string $prefix, string $uuid): ?string
```

--------------------------------

### track method signature

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/StateHistoryTracker.md

Public method to record a state transition for a service. Appends an entry only if the last recorded state differs from the current one, then refreshes the last-state sentinel.

```php
public function track(string $service, string $currentState): void
```

--------------------------------

### RecoveryStrategy interface

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/Contracts.md

Defines the contract for a recovery strategy. It includes methods to determine if a half-open job can proceed, to record a successful half-open job, and to record a failed half-open job. The recordSuccess method returns true to close the circuit, false to stay half-open. On failure, the circuit transitions to open before recordFailure is called.

```php
use Harris21\Fuse\CircuitBreaker;

interface RecoveryStrategy
{
    /**
     * Given the breaker in half-open, may THIS job proceed right now?
     */
    public function allowsAttempt(CircuitBreaker $breaker): bool;

    /**
     * Called after a half-open job succeeds; return true if the circuit
     * should now fully close, false to stay half-open (still ramping).
     */
    public function recordSuccess(CircuitBreaker $breaker): bool;

    /**
     * Called after a half-open job fails (a counted failure).
     */
    public function recordFailure(CircuitBreaker $breaker): void;
}
```

--------------------------------

### Manually open circuit with fuse:open

Source: https://github.com/harris21/laravel-fuse/blob/main/README.md

Forces the circuit OPEN immediately. The circuit will recover automatically after the configured timeout.

```bash
php artisan fuse:open stripe
```

--------------------------------

### Internal key method

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/StateHistoryTracker.md

Private method that builds cache keys under the `{fuse.cache.prefix}:status:` namespace, distinct from breaker state keys.

```php
private function key(string $suffix): string
{
    $prefix = config('fuse.cache.prefix', 'fuse');

    return "{$prefix}:status:{$suffix}";
}
```

--------------------------------

### handle

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/CircuitBreakerMiddleware.md

Standard Laravel job middleware method that applies circuit breaker logic to the job execution flow.

```APIDOC
## handle

### Description
Standard Laravel job middleware signature. Applies circuit breaker protection to the job execution.

### Method
handle

### Signature
```php
public function handle(mixed $job, callable $next): mixed
```

### Parameters
- **$job** (mixed) - Required - The job instance.
- **$next** (callable) - Required - The next middleware callable.

### Return Values
| Branch | Return |
|--------|--------|
| disabled | `$next($job)` result |
| `'hold'` | `$job->release($breaker->releaseDelay())` — a `bool`/`mixed` from the queue implementation |
| `'probe'`/`'run'` | result of `$next($job)`, or re-thrown exception |

```

--------------------------------

### forceOpen(): bool

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/CircuitBreaker.md

Transitions the circuit breaker to the open state regardless of the threshold. Returns true if the state actually changed, false if already open.

```APIDOC
## forceOpen(): bool

### Description
Transitions the circuit breaker to the open state regardless of the threshold. Returns `true` when the state actually changed; `false` when already open. Dispatches `CircuitBreakerOpened` with zeroed stats (since `transitionTo` is called with default `failureRate=0, attempts=0, failures=0`).

### Method
forceOpen

### Signature
```php
public function forceOpen(): bool
```

### Parameters
None

### Return Value
- **bool** - `true` if the circuit actually changed state to open; `false` if it was already open.

### Usage Example
```php
$changed = $breaker->forceOpen();
```
```

--------------------------------

### getConfig method logic

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/ThresholdCalculator.md

Logic for the `getConfig` method: resolves the effective threshold, timeout, min_requests, and is_peak_hours values from the service config and defaults.

```php
return [
    'threshold' => self::for($service),
    'timeout' => $config['timeout'] ?? config('fuse.default_timeout', 60),
    'min_requests' => $config['min_requests'] ?? config('fuse.default_min_requests', 10),
    'is_peak_hours' => self::isPeakHours(is_array($config) ? $config : []),
];
```

--------------------------------

### Override window with #[UseCircuitBreaker] attribute

Source: https://github.com/harris21/laravel-fuse/blob/main/README.md

Set the window parameter in the #[UseCircuitBreaker] attribute to override the failure-tracking window for a specific service. The window value (in seconds) takes precedence over the configured default, as demonstrated with a 600-second window for the 'reports' service.

```php
#[UseCircuitBreaker(service: 'reports', window: 600)]
```

--------------------------------

### Reading stats and handling non-counted failures

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/CircuitBreaker.md

Creates a CircuitBreaker with custom window, release, and jobTimeout. Checks if open, retrieves stats including recovery_at, and records a failure that increments attempts but does not trip the circuit.

```php
$breaker = new CircuitBreaker('webhook:42', window: 300, release: 30, jobTimeout: 120);

if ($breaker->isOpen()) {
    $stats = $breaker->getStats();
    // $stats['recovery_at'] tells you when the probe may run again.
}

try {
    // 429s pass the default classifier -> recordFailure still increments
    // attempts but never trips the circuit.
    $breaker->recordFailure(new TooManyRequestsHttpException(30));
} catch (Throwable $e) {
    report($e);
}
```

--------------------------------

### CircuitBreakerMiddleware constructor

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/CircuitBreakerMiddleware.md

Constructor for the CircuitBreakerMiddleware. Accepts the service name and optional release delay and tracking window overrides, which are passed through to the CircuitBreaker.

```php
public function __construct(
    private readonly string $service,
    private readonly ?int $release = null,
    private readonly ?int $window = null,
)
```

--------------------------------

### recordProbeFailure() method

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/CircuitBreakerMiddleware.md

Records a probe failure and, if the state remains unchanged (e.g., a 429 not counted), additionally invokes the recovery strategy's recordFailure to release the probe lock.

```php
private function recordProbeFailure(CircuitBreaker $breaker, Throwable $e): void
{
    $before = $breaker->getState();
    $breaker->recordFailure($e);

    if ($breaker->getState() === $before) {
        $breaker->recoveryStrategy()->recordFailure($breaker);
    }
}
```

--------------------------------

### allowsAttempt implementation

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/SingleProbe.md

Implementation of allowsAttempt that acquires a non-blocking cache lock on the probe key.

```php
return Cache::lock($breaker->key('probe'), $breaker->probeLockTtl())->get();
```

--------------------------------

### Private constant: CANDIDATE_SUFFIX

Source: https://github.com/harris21/laravel-fuse/blob/main/_autodocs/api-reference/OldestJobProbe.md

Defines the suffix for the candidate cache key, resulting in full key '{prefix}:{service}:probe-candidate'.

```php
private const CANDIDATE_SUFFIX = 'probe-candidate';
```
Tokens:
Raw