探索メモ: MoonBit の Workers 用アダプターを汎用化する #

http（ホストに依存しない部分） #

moon info の出力（moonbit/http/pkg.generated.mbti）から、主なものを抜き出す。

pub struct Request {
  verb : String          // メソッド。`method` は予約語なので使えない
  url : String           // ホストから受け取ったまま
  host : String
  raw_path : String      // エスケープしたまま
  path : String          // デコードした後
  raw_query : String
  headers : Headers
  body : Bytes
  env : Map[String, String]     // Worker の変数など、要求の外から渡るもの
  params : Map[String, String]  // Router が埋める wildcard の値
}
pub fn Request::Request(verb~ : String, url~ : String, headers? : Headers, body? : Bytes, env? : Map[String, String]) -> Self raise BadRequest
pub fn Request::query(Self) -> Values
pub fn Request::param(Self, String) -> String
pub fn Request::text(Self) -> String
pub fn Request::json(Self) -> Json raise BadRequest
pub fn Request::form(Self) -> Form raise BadRequest

pub(all) enum Body { Text(String); Binary(Bytes) }
pub struct Response { status : Int; headers : Headers; body : Body }
pub fn Response::Response / text / html / json / typed / redirect
pub fn Response::header(Self, String, value~ : String) -> Unit   // その場で書き換える。`..header(..)` でつなぐ

pub struct Router { ... }
pub fn Router::Router(decoded_path? : Bool, not_found? : Handler, method_not_allowed? : (Request, Array[String]) -> Response) -> Self
pub fn Router::handle(Self, String, Handler) -> Unit
pub fn Router::serve(Self, Request) -> Response

• Headers は名前と値の組の配列で、名前は大文字小文字を区別せずに引く。同じ名前を何度も持てる（Set-Cookie）。
• Values はクエリーや urlencoded のフォームの組の配列。get は最初の値、get_all はすべての値。
• Form は、ファイルでない欄の Values と、File（欄の名前、ファイル名、Content-Type、Bytes）の配列。
• エラーは BadRequest 1 つにまとめた。要求の解釈に失敗したら投げ、http/wasm は 400 で返す。

ルーター #

Go 1.22 の ServeMux のパターンをまねた。"[METHOD ]/path" で、セグメントはリテラル、{name}（1 セグメント、空は不可）、{name...}（残り全部）、{$}（そこで終わる）。/ で終わるパターンは、その下のすべてのパスに当たる。

• GET のパターンは HEAD にも当たる。
• パスに当たるパターンが、ほかのメソッドのものしかなければ 405 と Allow を返す。何にも当たらなければ 404。どちらも Router::Router の引数で差し替えられる。
• **優先順位**: より狭いパターンが勝つ。セグメントごとに、リテラル > {$} > {name} > {name...} > / で終わる部分木の順に比べ、同じならメソッドを指定したほうが勝つ。登録の順番は、同じ強さのときだけ効く。Go は重なりがあいまいなパターンを登録すると panic するが、こちらは登録の順で決める。
• **パスの分け方**: 既定では、エスケープしたままのパスを / で分けてから、セグメントごとにデコードする（Go 1.22 と同じ）。/posts/a%2Fb の {slug} は a/b になる。decoded_path=true にすると、デコードした後のパスを / で分ける。ブログは後者を使う（下の「ブログの載せ替え」）。
• 足りないもの: {slug}.md のような、wildcard の後ろに続く接尾辞のパターンはない（ブログはハンドラーで接尾辞を見ている）。ホスト名でのルーティング、/a から /a/ への自動のリダイレクト、ミドルウェアの仕組みもない。ミドルウェアは、ハンドラーを包む関数を書けば足りる（ブログのメソッドの確認とリダイレクトがそう）。

http/wasm（受け渡し） #

PR #31 の案 D'（線形メモリに UTF-8 でまとめて書く）を、要求の全体を運べるように広げた。

要求（JS が番地 0 から書く）:

method \n url \n (name \t value \n)* \n (name \t value \n)* \n body

メソッド、URL、ヘッダー、空行、env、空行、本文（バイト列のまま）。

応答（Wasm が上に書く。serve は長さを返す）:

status \n (name \t value \n)* \n body

• 本文の前までは UTF-8 のテキストで、名前と値に改行は入らない（Headers が改行を受け付けないため）。値にはタブが入りうるので、名前と値は**最初の**タブで分ける。PR #31 の worker.mjs は split("\t") で全部のタブで分けていたので、タブを含む値が壊れる可能性があった（ブログの応答のヘッダーには入らない）。
• env は、文字列の値で改行を含まないものだけを渡す（vars の JSON の値やバインディングのオブジェクトは渡さない）。PR #31 では BASE_URL だけを決め打ちで渡していた。
• 応答の本文は Body::Text なら UTF-8 に書き、Body::Binary ならバイトをそのまま写す。
• **本文の上限**: wasmApp の maxBodySize（既定は 1 MiB）を超える本文には、Wasm を呼ばずに 413 を返す。本文はストリームのまま上限まで読み、超えたらそこで捨てる（Content-Length のない要求にも効く）。Wasm の線形メモリは一度増えると減らないので、上限がないと、大きな POST を 1 つ送るだけで isolate のメモリ（128 MB）を食いつぶしうる。Workers は要求の本文をプランに応じて 100 MB 以上まで通す。PR #31 のアダプターは本文を読まなかったので、この危険は汎用にして初めて生じた。
• JS の側では、101、103、204、205、304 の応答は本文を null にする。new Response(body, { status: 204 }) は本文があると TypeError になる。ブログでは起きなかったが、汎用にすると要る。

アプリから見た形 #

let app : @http.Router = {
  let r = @http.Router()
  r.handle("GET /hello/{name}", req => @http.Response::text(200, "hello, \{req.param("name")}\n"))
  r.handle("POST /form", req => { ... req.form() ... })
  r
}

pub fn serve(n : Int) -> Int {
  @wasm.handle(n, req => app.serve(req))
}

import wasm from "../../../../_build/wasm-gc/release/build/pkg/http/wasm/integration/integration.wasm";
import { wasmApp } from "../../http/wasm/adapter.mjs";
export default wasmApp(wasm);

wasmApp は fetch のほかに、応答を部品（{ status, headers, body }）で返す call も返す。ブログの worker.mjs は call の結果をキャッシュし、toResponse で毎回 Response を作る（PR #31 の案 I をそのまま残した）。 ブログは本文を読まない（GET と HEAD 以外は 404）ので、worker.mjs は本文のない Request を作り直して call に渡す。413 にせず、Go 版と同じ 404 を返すため。50,000,000 B の POST にも、Go 版と同じ 404 を返した（wrangler dev）。 new Request(request, { body: null }) では本文が消えない（Node で確かめた。init.body が null でも、元の要求の本文が使われる）。new Request(request.url, request) も、request を init として読むので本文が付いてくる。new Request(url, { method, headers }) と書く。

1. ライブラリへの切り出し #

worker/memory.mbt を http/wasm に移し、要求の解釈を wire 形式に置き換えた。ブログの worker は、req.env の BASE_URL で Site を読み、Site::render(req.path, query=req.raw_query, verb=req.verb) の結果を @http.Response に直すだけになった。

2. 例（moonbit/pkg/http/wasm/integration） #

ライブラリの機能を一通り使う例を作った。make test は Node で、make dev-echo は wrangler dev で動かす（デプロイはしない）。

ほかに、200,000 B の本文（線形メモリの最初の 1 ページ、64 KiB を超える）、壊れたエスケープのパス（/%zz は 400）、HEAD（GET のルートに当たり、本文なし）も確かめた。

3. ブログの載せ替え #

Site::render の手書きの分岐を Router にした（Site::handle）。

• メソッドの確認（GET と HEAD 以外は 404）と、正規化したパスへのリダイレクトは、Go 版の route と同じくルーターの前に置いた。どちらもルーターの仕組みでは書けない（メソッドが違えば 405 ではなく 404 にしたい、すべてのパスに先にかけたい）ので、ハンドラーを包む形になる。
• **decoded_path が要った。** Go 版は r.URL.Path（デコードした後）で分岐するので、/docs%2F は /docs/ の一覧になる。既定の分け方（Go 1.22 の ServeMux と同じ）では docs/ という 1 つのセグメントになって 404 になり、make compare で一致しなかった。ブログは手書きの分岐を移植したもので、ServeMux とは振る舞いが違う、というのが理由。
• site の Response と、パスのデコード（unescape、unescape_path）は消し、http のものを使うようにした。Site::render はテストのために残し、パスとクエリーから @http.Request を作って handle を呼ぶ。
• ルーターは最初の要求で作り、Site に持たせる。

Go 版との比較 #

make dev とローカルの Go 版（-base-url https://blog.podhmo.workers.dev）を、55 パスで比べた。/ と /docs/ からたどれる記事と文書とその .md 版、/docs、/docs?x=1、//posts/../、/_livereload.js、存在しないパス、/favicon.svg、/site.css（?v=other 付きも）、PR #31 の変なエスケープの 14 パス、/posts/hell%6F。

• /%FF// は PR #31 の案 H の節にある既知の違い。
• POST の /posts/hello、/docs、/ は、どちらも 404 で本文が一致した。
• 最初に比べたとき、/docs/TODO などが一致しなかった。Go 版の repodocs は go generate でコピーした文書を埋め込むので、TODO.md を書き換えた後に go generate ./examples/blog/repodocs を忘れていた。アダプターとは関係ない。
• 本文の上限を入れた版を make deploy で blog にデプロイし（Total Upload 310.05 KiB、gzip 後 98.60 KiB、Worker Startup Time 2 ms）、同じ 55 パスで比べた。一致しないのは PR #31 の案 H の節と同じ /%FF//、/%zz、/a%00b の 3 つだった。50,000,000 B の POST にも、Go 版と同じ 404 を返した。

サイズ #

同じ文書を埋め込んだビルドで比べた（-Oz の後）。

• 切り出しで増えたのは、ヘッダーと env の解釈と Request の組み立て。Router を使うと、さらに約 3 KB 増える。
• 埋め込んだ文章がない echo.wasm でも 92 KB ある。中身（JSON の解析と文字列化、Map、ルーター）の内訳は見ていない。

処理時間（Node） #

PR #31 と同じ測り方（fetch に Request を渡して本文を読み終えるまで、1,000 回 × 5 回の中央値）。キャッシュは使わない。user-agent と accept のヘッダーを付けた。load average は 4〜6。

• 差はばらつきの範囲。ヘッダーを渡すぶんの増え方は、/ で 1 µs 前後。
• 本文をすべて写すコストは、本文の 1 バイトあたり約 1.4 ns（1,000,000 B の本文で、本文を読まない 405 の応答が約 1.4 ms）。
• ただし、本文を文字列にして JSON で返す echo のルートは、1 バイトあたり約 30 ns かかった（1,000,000 B で約 33 ms）。decode_lossy、Json::stringify、コード単位ごとの書き戻しのどれが重いのかは分けて測っていない。ブログのフォームくらいの大きさ（数 KB）なら数十 µs で済む。
• 典型的なブラウザーのヘッダー（9 個、約 700 B）を付けると、echo の GET /hello/x は 8.5 µs から 15.5 µs になる。ヘッダーは 1 つずつ Headers に積むので、本文より 1 バイトあたりが重い。