hakorune/docs/guides/p2p-guide.md

📡 Nyash P2P通信システム - 完全ガイド

目標: NyaMeshP2Pライブラリ実現のための本格的P2P通信システム

🏗️ システム全体像

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│   P2PBox    │◄──►│ MessageBus   │◄──►│ Transport   │
│ (ユーザーAPI) │    │ (ローカル配送)  │    │ (送受信層)   │
└─────────────┘    └──────────────┘    └─────────────┘
       ▲                    ▲                   ▲
       │                    │                   │
┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│ IntentBox   │    │ ハンドラ管理   │    │ InProcess   │
│ (構造化MSG)  │    │ ノード登録    │    │ WebSocket   │
└─────────────┘    └──────────────┘    │ WebRTC      │
                                       └─────────────┘

核心思想: 「P2PBox一つにTransport一つ + 共有MessageBus」

🧩 4つの主要Box

1. IntentBox - 構造化メッセージ 📨

pub struct IntentBoxData {
    pub name: String,           // "chat.message", "file.share"等
    pub payload: serde_json::Value,  // 任意のJSON data
}
pub type IntentBox = Arc<Mutex<IntentBoxData>>;

// 使用例
msg = new IntentBox("chat.message", { text: "Hello P2P!", timestamp: 12345 })
print(msg.name)     // "chat.message"  
print(msg.payload)  // {"text":"Hello P2P!","timestamp":12345}

2. MessageBus - プロセス内シングルトン 🚌

pub struct MessageBusData {
    nodes: HashMap<String, BusEndpoint>,           // ノード登録
    subscribers: HashMap<String, Vec<IntentHandler>>, // "node_id:intent_name" → ハンドラー
    stats: BusStatistics,
}
pub type MessageBus = Arc<Mutex<MessageBusData>>;

// シングルトンアクセス
MessageBusData::global() -> MessageBus

役割: 同プロセス内での超高速メッセージルーティング・ハンドラ管理

3. Transport - 送受信抽象化 🔌

pub trait Transport: Send + Sync {
    fn node_id(&self) -> &str;
    fn send(&self, to: &str, intent: IntentBox, opts: SendOpts) -> Result<(), SendError>;
    fn on_receive(&mut self, callback: Box<dyn Fn(IntentEnvelope) + Send + Sync>);
}

// 3種類の実装
pub struct InProcessTransport { ... }    // 同プロセス内
pub struct WebSocketTransport { ... }    // WebSocket通信  
pub struct WebRTCTransport { ... }       // WebRTC P2P

4. P2PBox - 統合ユーザーAPI 🎉

pub struct P2PBoxData {
    node_id: String,
    transport: Arc<dyn Transport>,
    bus: MessageBus,  // 全P2PBoxで共有
}
pub type P2PBox = Arc<Mutex<P2PBoxData>>;

impl P2PBoxData {
    pub fn new(node_id: String, kind: TransportKind) -> P2PBox
    pub fn on(&self, intent_name: &str, handler: IntentHandler) -> Result<(), P2PError>
    pub fn send(&self, to: &str, intent: IntentBox) -> Result<(), SendError>
}

🚀 実用的使用例

Level 1: 基本的なP2P通信

// 2つのノード作成
node_a = new P2PBox("alice", transport: "inprocess")
node_b = new P2PBox("bob", transport: "inprocess")

// 受信ハンドラ設定
node_b.on("chat.message", function(intent, from) {
    console = new ConsoleBox()
    console.log("From " + from + ": " + intent.payload.text)
})

// メッセージ送信
msg = new IntentBox("chat.message", { text: "Hello P2P!" })
node_a.send("bob", msg)  // → "From alice: Hello P2P!"

Level 2: 糖衣構文（将来実装）

// 文字列直送（内部でIntentBox化） - 個別送信のみ
node_a.send("bob", "hello")           // → IntentBox("message", "hello")
node_a.send("bob", "chat:hello")      // → IntentBox("chat", "hello")
// 注意: ブロードキャスト機能は安全性のため除外（無限ループリスク回避）

Level 3: 異なるTransport

// 将来：異なるTransportでも同じAPI
local_node = new P2PBox("local", transport: "inprocess")
web_node   = new P2PBox("web", transport: "websocket", { url: "ws://localhost:8080" })
p2p_node   = new P2PBox("p2p", transport: "webrtc", { ice_servers: [...] })

// Transportに関係なく同じsend/onメソッド
msg = new IntentBox("file.share", { filename: "data.json" })
local_node.send("web", msg)    // WebSocket経由
web_node.send("p2p", msg)      // WebRTC経由

🔄 送受信フロー詳細

📤 送信フロー（node_a.send("node_b", intent)）

1. bus.has_node("node_b") == true？
   YES → bus.route("node_b", intent)    ← 同プロセス内の最速配送
   NO  → transport.send("node_b", intent, opts)  ← WebSocket/WebRTC経由

📥 受信フロー（ネットワークからの到着）

transport.on_receive コールバックで受信
        ↓
1. envelope.to == self.node_id？
   YES → bus.dispatch_to_local(self.node_id, intent)  ← 自分宛
   NO  → 2へ
        ↓
2. bus.has_node(envelope.to)？
   YES → bus.route(envelope.to, intent)  ← 同プロセス内転送  
   NO  → bus.trace_drop(envelope)        ← ルート不明

📋 段階的実装計画

Phase 1: 基盤実装 （最優先）

1. IntentBox - メッセージBox（src/boxes/intent_box.rs）
2. MessageBus - プロセス内シングルトン（src/messaging/message_bus.rs）
3. Transport trait - 送受信抽象化（src/transport/mod.rs）

Phase 2: InProcess実装

4. InProcessTransport - Bus経由の同プロセス通信（src/transport/inprocess.rs）
5. P2PBox基本実装 - new, on, send メソッド（src/boxes/p2p_box.rs）
6. インタープリター統合 - Nyash言語でのnew構文対応

Phase 3: ネットワーク拡張 （将来）

7. WebSocketTransport - WebSocket経由通信
8. WebRTCTransport - 直接P2P通信
9. 高度機能 - timeout, ACK, reconnect等

🧪 テスト戦略

基本動作確認テスト

// tests/phase2/p2p_basic_test.hako
node_a = new P2PBox("alice", transport: "inprocess")
node_b = new P2PBox("bob", transport: "inprocess")

node_b.on("test.ping", function(intent, from) {
    console = new ConsoleBox()
    console.log("PING from " + from)
})

msg = new IntentBox("test.ping", { timestamp: 12345 })
result = node_a.send("bob", msg)

// 期待出力: "PING from alice"

🎯 重要な設計原則

なぜ「非InProcessでもBusを持つ」のか？

1. ローカル最速配送: Busが知ってればゼロコピー級の高速配送
2. 統一API: ローカルもネットも外側APIは同じsend/onメソッド
3. 集約ログ: 全P2P通信の統一ログ・メトリクス・デバッグ
4. ハンドラ集約: on()/subscribe登録・解除・トレースが一箇所

同期→非同期の段階的対応

• Phase 1: send() は同期版 fn で実装開始
• Phase 2: 基本機能確立後に async fn 化
• Phase 3: Nyashインタープリターでのasync/await対応

Arc統一アーキテクチャ準拠

• すべてのBoxは既存の Arc<Mutex<_>> パターンに準拠
• MessageBus も Arc<Mutex<MessageBusData>>
• IntentBox も Arc<Mutex<IntentBoxData>>

🚨 エラーハンドリング

#[derive(Debug, Clone)]
pub enum SendError {
    NodeNotFound(String),    // 宛先ノードが見つからない
    NetworkError(String),    // ネットワークエラー
    Timeout,                 // 送信タイムアウト
    SerializationError(String), // JSON変換エラー
    BusError(String),        // MessageBusエラー
}

🌟 最終目標

// NyaMeshP2Pライブラリの実現
mesh = new NyaMesh("my_node")
mesh.join("chat_room")  
mesh.send("Hello everyone!")
mesh.on("message", function(msg, from) {
    print(from + ": " + msg)
})

---

📚 関連ドキュメント

• DetailedP2PBoxSpec.md - ChatGPT大会議完全仕様（詳細版）
• MessageBusDesign.md - MessageBus詳細設計
• CURRENT_TASK.md - 現在の実装状況・優先順位

📝 最終更新: 2025-08-12 | 🎓 設計協力: Gemini先生・ChatGPT先生 | 🎯 目標: Everything is Box哲学によるP2P通信革命