@kubohiroya/turbowarp-http-server 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/LICENSE +373 -0
  2. package/README.ja.md +346 -0
  3. package/README.md +874 -0
  4. package/dist/auth/digest-file.d.ts +17 -0
  5. package/dist/auth/digest-file.js +90 -0
  6. package/dist/auth/digest-file.js.map +1 -0
  7. package/dist/auth/digest.d.ts +23 -0
  8. package/dist/auth/digest.js +139 -0
  9. package/dist/auth/digest.js.map +1 -0
  10. package/dist/cli.d.ts +1 -0
  11. package/dist/cli.js +156 -0
  12. package/dist/cli.js.map +1 -0
  13. package/dist/community.d.ts +81 -0
  14. package/dist/community.js +689 -0
  15. package/dist/community.js.map +1 -0
  16. package/dist/digest-cli.d.ts +1 -0
  17. package/dist/digest-cli.js +159 -0
  18. package/dist/digest-cli.js.map +1 -0
  19. package/dist/extension-manifest.json +441 -0
  20. package/dist/protocol.d.ts +59 -0
  21. package/dist/protocol.js +71 -0
  22. package/dist/protocol.js.map +1 -0
  23. package/dist/server.d.ts +89 -0
  24. package/dist/server.js +650 -0
  25. package/dist/server.js.map +1 -0
  26. package/dist/turbowarp-http-server.js +1110 -0
  27. package/docs/deployment-targets.ja.md +274 -0
  28. package/docs/turbowarp-http-server.architecture.html +15149 -0
  29. package/docs/turbowarp-http-server.architecture.json +1014 -0
  30. package/docs/turbowarp-http-server.architecture.visual-check.1440x900.dark.png +0 -0
  31. package/docs/turbowarp-http-server.architecture.visual-check.1440x900.light.png +0 -0
  32. package/docs/turbowarp-http-server.architecture.visual-check.2048x1320.dark.png +0 -0
  33. package/docs/turbowarp-http-server.architecture.visual-check.2048x1320.light.png +0 -0
  34. package/docs/turbowarp-http-server.architecture.visual-check.html +32 -0
  35. package/docs/turbowarp-http-server.architecture.visual-check.json +547 -0
  36. package/examples/01-hello-form/README.ja.md +46 -0
  37. package/examples/01-hello-form/server.mjs +59 -0
  38. package/examples/02-visitor-counter/README.ja.md +39 -0
  39. package/examples/02-visitor-counter/server.mjs +44 -0
  40. package/examples/03-message-board/README.ja.md +47 -0
  41. package/examples/03-message-board/server.mjs +72 -0
  42. package/examples/04-image-upload/README.ja.md +46 -0
  43. package/examples/04-image-upload/server.mjs +149 -0
  44. package/examples/05-live-camera/README.ja.md +47 -0
  45. package/examples/05-live-camera/server.mjs +147 -0
  46. package/examples/06-scratch-like-community/README.ja.md +82 -0
  47. package/examples/06-scratch-like-community/server.mjs +17 -0
  48. package/examples/README.ja.md +20 -0
  49. package/package.json +75 -0
  50. package/schemas/extension-manifest.schema.json +49 -0
  51. package/src/auth/digest-file.ts +115 -0
  52. package/src/auth/digest.ts +170 -0
  53. package/src/block-definitions.json +417 -0
  54. package/src/cli.ts +172 -0
  55. package/src/community.ts +815 -0
  56. package/src/config.ts +12 -0
  57. package/src/digest-cli.ts +178 -0
  58. package/src/extension-manifest.ts +149 -0
  59. package/src/extension.ts +713 -0
  60. package/src/globals.d.ts +30 -0
  61. package/src/index.ts +8 -0
  62. package/src/protocol.ts +132 -0
  63. package/src/server.ts +880 -0
package/README.ja.md ADDED
@@ -0,0 +1,346 @@
1
+ # TurboWarp-HTTP-Server
2
+
3
+ [English](README.md) | [日本語](README.ja.md)
4
+
5
+ CLI で起動する HTTP ブリッジサーバと、そのサーバへ WebSocket 接続する TurboWarp 機能拡張を同じ package で提供します。
6
+
7
+ **ユーザーガイド:** [English](https://kubohiroya.github.io/turbowarp-http-server/)
8
+
9
+ ## できること
10
+
11
+ - コマンドラインからローカル HTTP/WebSocket ブリッジサーバを起動できます。
12
+ - TurboWarp の Custom Extension として読み込む bundle を生成します。
13
+ - HTTP request/response protocol の確定前でも、TurboWarp とブリッジ間でテキストメッセージを送受信できます。
14
+
15
+ ## 要件と安全性
16
+
17
+ - カスタム拡張機能を有効化した TurboWarp Desktop、TurboWarp Web、または TurboWarp Packager。
18
+ - CLI ブリッジサーバを動かすための Node.js 22 以上。
19
+ - この拡張機能は incoming HTTP request で TurboWarp の hat thread を起動するため、unsandboxed mode が必要です。
20
+
21
+ ## インストール
22
+
23
+ ### CLI ブリッジサーバ
24
+
25
+ このリポジトリから起動する場合:
26
+
27
+ ```bash
28
+ corepack pnpm install
29
+ corepack pnpm run build
30
+ corepack pnpm start -- --host 127.0.0.1 --port 8787
31
+ ```
32
+
33
+ package としてインストールした場合:
34
+
35
+ ```bash
36
+ turbowarp-http-server --host 127.0.0.1 --port 8787
37
+ ```
38
+
39
+ インターネットへ出られない会場 LAN では、htdigest file を使って HTTP Digest 認証を有効化できます。
40
+
41
+ ```bash
42
+ turbowarp-http-digest init ./users.htdigest --realm turbowarp-lan
43
+ turbowarp-http-digest add ./users.htdigest alice --realm turbowarp-lan
44
+
45
+ turbowarp-http-server \
46
+ --host 0.0.0.0 \
47
+ --port 8787 \
48
+ --auth-digest ./users.htdigest \
49
+ --auth-realm turbowarp-lan
50
+ ```
51
+
52
+ Digest 認証は、証明書配布や外部 IdP を使えない trusted LAN 内での簡易的な user 識別を目的とします。既定では無効です。認証済み username は runtime-owned な `x-turbowarp-http-auth-user` request header として TurboWarp handler に渡され、client が同名 header を送っても上書きされます。`/ws` endpoint は localhost peer からの接続だけを受け付けます。
53
+
54
+ TurboWarp handler では、`current auth type`、`current authenticated user`、`current auth provider`、`current auth profile JSON`、`auth profile field [NAME]` の reporter block で認証 context を参照できます。Digest 認証では username を提供します。OAuth 対応 deployment では provider profile data を request auth context として渡し、handler 側で `email`、`name`、`organization.name` のような field を参照できます。
55
+
56
+ 証明書と秘密鍵をすでに用意できる場合は、server を直接 HTTPS で起動できます。
57
+
58
+ ```bash
59
+ turbowarp-http-server \
60
+ --host 0.0.0.0 \
61
+ --port 8787 \
62
+ --tls-cert ./certs/server.crt \
63
+ --tls-key ./certs/server.key
64
+ ```
65
+
66
+ 証明書の発行、更新、配布、OS/browser の trust 設定はこの package の責務外です。Internet-facing deployment では reverse proxy で TLS termination し、認証が必要な場合は Cloudflare/OAuth の deployment path を使います。
67
+
68
+ サーバは次の経路を提供します。
69
+
70
+ | Route | Purpose |
71
+ |---|---|
72
+ | `GET /health` | ヘルスチェック |
73
+ | `GET /ws` | TurboWarp extension が接続する WebSocket endpoint |
74
+ | `GET /@assets/<name>` | resource capability が接続されている場合、Asset Manager の named resource を配信 |
75
+ | `HEAD /@assets/<name>` | body なしで同じ resource metadata を返却 |
76
+ | `PUT /@assets/<name>` | 対応 capability で named resource を作成または atomic replace |
77
+ | `DELETE /@assets/<name>` | 対応 capability で named resource を削除 |
78
+ | `GET /@assets/` | binary payload を含めず metadata/listing を返却 |
79
+ | その他の HTTP route | HTTP forwarding 実装前の一時的な `503 not_connected` 応答 |
80
+
81
+ Sprite route はこれとは別の TurboWarp-facing layer です。`camera` という名前の Sprite は `/camera` を公開でき、Sprite を「隠す」とその route を無効化できます。Sprite handler は HTML、JSON、redirect、`/camera/image.jpg` のような friendly alias を返せますが、`@assets` を Sprite の子 namespace にするのではなく Asset Manager capability を参照します。
82
+
83
+ ### 学習用コミュニティサーバ
84
+
85
+ Issue #10 では、Scratch 風の project sharing app を local learning example 向けに追加しています。既定では無効なので、既存の bridge route と `@assets` route の動作は変わりません。
86
+
87
+ CLI から有効化する例:
88
+
89
+ ```bash
90
+ COMMUNITY=1 corepack pnpm start -- --host 127.0.0.1 --port 8787
91
+ # または
92
+ corepack pnpm start -- --host 127.0.0.1 --port 8787 --community
93
+ ```
94
+
95
+ 有効化時は次の route を提供します。
96
+
97
+ | Route | Purpose |
98
+ |---|---|
99
+ | `GET /` | 作品一覧 HTML と、login user 向け upload form |
100
+ | `GET /signup` / `POST /signup` | demo password registration |
101
+ | `GET /login` / `POST /login` | demo password login |
102
+ | `POST /logout` | session logout |
103
+ | `GET /auth/:provider/start` | configured OAuth demo flow の開始 |
104
+ | `GET /auth/:provider/callback` | OAuth demo flow の完了 |
105
+ | `POST /projects` | SB3 project と optional thumbnail の upload |
106
+ | `GET /projects/:id` | project detail HTML |
107
+ | `GET /projects/:id.sb3` | SB3 download |
108
+ | `POST /projects/:id/remix` | 元 project と関連付いた remix 作成 |
109
+ | `POST /projects/:id/update` | owner だけが実行できる metadata edit |
110
+ | `POST /projects/:id/replace` | owner だけが実行できる SB3 と thumbnail の replace |
111
+ | `POST /projects/:id/delete` | owner だけが実行できる project deletion |
112
+
113
+ demo password は Node 標準 `crypto.scrypt` で hash 化して保存します。session は HTTP-only `SameSite=Lax` cookie、HTML form の POST には CSRF token を使い、multipart body は form parse 前に上限を適用し、SB3 と thumbnail は file ごとの size limit、MIME type、file signature を検証します。owner 以外による owner-only 変更は拒否します。OAuth provider は次の環境変数が揃った場合だけ有効になります。
114
+
115
+ ```bash
116
+ COMMUNITY_OAUTH_DEMO_CLIENT_ID=demo-client
117
+ COMMUNITY_OAUTH_DEMO_AUTHORIZATION_URL=https://example.test/oauth/authorize
118
+ COMMUNITY_OAUTH_DEMO_REDIRECT_URI=http://127.0.0.1:8787/auth/demo/callback
119
+ COMMUNITY_OAUTH_DEMO_SCOPE=profile
120
+ ```
121
+
122
+ この community server は local educational implementation であり、公開運用向けではありません。internet に公開する前に、in-memory storage を durable storage に置き換え、rate limit と abuse moderation、HTTPS と secure cookie、完全な OAuth token/userinfo exchange、必要な email または external identity verification、upload scan、audit log、backup、retention、takedown、incident-response 手順を追加してください。
123
+
124
+ ## Asset Manager Resource Serving
125
+
126
+ HTTP server は camera-agnostic です。`turbowarp-asset-manager` のような外部 capability が提供する generic named resource を配信し、private field を読んだり Asset Manager の storage を複製したりしません。
127
+
128
+ generic Asset Manager namespace は `/@assets/` を root にします。これは Sprite route の管理下ではなく、background/server-side resource capability が管理します。Sprite route は friendly alias を提供できますが、generic resource route は global に保ちます。
129
+
130
+ | Resource | HTTP route |
131
+ |---|---|
132
+ | Resource `live-camera` | `/@assets/live-camera` |
133
+ | Resource `logo` | `/@assets/logo` |
134
+
135
+ resource capability の境界では、logical resource name、MIME type、consistent snapshot としての binary bytes、byte length、ETag に使える replacement identity、任意の last-modified timestamp、namespace publication policy を扱います。
136
+
137
+ resource response は `Content-Type`、`Content-Length`、可能な場合は `ETag`、提供されている場合は `Last-Modified`、そして `Cache-Control` を返します。ETag または last-modified がある場合の既定 cache policy は `no-cache`、validation metadata がない場合は `no-store` です。`HEAD` は `GET` と同じ metadata を body なしで返します。
138
+
139
+ `PUT` は request body bytes と `Content-Type` を使い、capability 経由で resource を作成または置換します。server は configurable body-size limit を適用し、capability が拒否する MIME type を `415` にし、置換は後続 request へ atomic に見えるようにします。進行中の `GET` は開始時点の snapshot を受け取ります。
140
+
141
+ `/_tw-http/` は management namespace として予約し、asset route として扱いません。`/camera/@assets/live-camera` のような path は generic Asset Manager route ではありません。必要なら Scratch/TurboWarp handler で friendly Sprite URL を `/@assets/<name>` へ alias します。authorization hook が設定されている場合は `GET`、`HEAD`、`PUT`、`DELETE`、listing に一貫して適用します。structured log には route、resource name、MIME type、byte count、status などの metadata だけを含め、binary request/response body は含めません。
142
+
143
+ ## Sprite Route Model
144
+
145
+ TurboWarp-facing route は project object と自然に対応させます。
146
+
147
+ | TurboWarp object | Public route |
148
+ |---|---|
149
+ | Stage/background script | `/` |
150
+ | Sprite `camera` が表示中 | `/camera` |
151
+ | Sprite `camera` が非表示 | route disabled |
152
+
153
+ これにより Scratch 上の操作が HTTP 公開状態と直感的につながります。Sprite を「表示する」と route が公開され、「隠す」と route が取り下げられます。Asset Manager resource は `/@assets/<name>` に global に置くため、同じ resource を複数の Sprite route から storage duplication なしに再利用できます。
154
+
155
+ live camera page は次のように扱えます。
156
+
157
+ ```text
158
+ Sprite: camera
159
+ visible -> /camera is enabled
160
+ hidden -> /camera is disabled
161
+
162
+ GET /camera
163
+ -> Sprite handler が HTML page を返す
164
+
165
+ GET /camera/image.jpg
166
+ -> /@assets/live-camera を返す friendly handler/alias
167
+ ```
168
+
169
+ つまり `/camera/image.jpg` は Sprite route の判断で、`/@assets/live-camera` は generic Asset Manager resource endpoint です。
170
+
171
+ ## デプロイターゲット検討
172
+
173
+ Sprite route と HTTP handler block を公開可能な serverless application へ変換する構想については、[デプロイ先と技術スタックの選定メモ](docs/deployment-targets.ja.md) にまとめています。MVP では Cloudflare Workers 向け TypeScript + Hono 生成を第一候補にし、D1/R2/KV/Durable Objects の使い分けと外部 IdP 認証連携の方針を整理しています。
174
+
175
+ ## Response Content Builders
176
+
177
+ HTTP response body を組み立てやすくするため、builder-style の補助ブロックを追加しています。これらはこの package 内の最小実装で、runtime dependency として `turbowarp-html` や `turbowarp-markdown` は追加しません。
178
+
179
+ Markdown builder は `md:1` のような opaque handle を返します。ブロックをチェインして content を追加し、最後に Markdown text として render します。
180
+
181
+ ```text
182
+ new markdown document
183
+ markdown [md:1] with heading level [1] [Status]
184
+ markdown [md:1] with paragraph [OK]
185
+ render markdown [md:1]
186
+ ```
187
+
188
+ HTML builder は `html:1` のような opaque handle を使います。text と attribute は escape され、`onclick` のような event-handler attribute は無視され、URL attribute は保守的な safe scheme のみを受け付け、未知の tag は `div` に fallback します。
189
+
190
+ ```text
191
+ new HTML element [section]
192
+ HTML text [Live camera]
193
+ HTML [section] with child [text]
194
+ render HTML document title [Camera] body [section]
195
+ ```
196
+
197
+ server diagnostics 向けに、`HTTP log viewer HTML` は virtual-scroll log viewport を持つ self-contained HTML document を返します。`record HTTP log [ENTRY]` で structured log JSON を追加し、`clear HTTP logs` で消去できます。明示的な JSON array から viewer を作る場合は `HTTP log viewer HTML from [LOGS]` を使います。
198
+
199
+ ## Request Protocol And Blocks
200
+
201
+ `/@assets` で処理されない通常の HTTP route は、CLI server から connected TurboWarp extension へ WebSocket 経由で forward されます。各 request には一意の request ID が付き、request context は ID ごとに分離されます。
202
+
203
+ protocol v1 の request message は、query parameter と header の複数値を保持します。
204
+
205
+ ```json
206
+ {
207
+ "type": "request",
208
+ "protocol": "turbowarp-http-server",
209
+ "version": 1,
210
+ "id": "req-1",
211
+ "method": "GET",
212
+ "url": "http://127.0.0.1:8787/users/42?tag=a&tag=b",
213
+ "path": "/users/42",
214
+ "route": "/users/:id",
215
+ "pathParams": {"id": "42"},
216
+ "query": {"tag": ["a", "b"]},
217
+ "headers": {"accept": ["text/html"]},
218
+ "body": {"kind": "empty"},
219
+ "clientAddress": ""
220
+ }
221
+ ```
222
+
223
+ TurboWarp blocks は selected current request を参照できます。
224
+
225
+ ```text
226
+ current HTTP method
227
+ current request path
228
+ current request URL
229
+ request header [name]
230
+ query parameter [name]
231
+ path parameter [name]
232
+ current request body
233
+ current request content type
234
+ current request ID
235
+ ```
236
+
237
+ simple query/header reporter は最初の値を返します。wire protocol は全値を保持するため、将来 list-oriented block を追加しても protocol を壊さずに済みます。
238
+
239
+ response blocks は current request の response builder を変更し、最後に response message として完了します。
240
+
241
+ ```text
242
+ set HTTP status [200]
243
+ set response header [name] to [value]
244
+ remove response header [name]
245
+ set response body [body]
246
+ send response [body]
247
+ respond with text [body]
248
+ respond with HTML [body]
249
+ respond with JSON [body]
250
+ ```
251
+
252
+ response status の既定値は `200` です。`100` から `599` の範囲外の status、不安全な response header、CR/LF を含む header injection value、`Content-Length` のような runtime-owned header は Node.js の HTTP response API に届く前に無視または拒否されます。server boundary では `HEAD`、`204`、`205`、`304` の body を抑止します。
253
+
254
+ bridge が未接続の場合、通常 route は `503` を返します。connected bridge が timeout までに応答しない場合は `504`、pending request 中に WebSocket が切断された場合は `502` を返します。
255
+
256
+ ## Live-Camera Pattern
257
+
258
+ 低頻度 camera publishing は、次の 3 つを独立して組み合わせます。
259
+
260
+ ```text
261
+ TurboWarp Camera Source
262
+ -> 10 秒ごとに current frame を capture
263
+ -> Asset Manager resource "live-camera" を replace
264
+ -> HTTP Server が /@assets/live-camera を配信
265
+ -> browser が stable URL を読み込む
266
+ ```
267
+
268
+ HTTP server は `turbowarp-camera-source` や `turbowarp-html` に依存しません。Camera Source は snapshot を作り、Asset Manager が named resource を所有し、HTTP Server は generic resource URL を配信します。
269
+
270
+ ブロックレベルの例:
271
+
272
+ ```text
273
+ forever
274
+ capture current camera frame
275
+ replace asset [live-camera] with captured JPEG bytes
276
+ wait 10 seconds
277
+ end
278
+ ```
279
+
280
+ 外部 consumer は stable URL を使えます。
281
+
282
+ ```text
283
+ /@assets/live-camera
284
+ ```
285
+
286
+ 必要なら Scratch/TurboWarp route handler で次の friendly alias を用意できます。
287
+
288
+ ```text
289
+ /camera/image.jpg -> /@assets/live-camera
290
+ ```
291
+
292
+ `turbowarp-html` で生成した HTML page が `<img>` を 10 秒ごとに refresh する構成でも、cache correctness は timestamp query string ではなく HTTP validation headers で担保します。Asset Manager から replacement identity が得られる場合、client は stable URL を ETag で revalidate し、古い browser cache に固定されず最新 snapshot を受け取れます。
293
+
294
+ ### TurboWarp extension bundle
295
+
296
+ 1. [`dist/turbowarp-http-server.js`](dist/turbowarp-http-server.js?raw=1) をダウンロードします。
297
+ 2. TurboWarp の **Extensions** を開きます。
298
+ 3. **Custom Extension** を選び、ファイルを読み込みます。
299
+
300
+ レビュー済みの JavaScript build をこのリポジトリへコミットする運用なので、利用者はインストールのために Node.js を用意する必要はありません。
301
+
302
+ ### npm package
303
+
304
+ レビューした exact version をインストールします。
305
+
306
+ ```bash
307
+ pnpm add --save-exact @kubohiroya/turbowarp-http-server@0.1.0
308
+ ```
309
+
310
+ standalone bundle は次の場所から読み込めます。
311
+
312
+ ```text
313
+ node_modules/@kubohiroya/turbowarp-http-server/dist/turbowarp-http-server.js
314
+ ```
315
+
316
+ version 固定の CDN URL は次の形式です。
317
+
318
+ ```text
319
+ https://cdn.jsdelivr.net/npm/@kubohiroya/turbowarp-http-server@0.1.0/dist/turbowarp-http-server.js
320
+ ```
321
+
322
+ ## 開発
323
+
324
+ `packageManager` で宣言された pnpm と Node.js 22 以上を使います。
325
+
326
+ ```bash
327
+ corepack enable
328
+ pnpm install --frozen-lockfile
329
+ pnpm check
330
+ ```
331
+
332
+ 主なコマンド:
333
+
334
+ | Command | Purpose |
335
+ |---|---|
336
+ | `pnpm dev` | TurboWarp extension bundle を watch rebuild |
337
+ | `pnpm run dev:server` | CLI ブリッジサーバを watch mode で起動 |
338
+ | `pnpm start` | build 済み CLI ブリッジサーバを起動 |
339
+ | `pnpm run test` | テスト実行 |
340
+ | `pnpm run docs` | ブロックドキュメント再生成 |
341
+ | `pnpm run check:dist` | コミット済み build artifact の検証 |
342
+ | `pnpm run pack:check` | npm package 内容の確認 |
343
+
344
+ ## ライセンス
345
+
346
+ [Mozilla Public License 2.0](LICENSE) (SPDX: `MPL-2.0`)。