Пакет · cast

Middleware

Middleware — шаг, через который проходит каждый запрос клиента и его ответ. В нём удобно ставить вычисляемые заголовки, обновлять токен, снимать метрики.

Интерфейс

php
use Flytachi\Winter\Cast\Message\CastRequest;
use Flytachi\Winter\Cast\Message\CastResponse;
use Flytachi\Winter\Cast\Middleware\CastMiddleware;

final class TimingMiddleware implements CastMiddleware
{
  public function __construct(private Metrics $metrics) {}

  public function process(CastRequest $request, callable $next): CastResponse
  {
      $start = hrtime(true);
      $response = $next($request);
      $this->metrics->observe($request->getUri()->getHost(), (hrtime(true) - $start) / 1e6);

      return $response;
  }
}

$client = $client->withMiddleware(new TimingMiddleware($metrics));

$next($request) передаёт запрос дальше по цепочке и возвращает ответ. Middleware может изменить запрос до вызова, ответ — после, или не вызывать $next вовсе и вернуть свой ответ.

Вместо класса подойдёт замыкание:

php
$client = $client->withMiddleware(
  fn(CastRequest $request, callable $next) => $next($request->withHeader('X-Request-ID', $requestId)),
);

Middleware всегда получает CastRequest — даже если клиенту передали чужой PSR-7 запрос.

Порядок

php
$client->withMiddleware($a)->withMiddleware($b, $c);

Первым выполняется добавленный первым: $a → $b → $c → сеть → $c → $b → $a. withoutMiddleware(TimingMiddleware::class) убирает middleware по классу — удобно в тестах.

Middleware выполняются один раз на запрос. Повторы и редиректы происходят внутри цепочки, ближе к сети. Заголовки клиента по умолчанию уже стоят в запросе, когда он приходит в middleware.

Встроенные

AuthMiddleware

php
use Flytachi\Winter\Cast\Middleware\AuthMiddleware;

AuthMiddleware::bearer($token);                         // Authorization: Bearer …
AuthMiddleware::bearer(fn() => $tokens->current());     // токен берётся на каждый запрос
AuthMiddleware::basic($user, $password);                // Authorization: Basic …
AuthMiddleware::header('X-Api-Key', $key);              // ключ в своём заголовке

Если в запросе уже есть этот заголовок, middleware его не трогает. Заголовок из header() помечается секретным: он скрыт в дампах и не уходит на другой хост при редиректе.

Постоянный ключ проще задать у клиента: withBearerToken() или withHeader(). AuthMiddleware нужен, когда значение меняется за время жизни клиента.

HeadersMiddleware

Заголовки, вычисляемые на каждый запрос:

php
use Flytachi\Winter\Cast\Middleware\HeadersMiddleware;

new HeadersMiddleware(fn(CastRequest $request) => [
  'X-Request-ID' => bin2hex(random_bytes(8)),
  'X-Signature'  => $signer->sign($request),
]);

new HeadersMiddleware([$signer, 'headersFor']);   // метод объекта

Заголовки ставятся поверх запроса: одноимённые заменяются.

RefreshTokenMiddleware

На ответ 401 получает новый токен и отправляет запрос ещё раз:

php
use Flytachi\Winter\Cast\Middleware\RefreshTokenMiddleware;

$client = $client
  ->withMiddleware(new RefreshTokenMiddleware(fn() => $tokens->refresh()))
  ->withMiddleware(AuthMiddleware::bearer(fn() => $tokens->current()));
  • функция получает ответ 401 и возвращает новый токен или null, если его нет — тогда возвращается 401;
  • запрос повторяется со всеми заголовками и телом; тело, которое нельзя перемотать, повторно не отправляется;
  • maxRetries (по умолчанию 1) — сколько раз пробовать обновить токен;
  • сохранить токен для следующих запросов — задача вашего хранилища, как в примере выше.

Свой лог

Логгер клиента пишет одну строку на запрос (см. Интеграцию с Winter). Нужен свой формат — это несколько строк middleware:

php
$client = $client->withMiddleware(function (CastRequest $request, callable $next) use ($logger) {
  $response = $next($request);
  $logger->info(sprintf(
      '%s %s → %d за %.3f с (%d попыток)',
      $request->getMethod(),
      $request->getUri()->getHost(),
      $response->getStatusCode(),
      $response->info()->totalTime,
      $response->info()->attempts,
  ));

  return $response;
});