rust-web

Rust HTTP サービスの提供

HTTP コントラクトとランタイムライフサイクルに基づいて、サーバーサイドの HTTP API を提供します。フレームワークはトランスポート層への適応を担い、ドメインロジックとデータアクセスは、バックエンドに関するあらゆる問題をハンドラーに埋め込むことなく、独立してテストできる状態に保ちます。

サービスコントラクトの確認

変更前に、OpenAPI 仕様、既存のルート、クライアント、テスト、設定、実行環境を確認します。

• メソッド、パス、ステータスコード、リクエスト／レスポンスのスキーマ、互換性の方針；
• 認証コンテキストの取得元（認証システムの設計はこのスキルの対象外です）；
• リクエストボディ、同時実行数の上限、タイムアウト、アップロードサイズ、レスポンスサイズの制約；
• 外部 HTTP サービス、データベース、キャッシュ、キューへの依存関係と、障害発生時の動作；
• リッスンアドレス、プロキシ、TLS 終端、ヘルスチェック、グレースフルシャットダウンの猶予時間；
• ロックされた依存関係における axum、Tokio、Tower、および関連クレートの Rust/MSRV バージョン；
• ログレベル、トレーシング設定、メトリクスの公開、機密フィールドの取り扱い、データ保持ポリシー。

既存のクライアントライブラリにおけるレスポンスフィールドは、互換性に関する制約となります。コントラクトが存在しない場合は、まず最小限の前提を明示します。

ワークフロー

1. 現在のベースラインを確認する

rustc --version --verbose
cargo metadata --format-version 1
cargo tree -e features
cargo test --all-targets

サービスのエントリーポイント、ルーターの構成、状態管理、エラー型、ミドルウェアの順序、シャットダウンシグナル、テストツールを確認します。Cargo.lock に記載されたバージョンと公式ドキュメントを厳守し、バージョンごとの仕様ではなく記憶に基づいて axum/Tower の API を混在させないでください。

2. トランスポート境界を定義する

推奨される呼び出しフロー：

HTTP request
  -> router / extractor / transport validation
  -> application service / use case
  -> repository or outbound HTTP port
  -> domain result/error
  -> centralized HTTP response mapping

• ハンドラーは値の抽出とトランスポート層の検証を行い、ユースケースを呼び出してレスポンスをマッピングします；
• ドメインロジックは axum のリクエスト／レスポンス型に依存しません；
• データベース接続プールと HTTP クライアントは、サービス層内の状態を持つ依存関係として扱います。ビジネスデータをグローバルロックに保存しないでください。
• トランザクションはユースケース／データアクセスの境界に置き、ハンドラー内に散在させて制御しないでください。
• DTO、ドメインモデル、永続化モデルは、変更理由に応じて分離し、制御されない構造体の意図しない再利用を避けてください。

具体的なレイヤリングやアダプターの要件を判断する際は、サービス境界を参照してください。

3. ルーティングと入力境界を実装する

• ルートパス、エクストラクター、レスポンス型は、ロックされた axum のバージョンに準拠させます；
• パスパラメーター、クエリ文字列、ヘッダー、リクエストボディを明示的に検証し、構文エラーとドメイン上の競合を区別します；
• リクエストボディサイズ、アップロード、ページネーション、バッチサイズに上限を設けます；
• ロックを保持した状態で .await をまたがないでください。共有可変状態は、専用のサービスまたはストレージ機構に委譲することを優先します。
• リクエスト処理、ネットワークアクセス、データベースクエリ、シリアライズの失敗処理に unwrap()／expect() を使用しないでください。代わりに、表現できない前提条件を型レベルのチェックに変換し、複数のハンドラーにまたがる重複を避ける一元的な検証を行います。

4. エラーレスポンスのマッピングを統一する

アプリケーションエラーから HTTP レスポンスへのマッピングを一元的に定義します。

• 検証エラー → クライアント側で修正可能な 4xx ステータスコード；
• 見つからない場合、競合、権限拒否 → 404、409、403 など、安定したクライアントエラーステータス；
• 下流サービスの利用不能、タイムアウト、内部の不具合 → 内部の詳細を漏らさない 5xx ステータスコード。

各エラーレスポンスには、相関付けに使用する安定した機械可読コードとリクエスト／トレーシング識別子を含める必要があります。エラーの全チェーンは管理されたログに記録し、レスポンスに SQL クエリ、トークン、ファイルパス、バックトレースを含めないでください。すべてのエラーを 500 にマッピングしたり、200 を返して失敗を隠したりしないでください。

5. ミドルウェアの合成とセキュリティ境界

実際の呼び出し順に従って、Tower のミドルウェア層を確認します。

• リクエスト ID とトレース識別子は保持しながら、機密性の高いヘッダーを秘匿します。
• グローバルタイムアウトと下流のタイムアウトを設定します。
• リクエストボディのサイズ制限と、同時実行数／負荷保護対策を適用します。
• 適切な箇所で認証コンテキストと認可チェックを統合します。
• CORS の許可リストを厳密に管理します。サービスチェーンに認証情報が含まれる場合、デフォルトで許容的なポリシーを設定しないでください。
• 圧縮に伴う CPU コストと、圧縮ヘッダーによって機密性の高いレスポンスが漏えいするリスクを考慮します。
• 明示的に管理された送信元からのプロキシヘッダーのみを信頼します。

ミドルウェアの順序、タイムアウト設定、グレースフルシャットダウン戦略については、ミドルウェアとライフサイクルに記載されています。

6. 非同期ライフサイクルの管理

• サーバー、外部リクエスト、データベース操作に対する階層的なタイムアウトを設定します。
• キャンセルが下位へ伝播してサブタスクをクリーンアップし、リクエストのライフタイムから切り離されたタスクがリークしないようにします。
• 新しい受信リクエストを停止し、予算の範囲内で処理中のリクエストを完了させてからリソースを解放し、グレースフルにシャットダウンします。
• 再試行不可のエラーと再試行可能なエラーを区別します。再試行には、予算、バックオフ戦略、冪等性の保証が必要です。
• Tokio のタスク、チャネル、Send／Sync、キャンセルセーフティ、ロックのスコープに関する詳細な設計は、$rust-concurrencyに委ねます。

7. 外部アダプターアクセスの制限

このスキルは、データベースや外部 HTTP クライアントを必要とするサービスと統合できますが、サーバー側の境界のみを対象とします。

• リクエストごとに新しい接続プールやクライアントインスタンスを作成せず、再利用します。
• 下流コンポーネント向けにタイムアウト、接続数の上限、観測可能なエラー報告を設定します。
• 不必要な外部ネットワーク待機を避けつつ、ユースケース全体をトランザクションでカバーします。
• スキーママイグレーション、インデックス、トランザクション、SQL チューニング、ORM モデリングは、$rust-databaseに委ねます。
• 独立した SDK、クローラー、大量処理用 HTTP クライアントは、サーバー側のメインフローには含まれません。これらは別のツーリング領域に属します。
• JWT／OAuth フロー、セッション、トークン、CORS／CSRF ポリシー、シークレット管理は、$rust-web-securityに委ねます。このスキルでは、検証済みの送信元からプリンシパルの識別情報と認可結果のみを受け取ります。
• WebSocket のアップグレード、メッセージプロトコル、ハートビート機構、バックプレッシャー処理は、明示的に要求された場合に独立したサブフローとして処理します。

8. レイヤー別のサービステスト

次の項目を網羅します。

1. ドメイン／ユースケースの純粋なテスト。
2. ユースケースごとに、実際のポートにバインドせずに行うルーターレベルのリクエストテスト。
3. エクストラクターの失敗、エラーマッピングロジック、ボディサイズ制限、タイムアウト、認証境界。
4. 外部アダプターのコントラクト検証と障害注入シナリオ。
5. 実際のデータベースが必要な場合の、分離されたデータベースマイグレーション、コミット、ロールバック。
6. リスニング動作、プロキシ設定、グレースフルシャットダウンの挙動を検証する、対象を絞ったソケットテスト。

詳細なテストマトリクスは、HTTP サービスのテストに記載されています。テストの構成、カバレッジ目標、CI ゲートのポリシー、パフォーマンスのベースラインは、rust-testingの管轄です。

共通ゲート

cargo fmt --all -- --check
cargo check --all-targets
cargo test --all-targets
cargo clippy --all-targets -- -D warnings

プロジェクトに応じて、OpenAPI／スキーマ互換性チェック、統合環境テスト、セキュリティスキャンを追加します。依存関係に基づくテストの失敗を黙ってスキップし、全体が合格したと見せかけないでください。

完了基準

• HTTP コントラクト、バージョニングに関する前提、互換性の保証が明確であること。
• ハンドラーは薄いまま保ち、ドメインロジックと外部アダプターを個別にテストできること。
• エラー処理、ステータスコード、タイムアウト、ミドルウェアの順序、グレースフルシャットダウンの動作に対応するテストがあること。
• ログやレスポンスから秘密情報や内部の詳細が漏えいしないこと。
• cargo fmt、cargo check、cargo test、clippy が正常に完了すること。
• 実際のデータベース、ネットワーク、TLS 接続、デプロイが検証されていない場合、残る境界を明示すること。

引き継ぎの境界

主な課題	担当範囲
スキーマ定義、マイグレーション、トランザクション、接続プール、SQL／ORM モデリング	rust-database
認証、認可、セッション／トークン、CORS／CSRF ポリシー、SSRF 保護	rust-web-security
Tokio タスク、ロック、チャネル、キャンセル安全性、グレースフルシャットダウンの実装	rust-concurrency
テストの階層化戦略、カバレッジ目標、属性テスト、パフォーマンスのベースライン	rust-testing
所有権のセマンティクス、serde の型コントラクト、汎用エラー設計のパターン	rust-stable
機能、ワークスペース設定、ビルドスクリプト、リリースパイプライン	rust-cargo-build
安全でないネットワークライブラリ、C ABI インターフェース、生バッファーの処理	rust-unsafe-ffi

必要に応じて参照するリソース

• サービスの境界：ハンドラー、状態管理、データ構造、外部 HTTP アダプターを設計する際に参照します。
• ミドルウェアとライフサイクル：Tower の設定、タイムアウトポリシー、CORS ルール、ロードバランシング戦略、グレースフルシャットダウンのロジックを確認する際に参照します。
• HTTP サービスのテスト：ルーターの統合、エンドツーエンドテスト、障害注入シナリオの設計パターンを参照します。
• 例：必要に応じて、エンドツーエンドのタスク分解にテンプレートを使用します。
• examples/golden-handler/：トランスポート境界の動作とエラーマッピングのロジックをオフラインでコンパイル、検証します。

参考資料

• Rust ネットワーキング
• axum のドキュメント
• Tokio のドキュメント
• Tower のドキュメント
• Serde