hakorune/docs/plugin-migration-request.md

📦 Nyash ビルトインBox → プラグイン化移行依頼

🎯 概要

NyashのビルトインBoxをプラグイン化し、コアを軽量化したい。 FileBoxプラグインの成功例を参考に、以下のBoxを順次プラグイン化してください。

📋 移行対象Box一覧

🌐 Phase 1: ネットワーク・通信系（最優先）

plugins/nyash-http-plugin/
├── HttpClientBox   - HTTP通信クライアント（GET/POST/PUT/DELETE）
├── HTTPServerBox   - HTTPサーバー機能
├── HTTPRequestBox  - HTTPリクエスト表現
└── HTTPResponseBox - HTTPレスポンス表現

plugins/nyash-socket-plugin/
└── SocketBox      - TCP/UDPソケット通信

🖼️ Phase 2: GUI・グラフィック系

plugins/nyash-egui-plugin/
└── EguiBox        - デスクトップGUI（既にfeature分離済み）

plugins/nyash-canvas-plugin/
├── CanvasEventBox - Canvas描画イベント
└── CanvasLoopBox  - Canvas描画ループ

plugins/nyash-web-plugin/（WASM専用）
├── WebDisplayBox  - HTML表示
├── WebConsoleBox  - ブラウザコンソール
└── WebCanvasBox   - Canvas描画

🎵 Phase 3: 特殊用途系

plugins/nyash-audio-plugin/
├── AudioBox       - 音声再生・合成
└── SoundBox       - 効果音再生

plugins/nyash-qr-plugin/
└── QRBox          - QRコード生成

plugins/nyash-stream-plugin/
└── StreamBox      - ストリーム処理

plugins/nyash-timer-plugin/
└── TimerBox       - タイマー機能

🔧 実装ガイドライン

1. 参考にするファイル

• 成功例: plugins/nyash-filebox-plugin/ - 動作確認済みのFileBoxプラグイン
• 設定例: nyash.toml - 型情報定義の書き方
• テスト: tools/plugin-tester/ - プラグイン診断ツール

2. 各プラグインの構成

plugins/nyash-xxx-plugin/
├── Cargo.toml      # 依存関係（例: reqwest for HTTP）
├── src/
│   └── lib.rs      # FFI実装
├── nyash.toml      # 型情報定義
└── README.md       # 使用方法

3. nyash.toml記述例（HttpClientBoxの場合）

[plugins.HttpClientBox.methods]
# GETリクエスト
get = { 
    args = [{ name = "url", from = "string", to = "string" }],
    returns = "string"
}

# POSTリクエスト
post = { 
    args = [
        { name = "url", from = "string", to = "string" },
        { name = "body", from = "string", to = "string" }
    ],
    returns = "string"
}

# ヘッダー付きリクエスト
request = {
    args = [
        { name = "method", from = "string", to = "string" },
        { name = "url", from = "string", to = "string" },
        { name = "options", from = "map", to = "map" }
    ],
    returns = "map"  # { status, body, headers }
}

# DELETE リクエスト
delete = {
    args = [{ name = "url", from = "string", to = "string" }],
    returns = "string"
}

# PUT リクエスト  
put = {
    args = [
        { name = "url", from = "string", to = "string" },
        { name = "body", from = "string", to = "string" }
    ],
    returns = "string"
}

4. テスト方法

# ビルド
cd plugins/nyash-xxx-plugin
cargo build --release

# plugin-testerで診断
cd ../../tools/plugin-tester
./target/release/plugin-tester ../../plugins/nyash-xxx-plugin/target/release/libnyash_xxx_plugin.so

# Nyashで実行テスト
./target/release/nyash test_xxx.nyash

📝 特記事項

HttpBox系

• 現在スタブ実装なので移行しやすい
• reqwest依存を復活させる
• 非同期処理の考慮が必要

EguiBox

• 既にfeature分離されているので参考になる
• メインスレッド制約に注意

AudioBox/SoundBox

• プラットフォーム依存性が高い
• Web/Desktop両対応を検討

依存関係の管理

• 各プラグインは独立したCargo.tomlを持つ
• ビルド時間短縮のため最小限の依存にする

💡 実装の重要ポイント

FFI境界での注意事項

1. メモリ管理:

   • Rustの所有権とCのメモリ管理の違いに注意
   • 文字列は必ずCString/CStr経由で変換

2. エラーハンドリング:

   • パニックをFFI境界で止める（catch_unwind使用）
   • エラーコードで通信（0=成功, 負値=エラー）

3. 型変換パターン (FileBoxプラグインより):

// Nyash文字列 → Rust文字列
let path = get_string_arg(&args[0], 0)?;

// Rust文字列 → Nyash文字列
encode_string_result(&contents, result, result_len)

参考ファイルの具体的パス

• FileBoxプラグイン実装: plugins/nyash-filebox-plugin/src/lib.rs
• FFI仕様書: docs/説明書/reference/plugin-system/ffi-abi-specification.md
• プラグインシステム説明: docs/説明書/reference/plugin-system/plugin-system.md
• BID-FFI型変換 (参考): src/bid-converter-copilot/tlv.rs

📅 推奨実装順序とロードマップ

Week 1: HttpBox系（最も簡単）

• 既にスタブ実装済み
• reqwest依存を追加するだけ
• FileBoxと同じパターンで実装可能

Week 2: 特殊用途系（独立性高い）

• QRBox: 単機能で簡単
• TimerBox: 非同期処理の練習に最適
• StreamBox: 中程度の複雑さ

Week 3: GUI/グラフィック系（プラットフォーム依存）

• EguiBox: feature分離済みなので参考になる
• Canvas系: Web/Desktop両対応必要
• Audio系: 最も複雑（最後に実装）

🎯 期待される効果

1. ビルド時間: 3分 → 30秒以下
2. バイナリサイズ: 最小構成で500KB以下
3. 保守性: 各プラグイン独立開発可能
4. 拡張性: ユーザーが独自プラグイン作成可能

📝 質問・相談先

• プラグイン化で不明な点があれば、FileBoxプラグインの実装を参考に
• FFI実装で困ったら、plugin-testerのソースコードも参考になります
• nyash.tomlの型定義で迷ったら、既存のFileBox定義を真似してください