93 lines
4.6 KiB
Markdown
93 lines
4.6 KiB
Markdown
# Phase 17 接続モデル（最小）: JSON NDJSON over stdio, exe↔exe
|
||
|
||
目的: まずは「簡単・見える・壊れない」。単一の接続モデル（JSONを1行ずつ、標準入出力でやり取り）で、エンジンを別プロセスの小さな実行ファイルとして積み上げる。
|
||
|
||
## 方針
|
||
- 1接続モデルのみ: NDJSON（1メッセージ=1行のJSON）。
|
||
- 1トランスポートのみ: 標準入出力（子プロセス起動）。パイプ/ソケットは後回し。
|
||
- 1エンジン=1 exe: `nyash-engine-core13`, `nyash-engine-loop`など。役割ごとに小さく分割。
|
||
- 可視化容易: すべてのトレースをNDJSONで出力し、そのまま保存・比較・変換（jq/簡易スクリプト）。
|
||
|
||
## メッセージ共通フィールド
|
||
- `op`: 操作名（例: "load_module", "call", "trace_sub"）
|
||
- `id`: リクエストID（数値/文字列）。応答に同じ`id`を返す。
|
||
- `schema`: プロトコル版（整数, 例: 1）。
|
||
- `ts`: 送信者時刻（オプション, ns/μs/ms表現は自由）。
|
||
|
||
応答の共通:
|
||
- `ok`: true/false
|
||
- `id`: リクエストと同一
|
||
- `err`: 失敗時のみ `{code, message, data?}`
|
||
|
||
## 操作一覧（最小）
|
||
1) load_module
|
||
- 要求: `{op:"load_module", id:1, schema:1, ir:"core13|loop", format:"json|bin", bytes:"<base64>"}`
|
||
- 応答: `{ok:true, id:1, module_id:1, features:["interp","trace"], ir:"core13"}`
|
||
|
||
2) call
|
||
- 要求: `{op:"call", id:2, module_id:1, func:"main", args:[1,2,3], timeout_ms:5000?}`
|
||
- 応答: `{ok:true, id:2, value:3, events_dropped:0}`
|
||
|
||
3) trace_sub（トレース購読）
|
||
- 要求: `{op:"trace_sub", id:3, mask:["EnterFunc","ExitFunc","LoopIter","Branch","ExternCall"], flush_ms:50?}`
|
||
- 応答: `{ok:true, id:3}`
|
||
- イベントストリーム: 別行で `{"event":"EnterFunc", "func":"main", ...}` を逐次出力（応答行とは独立）
|
||
|
||
4) unload（任意）
|
||
- 要求: `{op:"unload", id:4, module_id:1}`
|
||
- 応答: `{ok:true, id:4}`
|
||
|
||
5) ping（ヘルスチェック）
|
||
- 要求: `{op:"ping", id:5}`
|
||
- 応答: `{ok:true, id:5, now: 1725600000}`
|
||
|
||
エラー例:
|
||
- 応答: `{ok:false, id:2, err:{code:"E_NO_FUNC", message:"function not found", data:{func:"main"}}}`
|
||
|
||
## トレースイベント（NDJSON）
|
||
- 例: `{"event":"EnterFunc","func":"main","args":[1],"ts":...}`
|
||
- 最小セット: `EnterFunc, ExitFunc, Block, PhiMerge, LoopIter, Branch, ExternCall, Safepoint, Barrier`
|
||
- フィールドの原則: `event`必須、その他は柔軟に拡張し未知キーは無視可能。
|
||
|
||
## エンジンexeの約束
|
||
- 起動直後にバナー等を出力しない（標準出力は完全にプロトコル専用）。
|
||
- 標準エラーは自由（ログ用）。
|
||
- 読み込みは行単位でJSONをパース、応答は必ず1行。
|
||
- イベントは応答と独立行で流してよい（trace_sub済みのとき）。
|
||
- 大きなIRバイナリは `bytes` を base64。JSON IRはそのまま文字列可。
|
||
|
||
## クライアント側（nyash-cli）
|
||
- `nyash run --engine=remote --exe ./nyash-engine-core13 --ir=core13 -- program.ny`
|
||
- 実装は単純: 子プロセスspawn → stdin/stdoutにNDJSON → `load_module`→`call`。
|
||
- `--trace`で `trace_sub` を投げてNDJSONログをファイル保存（そのまま可視化可能）。
|
||
|
||
## 可視化（最小）
|
||
- NDJSON→Markdown表: `jq -r` で列抽出, `|`区切りでテーブル化。
|
||
- NDJSON→CSV: `jq -r '[.event, .func, .block, .ts] | @csv'`。
|
||
- 差分: 2つのトレースを event+順序でzip比較。簡易Python/nyashツールは後続で追加可。
|
||
|
||
## バージョニングと互換
|
||
- `schema` は整数で宣言、互換性は「追加のみ」原則。意味変更や削除は `schema+1`。
|
||
- 不明キーは無視。必須キー欠落は `E_SCHEMA`。
|
||
|
||
## タイムアウト/健全性
|
||
- `call.timeout_ms` を受付。内部でキャンセル/中断可能な範囲で対応。
|
||
- ハートビート: `ping` を定期送信して固まり検出。
|
||
|
||
## セキュリティ
|
||
- ローカル実行のみを想定（最小）。ネットワーク露出はしない。
|
||
- 外部からのファイルアクセス/実行はプロトコルに含めない（エンジンはIR実行に限定）。
|
||
|
||
## 最小試験手順（手動）
|
||
1) エンジンを起動（手動で別ターミナル）。`cat`でNDJSONを流せるならなお良い。
|
||
2) `load_module` を送信（小さなIR）。
|
||
3) `trace_sub` を送信。
|
||
4) `call` を送信 → 応答とイベント列を保存。
|
||
5) jqでCSV化して目視。
|
||
|
||
## 将来拡張（後回し）
|
||
- 長期接続（ソケット/名前付きパイプ）
|
||
- バイナリMessagePack/bincode実装（速度重視）
|
||
- 圧縮（gzip）
|
||
- ストリーム再同期（途中から読み直し）
|