rust-systems

Rust システム＆サービス

モダンなアプリケーション層の Rust（エディション 2024）を対象とします。CLI、Web サービス、ライブラリが含まれます。no_std／組み込みは対象外です。

作業ルール

• ライブラリではエラーのバリアントを保持し、アプリケーションの境界では運用上のコンテキストを追加します。
• 置き換えを書き込む前に、設定が存在しない場合と、ファイルを読み取れない場合や無効な場合を区別します。
• ブロッキング処理を非同期ワーカーから切り離し、キューと起動する処理数に上限を設け、シャットダウン時の動作を定義します。
• 変更を内部的なものとして扱う前に、エクスポートされたインターフェースを追跡し、インストール済みのランタイム機能を確認します。
• 並行テストでプロセス全体の状態を変更しないでください。実際のバイナリと、関連するフィーチャーの組み合わせをテストします。

Unsafe の規律

• デフォルトでは unsafe を使いません。clippy が警告した場合も、#[allow] を付けずにリファクタリングします。以下の #[expect] による回避策はここには適用されません。unsafe に関する指摘は注釈で済ませず、修正します。
• すべての unsafe ブロックの直前に、その不変条件がそれぞれ成り立つ理由を説明する // SAFETY: コメントを付けます。コメントがなければレビューで却下します。
• unsafe ブロックは最小限にします。モジュール境界で安全な抽象化で包み、モジュールを pub(crate) にします。
• unsafe または生ポインター演算を含むクレートでは miri（cargo +nightly miri test）を使います。最適化によって隠される UB を検出できます。
• ゼロコピーのパターンでは、手書きの transmute より bytemuck、zerocopy、bytes を優先します。
• エディション 2024 では環境変数への書き込みは unsafe です。書き込みは main 内で、ランタイムの開始前、またはスレッドが起動する前に限ります。 並行する getenv は UB です。OnceLock を使っても安全にはなりません。初回使用時に遅延して行われる LD_LIBRARY_PATH のような書き込みに注意し、起動時に実行するように移します。

規律

• まずシンプルさを優先します。変更は可能な限りシンプルにし、影響を与えるコードは最小限にします。
• 必要な箇所だけを変更し、PR で無関係な変更を避けます。
• 近道として #[allow(clippy::...)] を使わず、根本的な問題を修正します。抑制が本当に妥当な場合は、代わりに #[expect(clippy::lint_name, reason = "...")] を記述します。expect は lint が発生しなくなると警告するため、原因が解消された後も残っている抑制は、自らそのことを報告します。一方、allow はいつまでも黙って残ります。（expect には Rust 1.81 以降が必要です。エディション 2024 では最低バージョンもそれ以上になります。）
• トレイトやジェネリクスを追加する前に、3 か所以上で使われることを確認します。それ以外の場合は、具体的な型のほうが明確です。
• bool::then_some(x) は x を値として受け取ります。つまり、bool を確認する前に引数が評価されます。 条件と固定幅スライスを組み合わせたガードは、まさに条件で確認しようとした入力で panic を起こします。 (b.len() >= 19 && b[4] == b'-').then_some(&v[..19]) は、条件を未確定として報告するために書かれた関数内で、19 バイト未満の値を指定すると 101 で終了します。遅延評価される then(|| …) を使います。clippy はこの違いを警告しません。インデックス指定、スライス、unwrap、割り当てを行う引数を持つ then_some( を grep してください。関連事項：固定幅スライスはパースではありません。 &v[..19] は ASCII 以外の文字の途中でも panic を起こします。また、そのようなプレフィックスを辞書順で比較するとタイムゾーンオフセットが無視されるため、01:00+02:00 は 00:00Z より後に並びますが、実際には 1 時間前です。パースして正規化するか、拒否してください。

検証

• cargo fmt --all -- --check が差分ゼロで成功する
• cargo clippy --workspace --all-targets --all-features -- -D warnings が成功する
• cargo nextest run --workspace（または cargo test --workspace）が失敗ゼロで成功する
• nextest を使用する場合は、cargo test --doc --workspace も成功する。nextest は doctest を実行しません
• 本番環境に投入するクレートでは、cargo deny check が成功する（ライセンス、アドバイザリー、重複）
• 新たに unsafe を追加する場合は、必ず // SAFETY: コメントを付ける

タスク固有のリファレンス

該当する動作を実装またはレビューする前に、関連するリファレンスをお読みください。

• Cargo のセットアップ、ワークスペースの変更、パブリック API の到達可能性、ビルドプロファイル、または CI については、toolchain-and-interfaces.md を参照してください。
• エラー、所有権、解析の境界、Tokio、シャットダウン、または並行処理については、ownership-and-execution.md を参照してください。
• CLI／サービスのエントリーポイント、本番環境でのレジリエンス、テレメトリー、またはテストについては、applications-and-testing.md を参照してください。

該当するトピックに応じて、以下の既存の専門リファレンスも参照してください。

• macros-and-os-boundaries.md。
• rustdoc.md。
• build-profiles.md。
• performance.md。
• cli-tools.md。
• production-resilience.md。
• axum-service.md。
• observability.md。
• ci-pipeline.md。