HTTPミドルウェア

HTTPミドルウェアは、エンドポイントのメタデータが付与される前、またはルートによってパラメータとエンドポイントIDが提供された後の、2つのルーターチェーンのいずれかで実行されます。

分類：ミドルウェアリファレンス。 各YAMLブロックはルーターの断片です。指定したミドルウェアが登録済みであり、参照するトークンストア、ファイルシステム、エンドポイント、アクター、ポリシーの各エントリが存在することを前提としています。

ミドルウェアの仕組み

各ミドルウェアはオプションマップを受け取り、ハンドラのラッパーを返します：

middleware:
  - cors
  - ratelimit
options:
  cors.allow.origins: "https://example.com"
  ratelimit.requests: "100"

オプションにはmiddleware_name.option.name形式のドット記法を使用します。後方互換性のため、従来のアンダースコア形式もサポートされています。

プリハンドラとマッチ後

middleware:        # Before endpoint metadata
  - cors
  - compress
options:
  cors.allow.origins: "*"

post_middleware:   # Post-match
  - endpoint_firewall
post_options:
  endpoint_firewall.action: "access"

利用可能なミドルウェア

CORS {#cors}

プリハンドラ

ブラウザリクエスト向けのCross-Origin Resource Sharingです。

middleware:
  - cors
options:
  cors.allow.origins: "https://app.example.com"
  cors.allow.credentials: "true"

OPTIONSプリフライトリクエストは自動的に処理されます。

レート制限 {#ratelimit}

プリハンドラ

キー単位で追跡するトークンバケット方式のレート制限です。

middleware:
  - ratelimit
options:
  ratelimit.requests: "100"
  ratelimit.window: "1m"
  ratelimit.key: "ip"

キー戦略： ip、header:X-API-Key、query:api_key

429 Too Many Requestsをヘッダー付きで返します：X-RateLimit-Limit、X-RateLimit-Window。

圧縮 {#compress}

プリハンドラ

レスポンスをGzip圧縮します。

middleware:
  - compress
options:
  compress.level: "default"
  compress.min.length: "1024"

クライアントがAccept-Encoding: gzipを送信した場合にのみ圧縮します。

実クライアントIP {#real_ip}

プリハンドラ

プロキシヘッダーからクライアントIPを抽出します。

middleware:
  - real_ip
options:
  real_ip.trusted.subnets: "10.0.0.0/8,172.16.0.0/12"

ヘッダーの優先順位： True-Client-IP > X-Real-IP > X-Forwarded-For

トークン認証 {#token_auth}

プリハンドラ

トークンベースの認証です。トークンストアの設定についてはセキュリティを参照してください。

middleware:
  - token_auth
options:
  token_auth.store: "app:tokens"

後続ミドルウェア向けに、コンテキストへアクターとセキュリティスコープを設定します。リクエスト自体は拒否しません。認可はファイアウォールミドルウェアで行われます。

メトリクス {#metrics}

プリハンドラ

Prometheus形式のHTTPメトリクスです。このミドルウェアは、メトリクスコレクターが利用できる場合にのみ登録され、設定オプションはありません。

middleware:
  - metrics

エンドポイントファイアウォール {#endpoint_firewall}

マッチ後

一致したエンドポイントに基づく認可です。リクエストコンテキストにアクターとセキュリティスコープが必要です。token_authは、それらを提供する方法の1つです。

post_middleware:
  - endpoint_firewall
post_options:
  endpoint_firewall.action: "access"

アクターがない場合は401 Unauthorized、権限がない場合は403 Forbiddenを返します。

リソースファイアウォール {#resource_firewall}

マッチ後

特定のリソースをIDで保護します。ルーターレベルでの使用に適しています。

post_middleware:
  - resource_firewall
post_options:
  resource_firewall.action: "admin"
  resource_firewall.target: "app:admin-panel"

Sendfile {#sendfile}

プリハンドラ

ハンドラからX-Sendfileヘッダーを使用してファイルを配信します。

middleware:
  - sendfile
options:
  sendfile.fs: "app:downloads"

ハンドラは、ファイル配信を開始するために次のヘッダーを設定します：

再開可能なダウンロードのため、範囲リクエストをサポートしています。

WebSocketリレー {#websocket_relay}

マッチ後

WebSocket接続をプロセスへ中継します。WebSocketリレーを参照してください。

post_middleware:
  - websocket_relay
post_options:
  wsrelay.allowed.origins: "https://app.example.com"

SSEリレー {#sse_relay}

マッチ後

プロセスからServer-Sent Eventsをストリーミングします。Server-Sent Eventsを参照してください。

post_middleware:
  - sse_relay
post_options:
  sserelay.allowed.origins: "https://app.example.com"

OpenTelemetry {#otel}

プリハンドラ

受信リクエストのOpenTelemetryサーバースパンを記録します。常に登録され、OTelまたはそのHTTP計装が無効な場合はno-opとして動作します。

middleware:
  - otel

オプションはありません。metricsミドルウェアと併用できます。PrometheusカウンターとOTelトレースの両方が必要な場合は、両方を有効にしてください。

ミドルウェアの順序

リクエストでは、ミドルウェアは記載順に実行されます。レスポンス処理は逆順に戻ります。推奨される順序：

middleware:
  - real_ip       # 1. Extract real IP first
  - cors          # 2. Handle CORS preflight
  - compress      # 3. Set up response compression
  - ratelimit     # 4. Check rate limits
  - metrics       # 5. Record metrics
  - token_auth    # 6. Authenticate requests

post_middleware:
  - endpoint_firewall  # Authorize after route match

関連項目

• ルーティング - ルーター設定
• セキュリティ - トークンストアとポリシー
• WebSocketリレー - WebSocket処理
• Server-Sent Events - SSEストリーミング
• ターミナル - ターミナルサービス