80 lines
3.0 KiB
Markdown
80 lines
3.0 KiB
Markdown
# 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()` と再起動時はポート開放の遅延に注意（短い待機を挟むと安定）
|
||
- ログを有効化して競合や順序の問題を診断可能
|
||
|
||
## ログ出力
|
||
環境変数で簡易ログを有効化できます。
|
||
|
||
```bash
|
||
export NYASH_NET_LOG=1
|
||
export NYASH_NET_LOG_FILE=net_plugin.log
|
||
```
|
||
|
||
stderr とファイルの両方に出力されます。
|
||
|
||
## 例
|
||
```nyash
|
||
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())
|
||
```
|