Rustの `Path::hash` の盲点と、高速化キャッシュが引き起こすクラッシュ

1. 概要

言語の標準ライブラリが提供するインターフェースは、そのドキュメントに記載された仕様（契約）を満たしている限り、内部実装がどうであれ正しいとされる。しかし、そのライブラリの「暗黙の内部挙動」と、アプリケーション側の「極限のパフォーマンス最適化」の設計が噛み合わなかったとき、極めてデバッグ困難なバグが発生することがある。本稿では、Rust製の超高速Python Linter/FormatterであるRuffで発生した、キャッシュキー衝突によるパニックバグ（astral-sh/ruff#12158）を事例に、標準ライブラリの Path::hash の盲点と、キャッシュ設計における防御的プログラミングの重要性について分析する。

2. インシデントの分析：異なるパスが同じキャッシュとして扱われる怪

2.1. 現象：特定のフォルダ構造で発生するクラッシュ

Ruffを使用する際、以下のような特定のパターンを持つ異なるディレクトリが存在する環境において、2回目の実行時にRuffがパニック（クラッシュ）する現象が報告された。

ディレクトリ構造:
- dir/prefixabc/pyproject.toml
- dir/prefix/abc/__init__.py
エラー内容: wrong package cache for file: expected 'dir/prefixabc', got 'dir/prefix/abc'

Ruffは処理の高速化のために lint 結果をファイル単位でディスクキャッシュに保存している。このエラーは、「処理中のファイル（prefixabc）」に対して「異なるファイル（prefix/abc）」のキャッシュが誤ってロードされ、パッケージ構造の整合性チェックに引っかかったことを示している。

2.2. 原因：`std::path::Path::hash` の盲点

なぜ異なるファイルのキャッシュが混同されたのか。その原因は、Ruffがキャッシュファイルを識別するためのハッシュ（CacheKey）の計算に、Rust標準ライブラリの std::path::Path に対する hash 実装を直接適用していたことにあった。

Rustの Path は、WindowsとUnixのセパレータ（\ と /）の違いを正規化して同一に扱うため、内部でパスをコンポーネント（要素）に分解してハッシュを計算する。しかし、このハッシュ実装には「コンポーネントの境界（セパレータ）」を区切るための目印（デリミタ）がハッシュ値の計算に反映されない（または不十分である）という盲点があった。この仕様により、以下の2つの全く異なるパスが、完全に同一のハッシュ値になってしまう。

dir/prefixabc (コンポーネント: ["dir", "prefixabc"])
dir/prefix/abc (コンポーネント: ["dir", "prefix", "abc"])

2.3. 「メモリ上のハッシュ」と「ディスク上のハッシュ」のギャップ

Rustの Hash トレイトが保証する契約は、「k1 == k2 ならば hash(k1) == hash(k2)」という一方向の等価性のみである。「ハッシュ値が同じなら元の値も等しい」ことは保証していない。

通常の HashMap<PathBuf, V> では、ハッシュ値が衝突しても、衝突後に k1 == k2 による厳密な等価性検証が行われるため、この挙動は問題にならない（単にわずかな性能低下が起きるだけである）。しかし、Ruffはキャッシュを高速に読み書きするため、ディスク上のキャッシュファイル名（あるいはインデックスキー）として、このハッシュ値そのものを直接使用していた。 値の完全一致検証を行わずにハッシュ値のみを信頼してファイルを取り出したため、標準ライブラリの仕様の隙間に落ち、異なるファイルのキャッシュをロードしてパニックを引き起こしたのである。

3. 実体験：ライブラリの「仕様通り」に騙される瞬間

開発者が標準ライブラリや定評のあるサードパーティライブラリを信頼してシステムを構築する際、この種の「仕様通りだが、自分たちのコンテキストでは罠になる」ケースには誰もが一度は遭遇する。

実体験エピソード: ある開発プロジェクトで、APIのリクエストデータを高速にキャッシュするために、リクエストオブジェクトをシリアライズせずに言語内蔵のオブジェクトハッシュ関数（例: Pythonの hash() や Javaの hashCode()）を使ってインデックスを構築していた。開発環境では全く問題がなかったが、本番環境で高負荷時に特定のパターン（例: 特定の文字シーケンスを含むユーザー名など）のリクエストが集中した際、ハッシュ値の衝突によって他人のデータやキャッシュが誤って返却されるという致命的なバグが発生した。「ハッシュマップで普段使っているから」という理由で、ハッシュ関数の同一性チェックなしにハッシュ値のみを一意なIDとして流用することは、言語を問わずプロフェッショナルが最も踏みがちな「認知の死角」である。

4. 解決策と設計的防衛策

Ruffの開発チームは、このバグに対して Path を直接ハッシュ化するのをやめ、パスを一度文字列に変換（.to_string_lossy()）してセパレータ文字が確実に含まれた状態でハッシュ化を行うように修正した。

rust

impl CacheKey for Path {
    #[inline]
    fn cache_key(&self, state: &mut CacheKeyHasher) {
        // Pathのコンポーネント分解ハッシュではなく、文字列としてハッシュすることで境界を保証する
        self.to_string_lossy().hash(&mut *state);
    }
}

4.1. キャッシュ・シグネチャにおける「防衛的ハッシュ」

ハッシュ値をディスクキャッシュや分散システムのキーとして使用する場合、以下の防衛的設計が求められる。

デリミタの強制: 構造体や複数のコンポーネントをハッシュする場合、要素間に必ず一意なデリミタ（例: \0 や /）を挟んで文字列化してからハッシュする。
暗号論的ハッシュの使用: パフォーマンスが許す限り、衝突確率が極めて低いハッシュアルゴリズム（SHA-256など）を使用し、さらにハッシュ衝突が起きた場合の整合性チェック（ファイルのメタデータや元のキーの比較）をバックストップとして必ず残す。

5. 結論

Ruffのキャッシュバグは、Rust標準ライブラリの正しい（仕様を満たした）挙動であっても、ハッシュ値のみに依存したストレージ設計においては致命的な不整合を引き起こすという優れた教訓を示している。「等価性検証のないハッシュ値の信頼」は、パフォーマンス重視のシステム設計において最も見落とされがちな盲点である。ライブラリの暗黙の振る舞いを疑い、ハッシュキーの計算には要素の境界を厳密に保証する防衛的設計を適用することこそが、堅牢な高速化インフラを構築するための鉄則である。

6. 参考文献 / 一次情報

ruff has some cache bug that causes crashes: astral-sh/ruff#12158
Path hashing behavior on Rust playground: rust-lang-playground#467c0f7aedcfbfb484c9ca1ec65ff406

Rustの Path::hash の盲点と、高速化キャッシュが引き起こすクラッシュ ​

1. 概要 ​

2. インシデントの分析：異なるパスが同じキャッシュとして扱われる怪 ​

2.1. 現象：特定のフォルダ構造で発生するクラッシュ ​

2.2. 原因：std::path::Path::hash の盲点 ​

2.3. 「メモリ上のハッシュ」と「ディスク上のハッシュ」のギャップ ​

3. 実体験：ライブラリの「仕様通り」に騙される瞬間 ​

4. 解決策と設計的防衛策 ​

4.1. キャッシュ・シグネチャにおける「防衛的ハッシュ」 ​

5. 結論 ​

6. 参考文献 / 一次情報 ​