photoncloud-monorepo/docs/plans/chainfire_architecture_redefinition.md

Chainfire アーキテクチャ再定義案: 分散システム構築基盤への転換

Chainfire を単一の KV ストアサービスから、プロジェクト全体の「分散システム構築フレームワーク」へと位置づけ直すための設計案です。

1. アーキテクチャ概要

階層構造を整理し、低レイヤーのプリミティブから高レイヤーのマネージドサービスまでを明確に分離します。

graph TD
    subgraph Application_Layer
        FlareDB[FlareDB / Distributed DB]
        LightningStor[lightningstor / Object Storage]
        IAM[IAM / Control Plane]
    end

    subgraph L2_Service_Layer_Sidecar
        CFServer[Chainfire Server]
        CFServer -- gRPC Streaming --> IAM
    end

    subgraph L1_Framework_Layer
        CFCore[chainfire-core]
        CFCore -- Library Embed --> FlareDB
        CFCore -- Library Embed --> LightningStor

        MultiRaft[Multi-Raft Orchestrator]
        CFCore --> MultiRaft
    end

    subgraph L0_Primitive_Layer
        Gossip[chainfire-gossip]
        Raft[chainfire-raft]
        Storage[chainfire-storage]

        CFCore --> Gossip
        CFCore --> Raft
        Raft --> Storage
    end

    CFServer --> CFCore

2. 各レイヤーの責務定義

L0 Core (Library): primitives

• chainfire-gossip:
  • SWIM プロトコルに基づくメンバーシップ管理。
  • 特定のサービスに依存せず、任意の NodeMetadata を伝搬可能にする。
• chainfire-raft:
  • 単一 Raft グループのコンセンサスロジック。
  • StateMachine を Trait 化し、任意のビジネスロジックを注入可能にする。
  • RaftNetwork を抽象化し、gRPC 以外（UDS, In-memory）のトランスポートをサポート。
• chainfire-storage:
  • Raft ログおよび StateMachine のための永続化レイヤー。

L1 Framework: chainfire-core

• Multi-Raft Orchestrator:
  • 複数の Raft インスタンス（シャード）を同一プロセス内で効率的に管理。
  • ネットワーク接続やスレッドプール等のリソース共有を最適化。
• Cluster Manager:
  • Gossip のメンバーシップイベントを監視し、Raft グループへのノード追加・削除を自動化。
  • 「ノード発見（Gossip）」から「合意形成参加（Raft）」への橋渡しを行う。

L2 Service: chainfire-server (Standard Implementation)

• Shared Infrastructure:
  • KV ストア、分散ロック、リース管理を gRPC API として提供。
  • 独自に Raft を組む必要のない「軽量サービス」向けの共通基盤。
• Sidecar Mode Support:
  • gRPC Streaming による ClusterEvents の提供。
  • リーダー交代やメンバーシップ変更を外部プロセスにリアルタイム通知。

3. 分散サービスでの再利用シナリオ (例: FlareDB)

FlareDB が Chainfire 基盤をどのように利用して Multi-Raft を構成するかの具体例です。

1. ライブラリとして組み込み: FlareDB プロセスが chainfire-core をリンク。
2. 独自の StateMachine 実装: FlareDB のデータ操作ロジックを StateMachine Trait として実装。
3. シャード管理:
   • データのレンジごとに RaftGroup インスタンスを作成。
   • 各 RaftGroup に FlareDB 独自の StateMachine を登録。
4. ノード管理の委譲:
   • Gossip によるノード発見を chainfire-core に任せ、FlareDB 側では個別のノードリスト管理を行わない。

4. メリットの整理

• 開発効率の向上: Gossip や Raft といった複雑な分散プロトコルの再実装が不要になる。
• 観測性の一貫性: プロジェクト全体の全ノードが共通の Gossip 基盤に乗ることで、システム全体のトポロジー可視化が容易になる。
• 柔軟な配置: 同一のロジックを、ライブラリとして（高パフォーマンス）、あるいはサイドカーとして（疎結合）のどちらでも利用可能。