@kubohiroya/turbowarp-http-server 0.1.0 → 0.2.1
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.
- package/README.ja.md +29 -13
- package/README.md +101 -42
- package/dist/cli.js +131 -17
- package/dist/cli.js.map +1 -1
- package/dist/compiler/adapters/cloudflare.d.ts +2 -0
- package/dist/compiler/adapters/cloudflare.js +477 -0
- package/dist/compiler/adapters/cloudflare.js.map +1 -0
- package/dist/compiler/adapters/firebase.d.ts +2 -0
- package/dist/compiler/adapters/firebase.js +489 -0
- package/dist/compiler/adapters/firebase.js.map +1 -0
- package/dist/compiler/adapters/index.d.ts +2 -0
- package/dist/compiler/adapters/index.js +3 -0
- package/dist/compiler/adapters/index.js.map +1 -0
- package/dist/compiler/binary/codec.d.ts +4 -0
- package/dist/compiler/binary/codec.js +45 -0
- package/dist/compiler/binary/codec.js.map +1 -0
- package/dist/compiler/binary/error.d.ts +3 -0
- package/dist/compiler/binary/error.js +21 -0
- package/dist/compiler/binary/error.js.map +1 -0
- package/dist/compiler/binary/index.d.ts +4 -0
- package/dist/compiler/binary/index.js +5 -0
- package/dist/compiler/binary/index.js.map +1 -0
- package/dist/compiler/binary/runtime.d.ts +18 -0
- package/dist/compiler/binary/runtime.js +123 -0
- package/dist/compiler/binary/runtime.js.map +1 -0
- package/dist/compiler/binary/types.d.ts +17 -0
- package/dist/compiler/binary/types.js +2 -0
- package/dist/compiler/binary/types.js.map +1 -0
- package/dist/compiler/feature-flags.d.ts +4 -0
- package/dist/compiler/feature-flags.js +4 -0
- package/dist/compiler/feature-flags.js.map +1 -0
- package/dist/compiler/index.d.ts +35 -0
- package/dist/compiler/index.js +84 -0
- package/dist/compiler/index.js.map +1 -0
- package/dist/compiler/ir-v2/canonical.d.ts +3 -0
- package/dist/compiler/ir-v2/canonical.js +50 -0
- package/dist/compiler/ir-v2/canonical.js.map +1 -0
- package/dist/compiler/ir-v2/index.d.ts +4 -0
- package/dist/compiler/ir-v2/index.js +5 -0
- package/dist/compiler/ir-v2/index.js.map +1 -0
- package/dist/compiler/ir-v2/parse.d.ts +10 -0
- package/dist/compiler/ir-v2/parse.js +753 -0
- package/dist/compiler/ir-v2/parse.js.map +1 -0
- package/dist/compiler/ir-v2/strict-json.d.ts +4 -0
- package/dist/compiler/ir-v2/strict-json.js +133 -0
- package/dist/compiler/ir-v2/strict-json.js.map +1 -0
- package/dist/compiler/ir-v2/types.d.ts +412 -0
- package/dist/compiler/ir-v2/types.js +84 -0
- package/dist/compiler/ir-v2/types.js.map +1 -0
- package/dist/compiler/kvs/lowering.d.ts +13 -0
- package/dist/compiler/kvs/lowering.js +77 -0
- package/dist/compiler/kvs/lowering.js.map +1 -0
- package/dist/compiler/manifest/error.d.ts +7 -0
- package/dist/compiler/manifest/error.js +9 -0
- package/dist/compiler/manifest/error.js.map +1 -0
- package/dist/compiler/manifest/index.d.ts +6 -0
- package/dist/compiler/manifest/index.js +7 -0
- package/dist/compiler/manifest/index.js.map +1 -0
- package/dist/compiler/manifest/operations.d.ts +12 -0
- package/dist/compiler/manifest/operations.js +60 -0
- package/dist/compiler/manifest/operations.js.map +1 -0
- package/dist/compiler/manifest/parse.d.ts +9 -0
- package/dist/compiler/manifest/parse.js +280 -0
- package/dist/compiler/manifest/parse.js.map +1 -0
- package/dist/compiler/manifest/registry.d.ts +3 -0
- package/dist/compiler/manifest/registry.js +48 -0
- package/dist/compiler/manifest/registry.js.map +1 -0
- package/dist/compiler/manifest/resolve.d.ts +14 -0
- package/dist/compiler/manifest/resolve.js +116 -0
- package/dist/compiler/manifest/resolve.js.map +1 -0
- package/dist/compiler/manifest/types.d.ts +95 -0
- package/dist/compiler/manifest/types.js +3 -0
- package/dist/compiler/manifest/types.js.map +1 -0
- package/dist/compiler/named-body/index.d.ts +1 -0
- package/dist/compiler/named-body/index.js +2 -0
- package/dist/compiler/named-body/index.js.map +1 -0
- package/dist/compiler/named-body/lowering.d.ts +18 -0
- package/dist/compiler/named-body/lowering.js +83 -0
- package/dist/compiler/named-body/lowering.js.map +1 -0
- package/dist/compiler/pipeline/compiler.d.ts +18 -0
- package/dist/compiler/pipeline/compiler.js +105 -0
- package/dist/compiler/pipeline/compiler.js.map +1 -0
- package/dist/compiler/pipeline/core-generator.d.ts +3 -0
- package/dist/compiler/pipeline/core-generator.js +483 -0
- package/dist/compiler/pipeline/core-generator.js.map +1 -0
- package/dist/compiler/pipeline/index.d.ts +5 -0
- package/dist/compiler/pipeline/index.js +6 -0
- package/dist/compiler/pipeline/index.js.map +1 -0
- package/dist/compiler/pipeline/registry.d.ts +7 -0
- package/dist/compiler/pipeline/registry.js +17 -0
- package/dist/compiler/pipeline/registry.js.map +1 -0
- package/dist/compiler/pipeline/requirements.d.ts +9 -0
- package/dist/compiler/pipeline/requirements.js +135 -0
- package/dist/compiler/pipeline/requirements.js.map +1 -0
- package/dist/compiler/pipeline/types.d.ts +65 -0
- package/dist/compiler/pipeline/types.js +2 -0
- package/dist/compiler/pipeline/types.js.map +1 -0
- package/dist/compiler/runtime/error.d.ts +6 -0
- package/dist/compiler/runtime/error.js +9 -0
- package/dist/compiler/runtime/error.js.map +1 -0
- package/dist/compiler/runtime/index.d.ts +1 -0
- package/dist/compiler/runtime/index.js +2 -0
- package/dist/compiler/runtime/index.js.map +1 -0
- package/dist/compiler/structured-data/index.d.ts +3 -0
- package/dist/compiler/structured-data/index.js +4 -0
- package/dist/compiler/structured-data/index.js.map +1 -0
- package/dist/compiler/structured-data/lowering.d.ts +30 -0
- package/dist/compiler/structured-data/lowering.js +202 -0
- package/dist/compiler/structured-data/lowering.js.map +1 -0
- package/dist/compiler/structured-data/path.d.ts +2 -0
- package/dist/compiler/structured-data/path.js +60 -0
- package/dist/compiler/structured-data/path.js.map +1 -0
- package/dist/compiler/structured-data/runtime.d.ts +20 -0
- package/dist/compiler/structured-data/runtime.js +210 -0
- package/dist/compiler/structured-data/runtime.js.map +1 -0
- package/dist/compiler/turbowarp-v2.d.ts +8 -0
- package/dist/compiler/turbowarp-v2.js +479 -0
- package/dist/compiler/turbowarp-v2.js.map +1 -0
- package/dist/compiler/validator/index.d.ts +4 -0
- package/dist/compiler/validator/index.js +5 -0
- package/dist/compiler/validator/index.js.map +1 -0
- package/dist/compiler/validator/ir-validator.d.ts +10 -0
- package/dist/compiler/validator/ir-validator.js +463 -0
- package/dist/compiler/validator/ir-validator.js.map +1 -0
- package/dist/compiler/validator/resource-lifetime.d.ts +18 -0
- package/dist/compiler/validator/resource-lifetime.js +106 -0
- package/dist/compiler/validator/resource-lifetime.js.map +1 -0
- package/dist/compiler/validator/turbowarp-subset.d.ts +3 -0
- package/dist/compiler/validator/turbowarp-subset.js +241 -0
- package/dist/compiler/validator/turbowarp-subset.js.map +1 -0
- package/dist/compiler/validator/types.d.ts +30 -0
- package/dist/compiler/validator/types.js +7 -0
- package/dist/compiler/validator/types.js.map +1 -0
- package/dist/config.d.ts +11 -0
- package/dist/config.js +12 -0
- package/dist/config.js.map +1 -0
- package/dist/digest-cli.js +0 -0
- package/dist/extension-manifest.json +102 -0
- package/dist/named-body.d.ts +57 -0
- package/dist/named-body.js +396 -0
- package/dist/named-body.js.map +1 -0
- package/dist/named-data-namespace.d.ts +3 -0
- package/dist/named-data-namespace.js +6 -0
- package/dist/named-data-namespace.js.map +1 -0
- package/dist/protocol.d.ts +13 -1
- package/dist/protocol.js +34 -0
- package/dist/protocol.js.map +1 -1
- package/dist/resource-named-body-provider.d.ts +8 -0
- package/dist/resource-named-body-provider.js +88 -0
- package/dist/resource-named-body-provider.js.map +1 -0
- package/dist/server.d.ts +10 -1
- package/dist/server.js +37 -7
- package/dist/server.js.map +1 -1
- package/dist/turbowarp-http-server.js +516 -1
- package/docs/binary-resource-semantics.ja.md +84 -0
- package/docs/cloudflare-worker-compiler.ja.md +90 -0
- package/docs/compiler-manifest-registry.ja.md +79 -0
- package/docs/compiler-platform-pipeline.ja.md +94 -0
- package/docs/deploy-ir-v2.ja.md +123 -0
- package/docs/fixed-input-editors.ja.md +23 -0
- package/docs/index.html +80 -0
- package/docs/ir-v2-conformance.ja.md +65 -0
- package/docs/named-response-body.ja.md +120 -0
- package/docs/platform-storage-adapters.ja.md +99 -0
- package/docs/server-executable-subset.ja.md +88 -0
- package/docs/structured-data-lowering.ja.md +63 -0
- package/examples/compiler/message-app.v2.ir.json +41 -0
- package/package.json +44 -20
- package/schemas/block-editor-fixed-inputs.schema.json +85 -0
- package/schemas/compiler-extension-manifest.schema.json +126 -0
- package/schemas/compiler-manifest-lock-v1.schema.json +48 -0
- package/schemas/deploy-ir-v2.schema.json +835 -0
- package/schemas/ir-v2-conformance-fixture.schema.json +44 -0
- package/src/block-definitions.json +76 -0
- package/src/cli.ts +136 -23
- package/src/compiler/adapters/cloudflare.ts +510 -0
- package/src/compiler/adapters/firebase.ts +538 -0
- package/src/compiler/adapters/index.ts +2 -0
- package/src/compiler/binary/codec.ts +61 -0
- package/src/compiler/binary/error.ts +25 -0
- package/src/compiler/binary/index.ts +4 -0
- package/src/compiler/binary/runtime.ts +133 -0
- package/src/compiler/binary/types.ts +26 -0
- package/src/compiler/feature-flags.ts +7 -0
- package/src/compiler/index.ts +114 -0
- package/src/compiler/ir-v2/canonical.ts +46 -0
- package/src/compiler/ir-v2/index.ts +9 -0
- package/src/compiler/ir-v2/parse.ts +921 -0
- package/src/compiler/ir-v2/strict-json.ts +129 -0
- package/src/compiler/ir-v2/types.ts +462 -0
- package/src/compiler/kvs/lowering.ts +88 -0
- package/src/compiler/manifest/error.ts +29 -0
- package/src/compiler/manifest/index.ts +17 -0
- package/src/compiler/manifest/operations.ts +175 -0
- package/src/compiler/manifest/parse.ts +390 -0
- package/src/compiler/manifest/registry.ts +74 -0
- package/src/compiler/manifest/resolve.ts +159 -0
- package/src/compiler/manifest/types.ts +112 -0
- package/src/compiler/named-body/index.ts +1 -0
- package/src/compiler/named-body/lowering.ts +186 -0
- package/src/compiler/pipeline/compiler.ts +138 -0
- package/src/compiler/pipeline/core-generator.ts +486 -0
- package/src/compiler/pipeline/index.ts +5 -0
- package/src/compiler/pipeline/registry.ts +18 -0
- package/src/compiler/pipeline/requirements.ts +139 -0
- package/src/compiler/pipeline/types.ts +59 -0
- package/src/compiler/runtime/error.ts +11 -0
- package/src/compiler/runtime/index.ts +1 -0
- package/src/compiler/structured-data/index.ts +3 -0
- package/src/compiler/structured-data/lowering.ts +314 -0
- package/src/compiler/structured-data/path.ts +53 -0
- package/src/compiler/structured-data/runtime.ts +221 -0
- package/src/compiler/turbowarp-v2.ts +610 -0
- package/src/compiler/validator/index.ts +4 -0
- package/src/compiler/validator/ir-validator.ts +812 -0
- package/src/compiler/validator/resource-lifetime.ts +153 -0
- package/src/compiler/validator/turbowarp-subset.ts +387 -0
- package/src/compiler/validator/types.ts +68 -0
- package/src/extension.ts +87 -1
- package/src/fixed-input-editors.ts +181 -0
- package/src/fixed-input-schema.ts +15 -0
- package/src/named-body.ts +495 -0
- package/src/named-data-namespace.ts +6 -0
- package/src/protocol.ts +50 -1
- package/src/resource-named-body-provider.ts +106 -0
- package/src/server.ts +88 -8
- package/docs/turbowarp-http-server.architecture.visual-check.1440x900.dark.png +0 -0
- package/docs/turbowarp-http-server.architecture.visual-check.1440x900.light.png +0 -0
- package/docs/turbowarp-http-server.architecture.visual-check.2048x1320.dark.png +0 -0
- package/docs/turbowarp-http-server.architecture.visual-check.2048x1320.light.png +0 -0
- package/docs/turbowarp-http-server.architecture.visual-check.html +0 -32
- package/docs/turbowarp-http-server.architecture.visual-check.json +0 -547
- package/schemas/extension-manifest.schema.json +0 -49
- package/src/extension-manifest.ts +0 -149
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# IR v2 semantic conformance harness
|
|
2
|
+
|
|
3
|
+
conformance harnessは、同じTurboWarp programの意味論がfrontend、platform-neutral core、target adapter間でずれないことをversion固定fixtureで検証します。test専用でありproduction runtimeや生成projectには含めません。
|
|
4
|
+
|
|
5
|
+
## 実行
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
pnpm test:conformance
|
|
9
|
+
pnpm test:conformance:frontend
|
|
10
|
+
pnpm test:conformance:core
|
|
11
|
+
pnpm test:conformance:target
|
|
12
|
+
pnpm test:conformance:target-runtime
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
通常の`pnpm test`と`pnpm check`には決定的に実行できる全layerが含まれます。target layerは生成Cloudflare/Firebase projectの実typecheckまで実行し、cloud account、Emulator、課金resourceは使用しません。`test:conformance:target-runtime`は独立した明示実行用smoke testで、生成projectをWrangler local runtimeとFirebase Emulator Suiteで起動し、record作成とbinary object保存をHTTP経由で検証します。cloud credentialや課金resourceは使用しませんが、Firebase Emulatorの初回実行ではemulator binaryのdownloadが必要な場合があります。個別実行は末尾に`cloudflare-workers`または`firebase-functions`を指定します。
|
|
16
|
+
|
|
17
|
+
## fixture version 1
|
|
18
|
+
|
|
19
|
+
正本schemaは[`schemas/ir-v2-conformance-fixture.schema.json`](../schemas/ir-v2-conformance-fixture.schema.json)です。fixtureは`fixtureVersion: 1`、安定した`id`、`layer`を必須とします。互換性を壊すfield変更はversionを上げ、同じversionで既存goldenの意味を変更しません。
|
|
20
|
+
|
|
21
|
+
fixtureは`tests/fixtures/conformance`に次の3層で配置します。
|
|
22
|
+
|
|
23
|
+
1. **Frontend**: `project.json`、manifest lock、期待IR v2 JCS goldenまたは期待diagnostic code
|
|
24
|
+
2. **Core runtime**: IR v2、request、generated Hono appの期待HTTP/storage effect trace
|
|
25
|
+
3. **Target**: IR v2、target ID、adapter version、期待file一覧、生成project typecheck
|
|
26
|
+
|
|
27
|
+
IR goldenはDeploy IR v2 canonical serializerで比較します。JSONのpretty-printやobject挿入順には依存しません。外部extension vectorはpackage name、exact version、SHA-256 integrityをmanifest lockとfixtureの両方で固定し、lock解決時にも実bytesを再検証します。
|
|
28
|
+
|
|
29
|
+
## HTTPとeffect trace
|
|
30
|
+
|
|
31
|
+
HTTP traceはstatus、lowercase header名と値の順序付きpair、body text、body bytesのSHA-256を比較します。binary bodyそのものをsnapshotへ埋め込みません。将来multi-value headerを追加する場合もpairを複数保持し、単一objectへ潰しません。
|
|
32
|
+
|
|
33
|
+
storage traceは次だけを記録します。
|
|
34
|
+
|
|
35
|
+
- logical capability
|
|
36
|
+
- operation
|
|
37
|
+
- collectionまたは検証済みlogical locator
|
|
38
|
+
- byte列を含まないmetadata
|
|
39
|
+
|
|
40
|
+
record IDはtest adapterが`record-0001`から決定的に採番します。clock、random ID、absolute temp path、platform SDK内部値はgoldenへ含めません。binary fixtureはrepository内の小さなfileとSHA-256で固定し、IR JSONへbase64 payloadを格納しません。
|
|
41
|
+
|
|
42
|
+
## 現在のvector
|
|
43
|
+
|
|
44
|
+
- Structured Data: immutable path更新、Unicode code point順serialize、nested iteration、安定422 error
|
|
45
|
+
- Binary: file-backed put/get/delete、stream size limit、consume-once/error contract
|
|
46
|
+
- Named body: fake Structured Data/Asset Manager provider、JSON/raw response、HEAD metadata
|
|
47
|
+
- direct IR/TurboWarp frontend: status/header/bodyのobservable parity
|
|
48
|
+
- Target: Cloudflare/Firebase adapterのdeterministic artifact、manifest、TypeScript typecheck、任意のlocal runtime smoke test
|
|
49
|
+
|
|
50
|
+
新しいadapterをregistryへ登録する変更は、target matrixのentryと期待artifactを同じ変更で追加します。未完成targetをskipして成功扱いにはしません。Wrangler local runtimeとFirebase Emulator Suiteのsmoke testは、core goldenを維持した独立jobまたはrelease前検証として実行します。
|
|
51
|
+
|
|
52
|
+
## CIと失敗artifact
|
|
53
|
+
|
|
54
|
+
通常CIでは`pnpm check`をblockingにします。失敗時は次をCI artifactとして保持できるようにします。
|
|
55
|
+
|
|
56
|
+
- fixture IDとlayer
|
|
57
|
+
- actual canonical IRまたはdiagnostic code
|
|
58
|
+
- actual HTTP/effect trace
|
|
59
|
+
- target generated project(secret、absolute path、cloud credentialなし)
|
|
60
|
+
|
|
61
|
+
外部emulator jobがflakyな場合は別jobへ隔離できますが、失敗は可視化し、core goldenをskipしません。既定のlocal suiteは外部networkを使わないためretryやnormalizerで失敗を隠しません。
|
|
62
|
+
|
|
63
|
+
## ロールバック
|
|
64
|
+
|
|
65
|
+
harnessはproduction出力へ含まれないため、問題時は該当fixture/runner変更をrevertします。意味論差分が見つかった場合はgoldenを先に書き換えず、frontend、core、adapterのどの層が正本とずれたかを修正します。
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
# Named response body provider contract
|
|
2
|
+
|
|
3
|
+
Named response bodyは、Structured Data、将来のDocument Data、binary/Asset Manager dataを、HTTP Serverから同じsnapshot/stream契約で返すための実験的な内部APIです。各extensionのprivate state、IndexedDB/OPFS layout、platform SDK objectはHTTP Serverへ公開しません。
|
|
4
|
+
|
|
5
|
+
現時点ではprovider contract、共通Response builder、Deploy IR v2のcanonical terminal statementを提供します。Node側の既存`ResourceCapability`は`createAssetManagerNamedBodyProvider`でAsset Manager providerへ適合できます。TurboWarp block、実Structured Data provider、生成Cloudflare/Firebase targetへのprovider接続は未実装です。`namedResponseBody`は既定falseで、`--enable-named-response-body`を指定したcompiler呼び出しだけが新statementを受理します。
|
|
6
|
+
|
|
7
|
+
## 参照とscope
|
|
8
|
+
|
|
9
|
+
```ts
|
|
10
|
+
interface NamedDataReference {
|
|
11
|
+
namespace: string;
|
|
12
|
+
name: string;
|
|
13
|
+
kind: 'structured' | 'document' | 'binary' | 'asset';
|
|
14
|
+
scope: 'target' | 'project';
|
|
15
|
+
}
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
- `namespace`は小文字英字で始まり、小文字英数字・`.`・`-`だけを使う64文字以下のlogical IDです。データ型ではなく所有領域を表します。
|
|
19
|
+
- `name`は1〜256文字で、control characterを含めません。storage pathとして直接使用しません。
|
|
20
|
+
- `target` scopeはruntime-localな`targetId`を必須とします。
|
|
21
|
+
- `project` scopeへ`targetId`を付ける曖昧な参照は拒否します。
|
|
22
|
+
- requested representationは`json`、`yaml`、`html`、`markdown`、`raw`のいずれかです。
|
|
23
|
+
|
|
24
|
+
不正参照はproviderへ渡す前に`NAMED_DATA_INVALID_REF`で拒否します。canonical registryは`(namespace, kind)`をdispatch keyとし、同じ論理namespaceへ異なるkindのproviderを登録できます。HTTP Server固有のresolverへproviderを直接並べる場合は、`canResolve`でnamespace/kind/scopeを選択し、registry順の最初のproviderを使用します。
|
|
25
|
+
|
|
26
|
+
## stat、openBody、snapshot
|
|
27
|
+
|
|
28
|
+
providerはmetadataだけを返す`stat`と、snapshot handleを返す`openBody`を分離します。
|
|
29
|
+
|
|
30
|
+
```ts
|
|
31
|
+
interface NamedBodyHandle {
|
|
32
|
+
metadata: NamedBodyMetadata;
|
|
33
|
+
body: Uint8Array | ReadableStream<Uint8Array>;
|
|
34
|
+
release(reason: 'complete' | 'cancel' | 'abort' | 'error'): void | Promise<void>;
|
|
35
|
+
}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
`HEAD`は`stat`だけを呼び、bodyをopenしません。status errorを含めてbodyは返しません。`GET`相当の処理は`openBody`で得たhandleを1回だけreleaseします。open済みhandleはsnapshotであり、同じ名前のresourceがreplaceされても途中で新しい内容へ切り替わりません。
|
|
39
|
+
|
|
40
|
+
buffered bodyはresponseへ渡す前にcopyし、宣言`byteLength`と実byte数の不一致を502で拒否します。streamは既知lengthがなくてもchunkごとに上限をcountし、宣言`byteLength`がある場合は完了時の実測値とも照合します。未検証streamへ`Content-Length`は設定しません。Response開始後に判明した上限超過またはlength不一致は別のHTTP statusへ変更できないため、streamをcancelしてstable error codeで終了します。上限超過、consumer cancel、AbortSignal、正常完了をsource cancel/release reasonへ伝えます。release failureはprivate provider messageを返さず`NAMED_DATA_PROVIDER_RELEASED`へ変換します。
|
|
41
|
+
|
|
42
|
+
## representationとHTTP metadata
|
|
43
|
+
|
|
44
|
+
| representation | 許可media type |
|
|
45
|
+
| --- | --- |
|
|
46
|
+
| `json` | `application/json`, `*+json` |
|
|
47
|
+
| `yaml` | `application/yaml`, `application/x-yaml`, `text/yaml` |
|
|
48
|
+
| `html` | `text/html` |
|
|
49
|
+
| `markdown` | `text/markdown`, `text/x-markdown` |
|
|
50
|
+
| `raw` | 有効なtype/subtype |
|
|
51
|
+
|
|
52
|
+
metadataの`mediaType`、`byteLength`、`etag`/`revision`を検証し、Content-Type、Content-Length、ETagへ写像します。CR/LF/NUL、負数、不正length、representation mismatchを拒否します。body bytes、JSON/document内容、provider例外messageをerror responseへ含めません。
|
|
53
|
+
|
|
54
|
+
## stable error
|
|
55
|
+
|
|
56
|
+
| code | HTTP status |
|
|
57
|
+
| --- | ---: |
|
|
58
|
+
| `NAMED_DATA_INVALID_REF` | 400 |
|
|
59
|
+
| `NAMED_DATA_PROVIDER_NOT_FOUND` | 501 |
|
|
60
|
+
| `NAMED_DATA_NOT_FOUND` | 404 |
|
|
61
|
+
| `NAMED_DATA_KIND_MISMATCH` | 400 |
|
|
62
|
+
| `NAMED_DATA_SCOPE_MISMATCH` | 400 |
|
|
63
|
+
| `NAMED_DATA_REPRESENTATION_UNSUPPORTED` | 415 |
|
|
64
|
+
| `NAMED_DATA_INVALID_METADATA` | 502 |
|
|
65
|
+
| `NAMED_DATA_BODY_TOO_LARGE` | 413 |
|
|
66
|
+
| `NAMED_DATA_ABORTED` | 499 |
|
|
67
|
+
| `NAMED_DATA_PROVIDER_RELEASED` | 503 |
|
|
68
|
+
| `NAMED_DATA_INVALID_REGISTRY`/`NAMED_DATA_PROVIDER_CONFLICT` | 500 |
|
|
69
|
+
HTTP ServerはNamed Data `0.2.x`契約を要求します。`0.1.x`のruntime versioning error codeは受理せず、consumerはNamed DataとHTTP Serverを同時に更新します。
|
|
70
|
+
|
|
71
|
+
feature無効時は`NAMED_RESPONSE_BODY_DISABLED`、provider metadata contract違反は`NAMED_RESPONSE_INVALID_METADATA`です。
|
|
72
|
+
|
|
73
|
+
## 共通Named Data registry
|
|
74
|
+
|
|
75
|
+
`NamedDataRegistryResolver`は`@kubohiroya/turbowarp-named-data`のcanonical registryをHTTP response境界へ接続します。constructorのcontext resolverは、`targetId`を実際のTurboWarp target objectへ解決し、project scopeではruntime固有のproject objectを返します。文字列IDをprovider contextの代用にはしません。
|
|
76
|
+
|
|
77
|
+
実サーバーでは`startServer({namedBodyResolver: new NamedDataRegistryResolver(...)})`として明示的に注入します。HTTP ServerがTurboWarpとは別processで動作する場合、browser runtimeのregistry objectを直接共有することはできないため、server側providerを登録するか、検証済みのprocess間adapterを用意する必要があります。descriptorだけからbrowser内のWeakMapやasset stateを推測しません。
|
|
78
|
+
|
|
79
|
+
registryから返された`reference`、`kind`、`scope`、`nativeRepresentation`、出力`representation`、MIME、digest、revision、replayable属性はHTTP境界まで保持されます。HTTP Serverはprovider内部のJSON tree、document AST、binary storage、asset registryを参照しません。
|
|
80
|
+
|
|
81
|
+
## IR統合
|
|
82
|
+
|
|
83
|
+
`respond-named-body`はdescriptor、representation、最大byte数、target scopeの場合だけ`targetId`を持つ単一terminal statementです。
|
|
84
|
+
|
|
85
|
+
```json
|
|
86
|
+
{
|
|
87
|
+
"kind": "respond-named-body",
|
|
88
|
+
"reference": {
|
|
89
|
+
"namespace": "structured",
|
|
90
|
+
"name": "profile",
|
|
91
|
+
"kind": "structured",
|
|
92
|
+
"scope": "target"
|
|
93
|
+
},
|
|
94
|
+
"targetId": "Stage:1",
|
|
95
|
+
"representation": "json",
|
|
96
|
+
"maxBytes": 1048576
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
IRは`named-body-provider` capabilityを明示しなければなりません。生成Hono coreは`CoreServices.namedBodies`だけに依存し、provider SDKや保存形式をimportしません。現在のCloudflare/Firebase adapterは実providerを持たないため、flagを有効にしても`TW2_TARGET_CAPABILITY_UNSUPPORTED`でcompileを停止します。test adapterとfake providerでJSON/raw binary/HEADのsemantic parityを検証します。
|
|
101
|
+
|
|
102
|
+
requestのaffine `binary-body`はnamed snapshotへ暗黙変換せず、明示import operationが定義されるまで既存`respond-binary`と別型のまま維持します。text/base64 fallbackは行いません。
|
|
103
|
+
|
|
104
|
+
## Asset Manager ResourceCapability adapter
|
|
105
|
+
|
|
106
|
+
`createAssetManagerNamedBodyProvider(resources)`は、既存の公開`ResourceCapability`だけを使用し、Asset Manager extensionのprivate fieldやIndexedDB/OPFS layoutを読みません。canonicalな`asset` namespaceの`asset` kindと`raw` representationだけを受理します。project scopeはglobal resource namespace(既定`routeName = ""`)、target scopeはruntimeの`targetId`へ写像します。
|
|
107
|
+
|
|
108
|
+
`HEAD`は`listResources`が利用可能ならmetadataだけを参照し、`GET`は`getResource`が返したbytesをcopyしてsnapshotを分離します。`replacementId`または`etag`をcanonical revisionとして必須にし、同名resourceから偽のETagを生成しません。未公開namespaceはnot foundとして扱い、kind/representation不一致とabortは共通のstable errorへ変換します。このadapterはNode runtime向けであり、生成targetが`named-body-provider` capabilityを宣言する根拠にはしません。
|
|
109
|
+
|
|
110
|
+
## TurboWarp bridge block
|
|
111
|
+
|
|
112
|
+
`respond with named ...` blockはnamespace、name、kind、scope、任意のtarget ID、representation、最大byte数だけをWebSocket bridgeへ送ります。resource body、base64、data URLはbridge messageへ格納しません。Node serverは`--enable-named-response-body`指定時だけdescriptorを上記Asset Manager providerへ渡し、block側上限とserver側上限の小さい方を適用します。
|
|
113
|
+
|
|
114
|
+
同じblock messageをGETで受けるとsnapshot bodyを返し、HEADではproviderの`stat`を使用してbodyを返しません。feature flag未指定時はproviderへアクセスせず501 `NAMED_RESPONSE_BODY_DISABLED`です。Structured Dataなど別namespaceは対応providerが登録されるまで`NAMED_DATA_PROVIDER_NOT_FOUND`となります。
|
|
115
|
+
|
|
116
|
+
server compiler向けの`lowerNamedBodyResponse`は、同じblock引数をcanonical `respond-named-body` statementへ変換します。namespace、name、kind、scope、target ID、representation、最大byte数はcompile-time literalだけを受理します。これによりprovider capability、scope、target上限をcode generation前に検証できます。project scopeではblockの`TARGET_ID`入力をIRへ含めず、target scopeの場合だけ必須にします。IR v2 frontendはTurboWarp project全体を走査し、source位置と`named-body-provider` capabilityを保持してこのloweringへ接続します。
|
|
117
|
+
|
|
118
|
+
## ロールバック
|
|
119
|
+
|
|
120
|
+
compiler flagがOFFの場合は`TW2_NAMED_RESPONSE_BODY_DISABLED`で生成前に拒否します。runtimeの`namedResponseBody=false`ではproviderを参照せず501 `NAMED_RESPONSE_BODY_DISABLED`を返します。既存`respond`/`respond-binary`、browser runtime、cloud objectは変更・削除しません。問題時は新しい呼び出し経路だけを停止できます。
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# IR v2 platform storage adapter
|
|
2
|
+
|
|
3
|
+
Deploy IR v2のstorageは製品名ではなく、`key-value-store`、`record-store`、`object-storage`、`streaming-body` capabilityで表します。同じIRを`cloudflare-workers`または`firebase-functions`へcompileし、共有Hono coreはplatform SDKを参照しません。
|
|
4
|
+
|
|
5
|
+
## 現在の変換境界
|
|
6
|
+
|
|
7
|
+
`@kubohiroya/turbowarp-kvs` 0.1.0のmanifest format 2でserver対応と宣言された`setValue`、`getValue`、`hasKey`、`deleteKey`、`listKeys`だけを`kvs-*` IRへloweringします。lockされたpackage名、version、opcode、引数順、型、effect、immutable属性がcompiler allowlistと完全一致しない場合はcompileを停止します。
|
|
8
|
+
|
|
9
|
+
`@kubohiroya/turbowarp-asset-cache` 0.1.0はbrowser内のasset registry/cacheとして扱い、`registerAsset`、`isLoaded`、renderer、audio、IndexedDB cache操作をKVSへ推測変換しません。binary storageは[Binary resource semantics](binary-resource-semantics.ja.md)のdirect IRから利用できます。Structured DataのJSON値は[Structured Data lowering](structured-data-lowering.ja.md)を経てroute内で処理します。
|
|
10
|
+
|
|
11
|
+
## 論理操作と実装
|
|
12
|
+
|
|
13
|
+
| 論理責務 | Cloudflare Workers | Firebase Functions |
|
|
14
|
+
| --- | --- | --- |
|
|
15
|
+
| HTTP runtime | Hono Fetch handler | HTTPS `onRequest` + Hono Node listener |
|
|
16
|
+
| `key-value-store` | D1 `kvs` table | Firestore KVS collection |
|
|
17
|
+
| `record-store` | D1 `records` table | Firestore root collection |
|
|
18
|
+
| `object-storage` | R2 bucket | Cloud Storage bucket |
|
|
19
|
+
| object revision | R2 upload version + ETag + upload時刻のopaque token | Cloud Storage generation |
|
|
20
|
+
| binary integrity | 指定されたSHA-256をR2で検証しmetadataへ保持 | stream中にSHA-256を計算・検証してmetadataへ保持 |
|
|
21
|
+
| local boundary | Wrangler local runtime | Firebase Emulator Suite |
|
|
22
|
+
|
|
23
|
+
KVS text contractはnamespace/key単位のset/get/has/delete/listです。getの未存在は空文字、hasはfalse、deleteは副作用なし、listはkeyの昇順JSON配列を返します。namespaceとkeyはNFC正規化し、namespaceは`^[a-z][a-z0-9.-]{0,63}$`、keyは1〜512文字でNULおよび`.`/`..` path segmentを拒否します。listはブラウザ版と同じ全件契約であり、adapterが黙って件数を切り詰めません。bounded listing/paginationは新しいblockとIR operationで追加します。
|
|
24
|
+
|
|
25
|
+
現在の`record-store`はcreate/list/get/deleteの単一record CRUDです。複数record transaction、counter、object listing、cursor pagination、cacheはIRに存在せず、adapterが暗黙に追加しません。record listは生成core contractに従い最大100件です。
|
|
26
|
+
|
|
27
|
+
Cloudflare adapterのbinary上限はcompiler既定と同じ16 MiBです。Firebase 2nd genはHTTP requestを最大32 MBまで受け取れますが、streaming responseは10 MBのため、同じIRを安全に実行できるtarget上限を10,000,000 bytesに固定します。operationの`maxBytes`がtarget上限を超える場合は`TW2_TARGET_BINARY_LIMIT_EXCEEDED`でcompileを停止します。([Cloud Functions quotas](https://firebase.google.com/docs/functions/quotas))
|
|
28
|
+
|
|
29
|
+
TurboWarp KVSの名前は論理APIを表し、Cloudflare KV製品を指定しません。Cloudflare KVはeventual-consistencyを許容できるalias/cache用途の将来候補ですが、現在のread-after-write KVS/object/record操作には使用しません。CloudflareではKVSをD1へ写像します。eventual consistencyを許容する別contractを追加するときは新しいIR capabilityとして定義し、既存KVS操作から推測しません。
|
|
30
|
+
|
|
31
|
+
## keyとmetadataの共通規則
|
|
32
|
+
|
|
33
|
+
objectの物理keyは両targetで次の形式です。
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
v1/<namespace>/<key>
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
- `namespace`は小文字英字で始まり、小文字英数字・`.`・`-`だけを使う64文字以下のlogical IDです。
|
|
40
|
+
- `key`はrelative pathで、absolute path、backslash、空segment、`.`、`..`を拒否します。
|
|
41
|
+
- user inputをbucket名、Firestore collection名、binding名へ直接展開しません。
|
|
42
|
+
- binaryはbase64化してD1、Firestore、KVへ格納しません。
|
|
43
|
+
- `contentType`はCR/LFを拒否し、`integrity`は`sha256:<lowercase-hex-64>`だけを受理します。
|
|
44
|
+
- `revision`はadapter固有のopaque tokenで、target間で同じ値になることを保証しません。
|
|
45
|
+
|
|
46
|
+
metadata envelopeのversionは物理key prefixの`v1`で固定します。Cloudflareは入力にintegrityがある場合だけ`twIntegrity`へ保持し、R2のSHA-256検証を利用します。R2の文書化された`BadDigest (10037)`だけをintegrity不一致へ変換し、その他のSDK例外はstorage failureとして扱います。Firebaseはupload streamを一時objectへ書きながらincremental hashし、size/integrity検証後にだけdestinationへcopyします。計算したintegrityは`twIntegrity`へ保持します。共通coreが依存できるのはlogical descriptorだけで、R2 ETagやCloud Storage SDK objectを外へ公開しません。([R2 error codes](https://developers.cloudflare.com/r2/api/error-codes/))
|
|
47
|
+
|
|
48
|
+
## target config
|
|
49
|
+
|
|
50
|
+
target configはsecretを受け取らず、生成コードの識別子だけを設定します。
|
|
51
|
+
|
|
52
|
+
```json
|
|
53
|
+
{
|
|
54
|
+
"recordDatabaseBinding": "DB",
|
|
55
|
+
"objectBucketBinding": "OBJECTS"
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
CloudflareではD1/R2 binding名を大文字identifierとして受け取り、同じ名前は拒否します。実database IDやcredentialは`wrangler.jsonc`のplaceholderとdeployment環境で設定します。
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"functionName": "api",
|
|
64
|
+
"keyValueCollection": "key_values",
|
|
65
|
+
"objectBucketEnv": "ASSET_BUCKET",
|
|
66
|
+
"recordCollection": "records"
|
|
67
|
+
}
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Firebaseではfunction export名、bucket名を読む環境変数名、KVS用およびrecord用Firestore collection名だけを受け取ります。project ID、service account、credential、bucket名そのものはtarget configへ書きません。未定義の`ASSET_BUCKET`はAdmin SDKのdefault bucketを選びます。
|
|
71
|
+
|
|
72
|
+
未知field、不正identifier、secretらしい設定は`TW2_TARGET_CONFIG_INVALID`です。adapterが満たせないcapabilityは`TW2_TARGET_CAPABILITY_UNSUPPORTED`とし、target、route、取得できる場合は`sourceRef`、理由、代替案を返します。
|
|
73
|
+
|
|
74
|
+
## access policyと整合性
|
|
75
|
+
|
|
76
|
+
KVSのD1実装は`(namespace, key)`複合主キーとupsertを使い、listをkey昇順にします。入力検証失敗は`KVS_NAMESPACE_INVALID`/`KVS_KEY_INVALID`、D1例外は`KVS_STORAGE_FAILURE`へ変換します。
|
|
77
|
+
|
|
78
|
+
R2のWorkers APIはobjectのhead/get/put/deleteとstreamを提供し、objectとlistingのstrong consistencyを保証します。revisionはuploadごとに一意なR2 `version`、ETag、upload時刻を組み合わせたopaque tokenです。revision付きdeleteは事前に`version`を照合し、R2が原子的条件として提供するETagとupload時刻を使ったPUTでzero-byte tombstoneへ置換します。`version`自体はR2の条件付きPUTへ指定できないため、保証はR2の同一key書き込み制限とETag/upload時刻の識別性に依存します。revisionなしlocator deleteは条件不一致時に再解決して最大8回まで再試行しますが、rate limitなどR2が例外を返した場合はstorage failureです。resolve/getはtombstoneをnot foundとして扱います。D1とR2をまたぐ原子的transactionは提供しません。custom domain cacheを経由する場合の整合性はこのbinding contractの対象外です。([R2 Workers API](https://developers.cloudflare.com/r2/api/workers/workers-api-reference/), [R2 consistency](https://developers.cloudflare.com/r2/reference/consistency/), [R2 limits](https://developers.cloudflare.com/r2/platform/limits/))
|
|
79
|
+
|
|
80
|
+
Firebase生成handlerはAdmin SDKと実行service accountのIAMでFirestore/Cloud Storageへaccessします。KVS document IDは正規化済みnamespace/keyのSHA-256で、元のnamespace/keyもquery fieldとして保存します。deleteの存在判定と削除はFirestore transaction内で行い、namespace + key昇順list用composite indexを生成します。objectのreadはmetadataで確定したgenerationへstreamを固定し、copy完了時はAPI responseの`resource` metadataから宛先generationを取得します。revision付きdeleteと一時object cleanupにはgeneration preconditionを使用します。生成するFirestore RulesとStorage Rulesはbrowser clientのread/writeを既定で全拒否し、Admin SDKの認可境界とは混同しません。record collection + `createdAt` queryに必要なcomposite indexも生成します。([Admin SDK setup](https://firebase.google.com/docs/admin/setup), [Cloud Storage Admin](https://firebase.google.com/docs/storage/admin/start), [Firestore data](https://firebase.google.com/docs/firestore/manage-data/add-data))
|
|
81
|
+
|
|
82
|
+
## 検証とsmoke test
|
|
83
|
+
|
|
84
|
+
通常CIでは同じfixtureを両targetへ決定的に生成し、全生成TypeScriptをtypecheckします。cloud account、課金resource、credentialは使用しません。
|
|
85
|
+
|
|
86
|
+
外部runtime smoke testは独立jobとして次を確認します。
|
|
87
|
+
|
|
88
|
+
1. Wrangler local resourceまたはFirebase Emulator Suiteを起動する。
|
|
89
|
+
2. KVS set/get/has/delete/listとread-after-writeを実行する。
|
|
90
|
+
3. record create/list/get/deleteを実行する。
|
|
91
|
+
4. binary put/resolve/get/delete、content type、size、SHA-256、revision不一致を確認する。
|
|
92
|
+
5. path traversal、size超過、integrity不一致がstable errorになることを確認する。
|
|
93
|
+
6. emulator failureは可視化し、core/target conformance testをskipしない。
|
|
94
|
+
|
|
95
|
+
## ロールバックとcleanup
|
|
96
|
+
|
|
97
|
+
targetは明示的な`--target ...`でだけ選択されます。問題のあるtargetへの生成・deployを停止し、browser bridgeへ戻せます。生成はdeployやresource作成・削除を行いません。
|
|
98
|
+
|
|
99
|
+
deploymentをrollbackまたは停止してから、必要なD1/R2/Firestore/Cloud Storage dataをexportし、binding、IAM、依存functionを確認します。cloud resourceはgenerated READMEの手順に従い手動でcleanupし、generatorから自動削除しません。
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# Server-executable subset
|
|
2
|
+
|
|
3
|
+
Deploy IR v2 pipelineは、TurboWarp projectをそのままserver runtimeとして実行しません。frontendでHTTP handlerから到達するblockをallowlist検証し、lowering後のIRをtarget-neutral validatorで再検証します。validatorを迂回してv2 code generationするoptionは提供しません。
|
|
4
|
+
|
|
5
|
+
このvalidatorはすべてのDeploy IR v2生成で必ず実行し、検証を迂回するCLI経路を提供しません。
|
|
6
|
+
|
|
7
|
+
## TurboWarp block subset
|
|
8
|
+
|
|
9
|
+
MVPで許可するblockは次の範囲です。
|
|
10
|
+
|
|
11
|
+
- HTTP request hat、request field/query/header reporter
|
|
12
|
+
- response status/header/terminal response
|
|
13
|
+
- request-local handler variable
|
|
14
|
+
- HTTP method guardとしてのtop-level `control_if`
|
|
15
|
+
- string join等、loweringが定義されたpure expression
|
|
16
|
+
- literal `0..1000`の`control_repeat`
|
|
17
|
+
- lock済みmanifestで`server.supported: true`かつcompiler allowlistとsignatureが一致するoperation
|
|
18
|
+
|
|
19
|
+
明示的に拒否するものは次のとおりです。
|
|
20
|
+
|
|
21
|
+
| 分類 | 代表opcode | diagnostic | 理由 |
|
|
22
|
+
| --- | --- | --- | --- |
|
|
23
|
+
| global variable/list | `data_*` | `TW2_GLOBAL_STATE_UNSUPPORTED` | request/workerを越える共有stateになる |
|
|
24
|
+
| broadcast/message | `event_broadcast*` | `TW2_MESSAGE_UNSUPPORTED` | schedulerとlifetimeをbounded requestへ写像できない |
|
|
25
|
+
| unbounded loop | `control_forever` | `TW2_UNBOUNDED_LOOP` | 上限を静的証明できない |
|
|
26
|
+
| clone | `control_*clone*` | `TW2_CLONE_UNSUPPORTED` | sprite runtime stateへ依存する |
|
|
27
|
+
| renderer/audio/UI | `motion_*`、`looks_*`、`sound_*`等 | `TW2_RUNTIME_DEPENDENCY_UNSUPPORTED` | browser/sprite runtimeへ依存する |
|
|
28
|
+
| 一般Scratch branch | `control_if_else`等 | `TW2_CONTROL_FLOW_UNSUPPORTED` | Scratch coercionをMVP frontendで推測しない |
|
|
29
|
+
| manifest未許可 | 任意extension block | `TW2_UNSUPPORTED_OPERATION` | block manifestの存在だけではserver実行を許可しない |
|
|
30
|
+
|
|
31
|
+
project内に存在してもHTTP request hatから到達しないbrowser scriptはserver compilerの対象にせず、このvalidatorでは拒否しません。
|
|
32
|
+
|
|
33
|
+
## Handler variableとtyped binding
|
|
34
|
+
|
|
35
|
+
handler variableはrequestごとに生成・破棄するScratch互換scalar stateです。
|
|
36
|
+
|
|
37
|
+
- nameはScratch scalarからstring castできるものだけ
|
|
38
|
+
- `set`はscalar inputをScratch string変換してstringを保持
|
|
39
|
+
- `change`はscalar inputと既存値をScratch number変換してnumberを保持
|
|
40
|
+
- JSON、`binary-ref`、`binary-body`を格納しない
|
|
41
|
+
- route間、request間、thread間で共有しない
|
|
42
|
+
|
|
43
|
+
未設定nameのreadはScratch互換の空文字、existsはfalseとして初期化されます。globalな初期値や前requestの値を引き継ぎません。
|
|
44
|
+
|
|
45
|
+
JSON、record result、binary参照、resourceはcompilerが割り当てるlexical typed bindingで扱います。binding IDはdynamicなuser inputから作らず、producerより後かつ同じscope内だけで参照できます。`if`の後へbindingを持ち出す場合、継続する両branchが同じIDと型を宣言する必要があります。loop内で宣言したbindingはloop外へ漏れません。
|
|
46
|
+
|
|
47
|
+
## Control flowとresponse
|
|
48
|
+
|
|
49
|
+
- IR `if` conditionはboolean型。Scratch truthinessを暗黙適用しません。
|
|
50
|
+
- 各正常control-flow pathはterminal responseへちょうど1回到達します。
|
|
51
|
+
- response後のstatement、同一路径の2回目のresponseを拒否します。
|
|
52
|
+
- loop内responseを拒否します。loopは0回または複数回実行され得るためです。
|
|
53
|
+
- runtime error responseは後続pipelineの共通error boundaryが作るため、user response数には含めません。
|
|
54
|
+
|
|
55
|
+
## Loopとwork budget
|
|
56
|
+
|
|
57
|
+
target-neutral上限は固定です。
|
|
58
|
+
|
|
59
|
+
- loop literal bound: `0..1000`
|
|
60
|
+
- loop nesting: 最大8
|
|
61
|
+
- route worst-case work: 最大10,000
|
|
62
|
+
|
|
63
|
+
通常statement/expressionは各1 stepです。sequenceは加算、`if`はconditionと重い方のbranch、bounded loopは`1 + maxIterations × body steps`で計算します。計算は10,000を越えた時点でsaturateし、巨大な積でnumber overflowを起こしません。target adapterはより小さい上限を要求できますが、target-neutral validatorを緩和できません。
|
|
64
|
+
|
|
65
|
+
## Capability phase
|
|
66
|
+
|
|
67
|
+
record操作やclient address参照等が必要とするlogical capabilityはIR rootに宣言されていなければ`TW2_CAPABILITY_MISSING`です。これはtarget選択前のエラーです。
|
|
68
|
+
|
|
69
|
+
IRが正しくても選択targetが要求を実装できない場合は、adapter phaseの`TW2_TARGET_CAPABILITY_UNSUPPORTED`を使います。diagnosticの`phase`はそれぞれ`target-neutral`と`target-capability`であり、fallbackや近似変換を行いません。
|
|
70
|
+
|
|
71
|
+
## binary-body lifetime
|
|
72
|
+
|
|
73
|
+
`BinaryBodyLifetimeTracker`はlexical scopeごとに`binary-body` bindingを追跡します。
|
|
74
|
+
|
|
75
|
+
- consumeは最大1回
|
|
76
|
+
- scope終了後の参照を拒否
|
|
77
|
+
- 未宣言resourceを拒否
|
|
78
|
+
- clone、tee、暗黙bufferは行わない
|
|
79
|
+
|
|
80
|
+
二重consumeは`TW2_BINARY_BODY_CONSUMED`、scope外利用は`TW2_BINARY_BODY_SCOPE`、未宣言利用は`TW2_BINARY_BODY_UNDECLARED`です。具体的なbinary producer/consumer IR nodeはbinary resource Issueでこのtrackerへ接続します。
|
|
81
|
+
|
|
82
|
+
## Diagnostic
|
|
83
|
+
|
|
84
|
+
target-neutral diagnosticはcode、route ID、理由、修正候補を必須とします。元blockを持つ場合はtarget index/name、block ID、opcode、任意のinput名を`sourceRef`に保持します。runtime error codeとcompile diagnostic codeを混同しません。
|
|
85
|
+
|
|
86
|
+
## ロールバック
|
|
87
|
+
|
|
88
|
+
問題時は生成を停止してbrowser bridgeを利用します。validatorだけを無効化して未検証IRを生成する経路は作りません。
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
# Structured Data lowering
|
|
2
|
+
|
|
3
|
+
Deploy IR v2 frontendは、lockされた`@kubohiroya/turbowarp-structured-data` 0.4.0/manifest format 2のserver operationを、platform-neutralなIRとruntime helperへ変換します。Cloudflare Workers、Firebase等のSDKはこの層から参照しません。
|
|
4
|
+
|
|
5
|
+
この機能はmanifest lockのversion・integrity・signature検証が成功した場合だけ利用します。未対応versionやoperationを類似処理へfallbackしません。
|
|
6
|
+
|
|
7
|
+
## Operation mapping
|
|
8
|
+
|
|
9
|
+
| manifest operation | IR v2 |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| `structuredData.normalizeJson` | parse済みJSON + `json-stringify` |
|
|
12
|
+
| `structuredData.isValidJson` | `json-is-valid` |
|
|
13
|
+
| `structuredData.get` | `json-get` + `json-stringify` |
|
|
14
|
+
| `structuredData.has` | `json-has` |
|
|
15
|
+
| `structuredData.set` | `json-set` + `json-stringify` |
|
|
16
|
+
| `structuredData.delete` | `json-delete` + `json-stringify` |
|
|
17
|
+
| `structuredData.keys` | `json-keys` + `json-stringify` |
|
|
18
|
+
| `structuredData.length` | `json-length` |
|
|
19
|
+
| `structuredData.forEach` | bounded `json-for-each` |
|
|
20
|
+
| `structuredData.currentKey` | lexical `iteration-key` |
|
|
21
|
+
| `structuredData.currentIndex` | lexical `iteration-index` |
|
|
22
|
+
| `structuredData.currentValue` | lexical `iteration-value` + `json-stringify` |
|
|
23
|
+
|
|
24
|
+
TurboWarp blockのJSON入出力は実体がstringのnominal `json-text`です。動的な通常string入力には`json-text-coerce`を置き、その後`json-parse`で内部`JsonValue`へ変換します。JSON literalはcompile時に検証してtyped literalへfoldします。既知の不正literalは`TW2_STRUCTURED_INVALID_LITERAL`で停止し、動的入力の失敗だけをruntime `INVALID_JSON`にします。reporterがJSONを返す場合は`json-stringify`で`json-text`へ戻します。
|
|
25
|
+
|
|
26
|
+
## Path
|
|
27
|
+
|
|
28
|
+
MVPのgrammar IDは`tw-structured-path@1`です。compiler自身が次のliteral grammarだけを解析し、manifestからparser codeを読み込みません。
|
|
29
|
+
|
|
30
|
+
- root `$`
|
|
31
|
+
- identifier key `.name`
|
|
32
|
+
- array index `[0]`
|
|
33
|
+
- JSON quoted key `["name.with.dots"]`
|
|
34
|
+
|
|
35
|
+
`["0"]`はkey、`[0]`はindexとして異なるtyped segmentになります。dynamic pathは`TW2_STRUCTURED_DYNAMIC_PATH`、不正literalは`TW2_STRUCTURED_INVALID_PATH`です。diagnosticの`sourceRef.input`には`PATH`等の入力名を保持します。
|
|
36
|
+
|
|
37
|
+
`set`はroot置換、既存objectへのkey追加、既存array indexの置換だけを行います。中間container生成、sparse array、appendは行いません。`delete`はrootをcompile時に拒否し、array要素削除時は後続要素を左へ詰めます。すべての更新は入力を変更せず、新しいJSON値を返します。
|
|
38
|
+
|
|
39
|
+
## Iteration
|
|
40
|
+
|
|
41
|
+
`forEach`の`MAX`は1以上1000以下のinteger literalだけを受理します。IR validatorでは通常loopと共通のnesting上限8とroute worst-case work上限10000も適用します。
|
|
42
|
+
|
|
43
|
+
各loopはsource blockから決定的な`loopId`を作ります。current key/index/valueは構文木上で最も内側のactive `json-for-each`へ束縛され、nested loop終了後は外側contextへ戻ります。loop外またはscope終了後の参照は`TW2_ITERATION_CONTEXT_REQUIRED`です。objectはUnicode code point順、arrayはindex順で反復します。
|
|
44
|
+
|
|
45
|
+
## Runtime errors
|
|
46
|
+
|
|
47
|
+
runtime helperは次のcodeを持つ`IrRuntimeError`をHTTP status 422として送出します。
|
|
48
|
+
|
|
49
|
+
- `INVALID_JSON`
|
|
50
|
+
- `INVALID_PATH`(malformed IR防御。正常なgenerated codeでは発生しない)
|
|
51
|
+
- `PATH_NOT_FOUND`
|
|
52
|
+
- `TYPE_MISMATCH`
|
|
53
|
+
- `INDEX_OUT_OF_RANGE`
|
|
54
|
+
- `ITERATION_LIMIT_EXCEEDED`
|
|
55
|
+
- `ITERATION_CONTEXT_REQUIRED`(adapter側防御用)
|
|
56
|
+
|
|
57
|
+
helperのmessageに入力JSON、path、keyを埋め込みません。HTTP responseへの安定したerror envelope化はadapter error boundaryの責務です。
|
|
58
|
+
|
|
59
|
+
application JSONのobject keyはUnicode code point順に再帰的にserializeします。IR documentのcanonical serialization規則とは別であり、platform native object/mapの順序には依存しません。
|
|
60
|
+
|
|
61
|
+
## ロールバック
|
|
62
|
+
|
|
63
|
+
問題時は該当manifest lockを使う生成を停止します。manifest version不一致時はcompileを停止し、旧意味論へfallbackしません。
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": 2,
|
|
3
|
+
"name": "turbowarp-message-app",
|
|
4
|
+
"auth": {"kind": "none"},
|
|
5
|
+
"capabilities": [{"kind": "record-store"}],
|
|
6
|
+
"routes": [
|
|
7
|
+
{
|
|
8
|
+
"id": "home",
|
|
9
|
+
"method": "GET",
|
|
10
|
+
"path": "/",
|
|
11
|
+
"auth": "public",
|
|
12
|
+
"body": [
|
|
13
|
+
{
|
|
14
|
+
"kind": "respond",
|
|
15
|
+
"format": "text",
|
|
16
|
+
"body": {"kind": "literal", "valueType": "string", "value": "TurboWarp message API"}
|
|
17
|
+
}
|
|
18
|
+
]
|
|
19
|
+
},
|
|
20
|
+
{
|
|
21
|
+
"id": "create-message",
|
|
22
|
+
"method": "POST",
|
|
23
|
+
"path": "/messages",
|
|
24
|
+
"auth": "public",
|
|
25
|
+
"body": [
|
|
26
|
+
{
|
|
27
|
+
"kind": "record-create",
|
|
28
|
+
"collection": "messages",
|
|
29
|
+
"data": {"kind": "request", "valueType": "string", "source": "body-text"},
|
|
30
|
+
"result": {"id": "created", "type": {"kind": "value", "valueType": "json-object"}}
|
|
31
|
+
},
|
|
32
|
+
{"kind": "set-status", "status": 201},
|
|
33
|
+
{
|
|
34
|
+
"kind": "respond",
|
|
35
|
+
"format": "json",
|
|
36
|
+
"body": {"kind": "binding", "valueType": "json-object", "binding": "created"}
|
|
37
|
+
}
|
|
38
|
+
]
|
|
39
|
+
}
|
|
40
|
+
]
|
|
41
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kubohiroya/turbowarp-http-server",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "A TurboWarp extension for connecting block programs to an HTTP bridge server.",
|
|
5
5
|
"author": "Hiroya Kubo <hiroya@cuc.ac.jp>",
|
|
6
6
|
"license": "MPL-2.0",
|
|
@@ -37,33 +37,22 @@
|
|
|
37
37
|
"README.ja.md",
|
|
38
38
|
"LICENSE"
|
|
39
39
|
],
|
|
40
|
+
"packageManager": "pnpm@11.11.0",
|
|
40
41
|
"engines": {
|
|
41
42
|
"node": ">=22.18.0"
|
|
42
43
|
},
|
|
43
|
-
"dependencies": {
|
|
44
|
-
"@hono/node-server": "^1.19.6",
|
|
45
|
-
"hono": "^4.10.7",
|
|
46
|
-
"ws": "^8.18.3"
|
|
47
|
-
},
|
|
48
|
-
"devDependencies": {
|
|
49
|
-
"@eslint/js": "^9.39.5",
|
|
50
|
-
"@kubohiroya/vite-plugin-turbowarp-extension": "0.4.0",
|
|
51
|
-
"@types/node": "^24.13.3",
|
|
52
|
-
"@types/ws": "^8.18.1",
|
|
53
|
-
"eslint": "^9.39.5",
|
|
54
|
-
"tsx": "^4.21.0",
|
|
55
|
-
"typescript": "^5.9.3",
|
|
56
|
-
"typescript-eslint": "^8.66.0",
|
|
57
|
-
"vite": "^8.2.2",
|
|
58
|
-
"vitest": "^4.1.10"
|
|
59
|
-
},
|
|
60
44
|
"scripts": {
|
|
61
45
|
"dev": "vite build --watch",
|
|
62
46
|
"dev:server": "tsx watch src/cli.ts",
|
|
63
47
|
"typecheck": "tsc --noEmit",
|
|
64
48
|
"build": "vite build && tsc -p tsconfig.cli.json",
|
|
65
|
-
"lint": "eslint src tests vite.config.ts",
|
|
49
|
+
"lint": "eslint src tests scripts/check-target-runtimes.mts vite.config.ts",
|
|
66
50
|
"test": "vitest run",
|
|
51
|
+
"test:conformance": "vitest run tests/conformance",
|
|
52
|
+
"test:conformance:frontend": "vitest run tests/conformance/frontend.test.ts",
|
|
53
|
+
"test:conformance:core": "vitest run tests/conformance/core-runtime.test.ts",
|
|
54
|
+
"test:conformance:target": "vitest run tests/conformance/target.test.ts",
|
|
55
|
+
"test:conformance:target-runtime": "tsx scripts/check-target-runtimes.mts",
|
|
67
56
|
"examples:check": "node scripts/check-examples.ts",
|
|
68
57
|
"docs": "node scripts/generate-readme.ts",
|
|
69
58
|
"docs:check": "node scripts/generate-readme.ts --check",
|
|
@@ -71,5 +60,40 @@
|
|
|
71
60
|
"start": "node dist/cli.js",
|
|
72
61
|
"check:dist": "pnpm run build && node scripts/check-dist.ts",
|
|
73
62
|
"check": "pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run examples:check && pnpm run docs:check && pnpm run check:dist && pnpm run pack:check"
|
|
63
|
+
},
|
|
64
|
+
"dependencies": {
|
|
65
|
+
"@hono/node-server": "^2.1.1",
|
|
66
|
+
"hono": "^4.13.8",
|
|
67
|
+
"ws": "^8.18.3"
|
|
68
|
+
},
|
|
69
|
+
"peerDependencies": {
|
|
70
|
+
"@kubohiroya/turbowarp-named-data": "0.3.1"
|
|
71
|
+
},
|
|
72
|
+
"devDependencies": {
|
|
73
|
+
"@cloudflare/workers-types": "^5.20260919.1",
|
|
74
|
+
"@eslint/js": "^9.39.5",
|
|
75
|
+
"@kubohiroya/turbowarp-extension-manifest": "0.3.2",
|
|
76
|
+
"@kubohiroya/turbowarp-named-data": "0.3.1",
|
|
77
|
+
"@kubohiroya/vite-plugin-turbowarp-extension": "0.6.1",
|
|
78
|
+
"@types/node": "^24.13.3",
|
|
79
|
+
"@types/ws": "^8.18.1",
|
|
80
|
+
"eslint": "^9.39.5",
|
|
81
|
+
"firebase-admin": "^14.4.0",
|
|
82
|
+
"firebase-functions": "^7.4.0",
|
|
83
|
+
"firebase-tools": "15.30.2",
|
|
84
|
+
"jose": "^6.1.0",
|
|
85
|
+
"tsx": "^4.21.0",
|
|
86
|
+
"typescript": "^5.9.3",
|
|
87
|
+
"typescript-eslint": "^8.66.0",
|
|
88
|
+
"vite": "^8.2.2",
|
|
89
|
+
"vitest": "^4.1.10",
|
|
90
|
+
"wrangler": "4.135.0",
|
|
91
|
+
"@kubohiroya/turbowarp-extension-data-editor": "0.2.1"
|
|
92
|
+
},
|
|
93
|
+
"gitHead": "43f179cbde9bc0f6b734a15e13eeb4495fc6e7b8",
|
|
94
|
+
"x-turbowarp-source": {
|
|
95
|
+
"revision": "43f179cbde9bc0f6b734a15e13eeb4495fc6e7b8",
|
|
96
|
+
"revisionRole": "base-commit",
|
|
97
|
+
"sourceState": "local-release-overlay"
|
|
74
98
|
}
|
|
75
|
-
}
|
|
99
|
+
}
|