246 lines
7.1 KiB
Markdown
246 lines
7.1 KiB
Markdown
# 🔄 ビルトインBox → プラグイン変換手順書
|
||
|
||
## 🎯 概要
|
||
|
||
ビルトインBoxをBID-FFI v1プラグインに変換する標準手順。実際の変換作業で発見された問題と解決策を蓄積し、効率的な開発手法を確立する。
|
||
|
||
## 📊 変換パターン分析
|
||
|
||
### 🏆 成功事例：FileBox変換
|
||
- **元実装**: `src/boxes/file/mod.rs` (RwLock<File>)
|
||
- **プラグイン**: `plugins/nyash-filebox-plugin/` (BID-FFI v1)
|
||
- **結果**: ✅ 完全動作、プラグイン優先使用
|
||
|
||
### 🔍 現状分析：HTTP系Box
|
||
- **実装状況**: 完全実装済み（432行の高機能HTTPサーバー）
|
||
- **問題**: Unified Registry未登録（Legacy Match使用）
|
||
- **潜在性**: 即座にプラグイン化可能
|
||
|
||
## 🚀 標準変換手順（3段階アプローチ）
|
||
|
||
### Phase 1: ビルトイン最適化
|
||
**目的**: 既存実装の性能向上・デバッグ
|
||
**期間**: 1-3日
|
||
|
||
#### 手順
|
||
1. **Unified Registry登録**
|
||
```rust
|
||
// src/box_factory/builtin.rs 内
|
||
fn register_io_types(&mut self) {
|
||
// HTTPServerBox追加
|
||
self.register("HTTPServerBox", |args| {
|
||
if !args.is_empty() {
|
||
return Err(RuntimeError::InvalidOperation {
|
||
message: format!("HTTPServerBox constructor expects 0 arguments, got {}", args.len()),
|
||
});
|
||
}
|
||
Ok(Box::new(HTTPServerBox::new()))
|
||
});
|
||
// 他のHTTP系Boxも同様に追加
|
||
}
|
||
```
|
||
|
||
2. **動作テスト作成**
|
||
```nyash
|
||
// local_tests/test_http_builtin.nyash
|
||
static box Main {
|
||
main() {
|
||
local server = new HTTPServerBox()
|
||
server.bind("localhost", 8080)
|
||
server.get("/test", TestHandler.handle)
|
||
return "HTTP builtin test complete"
|
||
}
|
||
}
|
||
```
|
||
|
||
3. **性能ベンチマーク**
|
||
- Legacy Match vs Unified Registry比較
|
||
- メモリ使用量測定
|
||
|
||
#### 期待効果
|
||
- ✅ 高速化（Legacy Match削除）
|
||
- ✅ デバッグ環境確立
|
||
- ✅ 安定性確認
|
||
|
||
### Phase 2: プラグイン変換実装
|
||
**目的**: BID-FFI v1プラグイン実装
|
||
**期間**: 3-7日
|
||
|
||
#### 手順
|
||
1. **プラグインプロジェクト作成**
|
||
```bash
|
||
mkdir plugins/nyash-http-plugin
|
||
cd plugins/nyash-http-plugin
|
||
cargo init --lib
|
||
```
|
||
|
||
2. **Cargo.toml設定**
|
||
```toml
|
||
[lib]
|
||
crate-type = ["cdylib"]
|
||
|
||
[dependencies]
|
||
once_cell = "1.0"
|
||
# HTTP依存関係
|
||
```
|
||
|
||
3. **BID-FFI v1実装**
|
||
- マルチBox対応（HTTPServerBox, HTTPClientBox, SocketBox）
|
||
- TLV Protocol実装
|
||
- Method ID定義
|
||
|
||
4. **nyash.toml設定**
|
||
```toml
|
||
[libraries."libnyash_http_plugin.so"]
|
||
boxes = ["HTTPServerBox", "HTTPClientBox", "SocketBox"]
|
||
|
||
[libraries."libnyash_http_plugin.so".HTTPServerBox]
|
||
type_id = 10
|
||
[libraries."libnyash_http_plugin.so".HTTPServerBox.methods]
|
||
birth = { method_id = 0 }
|
||
bind = { method_id = 1, args = ["address", "port"] }
|
||
listen = { method_id = 2, args = ["backlog"] }
|
||
start = { method_id = 3 }
|
||
stop = { method_id = 4 }
|
||
fini = { method_id = 4294967295 }
|
||
```
|
||
|
||
### Phase 3: 移行・検証
|
||
**目的**: 完全移行とパフォーマンス検証
|
||
**期間**: 1-2日
|
||
|
||
#### 手順
|
||
1. **プラグイン優先テスト**
|
||
- 同じテストケースでビルトイン vs プラグイン比較
|
||
- メモリリーク検証
|
||
- エラーハンドリング確認
|
||
|
||
2. **ビルトイン実装削除**
|
||
- `src/boxes/http_*` ファイル削除
|
||
- BUILTIN_BOXES リストから除去
|
||
- コンパイル確認
|
||
|
||
3. **本格アプリテスト**
|
||
```nyash
|
||
// apps/http_example/
|
||
// 実用的なHTTPサーバーアプリで動作確認
|
||
```
|
||
|
||
## 🔧 BID-FFI v1必須要件
|
||
|
||
### ✅ **絶対必須の2つのメソッド**
|
||
|
||
すべてのBID-FFI v1プラグインで実装必須：
|
||
|
||
**🔧 birth() - コンストラクタ (METHOD_ID = 0)**
|
||
```rust
|
||
const METHOD_BIRTH: u32 = 0; // Constructor
|
||
```
|
||
- **機能**: インスタンス作成、instance_id返却
|
||
- **必須実装**: インスタンス管理、メモリ確保
|
||
- **戻り値**: TLV形式のinstance_id (u32)
|
||
|
||
**🧹 fini() - デストラクタ (METHOD_ID = u32::MAX)**
|
||
```rust
|
||
const METHOD_FINI: u32 = u32::MAX; // Destructor (4294967295)
|
||
```
|
||
- **機能**: インスタンス解放、メモリクリーンアップ
|
||
- **必須実装**: INSTANCES.remove(), リソース解放
|
||
- **戻り値**: 成功ステータス
|
||
|
||
### 📝 設定例
|
||
```toml
|
||
[libraries."libnyash_example_plugin.so".ExampleBox.methods]
|
||
birth = { method_id = 0 } # 🔧 必須
|
||
# ... カスタムメソッド ...
|
||
fini = { method_id = 4294967295 } # 🧹 必須
|
||
```
|
||
|
||
## 🐛 発見済み問題と解決策
|
||
|
||
### Problem 1: toString()メソッドエラー
|
||
**現象**: `Unknown method 'toString' for FileBox`
|
||
```
|
||
❌ Interpreter error: Invalid operation: Unknown method 'toString' for FileBox
|
||
```
|
||
|
||
**原因**: プラグインにtoString()メソッド未定義
|
||
**解決策**: nyash.tomlでtoStringメソッド追加
|
||
```toml
|
||
toString = { method_id = 5 }
|
||
```
|
||
|
||
### Problem 2: Unified Registry未登録Box
|
||
**現象**: `Falling back to legacy match statement`
|
||
```
|
||
🔍 Unified registry failed for HTTPServerBox: Unknown Box type
|
||
🔍 Falling back to legacy match statement
|
||
```
|
||
|
||
**原因**: BuiltinBoxFactory.register_io_types()未登録
|
||
**解決策**: HTTP系Box登録追加
|
||
|
||
### Problem 3: 複雑な依存関係
|
||
**予想問題**: HTTPServerBox → SocketBox → OS固有API
|
||
**解決策**: プラグイン内で依存関係完結
|
||
|
||
## 📋 チェックリスト
|
||
|
||
### ✅ Phase 1完了条件
|
||
- [ ] Unified Registry登録完了
|
||
- [ ] Legacy Match削除確認
|
||
- [ ] 基本動作テスト成功
|
||
- [ ] パフォーマンス改善確認
|
||
|
||
### ✅ Phase 2完了条件
|
||
- [ ] プラグインビルド成功
|
||
- [ ] BID-FFI v1インターフェース実装
|
||
- [ ] 全メソッドTLV対応
|
||
- [ ] plugin-testerで検証成功
|
||
|
||
### ✅ Phase 3完了条件
|
||
- [ ] プラグイン優先動作確認
|
||
- [ ] ビルトイン実装削除成功
|
||
- [ ] 実用アプリケーション動作確認
|
||
- [ ] メモリリーク・エラーなし
|
||
|
||
## 🚀 期待効果
|
||
|
||
### 短期効果（Phase 1）
|
||
- **5-10倍高速化**: Legacy Match → Unified Registry
|
||
- **保守性向上**: 統一的なファクトリパターン
|
||
- **デバッグ環境**: 安定したテスト基盤
|
||
|
||
### 長期効果（Phase 3）
|
||
- **プラグイン化完了**: 外部配布可能
|
||
- **アーキテクチャ改善**: コア軽量化
|
||
- **拡張性向上**: 独立開発可能
|
||
|
||
## 🎯 次期対象Box候補
|
||
|
||
### 優先度高（実装済み）
|
||
1. **HTTP系**: HTTPServerBox, HTTPClientBox, SocketBox
|
||
2. **BufferBox**: バイナリデータ処理
|
||
3. **RegexBox**: 正規表現処理
|
||
|
||
### 優先度中（要調査）
|
||
1. **MathBox, RandomBox**: プラグイン実装あり（第1世代C ABI）
|
||
2. **JSONBox**: データ交換
|
||
3. **StreamBox**: ストリーム処理
|
||
|
||
## 📝 学習記録
|
||
|
||
### 成功パターン
|
||
- FileBox: 単純構造、明確API → スムーズ変換
|
||
- プラグイン優先システム動作確認済み
|
||
|
||
### 注意点
|
||
- toString()等の基本メソッド必須
|
||
- 依存関係の循環に注意
|
||
- メモリ管理の完全分離
|
||
|
||
---
|
||
|
||
**最終更新**: 2025年8月20日 - 初版作成
|
||
**Phase**: 9.75g-0 完了後 - HTTP系Box変換準備完了
|
||
**Next**: Phase 1実装→Phase 2プラグイン化 |