163 lines
5.3 KiB
Markdown
163 lines
5.3 KiB
Markdown
|
# nyash.toml v2 仕様 - 究極のシンプル設計
|
|||
|
|
|
|||
|
|
> ⚠️ **PARTIALLY OUTDATED - 部分的に古い**
|
|||
|
|
>
|
|||
|
|
> この文書の基本構造は正しいですが、実際の形式と一部異なります。
|
|||
|
|
>
|
|||
|
|
> **最新の実際の設定形式については、以下を参照してください：**
|
|||
|
|
> - [BID-FFI v1 実装仕様書](./bid-ffi-v1-actual-specification.md) - 現在動作中の仕様
|
|||
|
|
> - [nyash.toml設定例](../../../../nyash.toml) - 実際の設定形式
|
|||
|
|
|
|||
|
|
## 🎯 概要
|
|||
|
|
**革命的シンプル設計**: nyash.toml中心アーキテクチャ + 最小限FFI
|
|||
|
|
|
|||
|
|
## 📝 nyash.toml v2形式
|
|||
|
|
|
|||
|
|
### マルチBox型プラグイン対応
|
|||
|
|
```toml
|
|||
|
|
[libraries]
|
|||
|
|
# ライブラリ定義（1つのプラグインで複数のBox型を提供可能）
|
|||
|
|
"libnyash_filebox_plugin.so" = {
|
|||
|
|
boxes = ["FileBox"],
|
|||
|
|
path = "./target/release/libnyash_filebox_plugin.so"
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
# 将来の拡張例: 1つのプラグインで複数Box型
|
|||
|
|
"libnyash_network_plugin.so" = {
|
|||
|
|
boxes = ["SocketBox", "HTTPServerBox", "HTTPClientBox"],
|
|||
|
|
path = "./target/release/libnyash_network_plugin.so"
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
# FileBoxの型情報定義
|
|||
|
|
[libraries."libnyash_filebox_plugin.so".FileBox]
|
|||
|
|
type_id = 6
|
|||
|
|
abi_version = 1 # ABIバージョンもここに！
|
|||
|
|
|
|||
|
|
[libraries."libnyash_filebox_plugin.so".FileBox.methods]
|
|||
|
|
# method_id だけで十分（引数情報は実行時チェック）
|
|||
|
|
birth = { method_id = 0 }
|
|||
|
|
open = { method_id = 1 }
|
|||
|
|
read = { method_id = 2 }
|
|||
|
|
write = { method_id = 3 }
|
|||
|
|
close = { method_id = 4 }
|
|||
|
|
fini = { method_id = 4294967295 } # 0xFFFFFFFF
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🚀 究極のシンプルFFI
|
|||
|
|
|
|||
|
|
### プラグインが実装する関数
|
|||
|
|
|
|||
|
|
#### 必須: メソッド実行エントリーポイント
|
|||
|
|
```c
|
|||
|
|
// 唯一の必須関数 - すべてのメソッド呼び出しはここから
|
|||
|
|
extern "C" fn nyash_plugin_invoke(
|
|||
|
|
type_id: u32, // Box型ID（例: FileBox = 6）
|
|||
|
|
method_id: u32, // メソッドID（0=birth, 0xFFFFFFFF=fini）
|
|||
|
|
instance_id: u32, // インスタンスID（0=static/birth）
|
|||
|
|
args: *const u8, // TLVエンコード引数
|
|||
|
|
args_len: usize,
|
|||
|
|
result: *mut u8, // TLVエンコード結果バッファ
|
|||
|
|
result_len: *mut usize // [IN/OUT]バッファサイズ
|
|||
|
|
) -> i32 // 0=成功, 負=エラー
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
#### オプション: グローバル初期化
|
|||
|
|
```c
|
|||
|
|
// プラグインロード時に1回だけ呼ばれる（実装は任意）
|
|||
|
|
extern "C" fn nyash_plugin_init() -> i32 {
|
|||
|
|
// グローバルリソースの初期化
|
|||
|
|
// 設定ファイルの読み込み
|
|||
|
|
// ログファイルのオープン
|
|||
|
|
// 0=成功, 負=エラー（プラグインは無効化される）
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 廃止されたAPI
|
|||
|
|
```c
|
|||
|
|
// ❌ これらは全部不要！
|
|||
|
|
nyash_plugin_abi_version() // → nyash.tomlのabi_version
|
|||
|
|
nyash_plugin_get_box_count() // → nyash.tomlのboxes配列
|
|||
|
|
nyash_plugin_get_box_info() // → nyash.tomlから取得
|
|||
|
|
NyashHostVtable // → 完全廃止！
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 📊 設計原則
|
|||
|
|
|
|||
|
|
### 1. **Single Source of Truth**
|
|||
|
|
- すべてのメタ情報はnyash.tomlに集約
|
|||
|
|
- プラグインは純粋な実装のみ
|
|||
|
|
|
|||
|
|
### 2. **Zero Dependencies**
|
|||
|
|
- Host VTable廃止 = 依存関係ゼロ
|
|||
|
|
- プラグインは完全に独立
|
|||
|
|
|
|||
|
|
### 3. **シンプルなライフサイクル**
|
|||
|
|
- `init` (オプション): プラグインロード時の初期化
|
|||
|
|
- `birth` (method_id=0): インスタンス作成
|
|||
|
|
- 各種メソッド: インスタンス操作
|
|||
|
|
- `fini` (method_id=0xFFFFFFFF): 論理的終了
|
|||
|
|
|
|||
|
|
### 4. **ログ出力**
|
|||
|
|
```rust
|
|||
|
|
// プラグインは自己完結でログ出力
|
|||
|
|
eprintln!("[FileBox] Opened: {}", path); // 標準エラー
|
|||
|
|
|
|||
|
|
// または専用ログファイル
|
|||
|
|
let mut log = File::create("plugin_debug.log")?;
|
|||
|
|
writeln!(log, "{}: FileBox birth", chrono::Local::now())?;
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 5. **init関数の活用例**
|
|||
|
|
```rust
|
|||
|
|
static mut LOG_FILE: Option<File> = None;
|
|||
|
|
|
|||
|
|
#[no_mangle]
|
|||
|
|
pub extern "C" fn nyash_plugin_init() -> i32 {
|
|||
|
|
// ログファイルを事前に開く
|
|||
|
|
match File::create("filebox.log") {
|
|||
|
|
Ok(f) => {
|
|||
|
|
unsafe { LOG_FILE = Some(f); }
|
|||
|
|
0 // 成功
|
|||
|
|
}
|
|||
|
|
Err(_) => -1 // エラー → プラグイン無効化
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 🔧 実装の流れ
|
|||
|
|
|
|||
|
|
### Phase 1: nyash.toml v2パーサー
|
|||
|
|
1. 新形式の読み込み
|
|||
|
|
2. Box型情報の抽出
|
|||
|
|
3. メソッドID管理
|
|||
|
|
|
|||
|
|
### Phase 2: プラグインローダー簡素化
|
|||
|
|
1. `nyash_plugin_init`（オプション）と`nyash_plugin_invoke`（必須）をロード
|
|||
|
|
2. nyash.tomlベースの型登録
|
|||
|
|
3. Host VTable関連コードを削除
|
|||
|
|
4. init関数が存在し失敗した場合はプラグインを無効化
|
|||
|
|
|
|||
|
|
### Phase 3: プラグイン側の対応
|
|||
|
|
1. abi/get_box_count/get_box_info関数を削除
|
|||
|
|
2. init関数は必要に応じて実装（グローバル初期化）
|
|||
|
|
3. invoke関数でメソッド処理
|
|||
|
|
4. ログ出力を自己完結に
|
|||
|
|
|
|||
|
|
## 🎉 メリット
|
|||
|
|
|
|||
|
|
1. **究極のシンプルさ** - 基本的にFFI関数1つ（initはオプション）
|
|||
|
|
2. **保守性向上** - 複雑な相互依存なし
|
|||
|
|
3. **テスト容易性** - モック不要
|
|||
|
|
4. **移植性** - どの言語でも実装可能
|
|||
|
|
5. **拡張性** - nyash.toml編集で機能追加
|
|||
|
|
6. **初期化保証** - init関数で早期エラー検出可能
|
|||
|
|
|
|||
|
|
## 🚨 注意事項
|
|||
|
|
|
|||
|
|
- プラグインのログは標準エラー出力かファイル出力で
|
|||
|
|
- メモリ管理はプラグイン内で完結
|
|||
|
|
- 非同期処理はNyash側でFutureBoxラップ
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**革命完了**: これ以上シンプルにできない究極の設計！
|