Crate fandhe_backend_core 

fandhe-backend の最小コア。

このクレートの役割

crates/core は HTTP/1.1 パーサ・keep-alive・3 種拡張点 （Middleware / UpgradeHandler / RequestGate、extension モジュール）を 実装する最小コアの置き場所。TASK-1.4-1（#69）で 3 拡張点の trait 定義を、 TASK-1.4-2（#70）でコアループ（接続受理・リクエストループ、server モジュール）による実接続を提供する。3 拡張点で表現できないリダイレクト・ レスポンス改変（interceptor::Interceptor、イシュー #420）は feature ゲート不要の追加拡張点として同モジュールに置く（詳細は interceptor を参照）。

workspace 内での依存方向

docs/spec/04-requirements.md REQ-1 / docs/spec/05-tasks.md TASK-1.5 の方針に従い、 workspace 全体の依存方向は次の一方向を維持する:

server → routes → http::*

core（本クレート）はこの依存グラフの末端に位置し、plugin-* の固有シンボルには 一切依存しない。プラグインは feature 経由でコアの拡張点（Middleware / UpgradeHandler / RequestGate）を実装する側であり、コアからプラグインへの 依存は発生しない（pay-for-what-you-use、.claude/rules/pay-for-what-you-use.md）。 fandhe-backend-http（sans-IO な HTTP/1.1 パーサ、TASK-1.3）は workspace 内の下位層クレート であり、外部 crates.io 依存はここでも増やさない。

crates/routes（fandhe-backend-routes）は TASK-1.5（#14）で新設し、server → routes エッジを Cargo.toml の依存宣言として実体化した。fandhe_backend_routes::Router は impl server::Handler for fandhe_backend_routes::Router により本クレートの 既定ハンドラとしてそのまま登録できる（crates/core/examples/minimal.rs 参照）。依存方向の機械検証は scripts/dep-direction-check.sh（TASK-1.5）が cargo metadata の依存エッジホワイトリスト照合で行う。

feature 一覧

• webrtc-proxy（TASK-2.1 / #18）: crates/plugin-webrtc-proxy を optional = true + dep: 構文で組み込み、[server::Server::webrtc_proxy] で登録した fandhe_backend_plugin_webrtc_proxy::ProxyConfig に基づき POST /rtc/offer をパスインターセプトする。無効時（既定）は依存・コード・ unsafe を一切含まない（クレート非公開の plugin モジュールの doc・ docs/design/plugin-boundary.md を参照）。
• webrtc（TASK-8.1 / #26）: crates/plugin-webrtc（in-process 型、 webrtc-rs 直接依存）を同じくプラグイン境界パターンで組み込み、 [server::Server::webrtc] で登録した fandhe_backend_plugin_webrtc::WebRtcConfig に 基づき POST /rtc/offer をパスインターセプトする。webrtc-proxy と 同時有効時は webrtc-proxy が優先される（plugin::try_intercept の doc）。無効時（既定）は依存・コード・unsafe を一切含まない。
• websocket（TASK-4.1 / #22）: crates/plugin-websocket を optional = true + dep: 構文で組み込み、[server::Server::websocket] で登録した fandhe_backend_plugin_websocket::WebSocketConfig の指すパス（既定 /ws）への GET + Upgrade: websocket を UpgradeHandler 拡張点経由で 検知し、fandhe_backend_plugin_websocket::handle_upgrade へ完全委譲する（RFC 6455 ハンドシェイク・フレーミングは crates/plugin-websocket 側の責務）。設定型 WebSocketConfig は [plugin_websocket] モジュールとして再エクスポートし （イシュー #435）、fandhe-backend-plugin-websocket へ直接依存せずに構築できる。 無効時（既定）は依存・コード・unsafe を一切含まない。
• graphql（TASK-2.4 / #21）: crates/plugin-graphql を組み込み、 [server::Server::graphql] へ渡す設定型 GraphQlConfig を [plugin_graphql] モジュールとして再エクスポートする（イシュー #435）。 利用者は fandhe-backend-plugin-graphql へ直接依存せずに fandhe_backend_core::plugin_graphql::GraphQlConfig を構築できる。 無効時（既定）は依存・コード・unsafe を一切含まない。
• cors（イシュー #305）: crates/plugin-cors を組み込み、 [server::Server::cors] へ渡す設定型 CorsConfig を [plugin_cors] モジュールとして再エクスポートする（イシュー #435）。 利用者は fandhe-backend-plugin-cors へ直接依存せずに fandhe_backend_core::plugin_cors::CorsConfig を構築できる。 無効時（既定）は依存・コード・unsafe を一切含まない。
• tracing（TASK-10.1 / #56）: crates/plugin-tracing を組み込み、 [server::Server::tracing] へ渡す設定型 TracingConfig を [plugin_tracing] モジュールとして再エクスポートする（イシュー #435）。 利用者は fandhe-backend-plugin-tracing へ直接依存せずに fandhe_backend_core::plugin_tracing::TracingConfig を構築できる。 無効時（既定）は依存・コード・unsafe を一切含まない。
• openapi（TASK-2.1 / #256）: crates/plugin-openapi を組み込み、 [server::Server::openapi_with] へ渡す設定型 OpenApiDoc を [plugin_openapi] モジュールとして再エクスポートする（イシュー #435）。 利用者は fandhe-backend-plugin-openapi へ直接依存せずに fandhe_backend_core::plugin_openapi::OpenApiDoc を構築できる。 無効時（既定）は依存・コード・unsafe を一切含まない。
• static（イシュー #318）: crates/plugin-static を組み込み、 [server::Server::static_files] へ渡す設定型 StaticFilesConfig を [plugin_static] モジュールとして再エクスポートする（イシュー #421）。 利用者は fandhe-backend-plugin-static へ直接依存せずに fandhe_backend_core::plugin_static::StaticFilesConfig を構築できる。 無効時（既定）は依存・コード・unsafe を一切含まない。
• compression（イシュー #321）: crates/plugin-compression を組み込み、 [server::Server::compression] へ渡す設定型 CompressionConfig を [plugin_compression] モジュールとして再エクスポートする（イシュー #421）。 利用者は fandhe-backend-plugin-compression へ直接依存せずに fandhe_backend_core::plugin_compression::CompressionConfig を構築できる。 無効時（既定）は依存・コード・unsafe を一切含まない。

webrtc / webrtc-proxy の設定型 WebRtcConfig / ProxyConfig も同様に それぞれ [plugin_webrtc] / [plugin_webrtc_proxy] モジュールとして 再エクスポートする（イシュー #435）。

今後のタスクとの対応

• TASK-2.1（#18）で確立したプラグイン境界パターン（feature flag + dep: 構文、cfg-free なコアループ + 固定シグネチャシーム）は非公開 plugin モジュールの try_intercept（パスインターセプト型）・ try_handle_upgrade（Upgrade 型、TASK-4.1 / #22 で実装）の 2 種として 実証済みであり、後続プラグインは docs/design/plugin-boundary.md の 適用手順に従って同パターンを踏襲する

クイックスタート（TASK-11.5 / #95、docs/guide/getting-started.md の裏取り）

Server に fandhe_backend_routes::Router を 1 件登録するだけで最小サーバが 組み立てられる。bind → run の流れは crates/core/examples/minimal.rs （cargo run --example minimal -p fandhe-backend-core で実行可能）と同一。 本 doc test は no_run（実際に listen はしない）だが cargo test --doc で コンパイル可能性を機械検証する（AI ファースト保守性、 .claude/rules/feature-modification.md の「実装にはテスト追加を伴う」）。

use fandhe_backend_core::Server;
use fandhe_backend_http::response::Response;
use fandhe_backend_routes::Router;

let router = Router::new().route("GET", "/", |_head, _body| {
    Response::new(200, b"hello\n".to_vec())
});

let server = Server::new().handler(router);
// 外部公開する場合は呼び出し側の責任でバインドアドレスを明示する
// （.claude/rules/security.md の攻撃表面最小化）。ここではループバック限定。
let bound = server.bind("127.0.0.1:3000").await?;
bound.run().await

プロセス終了を run() の kill に頼らず、accept 停止 → in-flight 完了待ち（上限時間・超過時強制クローズ）を伴って安全に停止したい場合は server::BoundServer::run_until（イシュー #313）を使う。run() は run_until への薄い委譲であり後方互換を維持する。利用例は crates/core/examples/graceful_shutdown.rs、設計判断は docs/design/graceful-shutdown.md を参照。

Re-exports

pub use extension::GateContext;

pub use extension::GateOutcome;

pub use extension::Middleware;

pub use extension::RequestGate;

pub use extension::UpgradeHandler;

pub use interceptor::Interceptor;

pub use diagnostics::DiagnosticEvent;

pub use diagnostics::Diagnostics;

pub use diagnostics::StderrDiagnostics;

pub use server::BoundServer;

pub use server::Handler;

pub use server::RebindHandle;

pub use server::Server;

pub use server::handle_connection;

pub use server::handle_connection_with_peer_addr;

pub use streaming::BodyWriter;

pub use streaming::StreamClosed;

pub use streaming::StreamingResponse;

Modules

diagnostics

ライブラリ内部の実行時診断を利用側で差し替え可能にする診断シンク （イシュー #720）。

extension

コアが公開する 3 種の拡張点（Middleware / UpgradeHandler / RequestGate）。

interceptor

ユーザー向けインターセプト・レスポンス改変拡張点 Interceptor（イシュー #420）。

server

コアループ（接続受理・リクエストループ）と 3 拡張点の実接続（TASK-1.4-2 / #70）。

streaming

レスポンス側 chunked ストリーミング送信の opt-in API（イシュー #319）。

Functions

version

このクレートのバージョン文字列を返す。