@kubohiroya/turbowarp-http-server 0.2.0 → 0.3.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 (237) hide show
  1. package/README.ja.md +32 -14
  2. package/README.md +104 -43
  3. package/assets/block-icon.svg +1 -0
  4. package/dist/cli.js +131 -17
  5. package/dist/cli.js.map +1 -1
  6. package/dist/compiler/adapters/cloudflare.d.ts +2 -0
  7. package/dist/compiler/adapters/cloudflare.js +477 -0
  8. package/dist/compiler/adapters/cloudflare.js.map +1 -0
  9. package/dist/compiler/adapters/firebase.d.ts +2 -0
  10. package/dist/compiler/adapters/firebase.js +489 -0
  11. package/dist/compiler/adapters/firebase.js.map +1 -0
  12. package/dist/compiler/adapters/index.d.ts +2 -0
  13. package/dist/compiler/adapters/index.js +3 -0
  14. package/dist/compiler/adapters/index.js.map +1 -0
  15. package/dist/compiler/binary/codec.d.ts +4 -0
  16. package/dist/compiler/binary/codec.js +45 -0
  17. package/dist/compiler/binary/codec.js.map +1 -0
  18. package/dist/compiler/binary/error.d.ts +3 -0
  19. package/dist/compiler/binary/error.js +21 -0
  20. package/dist/compiler/binary/error.js.map +1 -0
  21. package/dist/compiler/binary/index.d.ts +4 -0
  22. package/dist/compiler/binary/index.js +5 -0
  23. package/dist/compiler/binary/index.js.map +1 -0
  24. package/dist/compiler/binary/runtime.d.ts +18 -0
  25. package/dist/compiler/binary/runtime.js +123 -0
  26. package/dist/compiler/binary/runtime.js.map +1 -0
  27. package/dist/compiler/binary/types.d.ts +17 -0
  28. package/dist/compiler/binary/types.js +2 -0
  29. package/dist/compiler/binary/types.js.map +1 -0
  30. package/dist/compiler/feature-flags.d.ts +4 -0
  31. package/dist/compiler/feature-flags.js +4 -0
  32. package/dist/compiler/feature-flags.js.map +1 -0
  33. package/dist/compiler/index.d.ts +35 -0
  34. package/dist/compiler/index.js +84 -0
  35. package/dist/compiler/index.js.map +1 -0
  36. package/dist/compiler/ir-v2/canonical.d.ts +3 -0
  37. package/dist/compiler/ir-v2/canonical.js +50 -0
  38. package/dist/compiler/ir-v2/canonical.js.map +1 -0
  39. package/dist/compiler/ir-v2/index.d.ts +4 -0
  40. package/dist/compiler/ir-v2/index.js +5 -0
  41. package/dist/compiler/ir-v2/index.js.map +1 -0
  42. package/dist/compiler/ir-v2/parse.d.ts +10 -0
  43. package/dist/compiler/ir-v2/parse.js +753 -0
  44. package/dist/compiler/ir-v2/parse.js.map +1 -0
  45. package/dist/compiler/ir-v2/strict-json.d.ts +4 -0
  46. package/dist/compiler/ir-v2/strict-json.js +133 -0
  47. package/dist/compiler/ir-v2/strict-json.js.map +1 -0
  48. package/dist/compiler/ir-v2/types.d.ts +412 -0
  49. package/dist/compiler/ir-v2/types.js +84 -0
  50. package/dist/compiler/ir-v2/types.js.map +1 -0
  51. package/dist/compiler/kvs/lowering.d.ts +13 -0
  52. package/dist/compiler/kvs/lowering.js +77 -0
  53. package/dist/compiler/kvs/lowering.js.map +1 -0
  54. package/dist/compiler/manifest/error.d.ts +7 -0
  55. package/dist/compiler/manifest/error.js +9 -0
  56. package/dist/compiler/manifest/error.js.map +1 -0
  57. package/dist/compiler/manifest/index.d.ts +6 -0
  58. package/dist/compiler/manifest/index.js +7 -0
  59. package/dist/compiler/manifest/index.js.map +1 -0
  60. package/dist/compiler/manifest/operations.d.ts +12 -0
  61. package/dist/compiler/manifest/operations.js +60 -0
  62. package/dist/compiler/manifest/operations.js.map +1 -0
  63. package/dist/compiler/manifest/parse.d.ts +9 -0
  64. package/dist/compiler/manifest/parse.js +280 -0
  65. package/dist/compiler/manifest/parse.js.map +1 -0
  66. package/dist/compiler/manifest/registry.d.ts +3 -0
  67. package/dist/compiler/manifest/registry.js +48 -0
  68. package/dist/compiler/manifest/registry.js.map +1 -0
  69. package/dist/compiler/manifest/resolve.d.ts +14 -0
  70. package/dist/compiler/manifest/resolve.js +116 -0
  71. package/dist/compiler/manifest/resolve.js.map +1 -0
  72. package/dist/compiler/manifest/types.d.ts +95 -0
  73. package/dist/compiler/manifest/types.js +3 -0
  74. package/dist/compiler/manifest/types.js.map +1 -0
  75. package/dist/compiler/named-body/index.d.ts +1 -0
  76. package/dist/compiler/named-body/index.js +2 -0
  77. package/dist/compiler/named-body/index.js.map +1 -0
  78. package/dist/compiler/named-body/lowering.d.ts +18 -0
  79. package/dist/compiler/named-body/lowering.js +83 -0
  80. package/dist/compiler/named-body/lowering.js.map +1 -0
  81. package/dist/compiler/pipeline/compiler.d.ts +18 -0
  82. package/dist/compiler/pipeline/compiler.js +105 -0
  83. package/dist/compiler/pipeline/compiler.js.map +1 -0
  84. package/dist/compiler/pipeline/core-generator.d.ts +3 -0
  85. package/dist/compiler/pipeline/core-generator.js +483 -0
  86. package/dist/compiler/pipeline/core-generator.js.map +1 -0
  87. package/dist/compiler/pipeline/index.d.ts +5 -0
  88. package/dist/compiler/pipeline/index.js +6 -0
  89. package/dist/compiler/pipeline/index.js.map +1 -0
  90. package/dist/compiler/pipeline/registry.d.ts +7 -0
  91. package/dist/compiler/pipeline/registry.js +17 -0
  92. package/dist/compiler/pipeline/registry.js.map +1 -0
  93. package/dist/compiler/pipeline/requirements.d.ts +9 -0
  94. package/dist/compiler/pipeline/requirements.js +135 -0
  95. package/dist/compiler/pipeline/requirements.js.map +1 -0
  96. package/dist/compiler/pipeline/types.d.ts +65 -0
  97. package/dist/compiler/pipeline/types.js +2 -0
  98. package/dist/compiler/pipeline/types.js.map +1 -0
  99. package/dist/compiler/runtime/error.d.ts +6 -0
  100. package/dist/compiler/runtime/error.js +9 -0
  101. package/dist/compiler/runtime/error.js.map +1 -0
  102. package/dist/compiler/runtime/index.d.ts +1 -0
  103. package/dist/compiler/runtime/index.js +2 -0
  104. package/dist/compiler/runtime/index.js.map +1 -0
  105. package/dist/compiler/structured-data/index.d.ts +3 -0
  106. package/dist/compiler/structured-data/index.js +4 -0
  107. package/dist/compiler/structured-data/index.js.map +1 -0
  108. package/dist/compiler/structured-data/lowering.d.ts +30 -0
  109. package/dist/compiler/structured-data/lowering.js +202 -0
  110. package/dist/compiler/structured-data/lowering.js.map +1 -0
  111. package/dist/compiler/structured-data/path.d.ts +2 -0
  112. package/dist/compiler/structured-data/path.js +60 -0
  113. package/dist/compiler/structured-data/path.js.map +1 -0
  114. package/dist/compiler/structured-data/runtime.d.ts +20 -0
  115. package/dist/compiler/structured-data/runtime.js +210 -0
  116. package/dist/compiler/structured-data/runtime.js.map +1 -0
  117. package/dist/compiler/turbowarp-v2.d.ts +8 -0
  118. package/dist/compiler/turbowarp-v2.js +479 -0
  119. package/dist/compiler/turbowarp-v2.js.map +1 -0
  120. package/dist/compiler/validator/index.d.ts +4 -0
  121. package/dist/compiler/validator/index.js +5 -0
  122. package/dist/compiler/validator/index.js.map +1 -0
  123. package/dist/compiler/validator/ir-validator.d.ts +10 -0
  124. package/dist/compiler/validator/ir-validator.js +463 -0
  125. package/dist/compiler/validator/ir-validator.js.map +1 -0
  126. package/dist/compiler/validator/resource-lifetime.d.ts +18 -0
  127. package/dist/compiler/validator/resource-lifetime.js +106 -0
  128. package/dist/compiler/validator/resource-lifetime.js.map +1 -0
  129. package/dist/compiler/validator/turbowarp-subset.d.ts +3 -0
  130. package/dist/compiler/validator/turbowarp-subset.js +241 -0
  131. package/dist/compiler/validator/turbowarp-subset.js.map +1 -0
  132. package/dist/compiler/validator/types.d.ts +30 -0
  133. package/dist/compiler/validator/types.js +7 -0
  134. package/dist/compiler/validator/types.js.map +1 -0
  135. package/dist/config.d.ts +11 -0
  136. package/dist/config.js +12 -0
  137. package/dist/config.js.map +1 -0
  138. package/dist/digest-cli.js +0 -0
  139. package/dist/extension-manifest.json +102 -0
  140. package/dist/named-body.d.ts +57 -0
  141. package/dist/named-body.js +396 -0
  142. package/dist/named-body.js.map +1 -0
  143. package/dist/named-data-namespace.d.ts +3 -0
  144. package/dist/named-data-namespace.js +6 -0
  145. package/dist/named-data-namespace.js.map +1 -0
  146. package/dist/protocol.d.ts +13 -1
  147. package/dist/protocol.js +34 -0
  148. package/dist/protocol.js.map +1 -1
  149. package/dist/resource-named-body-provider.d.ts +8 -0
  150. package/dist/resource-named-body-provider.js +88 -0
  151. package/dist/resource-named-body-provider.js.map +1 -0
  152. package/dist/server.d.ts +10 -1
  153. package/dist/server.js +37 -7
  154. package/dist/server.js.map +1 -1
  155. package/dist/turbowarp-http-server.js +1614 -1099
  156. package/docs/binary-resource-semantics.ja.md +84 -0
  157. package/docs/cloudflare-worker-compiler.ja.md +90 -0
  158. package/docs/compiler-manifest-registry.ja.md +79 -0
  159. package/docs/compiler-platform-pipeline.ja.md +94 -0
  160. package/docs/deploy-ir-v2.ja.md +123 -0
  161. package/docs/fixed-input-editors.ja.md +23 -0
  162. package/docs/index.html +86 -0
  163. package/docs/ir-v2-conformance.ja.md +65 -0
  164. package/docs/named-response-body.ja.md +120 -0
  165. package/docs/platform-storage-adapters.ja.md +99 -0
  166. package/docs/server-executable-subset.ja.md +88 -0
  167. package/docs/structured-data-lowering.ja.md +63 -0
  168. package/docs/turbowarp-http-server.architecture.html +4 -0
  169. package/examples/compiler/message-app.v2.ir.json +41 -0
  170. package/package.json +45 -20
  171. package/schemas/block-editor-fixed-inputs.schema.json +85 -0
  172. package/schemas/compiler-extension-manifest.schema.json +126 -0
  173. package/schemas/compiler-manifest-lock-v1.schema.json +48 -0
  174. package/schemas/deploy-ir-v2.schema.json +835 -0
  175. package/schemas/ir-v2-conformance-fixture.schema.json +44 -0
  176. package/src/block-definitions.json +76 -0
  177. package/src/cli.ts +136 -23
  178. package/src/compiler/adapters/cloudflare.ts +510 -0
  179. package/src/compiler/adapters/firebase.ts +538 -0
  180. package/src/compiler/adapters/index.ts +2 -0
  181. package/src/compiler/binary/codec.ts +61 -0
  182. package/src/compiler/binary/error.ts +25 -0
  183. package/src/compiler/binary/index.ts +4 -0
  184. package/src/compiler/binary/runtime.ts +133 -0
  185. package/src/compiler/binary/types.ts +26 -0
  186. package/src/compiler/feature-flags.ts +7 -0
  187. package/src/compiler/index.ts +114 -0
  188. package/src/compiler/ir-v2/canonical.ts +46 -0
  189. package/src/compiler/ir-v2/index.ts +9 -0
  190. package/src/compiler/ir-v2/parse.ts +921 -0
  191. package/src/compiler/ir-v2/strict-json.ts +129 -0
  192. package/src/compiler/ir-v2/types.ts +462 -0
  193. package/src/compiler/kvs/lowering.ts +88 -0
  194. package/src/compiler/manifest/error.ts +29 -0
  195. package/src/compiler/manifest/index.ts +17 -0
  196. package/src/compiler/manifest/operations.ts +175 -0
  197. package/src/compiler/manifest/parse.ts +390 -0
  198. package/src/compiler/manifest/registry.ts +74 -0
  199. package/src/compiler/manifest/resolve.ts +159 -0
  200. package/src/compiler/manifest/types.ts +112 -0
  201. package/src/compiler/named-body/index.ts +1 -0
  202. package/src/compiler/named-body/lowering.ts +186 -0
  203. package/src/compiler/pipeline/compiler.ts +138 -0
  204. package/src/compiler/pipeline/core-generator.ts +486 -0
  205. package/src/compiler/pipeline/index.ts +5 -0
  206. package/src/compiler/pipeline/registry.ts +18 -0
  207. package/src/compiler/pipeline/requirements.ts +139 -0
  208. package/src/compiler/pipeline/types.ts +59 -0
  209. package/src/compiler/runtime/error.ts +11 -0
  210. package/src/compiler/runtime/index.ts +1 -0
  211. package/src/compiler/structured-data/index.ts +3 -0
  212. package/src/compiler/structured-data/lowering.ts +314 -0
  213. package/src/compiler/structured-data/path.ts +53 -0
  214. package/src/compiler/structured-data/runtime.ts +221 -0
  215. package/src/compiler/turbowarp-v2.ts +610 -0
  216. package/src/compiler/validator/index.ts +4 -0
  217. package/src/compiler/validator/ir-validator.ts +812 -0
  218. package/src/compiler/validator/resource-lifetime.ts +153 -0
  219. package/src/compiler/validator/turbowarp-subset.ts +387 -0
  220. package/src/compiler/validator/types.ts +68 -0
  221. package/src/config.ts +1 -1
  222. package/src/extension.ts +87 -1
  223. package/src/fixed-input-editors.ts +181 -0
  224. package/src/fixed-input-schema.ts +15 -0
  225. package/src/named-body.ts +495 -0
  226. package/src/named-data-namespace.ts +6 -0
  227. package/src/protocol.ts +50 -1
  228. package/src/resource-named-body-provider.ts +106 -0
  229. package/src/server.ts +88 -8
  230. package/docs/turbowarp-http-server.architecture.visual-check.1440x900.dark.png +0 -0
  231. package/docs/turbowarp-http-server.architecture.visual-check.1440x900.light.png +0 -0
  232. package/docs/turbowarp-http-server.architecture.visual-check.2048x1320.dark.png +0 -0
  233. package/docs/turbowarp-http-server.architecture.visual-check.2048x1320.light.png +0 -0
  234. package/docs/turbowarp-http-server.architecture.visual-check.html +0 -32
  235. package/docs/turbowarp-http-server.architecture.visual-check.json +0 -547
  236. package/schemas/extension-manifest.schema.json +0 -49
  237. package/src/extension-manifest.ts +0 -149
@@ -0,0 +1,84 @@
1
+ # Binary resource semantics
2
+
3
+ Deploy IR v2はbinary payloadをJSON文字列やbase64として保持せず、永続objectを示す`binary-ref`と、実行時streamを示すaffine `binary-body`を区別します。この層はCloudflare R2、Firebase Cloud Storage、Node filesystem等の製品型を参照しません。
4
+
5
+ ## 値とresource
6
+
7
+ `binary-ref`はIR JSONへ格納できるlogical descriptorです。
8
+
9
+ ```json
10
+ {
11
+ "namespace": "asset",
12
+ "key": "images/hero.png",
13
+ "contentType": "image/png",
14
+ "size": 1234,
15
+ "integrity": "sha256:<lowercase-hex-64>",
16
+ "revision": "opaque-adapter-token"
17
+ }
18
+ ```
19
+
20
+ `namespace`は小文字英字で始まり、小文字英数字・`.`・`-`だけを使う64文字以下のlogical ID、`key`は512文字以下です。absolute path、backslash、空segment、`.`/`..` segment、NULを拒否します。`revision`はintegrityやplatform間共通ETagではなく、adapterだけが解釈するopaque tokenです。
21
+
22
+ `binary-body`はIR JSONへ本体を格納しないresource bindingです。producerがbinding IDを宣言し、putまたはbinary responseが最大1回consumeします。clone、tee、base64化、同じbodyの保存とresponseへの併用はMVP対象外です。分岐後に利用するbodyは全continuing branchで同じ所有状態でなければならず、複数回実行し得るloopから外側bodyをconsumeできません。
23
+
24
+ ## IR operation
25
+
26
+ | statement | producer/consumer | requirement |
27
+ | --- | --- | --- |
28
+ | `asset-resolve` | locatorから`binary-ref \| null` valueを生成 | `object-storage` |
29
+ | `request-body-binary` | request streamから`binary-body`を生成 | `streaming-body` |
30
+ | `asset-object-get` | `binary-ref`から`binary-body`を生成 | `object-storage`, `streaming-body` |
31
+ | `asset-object-put` | `binary-body`をconsumeし`binary-ref`を生成 | `object-storage` |
32
+ | `asset-object-delete` | refまたはlocatorをidempotentに削除しbooleanを生成 | `object-storage` |
33
+ | `respond-binary` | `binary-body`をconsumeしてresponseを完了 | `streaming-body` |
34
+
35
+ producer/consumer集合は閉じており、未知statementがresource bindingを生成・複製・消費できません。`respond-binary`は通常の`respond`と同じterminal responseです。
36
+
37
+ ## Size policy
38
+
39
+ compiler policyの既定`maxBinaryBytes`は16 MiB(16777216 bytes)です。request、get、putは1以上policy以下のliteral `maxBytes`を必須とします。実行時のeffective limitは次です。
40
+
41
+ ```text
42
+ min(operation maxBytes, compiler maxBinaryBytes, target maxBinaryBytes)
43
+ ```
44
+
45
+ 既知のsizeが上限を超える場合はstream開始前に拒否します。sizeがない、または信用できない場合もchunkごとにcountし、超過時にiteratorをcancelして`BINARY_TOO_LARGE`とします。production adapter contractはstreamingを許し、bufferを要求しません。test用`InMemoryBinaryObjectStore`だけが決定的なfixture比較のためbufferします。
46
+
47
+ ## Metadataとresponse
48
+
49
+ - `contentType`: CR/LFを含まないmedia type
50
+ - `size`: 0以上のsafe integer
51
+ - `integrity`: `sha256:<lowercase-hex-64>`
52
+ - `revision`: 1〜256文字のopaque token
53
+ - attachment filename: metadataとは別のresponse dispositionで指定し、RFC 5987形式へencode
54
+
55
+ 入力metadataのsize/integrityが実データと一致しない場合は保存しません。binary byte列、locator、platform errorはdiagnosticやHTTP error responseへ含めません。
56
+
57
+ ## Runtime errors
58
+
59
+ | code | HTTP status |
60
+ | --- | ---: |
61
+ | `BINARY_INVALID_REF` | 422 |
62
+ | `BINARY_NOT_FOUND` | 404 |
63
+ | `BINARY_TOO_LARGE` | 413 |
64
+ | `BINARY_INTEGRITY_MISMATCH` | 502 |
65
+ | `BINARY_BODY_CONSUMED` | 500 |
66
+ | `BINARY_STORAGE_FAILURE` | 502 |
67
+
68
+ HTTP JSON envelope化とstream開始後のabort処理はcompiler pipeline/adapter error boundaryの責務です。
69
+
70
+ ## Asset Cache manifest境界
71
+
72
+ 対応syntaxの正本は`@kubohiroya/turbowarp-asset-cache` 0.1.0のmanifest format 2です。このmanifestは全blockを明示的にbrowser-onlyと宣言し、server operation hintを持ちません。`registerAsset`はURL、costume、sound、runtime text等をまとめるbrowser registry操作であり、object storage putへ近似しません。`isLoaded`、renderer、audio、IndexedDB cache blockも同様にbrowser-onlyとして`TW2_UNSUPPORTED_OPERATION`になります。
73
+
74
+ したがって現時点のAsset Cache manifestからbinary IR actionへloweringされるopcodeはありません。将来manifestにcompiler allowlistと一致するserver hint/専用blockが追加された場合だけ対応します。request uploadは対応source opcodeがないためdirect IRからのみ生成できます。この境界により、browser意味論を推測してcloud storageへ誤変換しません。
75
+
76
+ ## Adapter contract
77
+
78
+ `BinaryObjectStore`は`resolve/get/put/delete`をlogical locatorとstreamで提供します。getの未存在は`null`、deleteの未存在は`false`、storage failureは例外として区別します。targetは`object-storage`、`streaming-body`、最大byte数をcapability planで宣言します。IRやfrontendを変更せず別adapterを追加できます。
79
+
80
+ Cloudflare R2/D1とFirebase Cloud Storage/Firestoreへの具体的なmapping、key prefix、設定、整合性、smoke test方針は[IR v2 platform storage adapter](platform-storage-adapters.ja.md)を参照してください。
81
+
82
+ ## ロールバック
83
+
84
+ rollbackはbinary resourceを含む生成・deployを停止するだけで、既存cloud objectやbrowser側Asset Cache dataを自動削除しません。
@@ -0,0 +1,90 @@
1
+ # TurboWarp → Cloudflare Workers/Hono コンパイラ設計
2
+
3
+ Issue #13のMVPとして、TurboWarpのHTTP handlerまたはDeploy IR v2から、Cloudflare Workers上で動作するHono applicationを生成する。compilerはIR v2だけを受理し、targetとして`cloudflare-workers`を明示する。旧IR v1とそのupgraderは提供しない。
4
+
5
+ 既存のWebSocket bridgeは独立した実行経路であり、`compile` subcommandを実行しない限り生成処理は行わない。
6
+
7
+ ## アーキテクチャ
8
+
9
+ ```text
10
+ TurboWarp project.json ─ manifest-aware frontend ─┐
11
+ ├─ Deploy IR v2
12
+ Deploy IR v2 JSON ─────── strict parser ──────────┘
13
+ -> server-safe validator
14
+ -> capability extraction
15
+ -> platform-neutral Hono core
16
+ -> Cloudflare adapter
17
+ -> deterministic filesystem artifacts
18
+ ```
19
+
20
+ IRの型とserializationは[Deploy IR v2 基礎仕様](deploy-ir-v2.ja.md)、許可blockは[Server-executable subset](server-executable-subset.ja.md)、target境界は[Compiler/Platform pipeline](compiler-platform-pipeline.ja.md)を正本とする。
21
+
22
+ ## CLI
23
+
24
+ ```sh
25
+ # TurboWarp project.json
26
+ turbowarp-http-server compile \
27
+ --input ./project.json \
28
+ --output ./generated-worker \
29
+ --format turbowarp-json \
30
+ --target cloudflare-workers \
31
+ --manifest-lock ./turbowarp-server.lock.json
32
+
33
+ # Deploy IR v2 JSON
34
+ turbowarp-http-server compile \
35
+ --input ./examples/compiler/message-app.v2.ir.json \
36
+ --output ./generated-worker \
37
+ --format ir \
38
+ --target cloudflare-workers
39
+ ```
40
+
41
+ `--target`は必須であり、compilerはplatformを推測しない。`.sb3`の直接入力は対象外なので、TurboWarpから`project.json`を取り出して入力する。出力先が空でない場合は失敗し、置換する場合だけ`--force`を明示する。
42
+
43
+ ## 生成物
44
+
45
+ IRのcapabilityに応じて次のfileを生成する。
46
+
47
+ ```text
48
+ generated-worker/
49
+ src/core.generated.ts
50
+ src/index.ts
51
+ src/platform.ts
52
+ migrations/0001_init.sql # record-storeまたはkey-value-store利用時
53
+ package.json
54
+ tsconfig.json
55
+ wrangler.jsonc
56
+ README.md
57
+ turbowarp-server.generated.json
58
+ ```
59
+
60
+ `core.generated.ts`はCloudflare SDKをimportしない。`index.ts`と`platform.ts`がD1/R2 bindingをHono coreのservice interfaceへ接続する。出力manifestにはadapter ID/version、capability plan、binding、生成file一覧を記録する。
61
+
62
+ ## HTTP、state、storage
63
+
64
+ - request method、path、query、header、bodyは型付きIR expressionへ変換する。
65
+ - status/header操作の後、すべてのcontrol-flow pathをちょうど一つのterminal responseで終了する。
66
+ - handler variableはrequest-localであり、request終了時に破棄する。
67
+ - Scratch variable/list、broadcast、`forever`、暗黙の並行scriptは拒否する。
68
+ - `record-store`と`key-value-store`はCloudflare adapterでD1へ写像する。
69
+ - `object-storage`とstreaming binary bodyはR2へ写像する。
70
+ - 正確なcounterやroom state向けDurable ObjectsはMVP対象外である。
71
+
72
+ Asset Manager/Asset Cacheのbrowser blockをR2操作へ読み替えない。Asset Cacheはbrowser内の登録・cache・再生を担当し、server compilerではbrowser-only opcodeとして拒否する。portableなnamespace/key操作は`turbowarp-kvs` manifest、binary bodyは独立したIR v2 resource contractを正本とする。
73
+
74
+ ## 認証と安全性
75
+
76
+ IR v2の認証はplatform-neutralなJWT capabilityとして表現する。Cloudflare adapterが未対応の認証capabilityを宣言した場合は、類似実装へfallbackせずcompile errorにする。OAuth/OIDC provider、login/callback、token発行は生成しない。
77
+
78
+ 生成コードでは次を禁止する。
79
+
80
+ - Node.js専用の`fs`、`net`、`http`、`process`をWorker処理へ持ち込むこと
81
+ - module/global変数を永続stateとして使うこと
82
+ - unsafe header、CR/LF injection、runtime所有headerの上書き
83
+ - secret、credential、project IDをIR、target config、生成sourceへ直書きすること
84
+ - request body、binary payload、logical locator、platform SDK errorをdiagnosticへ出すこと
85
+
86
+ secretはWrangler secretまたはCloudflare dashboardから設定する。compilerとadapterはnetwork deploy、credential操作、cloud resource作成を行わない。
87
+
88
+ ## ロールバック
89
+
90
+ 問題時は生成物のdeployを停止し、既存のWebSocket bridgeを使用する。既存cloud resourceは自動削除しない。必要なD1/R2 dataをexportし、依存deploymentとbindingを確認した後、generated READMEに従って利用者が明示的にcleanupする。
@@ -0,0 +1,79 @@
1
+ # Compiler extension manifest registry
2
+
3
+ Deploy IR v2 frontendは、外部TurboWarp extensionのopcodeをcompiler内の手書き定義だけから推測しません。明示された`turboWarp-server.lock.json`、lockが指すmanifestのexact bytes、compiler側allowlistの3つが一致した場合だけopcode registryへ登録します。
4
+
5
+ manifest registryはTurboWarp projectをIR v2へ変換する唯一の外部extension解決経路です。
6
+
7
+ ## 対応形式
8
+
9
+ - compiler manifest format 1: extension ID、block type、argument ID/typeだけを提供するlegacy block API manifest。
10
+ - compiler manifest format 2: format 1にresult type、effect、immutable、runtime error、server-operation hintを加えた形式。Asset Cache 0.1.0のbrowser-only宣言、Structured Data 0.4.0、KVS 0.1.0のfixtureとの互換性を確認します。
11
+ - lock format 1: extension ID、exact package version、manifest format version、exact-byte SHA-256、sourceを固定します。
12
+
13
+ machine-readable schemaは次のとおりです。
14
+
15
+ - [`schemas/compiler-extension-manifest.schema.json`](../schemas/compiler-extension-manifest.schema.json)
16
+ - [`schemas/compiler-manifest-lock-v1.schema.json`](../schemas/compiler-manifest-lock-v1.schema.json)
17
+
18
+ format 1 manifestはregistryへ読めますが、server-operation hintがないblockを自動的にserver対応とは判断しません。Asset Cache blockをKVSやobject storageへ推測変換しません。KVSはformat 2の明示的な`kvs.*` operationだけをloweringします。
19
+
20
+ ## Lock
21
+
22
+ ```json
23
+ {
24
+ "lockVersion": 1,
25
+ "extensions": [
26
+ {
27
+ "extensionId": "kubohiroyastructureddata",
28
+ "packageName": "@kubohiroya/turbowarp-structured-data",
29
+ "packageVersion": "0.4.0",
30
+ "manifestFormatVersion": 2,
31
+ "integrity": "sha256-<base64 SHA-256>",
32
+ "source": {"kind": "local", "path": "manifests/structured-data.json"}
33
+ }
34
+ ]
35
+ }
36
+ ```
37
+
38
+ `packageVersion`はexact versionだけを受理し、range、tag、`latest`を解決しません。integrityはmanifest fileのexact bytesに対するSHA-256です。JSONの再整形やcanonicalization後のhashではありません。
39
+
40
+ sourceは次の2種類だけです。
41
+
42
+ - `bundled`: compiler callerがIDとexact bytesを登録したmanifest
43
+ - `local`: lock fileのdirectoryを基準とする相対path
44
+
45
+ URL、npm registry、cwd探索、暗黙downloadはありません。resolver順は常に「lock entry → entryが指すbundled/local source」です。
46
+
47
+ CLIではTurboWarp project入力に限り`--manifest-lock <file>`でlockを指定します。このoptionは`--format turbowarp-json`と組み合わせ、direct IR入力では受理しません。
48
+
49
+ local sourceはabsolute path、lock directory外への`..`、symlink componentを拒否します。realpath後にもlock directory内であることを再確認します。
50
+
51
+ ## Registryとoperation hint
52
+
53
+ project opcodeは`<extensionId>_<opcode>`で一意に解決します。lockにないextension/opcodeは`TW2_MANIFEST_UNKNOWN_OPCODE`です。package versionをopcode prefixから推測しません。
54
+
55
+ `server.irOperation`は実装ruleではなくhintです。`server.supported: true`の場合、operation ID、opcode、block type、argument順・型・制約、result type、effect、immutableがcompilerの`KNOWN_SERVER_OPERATIONS`と完全一致しなければ`TW2_MANIFEST_OPERATION_MISMATCH`になります。manifestからJavaScript、module path、template、code snippetを読み込んだり実行したりしません。
56
+
57
+ ## 入力制限
58
+
59
+ 既定値はtargetによらず固定です。
60
+
61
+ - manifest/lock: 最大1 MiB
62
+ - JSON nesting: 最大64
63
+ - blocks: 最大2048
64
+ - duplicate JSON key: 拒否
65
+ - duplicate extension ID、opcode、argument ID、error code: 拒否
66
+ - unknown field/version/enum: 拒否
67
+ - UTF-8不正: 拒否
68
+
69
+ 失敗は`CompilerManifestError`と安定した`TW2_MANIFEST_*` codeで返します。runtime error codeとは別namespaceです。
70
+
71
+ ## Lowering境界
72
+
73
+ 1. frontendはprojectで使われるnon-core extensionにlock entryを要求します。
74
+ 2. registryでblock signatureとoperation hintを検証してから、既知loweringへ渡します。
75
+ 3. manifest version不一致時に旧定義や類似operationへfallbackしません。
76
+
77
+ ## ロールバック
78
+
79
+ 問題時は該当manifest lockを使う生成を停止します。lockは診断・再現用artifactとして保持し、compilerは外部packageやcloud resourceを変更しません。
@@ -0,0 +1,94 @@
1
+ # IR v2 compiler/platform adapter境界
2
+
3
+ Deploy IR v2の生成pipelineは、target-neutralな検証とHono core生成を、platform固有の計画・entrypoint・storage・deploy artifact生成から分離します。compilerはIR v2だけを扱い、CLIではtargetを必ず明示します。
4
+
5
+ ```text
6
+ Deploy IR v2
7
+ -> target-neutral validator
8
+ -> capability requirement extraction
9
+ -> PlatformAdapter registry / plan
10
+ -> platform-neutral Hono core generator
11
+ -> adapter artifact generator
12
+ -> deterministic generated project + output manifest
13
+ ```
14
+
15
+ ## CLI contract
16
+
17
+ v2 direct IRは次のようにcompileします。
18
+
19
+ ```sh
20
+ turbowarp-http-server compile \
21
+ --input deploy-ir-v2.json \
22
+ --output generated-worker \
23
+ --format ir \
24
+ --target cloudflare-workers
25
+ ```
26
+
27
+ 同じIRをFirebase Functionsへ生成する場合は`--target firebase-functions`へ切り替えます。target固有のbinding/環境変数名は`--target-config`で指定し、IRは変更しません。
28
+
29
+ TurboWarp `project.json`と外部extensionをcompileする場合は、検証済みmanifest lockを明示します。
30
+
31
+ ```sh
32
+ turbowarp-http-server compile \
33
+ --input project.json \
34
+ --output generated-worker \
35
+ --format turbowarp-json \
36
+ --target cloudflare-workers \
37
+ --manifest-lock turboWarp-server.lock.json
38
+ ```
39
+
40
+ - `--target`を必須とし、targetを推測しません。
41
+ - CLI入力はcanonical `--format ir`に加え、built-in HTTP block subsetの`--format turbowarp-json`を受理します。
42
+ - `--target-config <file>`はadapter設定です。IRへmergeせず、secret値を受け取りません。
43
+ - `--enable-named-response-body`は実験的な`respond-named-body`だけを有効化し、既定OFFです。選択targetに`named-body-provider`がなければ生成しません。
44
+ - `--format turbowarp-json`はbuilt-in HTTP block、literal bounded repeat、named responseを直接IR v2へloweringします。`--manifest-lock`指定時はlock済みStructured Data reporter/loopとKVS 0.1.0の5操作も同じfrontendでloweringします。lockにないextension opcodeやAsset Cacheのbrowser-only操作を推測しません。
45
+ - Cloudflare adapterはD1/R2 binding名、Firebase adapterはfunction名/bucket環境変数名/Firestore collection名だけを受け取ります。secretやproject IDは受け取りません。詳細は[IR v2 platform storage adapter](platform-storage-adapters.ja.md)を参照してください。
46
+
47
+ ## module責務
48
+
49
+ | phase | module | 責務 |
50
+ | --- | --- | --- |
51
+ | parse | `compiler/ir-v2` | strict JSON/schemaから型付きIRを作る |
52
+ | validate | `compiler/validator` | targetに依存しない型、control flow、resource lifetimeを検証する |
53
+ | requirements | `compiler/pipeline/requirements` | 宣言capabilityを正規化し、要求元route/`sourceRef`を特定する |
54
+ | registry/plan | `compiler/pipeline` | targetを解決し、adapter capabilityと設定を検証する |
55
+ | core generator | `compiler/pipeline/core-generator` | Hono routeと抽象service境界を生成する |
56
+ | adapter | `compiler/adapters` | platform entrypoint、binding、storage、deploy設定を生成する |
57
+
58
+ `PlatformAdapter.plan`と`generate`はnetwork、deploy、cloud resource作成を行わないpure filesystem artifact operationです。新しいadapterはregistryへ追加でき、frontendやopcode loweringを変更する必要はありません。
59
+
60
+ 共有coreはCloudflare、Firebase、D1、R2等の製品型を参照しません。たとえばclient addressは`CoreServices.clientAddress`、KVSは`CoreServices.keyValues`、record永続化は`CoreServices.records`、binary objectは`CoreServices.objects`を介し、選択adapterがplatform APIへ結び付けます。
61
+
62
+ ## diagnostic
63
+
64
+ - 未登録target: `TW2_UNKNOWN_TARGET`
65
+ - target capability不足: `TW2_TARGET_CAPABILITY_UNSUPPORTED`
66
+ - adapter設定不正: `TW2_TARGET_CONFIG_INVALID`
67
+
68
+ capability不足にはtarget ID、要求元route ID、取得可能な場合はTurboWarp blockの`sourceRef`、理由、代替案を含めます。target-neutral validationが失敗した場合はadapter planへ進まず、部分的な生成物も書きません。
69
+
70
+ ## runtime error boundary
71
+
72
+ terminal response開始前の既知runtime faultは次のenvelopeへ変換します。
73
+
74
+ ```json
75
+ {"error":{"code":"STABLE_CODE"}}
76
+ ```
77
+
78
+ Structured Dataのstatus mappingは[Structured Data lowering](structured-data-lowering.ja.md)、binaryは[Binary resource semantics](binary-resource-semantics.ja.md)を正本とします。KVSの不正namespace/keyは422、storage failureは502です。未知の例外または未知codeは500 `IR_RUNTIME_ERROR`です。message、stack、request body、binary、locator、secret、platform SDK errorはresponseへ含めません。
79
+
80
+ ## deterministic output manifest
81
+
82
+ 生成fileはpath昇順、UTF-8、LF、末尾newlineありで正規化します。timestamp、random ID、absolute pathは生成物へ埋め込みません。`turbowarp-server.generated.json`は次を記録します。
83
+
84
+ - manifest format version
85
+ - Deploy IR version
86
+ - target adapter ID/version
87
+ - capability plan
88
+ - 生成file一覧
89
+
90
+ 同じIR、target、adapter version、target configからはbyte-for-byte同じ生成物を得ます。
91
+
92
+ ## ロールバック
93
+
94
+ 問題時は対象targetへの生成・deployを停止し、既存のbrowser bridgeを利用します。生成処理はcloud resourceを変更しないため、rollback時にresource削除は行いません。
@@ -0,0 +1,123 @@
1
+ # Deploy IR v2 基礎仕様
2
+
3
+ Deploy IR v2は、TurboWarpのHTTP handlerをplatform-neutralな型付き表現へ変換する中間表現です。compilerが受理するIR versionはv2だけです。
4
+
5
+ 型、strict parser、JSON Schema、canonical serializerに加え、明示的なtargetを選択するCLI pipelineを提供します。[Compiler/platform adapter境界](compiler-platform-pipeline.ja.md)を参照してください。
6
+
7
+ 外部extension manifestのlock/offline解決仕様は[Compiler extension manifest registry](compiler-manifest-registry.ja.md)を参照してください。
8
+
9
+ 許可block、binding scope、bounded control flow、response、work budgetの規則は[Server-executable subset](server-executable-subset.ja.md)を参照してください。
10
+
11
+ Structured Data blockの変換規則は[Structured Data lowering](structured-data-lowering.ja.md)を参照してください。
12
+
13
+ binary resourceの所有権、上限、storage contractは[Binary resource semantics](binary-resource-semantics.ja.md)を参照してください。
14
+
15
+ Cloudflare/Firebaseのstorage mappingとtarget設定は[IR v2 platform storage adapter](platform-storage-adapters.ja.md)を参照してください。
16
+
17
+ layer横断のgolden/trace検証は[IR v2 semantic conformance harness](ir-v2-conformance.ja.md)を参照してください。
18
+
19
+ Structured/document/binaryを共通HTTP bodyとして返すprovider contractと`respond-named-body` statementは[Named response body provider contract](named-response-body.ja.md)を参照してください。実provider adapterは後続実装です。
20
+
21
+ ## Versionと有効化
22
+
23
+ - rootの`version`は整数`2`です。
24
+ - manifest schema version、extension package version、adapter versionとは独立しています。
25
+ - CLIでは`--target`を必須とし、targetを暗黙選択しません。
26
+ - rootのversionが2以外なら`TW2_IR_VERSION`で拒否します。
27
+
28
+ ## 型
29
+
30
+ IR JSONへ格納できるatomic value typeは次のとおりです。
31
+
32
+ - `null`
33
+ - `boolean`
34
+ - `number`
35
+ - `string`
36
+ - `json-text`
37
+ - `json-array`
38
+ - `json-object`
39
+ - `binary-ref`
40
+
41
+ `number`は有限IEEE-754 binary64とし、`NaN`と±`Infinity`を拒否します。`-0`は`0`へ正規化します。`json-text`は有効なapplication JSONを表すnominal string境界で、通常の`string`やparse済みJSON値とは暗黙に混同しません。`json-array`と`json-object`は再帰的なJSON値で、resourceを内包できません。
42
+
43
+ `binary-ref`はbyte列ではなく、`namespace`と`key`、任意の`contentType`、`size`、`sha256:<hex>`形式の`integrity`、opaque `revision`を持つ論理descriptorです。`base64`、`bytes`、data URL等のinline payload fieldは許可しません。
44
+
45
+ `binary-body`はvalueではありません。stream本体をIR JSONへ格納せず、`resource` bindingのIDとしてだけ表現します。この区別により、後続validatorがclone、二重consume、scope外利用を検出できます。
46
+
47
+ union typeは次の形式です。
48
+
49
+ ```json
50
+ {"kind":"union","members":["null","json-object"]}
51
+ ```
52
+
53
+ ## Expressionとstatement
54
+
55
+ すべてのexpressionは`valueType`を持ちます。v2で定義済みのexpressionはliteral、request、request-value、concat、handler-variable、handler-variable-exists、handler-variable-names、bindingに加え、KVS get/has/list、明示的なJSON parse/serialize、path操作、iteration reporterです。
56
+
57
+ statementはHTTP response操作、handler-variable操作、KVS set/delete、論理record/object storage操作、binary body producer/consumer、typed `if`、bounded-loop、`json-for-each`、terminal responseを表現します。一般的なScratch control blockを受理するかどうかはschemaではなくfrontend/validatorの責務です。
58
+
59
+ statementのeffectは入力側が自由に申告するfieldにはせず、statement kindから`IR_V2_STATEMENT_EFFECTS`で決定的に導出します。分類は`response-write`、`handler-state-write`、`key-value-read`、`key-value-write`、`record-read`、`record-write`、`control`等です。これにより入力がeffectを過少申告してvalidatorを迂回することを防ぎます。
60
+
61
+ JSON pathは`PathSegmentV2`とschemaの`pathSegment`で、string keyと非負整数indexを別のvariantとして定義します。`json-for-each`はlexical `loopId`を作り、そのbody内だけでiteration key/index/value reporterから参照できます。
62
+
63
+ `sourceRef`はtarget index/name、block ID、opcode、任意のinput名を保持します。diagnostic用であり、生成コードの意味には影響しません。direct IRでは省略できます。
64
+
65
+ ## Strict parsing
66
+
67
+ `parseDeployIrV2Json`はJSON textを読み、次を拒否します。
68
+
69
+ - duplicate object key
70
+ - unknown field
71
+ - unknown node kind
72
+ - 型とliteral値の不一致
73
+ - 非有限number
74
+ - 不正なbinding ID
75
+ - 不正なsourceRef
76
+
77
+ 失敗時は`DeployIrV2ParseError`を送出し、呼び出し側が文面を解析せず扱える安定したcodeを持たせます。
78
+
79
+ - `TW2_IR_JSON_SYNTAX`: JSON構文エラー
80
+ - `TW2_IR_DUPLICATE_KEY`: duplicate object key
81
+ - `TW2_IR_VERSION`: 未対応IR version
82
+ - `TW2_IR_UNKNOWN_FIELD`: unknown field
83
+ - `TW2_IR_UNKNOWN_NODE`: unknown expression/statement等のnode kind
84
+ - `TW2_IR_INVALID_VALUE`: その他のschema/値制約違反
85
+
86
+ 既知objectには`additionalProperties: false`を適用します。未知fieldを無視して将来の意味へ誤変換しません。
87
+
88
+ machine-readable schemaは[`schemas/deploy-ir-v2.schema.json`](../schemas/deploy-ir-v2.schema.json)です。runtime parserはschema validatorの有無に依存せず、同じnode集合を検証します。
89
+
90
+ ## Canonical serialization
91
+
92
+ IR documentのhashとgolden比較にはRFC 8785(JCS)形式を使用します。object keyはUTF-16 code unit順、array順は保持、whitespaceは挿入しません。lone surrogateを含む不正なUnicode stringはcanonicalizeせず拒否します。
93
+
94
+ これはStructured Data extensionが扱うapplication JSONの正規化規則とは別です。application JSONをIR document用JCSへ暗黙変換しません。
95
+
96
+ ## Capability
97
+
98
+ IR coreは製品名ではなく、次のような論理requirementを持ちます。
99
+
100
+ - `record-store`
101
+ - `key-value-store`
102
+ - `object-storage`
103
+ - `streaming-body`
104
+ - `named-body-provider`
105
+ - `request-metadata: client-address`
106
+ - `auth: external-jwt | trusted-access-jwt`
107
+
108
+ D1、Cloudflare KV、R2、Firestore、Cloud Storage等の選択はIRへ書かず、後続のPlatformAdapterが行います。現行`key-value-store`はread-after-writeを要求するため、Cloudflare adapterはD1へ写像します。
109
+
110
+ capabilityとunion typeのmemberはsetとして扱い、parserが重複を拒否して決定的な順序へ正規化します。routeとstatementの配列順は実行順なので保持します。
111
+
112
+ ## ファイル
113
+
114
+ - `src/compiler/ir-v2/types.ts`: TypeScript型
115
+ - `src/compiler/ir-v2/parse.ts`: strict object parser
116
+ - `src/compiler/ir-v2/strict-json.ts`: duplicate-keyを拒否するJSON text parser
117
+ - `src/compiler/ir-v2/canonical.ts`: canonical serializer
118
+ - `schemas/deploy-ir-v2.schema.json`: JSON Schema
119
+ - `examples/compiler/message-app.v2.ir.json`: v2 example
120
+
121
+ ## ロールバック
122
+
123
+ 問題時は生成・deployを停止し、既存のbrowser bridgeを利用します。compilerはcloud resourceを変更しないため、自動削除は行いません。
@@ -0,0 +1,23 @@
1
+ # 固定入力の編集
2
+
3
+ S3-4のローカル実装です。対応GUIの固定入力機能は既定OFFです。旧GUI・API無し・固定入力機能OFFではブロックの従来動作を保ちます。`getInfo()` に存在する対象opcodeだけ登録し、再取得・APIの置換・拡張の`dispose()`・runtimeの破棄に対応します。既存SOURCEエディターとopcodeは分離しています。
4
+
5
+ |ブロックopcode|引数|UI|
6
+ |---|---|---|
7
+ |`changeHandlerVariable`|`AMOUNT`|数値入力(NP)|
8
+ |`setHttpStatus`|`STATUS`|数値入力(NP)|
9
+ |`respondWithNamedBody`|`KIND`|既定値からの選択:`structured`, `document`, `binary`, `asset`|
10
+ |`respondWithNamedBody`|`SCOPE`|既定値からの選択:`target`, `project`|
11
+ |`respondWithNamedBody`|`REPRESENTATION`|既定値からの選択:`json`, `yaml`, `html`, `markdown`, `raw`|
12
+ |`respondWithNamedBody`|`MAX_BYTES`|数値入力(NP)|
13
+ |`markdownHeading`|`LEVEL`|数値入力(NP)|
14
+
15
+ 数値の新規入力は、空白を除いた完全な有限JSON数値トークンを受け付け、指数表記・負のゼロ・表記を保持します。空文字、16進表記、先頭の`+`、先頭ゼロや未完成トークンは新規保存しません。既存値は開いただけで書き換えません。既存の有限数値別表記は参照用に投影し、未編集の生値を保ちます。未知の旧enum値も無操作では保存し直しません。
16
+
17
+ `MAX_BYTES` は既存処理と同じく切捨て後に安全な正の整数になる値を受け付けます。`STATUS`・`LEVEL` の既存の切捨て/補正・範囲外処理は変更しません。選択値の照合は既存処理と同じく小文字化のみで、空白を削除しません。
18
+
19
+ reporter接続は読取専用で、実行・置換しません。新しい選択や数値を保存するときだけ純粋codecとSchemaで検証します。検証失敗時は全変更を拒否し、ブロックや接続を部分的に書き換えません。
20
+
21
+ 正本は本ownerの `schemas/block-editor-fixed-inputs.schema.json`、TSモジュールは選択・参照用、`dist`は生成物です。外部候補取得や実行時Schema生成は行いません。
22
+
23
+ 切戻しはGUIの固定入力機能OFFで行えます。既存のプロジェクト形式・opcode・メニュー・defaultValue・実行時の処理は維持します。