プラグイン設定 API リファレンス

1. 目的と位置づけ

• 本ページは fandhe-backend の各プラグイン（crates/plugin-*）の feature 名・登録方法・Config 型・既定値・注意点を一覧化するリファレンスである
• 一次情報源は各クレートの rustdoc（crates/plugin-*/src/lib.rs ほかの doc comment・doc test）であり、本ページは横断比較と契約の要約を担う
• 登録先 Server の全体像は サーバ API、配線パターンの設計判断は docs/design/plugin-boundary.md（<https://github.com/Fandhe-AI/fandhe-backend/blob/main/docs/design/plugin-boundary.md>）を参照
• curl 例を含む使い方の詳細は feature 構成別サンプル を参照し、本ページでは重複させない

全プラグイン対応早見表

• feature はすべて fandhe-backend-core の Cargo feature（hub-wiring を除く）。無効時は依存・コード・バイナリ増がゼロになる（pay-for-what-you-use）
• いずれも登録時のみ動作する opt-in。feature 有効でも未登録ならフォールスルーし、既定挙動を変えない

2. プラグイン別リファレンス

2.1 plugin-websocket（websocket）

RFC 6455 ハンドシェイク検証・101 応答・tokio-tungstenite へのフレーミング委譲。

• 型エイリアス: fandhe_backend_plugin_websocket::BoxFuture<'a, T> は futures_util::future::BoxFuture と同一の型。利用者は futures-util を直接依存に加えずに on_message 等の戻り値型を書ける
• 注意: 受信メッセージ/フレームが max_message_size / max_frame_size を超えた場合は、Close フレーム（close code 1009 Message Too Big）を送出してから閉じる。frame 上限超過では送信途中の巨大 payload により Close が RST で失われないよう、生ストリームの半閉鎖 + 有界な読み捨て（無通信 2 秒の打ち切りと、トリクラー対策の総上限 3 秒または close_grace 残り期限の短い方）を行う。戻り値は従来どおり Err(WsError::Protocol(Capacity))
• 注意: ハンドラが WsOutcome::Close を返すと送信キューを封鎖し、キュー済み push を Close より先に送出する（以後の send は Err。flush と Close は全体で close_grace が上限で、超過・世代キャンセル・送出失敗では残りと Close を送らない）。ハンドラが Err を返した場合も、封鎖してから close_grace を上限に排出して終了し、封鎖前に確定した WsSender::close があれば on_close の理由は SenderClose になる。WsOutcome::Reply 後の排出は容量回までに制限される
• 注意: サイズ上限はメモリ枯渇 DoS 対策。アイドルタイムアウトは既定で有効（fail-safe）であり、無効化は without_idle_timeout の明示操作でのみ可能
• 注意: close_grace（with_close_grace）はコアの世代キャンセル（最終 graceful shutdown・rebind 世代 drain）発火時の Close ハンドシェイク猶予。fandhe_backend_plugin_websocket::handle_upgrade の第 5 引数（キャンセル Future）が発火すると close code 1001 Going Away を送出し、close_grace を上限にクライアント応答を有界に待つ（v0.3.0 での BREAKING CHANGE）。接続元アドレスを渡したい呼び出し元は、同じ 5 引数 + peer_addr（6 番目）を取る handle_upgrade_with_peer_addr を使う（既存 handle_upgrade は peer_addr: None で本関数へ委譲する後方互換の薄いラッパー）。WsMessageHandler::on_message / on_message_with_ctx が返す Future は任意の await 点で drop されうる契約（docs/design/ws-cancellation-propagation.md）
• 注意: WsConnId はサーバー側の単調カウンタ発行（unsafe 不使用・クライアント入力から独立）でプロセス内一意。値は推測可能なため認可トークン・セッション秘密として使ってはならない（識別子であって資格情報ではない）
• 注意: on_message_with_ctx（on_message にも適用）実行中も WsSender::send の送信キュー（設定された容量、既定 8）を cancel（最優先）→ (ハンドラ完了 | outbound 到着) の順で消化するため、ハンドラ内（ctx.sender() 経由）から容量を超える回数 send(...).await してもデッドロックしない。排出ステップ開始時点で既に到着済みの push は、cancel・送出失敗・close 要求後の close_grace 超過で打ち切られない限り、そのハンドラが返す WsOutcome::Reply/Close より先に送出される（それ以外の push との相対順序は不定）。詳細契約は crates/plugin-websocket/src/session.rs モジュール doc「ハンドラ実行中の送信キュー消化」節・docs/design/ ws-connection-context-and-close.md 6 節を参照
• 注意（デッドロック）: WsSender::closed() を on_message / on_message_with_ctx の実装内でインライン await してはならない。ハンドラ実行中はセッションループがクライアントの受信ストリームを読まないため、受信側 Receiver はハンドラが返るまで drop されず自己デッドロックになる（世代キャンセル発火時のみ解除される）。on_open 等から tokio::spawn した別タスクでのみ使うこと
• 注意（idle_timeout と Ping keepalive の併用。設計判断は docs/design/ws-connection-context-and-close.md 14 節参照）: idle_timeout はクライアントからのフレーム受信でのみリセットされ、WsSender::send/try_send による push・with_ping_interval によるサーバー起点 Ping 送出では延長されない。push だけを受けている受信専用クライアントも死活監視したい場合は with_ping_interval を併用し、interval + pong_timeout を idle_timeout より小さく設定することを推奨する（例: 既定 60 秒に対し with_ping_interval(30s, 10s)）。Pong の受信は他の全フレーム種別と同じく idle_timeout もリセットするため、生存クライアントは Ping への Pong で切断されず、Pong を返さない対向は idle_timeout より先に CloseReason::PongTimeout で切断される（早い方のタイマーが勝つ契約）。逆に interval を idle_timeout 以上にすると、最初の Ping が送られる前に idle_timeout が発火してしまう誤設定になるため避ける。検証は crates/plugin-websocket/tests/idle_keepalive_e2e.rs

2.2 plugin-graphql（graphql）

POST /graphql（GRAPHQL_PATH 定数）のパスインターセプト。async-graphql による実クエリ実行。

• 注意: クエリ深さ・複雑度制限（Schema::limit_depth / limit_complexity）と introspection 無効化（Schema::disable_introspection）はスキーマ登録者の責務
• 不正な body は 400 + 固定エラー body（リクエスト由来の値を一切エコーしない）。未登録時は feature 有効でもフォールスルー

2.3 plugin-openapi（openapi）

GET /openapi.json / GET /openapi.yaml の静的サービング（明示登録時のみ）。

• 注意: openapi() と openapi_with() は排他ではなく後勝ち（最後に呼んだ方の登録が残る）。YAML 変換依存は開発用 gen-cli feature に閉じ、サーバ経路には現れない

2.4 plugin-cors（cors）

実リクエスト応答への CORS ヘッダ付与（レスポンス後処理型）+ プリフライト応答関数の 2 点構成。外部依存ゼロ。

• 注意: オリジン照合はバイト完全一致でありワイルドカード部分一致はない。ヘッダ付与に失敗した場合は当該ヘッダを付与しない側へ倒す（フェイルクローズ）

2.5 plugin-compression（compression）

条件充足レスポンスの gzip 圧縮（レスポンス後処理型の第 2 インスタンス、CORS の後に逐次適用）。外部依存は flate2（純 Rust の rust_backend）のみ。

• 注意: gzip のみ（br はスコープ外）。秘密情報とリクエスト反映値を同一圧縮 body に同居させると BREACH 類似の情報漏洩リスクがある（rustdoc に明記）

2.6 plugin-static（static）

GET の静的ファイル配信（パスインターセプト型 + spawn_blocking 変種）。外部依存ゼロ（fandhe-backend-http + tokio の rt feature のみ）。

• 注意: 二層防御（I/O 前の字句検証 + canonicalize 後の root 配下検証）でパストラバーサル・シンボリックリンク脱出を拒否。先頭ドットセグメント（.env・.git/config 等）も配信拒否。未検出・検証失敗・サイズ超過は一律 404（存在秘匿）

2.7 plugin-tracing（tracing）

サンプリング付きトレーシング（Middleware 型の第 1 号）。決定的カウンタ方式 + 非同期・バッファ済み I/O。

• 注意: exclude_paths はクエリ除去後パスとの完全一致のみ（プレフィックス・glob 非対応。ログ抑制範囲の意図しない拡大を防ぐ安全側の設計）。除外パスはサンプラーのカウンタも消費しない

2.8 plugin-webrtc-proxy（webrtc-proxy）

WebRTC シグナリングの別プロセス切り出し型プロキシ。POST /rtc/offer（OFFER_PATH 定数）を upstream へ委譲する。攻撃表面をプロセス境界で分離でき、MVP 推奨。

• 注意: offer / answer 双方向にサイズ上限を持つ（upstream 応答の肥大もフェイルクローズで遮断）。webrtc feature と同時有効時は webrtc-proxy が優先評価される

2.9 plugin-webrtc（webrtc）

in-process WebRTC（webrtc-rs 直接依存）。POST /rtc/offer を同一プロセス内で処理する。

• 注意: webrtc-rs の依存ツリーが大きく攻撃表面が広いため、クレート境界で完全分離されている。まず plugin-webrtc-proxy の採用を検討すること
• 注意: close_active_peers / drain_for_shutdown はいずれも WebRtcConfig::registry 上のアクティブな RTCPeerConnection を 1 接続あたり per_close_timeout の有界タイムアウトで並行に明示 close する。drain_for_shutdown のみ WebRtcConfig::begin_terminal_drain で以降の新規登録を拒否するフェイルクローズ判定を伴う（close_active_peers は rebind 用途を想定し新規登録は拒否しない）。コアの SessionDrain（webrtc feature ゲート、独立シーム）が最終 graceful shutdown・rebind の両経路から自動でこれらを呼ぶため、通常は利用側が直接呼ぶ必要はない（docs/design/ws-cancellation-propagation.md 10 節を参照）

2.10 plugin-hub-wiring（feature なし・依存逆転型）

hub 共通配線（JWT RS256 / JWKS / テナント境界強制・同意ゲート・outbox・監査）。他プラグインと異なりコア側 feature を持たず、利用側サービスが本クレートを依存に追加してコアの RequestGate 拡張点へ登録する（プラグイン → コアの一方向依存）。

• 注意: 検証失敗はキャッシュしない（キャッシュ汚染防止）。各型の詳細契約は rustdoc（crates/plugin-hub-wiring/src/{gate,auth,jwks,consent,outbox,audit}.rs）を参照

3. 契約・不変条件（横断）

• opt-in 契約: すべてのプラグインは feature 有効化 + Server::xxx(...) 登録の 2 段階が揃って初めて動作する。未登録時のリクエスト挙動は feature 無効時と同一
• 構築時検証（フェイルクローズ）: 不正設定は実行時ではなく構築時に Result で拒否する（CorsConfigError / StaticConfigError / OpenApiDocError）。実行時に初めて失敗する経路を作らない
• DoS 上限内蔵: サイズ・接続数・タイムアウトの上限は既定で有効。無効化・緩和は明示操作のみ
• レスポンス後処理の適用順: finalize_response シームで CORS → compression の順に逐次適用される

4. セキュリティ観点

5. スコープ外・関連ドキュメント

• スコープ外: 各プラグインのプロトコル仕様詳細（RFC 6455 / GraphQL over HTTP / SDP 等）、curl での動作確認手順（feature 構成別サンプル）、hub-wiring の JWT / JWKS / outbox の詳細契約（rustdoc）、TLS 終端・multipart（v1 スコープ外。docs/design/v1-scope-tls-multipart.md）
• Server 本体の設定（接続数・body 上限・タイムアウト・graceful shutdown）: サーバ API、graceful shutdown ガイド
• ルーティングとの接続（options_fallback / パスインターセプトの前提）: ルーティング API
• 拡張点の契約（Middleware / UpgradeHandler / RequestGate）: 拡張 API、拡張点ガイド
• 配線パターンの設計判断・境界検証: docs/design/plugin-boundary.md（<https://github.com/Fandhe-AI/fandhe-backend/blob/main/docs/design/plugin-boundary.md>）
• 入門: Getting Started、チュートリアル