10 middleware

Middleware is the primary extension mechanism for the HTTP client. It lets you add behaviors — logging, retries, circuit breaking, authentication, response transformation — without modifying drivers or request code. Each middleware sits in a pipeline: requests pass through in order on the way out, and responses pass through in reverse order on the way back.

How Middleware Works

The middleware pipeline follows a simple pattern:

Request  -> Middleware A -> Middleware B -> Middleware C -> Driver -> Server
Response <- Middleware A <- Middleware B <- Middleware C <- Driver <- Server
// @doctest id="4ce5"

Each middleware receives the request and a reference to the next handler in the chain. It can modify the request, call the next handler, inspect or modify the response, or short-circuit the chain entirely by returning a response without calling next.

The HttpMiddleware Interface

All middleware implements a single interface:

namespace Cognesy\Http\Contracts;

interface HttpMiddleware
{
    public function handle(HttpRequest $request, CanHandleHttpRequest $next): HttpResponse;
}
// @doctest id="0119"

Here is a complete example that adds a header to every request:

use Cognesy\Http\Contracts\CanHandleHttpRequest;
use Cognesy\Http\Contracts\HttpMiddleware;
use Cognesy\Http\Data\HttpRequest;
use Cognesy\Http\Data\HttpResponse;

final class AddHeaderMiddleware implements HttpMiddleware
{
    public function __construct(
        private string $name,
        private string $value,
    ) {}

    public function handle(HttpRequest $request, CanHandleHttpRequest $next): HttpResponse
    {
        $request = $request->withHeader($this->name, $this->value);
        return $next->handle($request);
    }
}
// @doctest id="39e6"

The BaseMiddleware Abstract Class

For most middleware, you do not need to implement the full handle() method. The BaseMiddleware class provides a template with overridable hooks:

use Cognesy\Http\Extras\Support\BaseMiddleware;
use Cognesy\Http\Data\HttpRequest;
use Cognesy\Http\Data\HttpResponse;

final class TimingMiddleware extends BaseMiddleware
{
    private float $start;

    protected function beforeRequest(HttpRequest $request): HttpRequest
    {
        $this->start = microtime(true);
        return $request;
    }

    protected function afterRequest(HttpRequest $request, HttpResponse $response): HttpResponse
    {
        $duration = round((microtime(true) - $this->start) * 1000, 2);
        error_log("Request to {$request->url()} took {$duration}ms");
        return $response;
    }
}
// @doctest id="db64"

The available hooks are:

Method	Purpose
`beforeRequest($request)`	Modify the request before sending. Return the (possibly modified) request.
`afterRequest($request, $response)`	Inspect or modify the response after receiving it. Return the response.
`shouldDecorateResponse($request, $response)`	Return `true` to wrap the response through `toResponse()`. Defaults to `true`.
`toResponse($request, $response)`	Return a decorated response (e.g., with a transformed stream).
`shouldExecute($request)`	Return `false` to skip this middleware entirely for a given request.

Registering Middleware

On an Existing Client

The HttpClient is immutable. withMiddleware() returns a new client with the middleware appended:

$client = $client->withMiddleware(new AddHeaderMiddleware('X-Request-ID', 'req-123'), 'request-id');
// @doctest id="0e87"

The second argument is an optional name, which lets you remove the middleware later:

$client = $client->withoutMiddleware('request-id');
// @doctest id="8263"

Via the Builder

The builder collects middleware before creating the client:

use Cognesy\Http\Creation\HttpClientBuilder;

$client = (new HttpClientBuilder())
    ->withMiddleware(new AddHeaderMiddleware('X-Api-Version', '2'))
    ->withMiddleware(new TimingMiddleware())
    ->create();
// @doctest id="07d8"

Built-in Middleware

The package ships with several production-ready middleware components.

RetryMiddleware

Automatically retries failed requests with exponential backoff and jitter:

use Cognesy\Http\Extras\Middleware\RetryMiddleware;
use Cognesy\Http\Extras\Support\RetryPolicy;

$client = (new HttpClientBuilder())
    ->withRetryPolicy(new RetryPolicy(
        maxRetries: 3,
        baseDelayMs: 250,
        maxDelayMs: 8000,
        jitter: 'full',                    // none, full, or equal
        retryOnStatus: [408, 429, 500, 502, 503, 504],
        respectRetryAfter: true,
    ))
    ->create();
// @doctest id="faeb"

The retry middleware only operates on synchronous (non-streamed) requests. It respects the Retry-After header when present. The jitter options are:

none — exact exponential backoff
full — random delay between 0 and the calculated backoff
equal — half the backoff plus a random portion of the other half

CircuitBreakerMiddleware

Prevents repeated calls to a failing service by tracking failures per host:

use Cognesy\Http\Extras\Middleware\CircuitBreakerMiddleware;
use Cognesy\Http\Extras\Support\CircuitBreakerPolicy;

$client = (new HttpClientBuilder())
    ->withCircuitBreakerPolicy(new CircuitBreakerPolicy(
        failureThreshold: 5,
        openForSec: 30,
        halfOpenMaxRequests: 2,
        successThreshold: 2,
        failureStatusCodes: [429, 500, 502, 503, 504],
    ))
    ->create();
// @doctest id="8fda"

The circuit breaker follows the standard state machine:

Closed — requests flow normally; failures are counted.
Open — after failureThreshold failures, the circuit opens and all requests throw CircuitBreakerOpenException for openForSec seconds.
Half-open — after the timeout, a limited number of probe requests are allowed. If successThreshold probes succeed, the circuit closes. If any fail, it reopens.

State is stored in APCu when available, with an in-memory fallback for environments without it.

IdempotencyMiddleware

Attaches a unique idempotency key to requests, which prevents duplicate processing when retries occur:

use Cognesy\Http\Extras\Middleware\IdempotencyMiddleware;

$client = (new HttpClientBuilder())
    ->withIdempotencyMiddleware(new IdempotencyMiddleware(
        headerName: 'Idempotency-Key',
        methods: ['POST'],
        hostAllowList: ['api.stripe.com'],
    ))
    ->create();
// @doctest id="2622"

The middleware only attaches keys to the specified HTTP methods and hosts. If the request already has an idempotency key header, it is left unchanged.

EventSourceMiddleware

Parses server-sent event streams into clean payloads. See Streaming Responses for usage details.

RecordReplayMiddleware

Records HTTP interactions to disk and replays them later, which is invaluable for testing and development:

use Cognesy\Http\Extras\Middleware\RecordReplay\RecordReplayMiddleware;

// Record mode -- real requests are made and saved
$recorder = new RecordReplayMiddleware(
    mode: RecordReplayMiddleware::MODE_RECORD,
    storageDir: '/tmp/http_recordings',
);

// Replay mode -- saved responses are returned without network calls
$replayer = new RecordReplayMiddleware(
    mode: RecordReplayMiddleware::MODE_REPLAY,
    storageDir: '/tmp/http_recordings',
    fallbackToRealRequests: true,
);

$client = (new HttpClientBuilder())
    ->withMiddleware($replayer)
    ->create();
// @doctest id="1c6b"

When fallbackToRealRequests is true, unrecorded requests are sent to the real server. When false, a RecordingNotFoundException is thrown. Record/replay matching is intentionally narrow in 2.0.0: recordings are keyed by request method, full URL, and body. Request headers and request options are not part of the identity contract. For streamed responses, recording mode buffers the full upstream stream before returning a replayable streamed response. That keeps replay deterministic, but it means recording mode is not a transparent progressive-streaming path.

Response Decoration

For middleware that needs to transform streamed responses, use BaseResponseDecorator to wrap the stream with a transformation function:

use Cognesy\Http\Extras\Support\BaseResponseDecorator;

$decorated = BaseResponseDecorator::decorate(
    $response,
    fn(string $chunk): string => strtoupper($chunk),
);
// @doctest id="dd95"

This creates a new HttpResponse with a TransformStream that applies your function to each chunk. The original response is not modified.

Writing Custom Middleware

Here is a practical example of authentication middleware:

use Cognesy\Http\Extras\Support\BaseMiddleware;
use Cognesy\Http\Data\HttpRequest;

final class BearerAuthMiddleware extends BaseMiddleware
{
    public function __construct(
        private string $token,
    ) {}

    protected function beforeRequest(HttpRequest $request): HttpRequest
    {
        return $request->withHeader('Authorization', 'Bearer ' . $this->token);
    }
}
// @doctest id="4344"

And a logging middleware that records request duration:

use Cognesy\Http\Contracts\CanHandleHttpRequest;
use Cognesy\Http\Contracts\HttpMiddleware;
use Cognesy\Http\Data\HttpRequest;
use Cognesy\Http\Data\HttpResponse;
use Psr\Log\LoggerInterface;

final class LoggingMiddleware implements HttpMiddleware
{
    public function __construct(
        private LoggerInterface $logger,
    ) {}

    public function handle(HttpRequest $request, CanHandleHttpRequest $next): HttpResponse
    {
        $this->logger->info('HTTP request', [
            'method' => $request->method(),
            'url' => $request->url(),
        ]);

        $start = microtime(true);
        $response = $next->handle($request);
        $duration = microtime(true) - $start;

        $this->logger->info('HTTP response', [
            'status' => $response->statusCode(),
            'duration_ms' => round($duration * 1000, 2),
        ]);

        return $response;
    }
}
// @doctest id="4d8a"

Middleware Order

The order you register middleware determines the execution flow. Middleware registered first is the outermost layer:

$client = (new HttpClientBuilder())
    ->withMiddleware(new LoggingMiddleware($logger))      // 1st: logs everything
    ->withMiddleware(new RetryMiddleware($retryPolicy))   // 2nd: retries include auth
    ->withMiddleware(new BearerAuthMiddleware($token))    // 3rd: adds auth header
    ->create();
// @doctest id="91e4"

In this setup:

Request flow: Logging -> Retry -> Auth -> Driver
Response flow: Driver -> Auth -> Retry -> Logging

The retry middleware wraps the auth middleware, so retried requests get fresh auth headers. The logging middleware sees all attempts, including retries.

Middleware Stack API

The MiddlewareStack class provides fine-grained control over the middleware collection:

$stack->append($middleware, 'name');     // Add to end
$stack->prepend($middleware, 'name');    // Add to beginning
$stack->remove('name');                 // Remove by name
$stack->replace('name', $newMiddleware); // Replace by name
$stack->has('name');                    // Check existence
$stack->get('name');                    // Get by name
$stack->clear();                       // Remove all
$stack->all();                         // Get all middleware
// @doctest id="81f1"

You can replace the entire stack on a client:

$client = $client->withMiddlewareStack($newStack);
// @doctest id="822b"

Packages

Instructor

Polyglot

Agents

Agent-ctrl

Telemetry

Sandbox

HTTP Client

Laravel

Symfony

Xprompt

How Middleware Works

The HttpMiddleware Interface

The BaseMiddleware Abstract Class

Registering Middleware

On an Existing Client

Via the Builder

Built-in Middleware

RetryMiddleware

CircuitBreakerMiddleware

IdempotencyMiddleware

EventSourceMiddleware

RecordReplayMiddleware

Response Decoration

Writing Custom Middleware

Middleware Order

Middleware Stack API

See Also

​How Middleware Works

​The HttpMiddleware Interface

​The BaseMiddleware Abstract Class

​Registering Middleware

​On an Existing Client

​Via the Builder

​Built-in Middleware

​RetryMiddleware

​CircuitBreakerMiddleware

​IdempotencyMiddleware

​EventSourceMiddleware

​RecordReplayMiddleware

​Response Decoration

​Writing Custom Middleware

​Middleware Order

​Middleware Stack API

​See Also

How Middleware Works

The HttpMiddleware Interface

The BaseMiddleware Abstract Class

Registering Middleware

On an Existing Client

Via the Builder

Built-in Middleware

RetryMiddleware

CircuitBreakerMiddleware

IdempotencyMiddleware

EventSourceMiddleware

RecordReplayMiddleware

Response Decoration

Writing Custom Middleware

Middleware Order

Middleware Stack API

See Also