WebServer

実験中 ( 安定保証の対象外 )

この API はまだ形が固まっていません。予告なく変更・削除される ことがあります ( 非互換変更でもメジャー番号は上がりません )。 版の上げ方は バージョン運用 を参照してください。

開発・検証用の API です。REPL / デバッグ窓の整備にあわせて変わります。 組み込みルートは予告なく増えることがあります ( 増えたパスは register で上書きできません )。

WebServer クラスは吉里吉里Z に組み込まれた HTTP + SSE サーバを制御するためのクラスです。このクラスからオブジェクトを作成することはできません。System と同様に WebServer.start(...) のように直接呼び出して使用します。

このサーバはコマンドラインオプションの -replweb によって使用されるもので、TJS からエンドポイントを登録することで、ブラウザ UI や外部からの制御を組むことができます。このクラスは KRKRZ_REPL_WEB を有効にしたビルドでのみ利用できます。

登録するハンドラは handler(req) の形式で、req は以下のキーを持つ辞書です。ハンドラは必ずメインスレッドで実行されます。

• method ... HTTP メソッド ( "GET" / "POST" 等 )
• path ... リクエストパス
• query ... クエリ文字列
• body ... リクエストボディ ( 文字列 )
• bytes ... リクエストボディ ( オクテット。body が空でない場合のみ存在 )

ハンドラの戻り値によってレスポンスが決まります。

• 文字列 ... 200 application/json として返します
• オクテット ... 200 application/octet-stream として返します
• 整数 ... そのステータスコードで空ボディを返します
• void ... 204 を返します
• 辞書 %[status, mime, body] ... 指定した通りに返します
• TJS 例外が発生した場合は 500 を返します

また、以下のルートはサーバ側に組み込まれています ( TJS のメンバではありません )。

• GET / ... ビューワー本体 ( Console / Watch / Pad のタブ UI )
• GET /events ... REPL コンソール用の SSE ストリーム
• POST /cmd ... REPL へのコマンド送信
• GET /sub/<channel> ... 任意チャンネルの SSE 購読
• GET/POST /watch ... 監視式の取得 / 操作
• GET/POST /state ... コントローラ ( System.eventDisabled / 終了要求 )
• POST /pad/exec , GET/POST /pad/file ... Pad ( スクリプトエディタ )
• GET /panels ... 登録されたパネルの一覧 ( 組み込み UI がタブを組むのに使う )
• POST /bye ... ページを閉じる合図

組み込みルートは register より先に判定されます

上のパスは WebServer.register や serveStatic で上書きできません。 自前のエンドポイントには別の接頭辞を使ってください ( 例: /api/ /ui/ )。

日本語などマルチバイトの値は body で受ける

query は percent-encoding されたままの文字列です。これを戻す System.urldecode は Windows ネイティブビルド限定なので、 SDL3 ビルドではクエリで非 ASCII を受け取れません。 文字列の受け渡しは body ( UTF-8 ) を使い、query は数値や識別子など ASCII の指定にとどめるのが安全です。

最小構成の実装例はコアデモ webui にあります ( 静的配信 + 動的 エンドポイント + ゲームからの push を 1 画面にまとめたもの )。

メンバー一覧

プロパティ

• active
• url

メソッド

• register
• registerPanel
• unregisterPanel
• unregister
• serveStatic
• unserveStatic
• broadcast
• start
• startAt
• stop
• openBrowser

---

active

プロパティ \ アクセス: r

解説

サーバが稼働中かどうか

サーバが稼働中の場合に真を返します。読み出し専用。

関連: WebServer.url

---

url

プロパティ \ アクセス: r

解説

待受 URL

サーバの待受 URL ( http://host:port/ 形式 ) を表します。稼働していない 場合は空文字列になります。読み出し専用。

関連: WebServer.active

---

register

メソッド

引数

引数	既定値	説明
prefix	 	ハンドラを割り当てるパスの接頭辞を指定します。
handler	 	handler(req) 形式のハンドラ関数を指定します。

解説

動的ハンドラの登録

指定した prefix に対して動的ハンドラを登録します。マッチングは最長一致で 行われます。同一の prefix に登録した場合は上書きされます。

関連: WebServer.unregister

---

registerPanel

メソッド

引数

引数	既定値	説明
id	 	パネルの識別子。上書き・解除のキーになります。
label	 	タブに表示する名前。
path	 	パネルの中身の URL パス。/ で始まるサーバ上のパスを 指定します ( ローカルのファイルパスではありません )。不正な場合は 登録されず、理由がログへ出ます。

解説

組み込み UI へパネル ( タブ ) を追加する

-replweb の組み込みブラウザ UI ( Console / Watch / Pad ) の右へ、 案件独自のパネルをタブとして 1 枚足します。自前のページを serveStatic で配信しておき、そのパスを path に渡します。

中身は iframe で読み込まれます。組み込みページへスクリプトを差し込む 方式にしていないのは、案件を組み込み UI の内部 DOM へ依存させないためです ( こちらの UI を変えるたびに案件が壊れる、を避ける )。パネルは同一 オリジンなので、fetch や EventSource でサーバを自由に叩けます ( 組み込みの /cmd /watch /pad/exec や、自分で register したエンドポイント )。

同じ id で呼び直すと上書きされます。登録・解除は開いているページへ 即座に反映されます ( タブが増減する )。パネルの中身はそのタブを初めて 開いたときに読み込まれるので、重いツールを登録しても起動は遅くなりません。

WebServer.serveStatic("/tool/", "web/");
WebServer.registerPanel("mytool", "案件ツール", "/tool/tool.html");

関連: WebServer.unregisterPanel

---

unregisterPanel

メソッド

引数

引数	既定値	説明
id	 	削除するパネルの識別子。

戻り値

パネルが見つかって削除できた場合は 1、見つからなかった場合は 0 が返ります。

解説

組み込み UI からパネルを外す

registerPanel で追加したタブを削除します。 開いているページからも即座に消えます。

関連: WebServer.registerPanel

---

unregister

メソッド

引数

引数	既定値	説明
prefix	 	削除するハンドラの接頭辞を指定します。

戻り値

ハンドラが見つかって削除できた場合は 1、見つからなかった場合は 0 が返ります。

解説

動的ハンドラの削除

WebServer.register で登録したハンドラを削除します。

関連: WebServer.register

---

serveStatic

メソッド

引数

引数	既定値	説明
prefix	 	配信対象とするパスの接頭辞を指定します。
storageDir	 	配信元となるストレージのディレクトリを指定します。

解説

静的配信のマウント

prefix 以下への GET リクエストを、storageDir に相対パスを連結した ストレージから配信します。相対パスに .. が含まれる場合は 403 を返します。

関連: WebServer.unserveStatic

---

unserveStatic

メソッド

引数

引数	既定値	説明
prefix	 	削除する静的配信の接頭辞を指定します。

戻り値

マウントが見つかって削除できた場合は 1、見つからなかった場合は 0 が返ります。

解説

静的配信のアンマウント

WebServer.serveStatic で登録した静的配信の マウントを削除します。

関連: WebServer.serveStatic

---

broadcast

メソッド

引数

引数	既定値	説明
channel	 	配信先のチャンネル名を指定します。
text	 	配信するテキストを指定します。

解説

SSE 購読者への配信

/sub/<channel> を購読しているすべての SSE クライアントへ text を push します。 text には複数行を含めることができます。

---

start

メソッド

引数

引数	既定値	説明
port	8899	待受ポート番号を指定します。

戻り値

起動後の稼働状態が返ります。

解説

サーバの起動

127.0.0.1 でサーバを起動します。

関連: WebServer.startAt / WebServer.stop

---

startAt

メソッド

引数

引数	既定値	説明
host	 	待受ホストを指定します。
port	 	待受ポート番号を指定します。

戻り値

起動後の稼働状態が返ります。

解説

ホストを指定したサーバの起動

明示したホストでサーバを起動します。"0.0.0.0" を指定するとすべての ネットワークインターフェースで待ち受けます。

関連: WebServer.start / WebServer.stop

---

stop

メソッド

解説

サーバの停止

サーバを停止します。接続中のクライアントを閉じ、accept スレッドを終了します。

関連: WebServer.start

---

openBrowser

メソッド

引数

引数	既定値	説明
url	""	開く URL を指定します。省略した場合は稼働中のサーバの URL を 使用します。
appMode	true	真を指定すると、まず Edge → Chrome の順に --app= による アプリモードでの起動を試み、いずれも無い場合は OS の既定ブラウザで開きます。

戻り値

成否が返ります。

解説

ブラウザで開く

ブラウザで指定した url を開きます。

関連: WebServer.url

---