hakorune/docs/reference/execution-backend/p2p_spec.md

🌐 P2PBox完全実装 - AI大会議仕様準拠

Status: Planned（Phase 9.79で実装、Cranelift前に完了） Roadmap: docs/private/roadmap2/phases/phase-9/phase_9_79_p2pbox_rebuild.md

📋 Issue概要

目標: NyaMeshP2Pライブラリ実現のためのP2P通信システムを、AI大会議で決定した最新仕様に従って完全実装する

重要: 既存の src/boxes/intent_box.rs と src/boxes/p2p_box.rs は古い設計のため、完全に作り直しが必要

🎯 AI大会議決定事項

✅ 採用仕様

• 構造化IntentBox: name + payload 形式のメッセージBox
• 個別送信のみ: send(to, message) 固定API
• 明示的デリゲーション: from Parent.method() 統一構文

❌ 除外仕様

• ブロードキャスト: 安全性のため完全除外（無限ループリスク回避）
• 関数オーバーロード: send(a) vs send(a,b) 分岐不採用

🏗️ 新アーキテクチャ設計

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

📦 段階的実装計画

🎯 Phase 1: 基盤実装

Step 1: IntentBox（構造化メッセージ）

ファイル: src/boxes/intent_box.rs (完全作り直し)

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

実装要件:

• Arc統一パターン準拠
• BoxCore + NyashBox実装
• serde_json::Value使用

テストコード:

// tests/phase2/intent_box_test.hako
local msg = new IntentBox("chat.message", { text: "Hello P2P!" })
local console = new ConsoleBox()
console.log("Name: " + msg.name)     // "chat.message"
console.log("Text: " + msg.payload.text)  // "Hello P2P!"

Step 2: MessageBus（プロセス内シングルトン）

ファイル: src/messaging/message_bus.rs (新規作成)

pub struct MessageBusData {
    nodes: HashMap<String, BusEndpoint>,           // ノード登録
    subscribers: HashMap<String, Vec<IntentHandler>>, // ハンドラー管理
}
pub type MessageBus = Arc<Mutex<MessageBusData>>;

impl MessageBusData {
    pub fn global() -> MessageBus  // シングルトンアクセス
    pub fn register_node(&mut self, id: String, endpoint: BusEndpoint)
    pub fn route(&self, to: &str, intent: IntentBox) -> Result<(), SendError>
}

Step 3: Transport trait（送受信抽象化）

ファイル: src/transport/mod.rs (新規作成)

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>);
}

🎯 Phase 2: InProcess実装

Step 4: InProcessTransport

ファイル: src/transport/inprocess.rs (新規作成)

pub struct InProcessTransport {
    node_id: String,
    bus: MessageBus,  // MessageBus::global()を使用
}

impl Transport for InProcessTransport {
    // Bus経由の高速ローカル配送実装
}

🎯 Phase 3: P2PBox統合

Step 5: P2PBox基本実装

ファイル: src/boxes/p2p_box.rs (完全作り直し)

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>
    // ブロードキャストメソッドは実装しない
}

🧪 包括的テスト要件

基本動作テスト

ファイル: test_p2p_basic_new.hako

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

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

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

エラーハンドリングテスト

// 存在しないノードへの送信
local result = node_a.send("nonexistent", msg)
// → SendError::NodeNotFound

// 不正なIntentBox
local invalid_msg = "not an IntentBox"
local result = node_a.send("bob", invalid_msg)
// → 型エラー

パフォーマンステスト

// 大量メッセージ送信テスト
local start_time = new TimeBox()
loop(i < 1000) {
    local msg = new IntentBox("test.performance", { id: i })
    node_a.send("bob", msg)
    i = i + 1
}
local end_time = new TimeBox()
// 実行時間計測

📁 必要なディレクトリ構成

src/
├── boxes/
│   ├── intent_box.rs          # 完全作り直し
│   └── p2p_box.rs            # 完全作り直し
├── messaging/                # 新規作成
│   └── message_bus.rs        # MessageBus実装
└── transport/                # 新規作成
    ├── mod.rs               # Transport trait
    └── inprocess.rs         # InProcessTransport

🔧 実装時の重要注意点

Arc統一パターン厳守

// ✅ 正しい統一パターン
pub type IntentBox = Arc<Mutex<IntentBoxData>>;
pub type MessageBus = Arc<Mutex<MessageBusData>>;
pub type P2PBox = Arc<Mutex<P2PBoxData>>;

// ❌ 避けるべき
pub struct IntentBox { ... }  // Arcなし

BoxCore実装必須

impl BoxCore for IntentBox {
    fn box_id(&self) -> u64 { self.lock().unwrap().base.id }
    fn parent_type_id(&self) -> Option<TypeId> { None }
    fn fmt_box(&self, f: &mut fmt::Formatter) -> fmt::Result { ... }
    fn as_any(&self) -> &dyn Any { self }
    fn as_any_mut(&mut self) -> &mut dyn Any { self }
}

エラーハンドリング設計

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

🎯 成功の定義

以下のテストが全て通過すること：

1. 基本通信: ノード間でIntentBoxメッセージ送受信
2. ハンドラ登録: on() でイベントリスナー正常動作
3. エラーハンドリング: 不正な送信先・データで適切エラー
4. パフォーマンス: 1000メッセージ/秒以上の送信性能
5. メモリ安全性: valgrind等でメモリリーク検出なし

📚 参考ドキュメント

• P2P_GUIDE.md - 設計詳細・使用例
• CURRENT_TASK.md - 実装状況・優先順位
• ai_conference_overload_decision.md - AI大会議決定事項
• docs/reference/override-delegation-syntax.md - デリゲーション構文仕様

🚀 実装開始

Priority: High
Assignee: Copilot
Labels: enhancement, p2p, breaking-change
Milestone: P2P Phase 2 Complete

最初に取り組むべき: Step 1 IntentBox の完全作り直し

---

🎉 この実装により、Nyashは本格的なP2P通信システムを持つ現代的プログラミング言語になります！