photoncloud-monorepo/flaredb/advice.md

ざっくり結論

• Chainfireは、Raft＋RocksDB＋gRPC＋Gossip（SWIM/foca）で「etcd 風の分散KV＋Watch」を狙う設計。Rust のワークスペース分割もきれいで、API/ストレージ/ウォッチ/ゴシップ/ラフトがモジュール化されている。ただし**Raft の対外RPCがまだ未配線（in‑memory/ダミー）**で、本当の多ノードクラスタとしては未完成。単一ノードやプロセス内検証には十分使える段階。
• FlareDBは、PD（Placement Driver）＋TSO（単調増加タイムスタンプ）＋KV(Raw/CAS)＋Raftサービス＋リージョン/マルチラフトの下地＋Merkle（整合性検査の雛形）まで手が入っており、実験用の分散ストレージ最小系としてよくまとまっている。CI/テスト項目・Quickstart・検証スクリプトもあり、開発者体験が良い。実運用には、マルチラフトの完成度・レプリケーション/再配置・フォロワリード/線形化リード・トランザクションなど次の一歩が必要。

---

Chainfire：何ができていて、どこが足りないか

できていること（コードから確認できる実体）

• Rust Workspace でAPI/サーバ/ストレージ/ラフト/ゴシップ/ウォッチが分離。依存は openraft（Raft）・foca（SWIM Gossip）・rocksdb・tonic/prost（gRPC）に整理済み。
• Raft 設定は OpenRaft の典型値で初期化（心拍/選挙タイムアウト/スナップショット方針等）し、ユニットテストもあり。
• gRPC の KV / Watch / Cluster / （内部）Raft サービスを一つのTonicサーバに束ねて起動する作り。
• Watch は双方向ストリームで、内部のWatchRegistryとつながるちゃんとした実装。クライアント側の受信ハンドルも用意済み。
• RocksDB をCF分割で利用。スナップショットのビルド/適用テストあり（データ転送の下地）。

詰めが甘い/未完成な点（現状の制約）

• Raft RPCが未配線：RaftRpcClient は “gRPC実装を後で差す” 前提のトレイトのまま。ノード生成時も Dummy/In‑memory のクライアントが使われており、実ノード間通信になっていない。これだと単一プロセス内での検証はできるが、別プロセス/別ホストにまたぐクラスタは動かない。
• Raft用ポートの扱い：ログには Raft用アドレスを出しているが、実際のTonicサーバは APIアドレスでまとめて RaftService も公開している。ポート分離・セキュリティ/ネットワーク設計が未整理。
• クラスタメンバーシップ変更（joint consensus）や、線形化読み取り（ReadIndex）、スナップショット転送の堅牢化など、Raft運用の“本番ポイント”は未記述/未配線に見える（設計としてはOpenRaftが担保可能）。

今の実用性（どこで役に立つ？）

• 研究/検証・単一ノードのメタデータKVとしては十分。“etcd互換風のAPI＋Watch”の感触を掴むには良い。
• 本番クラスタやフェイルオーバを求める用途では、Raft RPC配線とメンバーシップ管理が入るまで待ちが必要。

短期で刺さる改善（着手順）

1. RaftのgRPCクライアントを internal_proto に基づいて実装し、RaftRpcClient に差し込む。
2. Raft用ポート分離：api_addr と raft_addr を別サーバで起動し、TLS/認証の下地も確保。
3. Gossip⇔Raft連携：focaでの生存監視をトリガに、メンバー自動追加/離脱をRaftのjoint‑consensusに流す。依存は既にワークスペースにある。
4. 線形化Read/ReadIndex実装、フォロワリード（許容するなら条件付き）を整理。
5. ウォッチの厳密な順序/Revision保証をStateMachineの適用と一体化（watch_txの結線）。
6. スナップショット転送の実戦投入（チャンク/再送/検証）。テストは下地あり。
7. メトリクス/トレース（Prometheus/OpenTelemetry）と障害注入テスト。
8. Docker/Helm/Flakeの梱包をCIに載せる。

---

FlareDB：何ができていて、どこが足りないか

できていること（コードから確認できる実体）

• PD＋TSO の独立プロセス。Quickstartに起動順とCLI操作（TSO/Raw Put/Get/CAS）が書かれており、User StoryのチェックリストにもTSO達成が明記。
• サーバ側サービス：KvRaw/KvCas/RaftService を同一 gRPC サーバで提供。
• PD連携のハートビート/再接続・リージョン更新ループの骨格がある（起動後に定期HB→失敗時は再接続、リージョン情報を同期）。
• Merkle（領域ハッシュの雛形）で後々のアンチエントロピー/整合性検査を意識。
• テストと仕様フォルダが豊富：レプリケーション/マルチリージョン/スプリット/整合性などのテスト群、spec・scripts で動作確認の導線がある。

詰めが甘い/未完成な点（現状の制約）

• マルチラフトの完成度：リージョン分割・再配置・投票者/ラーナ/学習者の遷移、PDのスケジューリング（リバランス/ホットキー対策）の“運用アルゴリズム”はこれから。ディレクトリやspecはあるが、本番相当の道具立ては未完成。
• リードパスの整理：強整合/フォロワリード/ReadIndexの選択や遅延観測の制御が未整備に見える。
• トランザクション（MVCC）：TSOはあるが、二相コミットや悲観/楽観制御、ロールバック/ロック解放の実働コードはこれから（CASはある）。
• 障害時挙動と耐久性：スナップショット/ログの回復・リージョンマージ・アンチエントロピー（Merkle駆動）のバックグラウンドジョブは雛形段階。

今の実用性

• 研究用途・PoC として**単一～少数ノードのKV（Raw/CAS）**を回し、PD/TSO連携やリージョンの概念を試すには充分。
• フル機能の分散トランザクショナルKV/SQL バックエンドを本番投入するには、マルチラフト/リージョン管理/トランザクション/可観測性などの整備が必要。

短期で刺さる改善（着手順）

1. マルチラフトの完成：リージョンスプリットのトリガ（サイズ/負荷）→新リージョンのRaft起動→PDのメタ更新→クライアントのRegion Cache更新をE2Eでつなぐ。テスト骨子は既にある。
2. フォロワリード/線形化Readの切替を導入（読み取りSLAと一貫性を両立）。
3. MVCC＋2PC：TSO を commit_ts/read_ts に使い、Prewrite/Commit（TiKV流） or OCC を追加。Quickstart のCASを土台に昇華。
4. Merkleベースのアンチエントロピー：バックグラウンドでリージョンのMerkle葉を比較し、差分レンジを修復。
5. PDのスケジューラ：移動コスト・ホットキー・障害隔離を考慮した配置。
6. メトリクス/トレース/プロファイリングとYCSB/Jepsen系テストで性能と安全性を可視化。

---

さらに高みへ（共通の設計指針）

1. 制御面（Chainfire）×データ面（FlareDB）の分業を明確化 Chainfire を“クラスタ制御の中枢”（ノードメタ/アロケーション/設定/ウォッチ）に、FlareDB を“データ平面”に寄せる。Gossipの生存情報→ChainfireのKV→FlareDB PDへの反映という単一路を敷くと運用が楽になる。

2. アドレス解決とメンバーシップの一元管理 ChainfireのCluster APIに Raft peer の BasicNode 情報を登録/取得する経路を作り、NetworkFactory がそこから動的にダイヤルできるようにする。現状はトレイトとFactoryが揃っているので配線だけで前進する。

3. 明示的なポート分離とゼロトラスト前提 Client API（KV/Watch）と Peer RPC（Raft）を分離配信し、mTLS＋認可を段階導入。今は一つのTonicサーバに同居している。

4. 線形化の“契約”をドキュメント化 Watch の順序／Revision と Read の一貫性（ReadIndex/フォロワ/リーダ）をモード化して明示する。API層は既に独立しているので拡張しやすい。

5. スナップショットと再構築の運用設計 既存のスナップショット構造を基にchunked streaming/再送/検証を実装し、ローリングアップグレードと迅速なリカバリを可能に。

6. MVCC＋TSOで“トランザクション対応のFlareDB”へ まずは単一リージョンで2PC/OCCを成立させ、その後リージョンを跨ぐ分散トランザクションへ。Quickstart とタスク表に沿って前進できる。

7. 可観測性と安全性 すべてのRaft RPC・適用・スナップショット・GossipイベントにトレースIDを通し、Prometheus でSLOを監視。障害注入テスト（ネット分断/ディスク遅延）を回す。

---

小さく始めるチェックリスト（1–2スプリント）

Chainfire

• RaftRpcClient の gRPC 実装を追加（internal_proto をクライアント化）し、Dummy を置き換え。
• api_addr と raft_addr を別 Server で serve。ログ出力と一致させる。
• Gossip からメンバーの up/down を拾い、Cluster API経由でRaft構成変更に反映。

FlareDB

• verify-multiraft.sh とテスト群に合わせ、リージョンスプリット→新ラフト起動→PD更新→クライアントRegion Cache更新の一連をE2E化。
• フォロワリード/線形化Readの切替をサービスに実装。
• TSO を使った MVCC の最小実装（単一リージョン）を追加してから、2PCへ拡張。

---

まとめ（現実的な採用ライン）

• 今すぐの実用：Chainfire はシングルノードの構成管理KV＋Watchに、FlareDB は PD/TSO を含む実験用KV に向く。
• クラスタ本番：Chainfire は Raft RPC 配線＋メンバーシップ実装が最初の関門。FlareDB は マルチラフト/リージョン運用＋MVCC/2PC が到達点。
• 設計の方向性はどちらも筋が良い。エンジンは積んだ、あとは**配線と路面（運用）**を敷けば走れる、という状態だ。

補足：この評価はアップロードされたリポジトリのソース構成・実装・Spec/Quickstart に基づいています（抜粋例：依存関係・OpenRaft設定・サーバ起動配線・Dummy/In‑memory RPC・PD/TSO・テスト/スクリプトなど）。必要なら、具体ファイル/行も辿れるように示しました。

この先、どのユースケース（たとえばK8sのコントロールプレーン用KV／大規模Key-Valueの裏側／学術実験）を主眼にするかで実装の優先度は変わります。用途を教えてくれれば、必要機能の優先順位表まで落とし込みます。