@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
@@ -0,0 +1,274 @@
1
+ # デプロイ先と技術スタックの選定メモ
2
+
3
+ このメモは、TurboWarp/Scratch 風のブロックで表現された HTTP ハンドラを、公開可能なサーバレスアプリへ変換してデプロイするための初期方針をまとめる。
4
+
5
+ ## 結論
6
+
7
+ MVP の生成ターゲットは **Cloudflare Workers 向け TypeScript + Hono** を第一候補にする。
8
+
9
+ 理由は次の通り。
10
+
11
+ - このリポジトリの HTTP 実装が Hono と Fetch API の `Request` / `Response` モデルに寄っている。
12
+ - Cloudflare Workers は TypeScript を第一級に扱える。
13
+ - Hono は Cloudflare Workers、Vercel、Netlify、AWS Lambda、Node.js、Deno など複数 runtime に展開しやすい。
14
+ - ブロックで表現される `method`、`path`、`query`、`header`、`body`、`status`、`response body` は Fetch API/Hono の抽象と対応しやすい。
15
+ - Cloudflare Workers には D1、R2、KV、Durable Objects というストレージ選択肢があり、ブロック由来の状態を用途別に永続化できる。
16
+
17
+ MVP では自前の OAuth/OIDC Provider は作らない。Google、Microsoft、GitHub アカウント連携を外部 IdP または Cloudflare Access に任せ、生成アプリ側は認証済みユーザー情報の参照と JWT/Access 検証に絞る。Apple Sign in は初期対象から外す。
18
+
19
+ ## デプロイ先候補
20
+
21
+ | 優先度 | デプロイ先 | 生成言語/形態 | 相性 | 主な用途 | 注意点 |
22
+ |---:|---|---|---:|---|---|
23
+ | 1 | Cloudflare Workers | TypeScript + Hono | ◎ | 軽量 HTTP API、HTML/JSON 返却、低レイテンシな公開、D1/R2/KV 連携 | Node.js 専用 API は避ける。長時間処理、大容量処理、ローカルファイル前提の設計は不向き |
24
+ | 2 | Vercel Functions | TypeScript/Node.js + Hono | ◎ | フロントエンド同梱、GitHub 連携、Next.js などとの統合 | Edge Runtime と Node.js Runtime の違いを明確にする。永続状態は外部 DB が必要 |
25
+ | 3 | Firebase Functions / Cloud Run functions | TypeScript/Node.js | ○ | Firebase Auth、Firestore、Storage を使うアプリ | Firebase 固有 SDK と設定に寄る。Hono を使う場合は entrypoint adapter が必要 |
26
+ | 4 | Google Cloud Run | Hono + Node.js server または container | ○ | WebSocket、長時間処理、独自サーバ構成、ブリッジサーバ自体の公開 | コンテナ、IAM、課金設定などの学習コストが上がる |
27
+ | 5 | Supabase Edge Functions | TypeScript/Deno + Hono | ○ | Supabase DB/Auth と一体化した軽量 API | Deno/npm 互換差分と Supabase CLI 前提の運用に注意 |
28
+ | 6 | AWS Lambda | TypeScript/Node.js + Hono adapter | △〜○ | 本格クラウド、IAM、API Gateway、企業利用 | 強力だが、初期ユーザー向けには設定が重い |
29
+ | 7 | Netlify Functions / Edge Functions | TypeScript + Hono | ○ | 静的サイト + 軽い API | 配置規約と runtime 差分に合わせる必要がある |
30
+
31
+ MVP は Cloudflare Workers に集中し、IR と adapter を分けておく。これにより、後から Vercel/Firebase 向けの entrypoint と storage adapter を追加できる。
32
+
33
+ ## 生成コードの基本形
34
+
35
+ 生成ツールは、ブロックを直接 Cloudflare Workers のコードへ落とすのではなく、一度中間表現に変換する。
36
+
37
+ ```text
38
+ TurboWarp blocks
39
+ -> route/action/storage/auth を持つ IR
40
+ -> TypeScript/Hono application
41
+ -> Cloudflare Workers scaffold
42
+ ```
43
+
44
+ 想定する生成物は次の構成にする。
45
+
46
+ ```text
47
+ generated-app/
48
+ src/index.ts
49
+ src/routes.generated.ts
50
+ src/auth.ts
51
+ src/storage.ts
52
+ migrations/0001_init.sql
53
+ wrangler.jsonc
54
+ .dev.vars.example
55
+ README.md
56
+ ```
57
+
58
+ Cloudflare Workers 向け entrypoint は `fetch(request, env, ctx)` を受け取り、Hono app が routing と response 生成を担当する。
59
+
60
+ ## ブロックと生成コードの対応
61
+
62
+ | TurboWarp 側の概念 | IR 上の意味 | TypeScript/Hono での対応 | 注意点 |
63
+ |---|---|---|---|
64
+ | Stage/background script | root route | `app.get('/')` など | `/` 以下の HTTP handler として扱う |
65
+ | Sprite 名 `camera` | sprite route namespace | `app.get('/camera')` | Sprite の表示/非表示による公開状態は、デプロイ後は静的設定または環境変数に変換する |
66
+ | `when HTTP request received` | handler entry | route callback | デプロイ先ではイベントではなく通常の HTTP 関数として実行する |
67
+ | `current HTTP method` | request method | `c.req.method` | `GET`/`POST`/`PUT`/`DELETE` などの分岐に使う |
68
+ | `current request path` | URL path | `new URL(c.req.url).pathname` | route pattern と実 path を区別する |
69
+ | `query parameter [NAME]` | query map | `c.req.query(name)` または `URLSearchParams.getAll()` | 複数値 query を将来扱えるようにする |
70
+ | `path parameter [NAME]` | path params | `c.req.param(name)` | `/users/:id` のような route pattern から得る |
71
+ | `request header [NAME]` | request headers | `c.req.header(name)` | header 名は小文字正規化する |
72
+ | `current request body` | text body | `await c.req.text()` | JSON、form、multipart は別 block/IR に分ける |
73
+ | `set HTTP status [STATUS]` | response status | `return c.text(body, status)` など | `100..599` の範囲に検証する |
74
+ | `set response header` | response headers | `c.header(name, value)` | `Content-Length` など runtime-owned header は禁止する |
75
+ | `respond with text` | text response | `return c.text(body)` | charset を統一する |
76
+ | `respond with HTML` | HTML response | `return c.html(html)` | HTML builder の escape 規則を生成 runtime にも持たせる |
77
+ | `respond with JSON` | JSON response | `return c.json(value)` | 文字列 JSON より構造化 JSON block を将来追加したい |
78
+ | Asset Manager resource | object storage | R2 + D1 metadata | binary は R2、検索/権限は D1 に分ける |
79
+ | Scratch 変数/リスト | persistent state | D1/KV/Durable Objects | Worker の global 変数は永続状態として扱わない |
80
+
81
+ ## 認証方針
82
+
83
+ 自前の OAuth/OIDC Provider は作らない。Google、Microsoft、GitHub でのログイン連携は外部の認証基盤に任せる。
84
+
85
+ | レベル | 内容 | MVP での扱い | 用途 |
86
+ |---|---|---:|---|
87
+ | Level 0 | 認証なし、secret token、Basic auth | ○ | 個人用、Webhook、学習用 |
88
+ | Level 1 | Cloudflare Access で Worker 全体または一部 route を保護 | ○ | 管理画面、限定公開、チーム/学校向け |
89
+ | Level 2 | 外部 IdP または auth broker の JWT を Worker で検証 | ○ | 一般ユーザー向け API、Google/Microsoft/GitHub login |
90
+ | Level 3 | OAuth/OIDC login flow を Worker 内で直接実装 | MVP では対象外 | provider-specific な高度な認証 |
91
+
92
+ ブロック側には provider 固有の callback 処理を見せず、抽象化された user context だけを公開する。
93
+
94
+ ```ts
95
+ type AuthUser = {
96
+ id: string;
97
+ email?: string;
98
+ name?: string;
99
+ provider?: 'google' | 'microsoft' | 'github';
100
+ claims: Record<string, unknown>;
101
+ };
102
+ ```
103
+
104
+ | ブロック/IR | 生成コードの役割 |
105
+ |---|---|
106
+ | `require login` | Hono middleware で未ログインなら redirect または `401` |
107
+ | `if current user logged in` | auth context の有無で分岐 |
108
+ | `current user id` | JWT の `sub` または Cloudflare Access の identity |
109
+ | `current user email` | JWT claim または Access header/JWT |
110
+ | `current user provider` | `google`、`microsoft`、`github` など |
111
+ | `current user claims [name]` | allowlist された claim のみ参照 |
112
+ | `logout URL` | 認証 broker または Access の logout endpoint に redirect |
113
+
114
+ Cloudflare Access を使う場合は、Access が付与する JWT/header を Worker 側で検証または参照する。Cloudflare は `Cf-Access-Jwt-Assertion` header の検証を案内している。
115
+
116
+ Secrets はコードに埋め込まない。client secret、JWT issuer/audience、cookie secret などは Wrangler secrets または Cloudflare の Variables and Secrets で注入する。ローカル開発用の `.dev.vars` や `.env` は commit 対象にしない。
117
+
118
+ ## 永続ストレージ方針
119
+
120
+ Cloudflare Workers では、Worker の module/global 変数を永続状態として使わない。cold start、runtime 再利用、複数 isolate、複数 region の影響で、値の保持や共有は保証できない。
121
+
122
+ 標準方針は **D1 を主 DB、R2 をファイル置き場、KV を設定/キャッシュ、Durable Objects を強い一貫性が必要な小さな状態** とする。
123
+
124
+ | 用途 | 推奨ストレージ | 理由 |
125
+ |---|---|---|
126
+ | 掲示板、投稿、コメント、履歴、一覧 | D1 | SQLite 互換の SQL DB なので検索、並び替え、絞り込みに向く |
127
+ | ユーザー別データ | D1 | `owner_id` で絞り込みや権限判定をしやすい |
128
+ | Scratch リスト相当 | D1 | append/list/delete/order の操作に合う |
129
+ | Scratch 変数相当 | D1 または KV | ユーザー別/履歴ありなら D1、低頻度更新の設定値なら KV |
130
+ | 画像、音声、SB3、アップロードファイル | R2 | binary object storage として扱う |
131
+ | asset metadata | D1 | R2 object key、MIME type、size、owner、公開状態を検索可能にする |
132
+ | route 公開設定、feature flag | KV | read-heavy で低頻度更新なら扱いやすい |
133
+ | HTML fragment cache、JWKS cache | KV | eventual consistency が許容される cache に向く |
134
+ | 正確なカウンタ、同時更新される部屋状態 | Durable Objects または D1 | KV の read-modify-write は取りこぼしやすい |
135
+
136
+ ### D1
137
+
138
+ D1 は MVP の必須ストレージにする。ブロックプログラミングで自然に作られる「リスト」「投稿」「スコア」「ユーザー別データ」は、KV より D1 の方が扱いやすい。
139
+
140
+ 汎用 record store の初期 schema 例:
141
+
142
+ ```sql
143
+ CREATE TABLE records (
144
+ id TEXT PRIMARY KEY,
145
+ collection TEXT NOT NULL,
146
+ owner_id TEXT,
147
+ data_json TEXT NOT NULL,
148
+ created_at TEXT NOT NULL,
149
+ updated_at TEXT NOT NULL
150
+ );
151
+
152
+ CREATE INDEX records_collection_created_at
153
+ ON records (collection, created_at);
154
+
155
+ CREATE INDEX records_owner_collection_created_at
156
+ ON records (owner_id, collection, created_at);
157
+ ```
158
+
159
+ | ブロック/IR 操作 | D1 実装 |
160
+ |---|---|
161
+ | `add record to [messages]` | `INSERT INTO records ...` |
162
+ | `list records from [messages]` | `SELECT ... WHERE collection = ? ORDER BY created_at` |
163
+ | `get record [id]` | `SELECT ... WHERE id = ?` |
164
+ | `delete record [id]` | `DELETE ... WHERE id = ?` |
165
+ | `set user value [key]` | user value table への `UPSERT` |
166
+ | `list current user's records` | `owner_id = currentUser.id` で絞る |
167
+
168
+ ### R2
169
+
170
+ R2 は Asset Manager の binary 保存先にする。D1 には metadata のみを置く。
171
+
172
+ ```sql
173
+ CREATE TABLE assets (
174
+ id TEXT PRIMARY KEY,
175
+ owner_id TEXT,
176
+ object_key TEXT NOT NULL,
177
+ mime_type TEXT NOT NULL,
178
+ size INTEGER NOT NULL,
179
+ visibility TEXT NOT NULL DEFAULT 'private',
180
+ created_at TEXT NOT NULL,
181
+ updated_at TEXT NOT NULL
182
+ );
183
+ ```
184
+
185
+ `/@assets/<id>` への request は、D1 で metadata と権限を確認し、R2 object を返す。Sprite route から `/camera/image.jpg` のような friendly alias を作る場合も、最終的な binary は同じ R2 object を参照する。
186
+
187
+ ### KV
188
+
189
+ KV は主 DB にしない。KV は高頻度 read と低頻度 write の設定、cache、feature flag には向くが、eventual consistency のため、投稿直後の一覧反映、正確なカウンタ、在庫、残高、投票数のような用途には向かない。
190
+
191
+ | KV に向く | KV に向かない |
192
+ |---|---|
193
+ | route 公開設定 | 掲示板投稿 |
194
+ | feature flag | 正確なカウンタ |
195
+ | HTML fragment cache | 投稿直後の強い反映 |
196
+ | OIDC/JWKS cache | 在庫、残高、投票数 |
197
+ | 軽い session 補助 | 同時更新が多いデータ |
198
+
199
+ ### Durable Objects
200
+
201
+ Durable Objects は MVP では必須にしない。ただし、次のような機能を生成対象に入れる場合は導入候補にする。
202
+
203
+ - 正確な訪問者カウンタ
204
+ - 同時更新されるゲーム部屋/チャット部屋
205
+ - per-room の短いリアルタイム状態
206
+ - WebSocket を使う interactive route
207
+
208
+ Scratch 的な「変数を 1 増やす」を KV の `get -> +1 -> put` で生成すると同時アクセスで取りこぼす。正確性が必要な場合は D1 の atomic update または Durable Objects に寄せる。
209
+
210
+ ## 生成ツールの adapter 境界
211
+
212
+ 生成 runtime は storage を直接 Cloudflare API に固定せず、adapter 境界を置く。
213
+
214
+ ```ts
215
+ type StorageAdapter = {
216
+ records: RecordStore;
217
+ assets?: AssetStore;
218
+ counters?: CounterStore;
219
+ config?: ConfigStore;
220
+ };
221
+ ```
222
+
223
+ Cloudflare Workers MVP の adapter 対応:
224
+
225
+ | Adapter | Cloudflare 実装 | MVP |
226
+ |---|---|---:|
227
+ | `RecordStore` | D1 | 必須 |
228
+ | `AssetStore` | R2 + D1 metadata | 任意だが早めに追加 |
229
+ | `CounterStore` | D1、上級設定で Durable Objects | D1 から開始 |
230
+ | `ConfigStore` | KV | 任意 |
231
+ | `SessionStore` | cookie/JWT 中心、必要に応じて KV/D1 | 認証方式に依存 |
232
+
233
+ この境界を保つことで、同じ IR から Vercel + 外部 DB、Firebase + Firestore/Storage、Supabase + Postgres/Storage へ後から展開しやすくなる。
234
+
235
+ ## MVP に含める範囲
236
+
237
+ | 機能 | MVP | 理由 |
238
+ |---|---:|---|
239
+ | TypeScript/Hono 生成 | ○ | 既存実装と相性がよい |
240
+ | Cloudflare Workers scaffold | ○ | `wrangler.jsonc`、binding、README まで出す |
241
+ | GET/POST route | ○ | ブロック HTTP handler の中心 |
242
+ | query/header/path/body 参照 | ○ | 既存 request block と対応する |
243
+ | text/html/json response | ○ | 既存 response block と対応する |
244
+ | D1 record store | ○ | 永続化の標準 |
245
+ | R2 asset store | △ | Asset Manager 連携を早めに試す価値がある |
246
+ | KV config/cache | △ | route 設定や feature flag 向け |
247
+ | Cloudflare Access mode | △ | 限定公開用途に便利 |
248
+ | 外部 JWT 検証 mode | △ | Google/Microsoft/GitHub login の broker 連携に必要 |
249
+ | OAuth/OIDC callback flow の自動生成 | × | MVP には重い。外部 auth broker に任せる |
250
+ | Durable Objects | × | 正確なカウンタやリアルタイム状態が必要になってから追加 |
251
+
252
+ ## 注意点
253
+
254
+ - 生成コードは Node.js server ではなく Fetch API を前提にする。
255
+ - `fs`、`net`、`http`、長寿命 process、local disk 依存は生成しない。
256
+ - HTML builder の escape、unsafe attribute 除外、safe URL scheme のルールは生成 runtime にも移植する。
257
+ - response header は CR/LF injection と runtime-owned header を拒否する。
258
+ - D1 migration は生成物に含め、schema をコード生成と同じ source of truth から作る。
259
+ - R2 object は public bucket に直置きせず、Worker 経由で認可と metadata 確認を行う。
260
+ - 認証 claim は allowlist 方式でブロックへ公開する。
261
+ - Secrets は `wrangler secret` または Cloudflare dashboard の secret として扱い、生成コードや git に含めない。
262
+
263
+ ## 参考
264
+
265
+ - [Cloudflare Workers Languages](https://developers.cloudflare.com/workers/languages/)
266
+ - [Cloudflare Workers + Hono](https://hono.dev/docs/getting-started/cloudflare-workers)
267
+ - [Cloudflare D1](https://developers.cloudflare.com/d1/)
268
+ - [Cloudflare R2](https://developers.cloudflare.com/r2/)
269
+ - [Workers KV consistency](https://developers.cloudflare.com/kv/concepts/how-kv-works/)
270
+ - [Durable Objects](https://developers.cloudflare.com/durable-objects/)
271
+ - [Cloudflare Access JWT validation](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/)
272
+ - [Vercel Functions runtimes](https://vercel.com/docs/functions/runtimes)
273
+ - [Firebase Cloud Functions](https://firebase.google.com/docs/functions)
274
+ - [Hono deployment targets](https://hono.dev/docs/)