HTTPミドルウェア

ミドルウェアはルート処理の前後にHTTPリクエストを処理します。

ミドルウェアの仕組み

ミドルウェアはHTTPハンドラをラップして処理ロジックを追加します。各ミドルウェアはオプションマップを受け取り、ハンドララッパーを返します：

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

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

マッチ前 vs マッチ後

マッチ前はルートマッチング前に実行—CORSや圧縮などの横断的な関心事に。 マッチ後はルートがマッチした後に実行—ルート情報が必要な認可に。 
middleware:        # マッチ前
  - cors
  - compress
options:
  cors.allow.origins: "*"

post_middleware:   # マッチ後
  - 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"
オプション デフォルト 説明
cors.allow.origins * 許可するオリジン（カンマ区切り、*.example.comをサポート）
cors.allow.methods GET,POST,PUT,DELETE,OPTIONS,PATCH 許可するメソッド
cors.allow.headers Origin,Content-Type,Accept,Authorization,X-Requested-With 許可するリクエストヘッダー
cors.expose.headers - クライアントに公開するヘッダー
cors.allow.credentials false Cookie/認証を許可
cors.max.age 86400 プリフライトキャッシュ（秒）
cors.allow.private.network false プライベートネットワークアクセス

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

レート制限 {#ratelimit}

マッチ前

キーごとの追跡を持つトークンバケットレート制限。

middleware:
  - ratelimit
options:
  ratelimit.requests: "100"
  ratelimit.window: "1m"
  ratelimit.key: "ip"
オプション デフォルト 説明
ratelimit.requests 100 ウィンドウごとのリクエスト数
ratelimit.window 1m 時間ウィンドウ
ratelimit.burst 20 バースト容量
ratelimit.key ip キー戦略
ratelimit.cleanup_interval 5m クリーンアップ頻度
ratelimit.entry_ttl 10m エントリ有効期限
ratelimit.max_entries 100000 追跡する最大キー数

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

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

圧縮 {#compress}

マッチ前

レスポンスのGzip圧縮。

middleware:
  - compress
options:
  compress.level: "default"
  compress.min.length: "1024"
オプション デフォルト 説明
compress.level default fastest、default、またはbest
compress.min.length 1024 最小レスポンスサイズ（バイト）

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

Real IP {#real_ip}

マッチ前

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

middleware:
  - real_ip
options:
  real_ip.trusted.subnets: "10.0.0.0/8,172.16.0.0/12"
オプション デフォルト 説明
real_ip.trusted.subnets プライベートネットワーク 信頼するプロキシCIDR
real_ip.trust_all false すべてのソースを信頼（安全でない）

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

トークン認証 {#token_auth}

マッチ前

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

middleware:
  - token_auth
options:
  token_auth.store: "app:tokens"
オプション デフォルト 説明
token_auth.store 必須 トークンストアレジストリID
token_auth.header.name Authorization ヘッダー名
token_auth.header.prefix Bearer ヘッダープレフィックス
token_auth.query.param x-auth-token クエリパラメータフォールバック
token_auth.cookie.name x-auth-token Cookieフォールバック

ダウンストリームミドルウェア用にコンテキストにアクターとセキュリティスコープを設定します。リクエストをブロックしません—認可はファイアウォールミドルウェアで行われます。

メトリクス {#metrics}

マッチ前

PrometheusスタイルのHTTPメトリクス。設定オプションはありません。

middleware:
  - metrics
メトリクス タイプ 説明
wippy_http_requests_total Counter 総リクエスト数
wippy_http_request_duration_seconds Histogram リクエストレイテンシー
wippy_http_requests_in_flight Gauge 同時リクエスト数

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

マッチ後

マッチしたエンドポイントに基づく認可。token_authからのアクターが必要。

post_middleware:
  - endpoint_firewall
post_options:
  endpoint_firewall.action: "access"
オプション デフォルト 説明
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"
オプション デフォルト 説明
resource_firewall.action access 権限アクション
resource_firewall.target 必須 リソースレジストリID

Sendfile {#sendfile}

マッチ前

ハンドラからのX-Sendfileヘッダー経由でファイルを配信。

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

ハンドラはファイル配信をトリガーするためにヘッダーを設定：

ヘッダー 説明
X-Sendfile ファイルシステム内のファイルパス
X-File-Name ダウンロードファイル名

再開可能なダウンロードのためのRangeリクエストをサポート。

WebSocketリレー {#websocket_relay}

マッチ後

WebSocket接続をプロセスにリレー。WebSocketリレーを参照。

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

ミドルウェアの順序

ミドルウェアはリストされた順序で実行されます。推奨される順序：

middleware:
  - real_ip       # 1. 最初にReal IPを抽出
  - cors          # 2. CORSプリフライトを処理
  - compress      # 3. レスポンス圧縮をセットアップ
  - ratelimit     # 4. レート制限をチェック
  - metrics       # 5. メトリクスを記録
  - token_auth    # 6. リクエストを認証

post_middleware:
  - endpoint_firewall  # ルートマッチ後に認可

関連項目