hakorune/docs/reference/plugin-system/net-plugin.md

Net Plugin (HTTP over TCP PoC)

最終更新: 2025-08-22

概要

• nyash-net-plugin は Socket/HTTP をプラグインとして提供します。
• HTTP は最小限の HTTP/1.1 実装（GET/POST、ヘッダ、Content-Length）を実ソケットで処理します。

提供Box

• SocketServerBox, SocketClientBox, SocketConnBox
• HttpServerBox, HttpRequestBox, HttpResponseBox, HttpClientBox

nyash.toml 定義例（抜粋）はリポジトリ直下の nyash.toml を参照。

動作仕様（HTTP）

• Server
  • start(port): TCP待受を開始
  • accept(): 接続受理＋リクエスト簡易パース（path/body）→ HttpRequestBox を返す
  • HttpRequestBox.respond(resp): resp の status/header/body を HTTP/1.1 として送出（Connection: close）
• Client
  • get(url), post(url, body): host:port に接続し、HTTP/1.1 リクエストを送出
  • HttpResponseBox は遅延受信。readBody()/getStatus()/getHeader() 呼び出し時に受信・パース

制限:

• Chunked/Keep-Alive/HTTP/2は非対応（PoC）。Content-Length のみ対応。

エラーモデル（PoC）

• BID-FFI の負値（例: -5 PluginError）は Nyash 側で例外（RuntimeFailure）として扱われます。
• タイムアウト系（Socket の acceptTimeout/recvTimeout）はエラーではなく、以下の値を返します:
  • acceptTimeout(ms): タイムアウト時は void
  • recvTimeout(ms): タイムアウト時は 空 bytes（長さ0の文字列）

HTTPエラーハンドリング（重要）

• 接続失敗（unreachable）: Result.Err(ErrorBox) を返す
  • 例: ポート8099に接続できない → Err("connect failed for 127.0.0.1:8099/...")
• HTTPステータスエラー（404/500等）: Result.Ok(HttpResponseBox) を返す
  • 例: 404 Not Found → Ok(response) で response.getStatus() が 404
  • トランスポート層は成功、アプリケーション層のエラーとして扱う

将来の整合:

• ResultBox での返却に対応する設計（Ok(value)/Err(ErrorBox)）を検討中。
• nyash.toml のメソッド宣言に戻り値型（Result）を記載し、ランタイムで自動ラップする案。

並列E2E運用の注意

• 各テストで異なるポートを使用（例: 8080/8081/8090/8091...）
• サーバの stop() と再起動時はポート開放の遅延に注意（短い待機を挟むと安定）
• ログを有効化して競合や順序の問題を診断可能

ログ出力

環境変数で簡易ログを有効化できます。

export NYASH_NET_LOG=1
export NYASH_NET_LOG_FILE=net_plugin.log

stderr とファイルの両方に出力されます。

例

local srv, cli, r, req, resp
srv = new HttpServerBox()
srv.start(8080)

cli = new HttpClientBox()
r = cli.get("http://localhost:8080/hello")

req = srv.accept()
resp = new HttpResponseBox()
resp.setStatus(200)
resp.setHeader("X-Test", "V")
resp.write("OK")
req.respond(resp)

// client side
print(r.getStatus())
print(r.getHeader("X-Test"))
print(r.readBody())