@kubohiroya/turbowarp-http-server 0.2.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.
Files changed (234) hide show
  1. package/README.ja.md +29 -13
  2. package/README.md +101 -42
  3. package/dist/cli.js +131 -17
  4. package/dist/cli.js.map +1 -1
  5. package/dist/compiler/adapters/cloudflare.d.ts +2 -0
  6. package/dist/compiler/adapters/cloudflare.js +477 -0
  7. package/dist/compiler/adapters/cloudflare.js.map +1 -0
  8. package/dist/compiler/adapters/firebase.d.ts +2 -0
  9. package/dist/compiler/adapters/firebase.js +489 -0
  10. package/dist/compiler/adapters/firebase.js.map +1 -0
  11. package/dist/compiler/adapters/index.d.ts +2 -0
  12. package/dist/compiler/adapters/index.js +3 -0
  13. package/dist/compiler/adapters/index.js.map +1 -0
  14. package/dist/compiler/binary/codec.d.ts +4 -0
  15. package/dist/compiler/binary/codec.js +45 -0
  16. package/dist/compiler/binary/codec.js.map +1 -0
  17. package/dist/compiler/binary/error.d.ts +3 -0
  18. package/dist/compiler/binary/error.js +21 -0
  19. package/dist/compiler/binary/error.js.map +1 -0
  20. package/dist/compiler/binary/index.d.ts +4 -0
  21. package/dist/compiler/binary/index.js +5 -0
  22. package/dist/compiler/binary/index.js.map +1 -0
  23. package/dist/compiler/binary/runtime.d.ts +18 -0
  24. package/dist/compiler/binary/runtime.js +123 -0
  25. package/dist/compiler/binary/runtime.js.map +1 -0
  26. package/dist/compiler/binary/types.d.ts +17 -0
  27. package/dist/compiler/binary/types.js +2 -0
  28. package/dist/compiler/binary/types.js.map +1 -0
  29. package/dist/compiler/feature-flags.d.ts +4 -0
  30. package/dist/compiler/feature-flags.js +4 -0
  31. package/dist/compiler/feature-flags.js.map +1 -0
  32. package/dist/compiler/index.d.ts +35 -0
  33. package/dist/compiler/index.js +84 -0
  34. package/dist/compiler/index.js.map +1 -0
  35. package/dist/compiler/ir-v2/canonical.d.ts +3 -0
  36. package/dist/compiler/ir-v2/canonical.js +50 -0
  37. package/dist/compiler/ir-v2/canonical.js.map +1 -0
  38. package/dist/compiler/ir-v2/index.d.ts +4 -0
  39. package/dist/compiler/ir-v2/index.js +5 -0
  40. package/dist/compiler/ir-v2/index.js.map +1 -0
  41. package/dist/compiler/ir-v2/parse.d.ts +10 -0
  42. package/dist/compiler/ir-v2/parse.js +753 -0
  43. package/dist/compiler/ir-v2/parse.js.map +1 -0
  44. package/dist/compiler/ir-v2/strict-json.d.ts +4 -0
  45. package/dist/compiler/ir-v2/strict-json.js +133 -0
  46. package/dist/compiler/ir-v2/strict-json.js.map +1 -0
  47. package/dist/compiler/ir-v2/types.d.ts +412 -0
  48. package/dist/compiler/ir-v2/types.js +84 -0
  49. package/dist/compiler/ir-v2/types.js.map +1 -0
  50. package/dist/compiler/kvs/lowering.d.ts +13 -0
  51. package/dist/compiler/kvs/lowering.js +77 -0
  52. package/dist/compiler/kvs/lowering.js.map +1 -0
  53. package/dist/compiler/manifest/error.d.ts +7 -0
  54. package/dist/compiler/manifest/error.js +9 -0
  55. package/dist/compiler/manifest/error.js.map +1 -0
  56. package/dist/compiler/manifest/index.d.ts +6 -0
  57. package/dist/compiler/manifest/index.js +7 -0
  58. package/dist/compiler/manifest/index.js.map +1 -0
  59. package/dist/compiler/manifest/operations.d.ts +12 -0
  60. package/dist/compiler/manifest/operations.js +60 -0
  61. package/dist/compiler/manifest/operations.js.map +1 -0
  62. package/dist/compiler/manifest/parse.d.ts +9 -0
  63. package/dist/compiler/manifest/parse.js +280 -0
  64. package/dist/compiler/manifest/parse.js.map +1 -0
  65. package/dist/compiler/manifest/registry.d.ts +3 -0
  66. package/dist/compiler/manifest/registry.js +48 -0
  67. package/dist/compiler/manifest/registry.js.map +1 -0
  68. package/dist/compiler/manifest/resolve.d.ts +14 -0
  69. package/dist/compiler/manifest/resolve.js +116 -0
  70. package/dist/compiler/manifest/resolve.js.map +1 -0
  71. package/dist/compiler/manifest/types.d.ts +95 -0
  72. package/dist/compiler/manifest/types.js +3 -0
  73. package/dist/compiler/manifest/types.js.map +1 -0
  74. package/dist/compiler/named-body/index.d.ts +1 -0
  75. package/dist/compiler/named-body/index.js +2 -0
  76. package/dist/compiler/named-body/index.js.map +1 -0
  77. package/dist/compiler/named-body/lowering.d.ts +18 -0
  78. package/dist/compiler/named-body/lowering.js +83 -0
  79. package/dist/compiler/named-body/lowering.js.map +1 -0
  80. package/dist/compiler/pipeline/compiler.d.ts +18 -0
  81. package/dist/compiler/pipeline/compiler.js +105 -0
  82. package/dist/compiler/pipeline/compiler.js.map +1 -0
  83. package/dist/compiler/pipeline/core-generator.d.ts +3 -0
  84. package/dist/compiler/pipeline/core-generator.js +483 -0
  85. package/dist/compiler/pipeline/core-generator.js.map +1 -0
  86. package/dist/compiler/pipeline/index.d.ts +5 -0
  87. package/dist/compiler/pipeline/index.js +6 -0
  88. package/dist/compiler/pipeline/index.js.map +1 -0
  89. package/dist/compiler/pipeline/registry.d.ts +7 -0
  90. package/dist/compiler/pipeline/registry.js +17 -0
  91. package/dist/compiler/pipeline/registry.js.map +1 -0
  92. package/dist/compiler/pipeline/requirements.d.ts +9 -0
  93. package/dist/compiler/pipeline/requirements.js +135 -0
  94. package/dist/compiler/pipeline/requirements.js.map +1 -0
  95. package/dist/compiler/pipeline/types.d.ts +65 -0
  96. package/dist/compiler/pipeline/types.js +2 -0
  97. package/dist/compiler/pipeline/types.js.map +1 -0
  98. package/dist/compiler/runtime/error.d.ts +6 -0
  99. package/dist/compiler/runtime/error.js +9 -0
  100. package/dist/compiler/runtime/error.js.map +1 -0
  101. package/dist/compiler/runtime/index.d.ts +1 -0
  102. package/dist/compiler/runtime/index.js +2 -0
  103. package/dist/compiler/runtime/index.js.map +1 -0
  104. package/dist/compiler/structured-data/index.d.ts +3 -0
  105. package/dist/compiler/structured-data/index.js +4 -0
  106. package/dist/compiler/structured-data/index.js.map +1 -0
  107. package/dist/compiler/structured-data/lowering.d.ts +30 -0
  108. package/dist/compiler/structured-data/lowering.js +202 -0
  109. package/dist/compiler/structured-data/lowering.js.map +1 -0
  110. package/dist/compiler/structured-data/path.d.ts +2 -0
  111. package/dist/compiler/structured-data/path.js +60 -0
  112. package/dist/compiler/structured-data/path.js.map +1 -0
  113. package/dist/compiler/structured-data/runtime.d.ts +20 -0
  114. package/dist/compiler/structured-data/runtime.js +210 -0
  115. package/dist/compiler/structured-data/runtime.js.map +1 -0
  116. package/dist/compiler/turbowarp-v2.d.ts +8 -0
  117. package/dist/compiler/turbowarp-v2.js +479 -0
  118. package/dist/compiler/turbowarp-v2.js.map +1 -0
  119. package/dist/compiler/validator/index.d.ts +4 -0
  120. package/dist/compiler/validator/index.js +5 -0
  121. package/dist/compiler/validator/index.js.map +1 -0
  122. package/dist/compiler/validator/ir-validator.d.ts +10 -0
  123. package/dist/compiler/validator/ir-validator.js +463 -0
  124. package/dist/compiler/validator/ir-validator.js.map +1 -0
  125. package/dist/compiler/validator/resource-lifetime.d.ts +18 -0
  126. package/dist/compiler/validator/resource-lifetime.js +106 -0
  127. package/dist/compiler/validator/resource-lifetime.js.map +1 -0
  128. package/dist/compiler/validator/turbowarp-subset.d.ts +3 -0
  129. package/dist/compiler/validator/turbowarp-subset.js +241 -0
  130. package/dist/compiler/validator/turbowarp-subset.js.map +1 -0
  131. package/dist/compiler/validator/types.d.ts +30 -0
  132. package/dist/compiler/validator/types.js +7 -0
  133. package/dist/compiler/validator/types.js.map +1 -0
  134. package/dist/config.d.ts +11 -0
  135. package/dist/config.js +12 -0
  136. package/dist/config.js.map +1 -0
  137. package/dist/digest-cli.js +0 -0
  138. package/dist/extension-manifest.json +102 -0
  139. package/dist/named-body.d.ts +57 -0
  140. package/dist/named-body.js +396 -0
  141. package/dist/named-body.js.map +1 -0
  142. package/dist/named-data-namespace.d.ts +3 -0
  143. package/dist/named-data-namespace.js +6 -0
  144. package/dist/named-data-namespace.js.map +1 -0
  145. package/dist/protocol.d.ts +13 -1
  146. package/dist/protocol.js +34 -0
  147. package/dist/protocol.js.map +1 -1
  148. package/dist/resource-named-body-provider.d.ts +8 -0
  149. package/dist/resource-named-body-provider.js +88 -0
  150. package/dist/resource-named-body-provider.js.map +1 -0
  151. package/dist/server.d.ts +10 -1
  152. package/dist/server.js +37 -7
  153. package/dist/server.js.map +1 -1
  154. package/dist/turbowarp-http-server.js +516 -1
  155. package/docs/binary-resource-semantics.ja.md +84 -0
  156. package/docs/cloudflare-worker-compiler.ja.md +90 -0
  157. package/docs/compiler-manifest-registry.ja.md +79 -0
  158. package/docs/compiler-platform-pipeline.ja.md +94 -0
  159. package/docs/deploy-ir-v2.ja.md +123 -0
  160. package/docs/fixed-input-editors.ja.md +23 -0
  161. package/docs/index.html +80 -0
  162. package/docs/ir-v2-conformance.ja.md +65 -0
  163. package/docs/named-response-body.ja.md +120 -0
  164. package/docs/platform-storage-adapters.ja.md +99 -0
  165. package/docs/server-executable-subset.ja.md +88 -0
  166. package/docs/structured-data-lowering.ja.md +63 -0
  167. package/examples/compiler/message-app.v2.ir.json +41 -0
  168. package/package.json +44 -20
  169. package/schemas/block-editor-fixed-inputs.schema.json +85 -0
  170. package/schemas/compiler-extension-manifest.schema.json +126 -0
  171. package/schemas/compiler-manifest-lock-v1.schema.json +48 -0
  172. package/schemas/deploy-ir-v2.schema.json +835 -0
  173. package/schemas/ir-v2-conformance-fixture.schema.json +44 -0
  174. package/src/block-definitions.json +76 -0
  175. package/src/cli.ts +136 -23
  176. package/src/compiler/adapters/cloudflare.ts +510 -0
  177. package/src/compiler/adapters/firebase.ts +538 -0
  178. package/src/compiler/adapters/index.ts +2 -0
  179. package/src/compiler/binary/codec.ts +61 -0
  180. package/src/compiler/binary/error.ts +25 -0
  181. package/src/compiler/binary/index.ts +4 -0
  182. package/src/compiler/binary/runtime.ts +133 -0
  183. package/src/compiler/binary/types.ts +26 -0
  184. package/src/compiler/feature-flags.ts +7 -0
  185. package/src/compiler/index.ts +114 -0
  186. package/src/compiler/ir-v2/canonical.ts +46 -0
  187. package/src/compiler/ir-v2/index.ts +9 -0
  188. package/src/compiler/ir-v2/parse.ts +921 -0
  189. package/src/compiler/ir-v2/strict-json.ts +129 -0
  190. package/src/compiler/ir-v2/types.ts +462 -0
  191. package/src/compiler/kvs/lowering.ts +88 -0
  192. package/src/compiler/manifest/error.ts +29 -0
  193. package/src/compiler/manifest/index.ts +17 -0
  194. package/src/compiler/manifest/operations.ts +175 -0
  195. package/src/compiler/manifest/parse.ts +390 -0
  196. package/src/compiler/manifest/registry.ts +74 -0
  197. package/src/compiler/manifest/resolve.ts +159 -0
  198. package/src/compiler/manifest/types.ts +112 -0
  199. package/src/compiler/named-body/index.ts +1 -0
  200. package/src/compiler/named-body/lowering.ts +186 -0
  201. package/src/compiler/pipeline/compiler.ts +138 -0
  202. package/src/compiler/pipeline/core-generator.ts +486 -0
  203. package/src/compiler/pipeline/index.ts +5 -0
  204. package/src/compiler/pipeline/registry.ts +18 -0
  205. package/src/compiler/pipeline/requirements.ts +139 -0
  206. package/src/compiler/pipeline/types.ts +59 -0
  207. package/src/compiler/runtime/error.ts +11 -0
  208. package/src/compiler/runtime/index.ts +1 -0
  209. package/src/compiler/structured-data/index.ts +3 -0
  210. package/src/compiler/structured-data/lowering.ts +314 -0
  211. package/src/compiler/structured-data/path.ts +53 -0
  212. package/src/compiler/structured-data/runtime.ts +221 -0
  213. package/src/compiler/turbowarp-v2.ts +610 -0
  214. package/src/compiler/validator/index.ts +4 -0
  215. package/src/compiler/validator/ir-validator.ts +812 -0
  216. package/src/compiler/validator/resource-lifetime.ts +153 -0
  217. package/src/compiler/validator/turbowarp-subset.ts +387 -0
  218. package/src/compiler/validator/types.ts +68 -0
  219. package/src/extension.ts +87 -1
  220. package/src/fixed-input-editors.ts +181 -0
  221. package/src/fixed-input-schema.ts +15 -0
  222. package/src/named-body.ts +495 -0
  223. package/src/named-data-namespace.ts +6 -0
  224. package/src/protocol.ts +50 -1
  225. package/src/resource-named-body-provider.ts +106 -0
  226. package/src/server.ts +88 -8
  227. package/docs/turbowarp-http-server.architecture.visual-check.1440x900.dark.png +0 -0
  228. package/docs/turbowarp-http-server.architecture.visual-check.1440x900.light.png +0 -0
  229. package/docs/turbowarp-http-server.architecture.visual-check.2048x1320.dark.png +0 -0
  230. package/docs/turbowarp-http-server.architecture.visual-check.2048x1320.light.png +0 -0
  231. package/docs/turbowarp-http-server.architecture.visual-check.html +0 -32
  232. package/docs/turbowarp-http-server.architecture.visual-check.json +0 -547
  233. package/schemas/extension-manifest.schema.json +0 -49
  234. package/src/extension-manifest.ts +0 -149
@@ -0,0 +1,495 @@
1
+ import {
2
+ NAMED_DATA_ERROR_CODES,
3
+ type NamedDataBody,
4
+ type NamedDataErrorCode,
5
+ type NamedDataKind,
6
+ type NamedDataMetadata,
7
+ type NamedDataReference,
8
+ type NamedDataRegistryService,
9
+ type NamedDataReleaseReason,
10
+ type NamedDataRepresentation,
11
+ type NamedDataResolveContext,
12
+ type NamedDataScope
13
+ } from '@kubohiroya/turbowarp-named-data/composition';
14
+ import {isNamedDataNamespace} from './named-data-namespace.js';
15
+
16
+ export {NAMED_DATA_ERROR_CODES};
17
+ export type {NamedDataErrorCode, NamedDataKind, NamedDataReference, NamedDataScope};
18
+ export type NamedBodyErrorCode =
19
+ | NamedDataErrorCode
20
+ | 'NAMED_RESPONSE_BODY_DISABLED'
21
+ | 'NAMED_RESPONSE_INVALID_METADATA';
22
+
23
+ export type NamedBodyRepresentation = NamedDataRepresentation;
24
+
25
+ export interface NamedBodyRequest {
26
+ reference: NamedDataReference;
27
+ representation: NamedBodyRepresentation;
28
+ /** Runtime-local identity used only when reference.scope is target. */
29
+ targetId?: string;
30
+ }
31
+
32
+ export interface NamedBodyMetadata extends NamedDataMetadata {
33
+ etag?: string;
34
+ }
35
+
36
+ export type NamedBodyReleaseReason = Exclude<NamedDataReleaseReason, 'shutdown'>;
37
+
38
+ export interface NamedBodyHandle {
39
+ metadata: NamedBodyMetadata;
40
+ body: Uint8Array | ReadableStream<Uint8Array>;
41
+ release(reason: NamedBodyReleaseReason): void | Promise<void>;
42
+ }
43
+
44
+ export interface NamedBodyProvider {
45
+ canResolve(request: NamedBodyRequest): boolean;
46
+ stat(request: NamedBodyRequest, signal: AbortSignal): NamedBodyMetadata | null | Promise<NamedBodyMetadata | null>;
47
+ openBody(request: NamedBodyRequest, signal: AbortSignal): NamedBodyHandle | null | Promise<NamedBodyHandle | null>;
48
+ }
49
+
50
+ export type NamedDataContextResolver = (
51
+ request: NamedBodyRequest
52
+ ) => NamedDataResolveContext | Promise<NamedDataResolveContext>;
53
+
54
+ export interface NamedResponseBodyFeatureFlags {
55
+ namedResponseBody: boolean;
56
+ }
57
+
58
+ export const DEFAULT_NAMED_RESPONSE_BODY_FEATURE_FLAGS: Readonly<NamedResponseBodyFeatureFlags> = Object.freeze({
59
+ namedResponseBody: false
60
+ });
61
+
62
+ export interface NamedBodyResponseOptions {
63
+ method?: string;
64
+ status?: number;
65
+ headers?: HeadersInit;
66
+ signal?: AbortSignal;
67
+ maxBodyBytes?: number;
68
+ featureFlags?: Readonly<NamedResponseBodyFeatureFlags>;
69
+ }
70
+
71
+ const DEFAULT_MAX_BODY_BYTES = 10 * 1024 * 1024;
72
+ const TARGET_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
73
+ const REPRESENTATIONS: readonly NamedBodyRepresentation[] = ['json', 'yaml', 'html', 'markdown', 'raw'];
74
+ const KINDS: readonly NamedDataKind[] = ['structured', 'document', 'binary', 'asset'];
75
+ const SCOPES: readonly NamedDataScope[] = ['target', 'project'];
76
+ const MEDIA_TYPE_ESSENCE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+\/[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
77
+
78
+ export class NamedBodyResolver {
79
+ public constructor(private readonly providers: readonly NamedBodyProvider[]) {}
80
+
81
+ public async stat(request: NamedBodyRequest, signal: AbortSignal): Promise<NamedBodyMetadata | null> {
82
+ const provider = this.providerFor(request);
83
+ return provider ? provider.stat(request, signal) : null;
84
+ }
85
+
86
+ public async openBody(request: NamedBodyRequest, signal: AbortSignal): Promise<NamedBodyHandle | null> {
87
+ const provider = this.providerFor(request);
88
+ return provider ? provider.openBody(request, signal) : null;
89
+ }
90
+
91
+ public canResolve(request: NamedBodyRequest): boolean {
92
+ return this.providerFor(request) !== undefined;
93
+ }
94
+
95
+ private providerFor(request: NamedBodyRequest): NamedBodyProvider | undefined {
96
+ return this.providers.find((provider) => provider.canResolve(request));
97
+ }
98
+ }
99
+
100
+ /** Adapts the canonical runtime registry to the HTTP response boundary. */
101
+ export class NamedDataRegistryResolver extends NamedBodyResolver {
102
+ public constructor(
103
+ registry: NamedDataRegistryService,
104
+ contextFor: NamedDataContextResolver
105
+ ) {
106
+ super([registryProvider(registry, contextFor)]);
107
+ }
108
+ }
109
+
110
+ function registryProvider(
111
+ registry: NamedDataRegistryService,
112
+ contextFor: NamedDataContextResolver
113
+ ): NamedBodyProvider {
114
+ return {
115
+ // Let the registry distinguish an absent namespace, kind mismatch, and an
116
+ // unsupported representation with their canonical stable error codes.
117
+ canResolve: () => true,
118
+ stat: async (request, signal) => {
119
+ const context = await contextFor(request);
120
+ return registry.stat(request.reference, request.representation, {...context, signal});
121
+ },
122
+ openBody: async (request, signal) => {
123
+ const context = await contextFor(request);
124
+ const body = await registry.openBody(request.reference, request.representation, {...context, signal});
125
+ return namedDataBodyHandle(body);
126
+ }
127
+ };
128
+ }
129
+
130
+ function namedDataBodyHandle(body: NamedDataBody): NamedBodyHandle {
131
+ return {
132
+ metadata: {
133
+ reference: body.reference,
134
+ nativeRepresentation: body.nativeRepresentation,
135
+ representation: body.representation,
136
+ mediaType: body.mediaType,
137
+ ...(body.byteLength === undefined ? {} : {byteLength: body.byteLength}),
138
+ ...(body.digest === undefined ? {} : {digest: body.digest}),
139
+ revision: body.revision,
140
+ replayable: body.replayable
141
+ },
142
+ body: body.body,
143
+ release: (reason) => body.release(reason)
144
+ };
145
+ }
146
+
147
+ export class NamedBodyResponder {
148
+ public constructor(
149
+ private readonly resolver: NamedBodyResolver,
150
+ private readonly featureFlags: Readonly<NamedResponseBodyFeatureFlags> = DEFAULT_NAMED_RESPONSE_BODY_FEATURE_FLAGS
151
+ ) {}
152
+
153
+ public respond(request: NamedBodyRequest, options: NamedBodyResponseOptions = {}): Promise<Response> {
154
+ return createNamedBodyResponse(this.resolver, request, {...options, featureFlags: this.featureFlags});
155
+ }
156
+ }
157
+
158
+ export async function createNamedBodyResponse(
159
+ resolver: NamedBodyResolver,
160
+ request: NamedBodyRequest,
161
+ options: NamedBodyResponseOptions = {}
162
+ ): Promise<Response> {
163
+ const method = options.method?.toUpperCase() ?? 'GET';
164
+ if (!(options.featureFlags ?? DEFAULT_NAMED_RESPONSE_BODY_FEATURE_FLAGS).namedResponseBody) {
165
+ return errorResponse('NAMED_RESPONSE_BODY_DISABLED', 501, method);
166
+ }
167
+
168
+ if (!isValidRequest(request)) return errorResponse('NAMED_DATA_INVALID_REF', 400, method);
169
+ const signal = options.signal ?? new AbortController().signal;
170
+ if (signal.aborted) return errorResponse('NAMED_DATA_ABORTED', 499, method);
171
+ if (!resolver.canResolve(request)) return errorResponse('NAMED_DATA_PROVIDER_NOT_FOUND', 501, method);
172
+ const status = options.status ?? 200;
173
+ const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
174
+ if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 1) {
175
+ return errorResponse('NAMED_RESPONSE_INVALID_METADATA', 500, method);
176
+ }
177
+
178
+ if (method === 'HEAD') {
179
+ let metadata: NamedBodyMetadata | null;
180
+ try {
181
+ metadata = await resolver.stat(request, signal);
182
+ } catch (error) {
183
+ const response = providerErrorResponse(error);
184
+ if (response) return withoutResponseBody(response);
185
+ throw error;
186
+ }
187
+ if (!metadata) return errorResponse('NAMED_DATA_NOT_FOUND', 404, method);
188
+ const metadataError = validateMetadata(metadata, request, maxBodyBytes);
189
+ if (metadataError) return withoutResponseBody(metadataError);
190
+ return new Response(null, {status, headers: responseHeaders(options.headers, metadata, true)});
191
+ }
192
+ if (isBodyForbidden(status)) return new Response(null, {status, headers: new Headers(options.headers)});
193
+
194
+ let handle: NamedBodyHandle | null;
195
+ try {
196
+ handle = await resolver.openBody(request, signal);
197
+ } catch (error) {
198
+ const response = providerErrorResponse(error);
199
+ if (response) return response;
200
+ throw error;
201
+ }
202
+ if (!handle) return errorResponse('NAMED_DATA_NOT_FOUND', 404);
203
+ const release = releaseOnce(handle);
204
+
205
+ if (signal.aborted) {
206
+ const releaseError = await releaseErrorResponse(release, 'abort');
207
+ if (releaseError) return releaseError;
208
+ return errorResponse('NAMED_DATA_ABORTED', 499);
209
+ }
210
+
211
+ const metadataError = validateMetadata(handle.metadata, request, maxBodyBytes);
212
+ if (metadataError) {
213
+ return (await releaseErrorResponse(release, 'error')) ?? metadataError;
214
+ }
215
+
216
+ if (handle.body instanceof Uint8Array) {
217
+ if (handle.body.byteLength > maxBodyBytes) {
218
+ return (await releaseErrorResponse(release, 'error')) ?? errorResponse('NAMED_DATA_BODY_TOO_LARGE', 413);
219
+ }
220
+ if (handle.metadata.byteLength !== undefined && handle.metadata.byteLength !== handle.body.byteLength) {
221
+ return (await releaseErrorResponse(release, 'error')) ?? errorResponse('NAMED_RESPONSE_INVALID_METADATA', 502);
222
+ }
223
+ const headers = responseHeaders(options.headers, handle.metadata, false);
224
+ headers.set('Content-Length', String(handle.body.byteLength));
225
+ const bytes = handle.body.slice();
226
+ const releaseError = await releaseErrorResponse(release, 'complete');
227
+ if (releaseError) return releaseError;
228
+ return new Response(toArrayBuffer(bytes), {status, headers});
229
+ }
230
+
231
+ // Do not promise Content-Length before an untrusted stream has completed.
232
+ // A mismatch discovered after headers are committed terminates the stream.
233
+ const headers = responseHeaders(options.headers, handle.metadata, false);
234
+ const body = managedBodyStream(
235
+ handle.body,
236
+ signal,
237
+ maxBodyBytes,
238
+ handle.metadata.byteLength,
239
+ release
240
+ );
241
+ return new Response(body, {status, headers});
242
+ }
243
+
244
+ function managedBodyStream(
245
+ source: ReadableStream<Uint8Array>,
246
+ signal: AbortSignal,
247
+ maxBodyBytes: number,
248
+ expectedBodyBytes: number | undefined,
249
+ release: (reason: NamedBodyReleaseReason) => Promise<void>
250
+ ): ReadableStream<Uint8Array> {
251
+ const reader = source.getReader();
252
+ let total = 0;
253
+ let finished = false;
254
+
255
+ const cancelSource = async (reason: unknown): Promise<void> => {
256
+ try {
257
+ await reader.cancel(reason);
258
+ } catch {
259
+ // Cancellation is best-effort; release remains mandatory.
260
+ }
261
+ };
262
+
263
+ const finish = async (reason: NamedBodyReleaseReason): Promise<void> => {
264
+ if (finished) return;
265
+ finished = true;
266
+ signal.removeEventListener('abort', onAbort);
267
+ await release(reason);
268
+ };
269
+ const onAbort = (): void => {
270
+ void finish('abort').catch(() => undefined);
271
+ void cancelSource(signal.reason);
272
+ };
273
+ signal.addEventListener('abort', onAbort, {once: true});
274
+
275
+ return new ReadableStream<Uint8Array>({
276
+ async pull(controller) {
277
+ try {
278
+ if (signal.aborted) throw namedBodyError('NAMED_DATA_ABORTED');
279
+ const chunk = await reader.read();
280
+ if (chunk.done) {
281
+ if (expectedBodyBytes !== undefined && total !== expectedBodyBytes) {
282
+ throw namedBodyError('NAMED_RESPONSE_INVALID_METADATA');
283
+ }
284
+ await finish('complete');
285
+ controller.close();
286
+ return;
287
+ }
288
+ total += chunk.value.byteLength;
289
+ if (total > maxBodyBytes) {
290
+ await cancelSource('named_body_too_large');
291
+ throw namedBodyError('NAMED_DATA_BODY_TOO_LARGE');
292
+ }
293
+ if (expectedBodyBytes !== undefined && total > expectedBodyBytes) {
294
+ await cancelSource('named_body_length_mismatch');
295
+ throw namedBodyError('NAMED_RESPONSE_INVALID_METADATA');
296
+ }
297
+ controller.enqueue(chunk.value);
298
+ } catch (error) {
299
+ let failure = signal.aborted ? namedBodyError('NAMED_DATA_ABORTED') : error;
300
+ try {
301
+ await finish(signal.aborted ? 'abort' : 'error');
302
+ } catch (releaseError) {
303
+ failure = releaseError;
304
+ }
305
+ controller.error(failure);
306
+ }
307
+ },
308
+ async cancel(reason) {
309
+ const releasePromise = finish(signal.aborted ? 'abort' : 'cancel');
310
+ await cancelSource(reason);
311
+ await releasePromise;
312
+ }
313
+ });
314
+ }
315
+
316
+ function validateMetadata(
317
+ metadata: NamedBodyMetadata,
318
+ request: NamedBodyRequest,
319
+ maxBodyBytes?: number
320
+ ): Response | null {
321
+ if (
322
+ metadata.reference.namespace !== request.reference.namespace ||
323
+ metadata.reference.name !== request.reference.name ||
324
+ metadata.reference.kind !== request.reference.kind ||
325
+ metadata.reference.scope !== request.reference.scope ||
326
+ metadata.representation !== request.representation ||
327
+ !isNativeRepresentation(metadata.reference.kind, metadata.nativeRepresentation) ||
328
+ typeof metadata.revision !== 'string' ||
329
+ metadata.revision.length === 0 ||
330
+ typeof metadata.replayable !== 'boolean'
331
+ ) {
332
+ return errorResponse('NAMED_RESPONSE_INVALID_METADATA', 502);
333
+ }
334
+ if (hasControlCharacter(metadata.mediaType) || metadata.mediaType.length > 255) {
335
+ return errorResponse('NAMED_RESPONSE_INVALID_METADATA', 502);
336
+ }
337
+ if (!isMediaTypeForRepresentation(metadata.mediaType, request.representation)) {
338
+ return errorResponse('NAMED_DATA_REPRESENTATION_UNSUPPORTED', 415);
339
+ }
340
+ if (metadata.byteLength !== undefined) {
341
+ if (!Number.isSafeInteger(metadata.byteLength) || metadata.byteLength < 0) {
342
+ return errorResponse('NAMED_RESPONSE_INVALID_METADATA', 502);
343
+ }
344
+ if (maxBodyBytes !== undefined && metadata.byteLength > maxBodyBytes) {
345
+ return errorResponse('NAMED_DATA_BODY_TOO_LARGE', 413);
346
+ }
347
+ }
348
+ for (const identity of [metadata.etag, metadata.revision]) {
349
+ if (identity !== undefined && (identity.length < 1 || identity.length > 256 || hasControlCharacter(identity))) {
350
+ return errorResponse('NAMED_RESPONSE_INVALID_METADATA', 502);
351
+ }
352
+ }
353
+ return null;
354
+ }
355
+
356
+ function isNativeRepresentation(
357
+ kind: NamedDataKind,
358
+ representation: NamedBodyRepresentation
359
+ ): boolean {
360
+ if (kind === 'structured') return representation === 'json' || representation === 'yaml';
361
+ if (kind === 'document') return representation === 'html' || representation === 'markdown';
362
+ return representation === 'raw';
363
+ }
364
+
365
+ function isValidRequest(request: NamedBodyRequest): boolean {
366
+ if (typeof request !== 'object' || request === null) return false;
367
+ const reference = request.reference;
368
+ if (
369
+ typeof reference !== 'object' ||
370
+ reference === null ||
371
+ !isNamedDataNamespace(reference.namespace) ||
372
+ typeof reference.name !== 'string' ||
373
+ reference.name.length < 1 ||
374
+ reference.name.length > 256 ||
375
+ hasControlCharacter(reference.name) ||
376
+ !KINDS.includes(reference.kind) ||
377
+ !SCOPES.includes(reference.scope) ||
378
+ !REPRESENTATIONS.includes(request.representation)
379
+ ) {
380
+ return false;
381
+ }
382
+ if (reference.scope === 'target') return typeof request.targetId === 'string' && TARGET_ID.test(request.targetId);
383
+ return request.targetId === undefined;
384
+ }
385
+
386
+ function hasControlCharacter(value: string): boolean {
387
+ return [...value].some((character) => {
388
+ const codePoint = character.codePointAt(0)!;
389
+ return codePoint <= 0x1f || codePoint === 0x7f;
390
+ });
391
+ }
392
+
393
+ function isMediaTypeForRepresentation(mediaType: string, representation: NamedBodyRepresentation): boolean {
394
+ const essence = mediaType.split(';', 1)[0]?.trim().toLowerCase() ?? '';
395
+ if (!MEDIA_TYPE_ESSENCE.test(essence)) return false;
396
+ if (representation === 'raw') return true;
397
+ if (representation === 'json') return essence === 'application/json' || essence.endsWith('+json');
398
+ if (representation === 'yaml') {
399
+ return essence === 'application/yaml' || essence === 'application/x-yaml' || essence === 'text/yaml';
400
+ }
401
+ if (representation === 'html') return essence === 'text/html';
402
+ return essence === 'text/markdown' || essence === 'text/x-markdown';
403
+ }
404
+
405
+ function responseHeaders(
406
+ existing: HeadersInit | undefined,
407
+ metadata: NamedBodyMetadata,
408
+ includeByteLength: boolean
409
+ ): Headers {
410
+ const headers = new Headers(existing);
411
+ headers.delete('Content-Length');
412
+ headers.set('Content-Type', metadata.mediaType);
413
+ if (includeByteLength && metadata.byteLength !== undefined) {
414
+ headers.set('Content-Length', String(metadata.byteLength));
415
+ }
416
+ const identity = metadata.etag ?? metadata.revision;
417
+ if (identity) headers.set('ETag', quoteEtag(identity));
418
+ return headers;
419
+ }
420
+
421
+ function releaseOnce(handle: NamedBodyHandle): (reason: NamedBodyReleaseReason) => Promise<void> {
422
+ let released = false;
423
+ return async (reason) => {
424
+ if (released) return;
425
+ released = true;
426
+ try {
427
+ await handle.release(reason);
428
+ } catch {
429
+ throw namedBodyError('NAMED_DATA_PROVIDER_RELEASED');
430
+ }
431
+ };
432
+ }
433
+
434
+ async function releaseErrorResponse(
435
+ release: (reason: NamedBodyReleaseReason) => Promise<void>,
436
+ reason: NamedBodyReleaseReason
437
+ ): Promise<Response | null> {
438
+ try {
439
+ await release(reason);
440
+ return null;
441
+ } catch {
442
+ return errorResponse('NAMED_DATA_PROVIDER_RELEASED', 503);
443
+ }
444
+ }
445
+
446
+ function quoteEtag(value: string): string {
447
+ if (/^(W\/)?"[^"]*"$/.test(value)) return value;
448
+ return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
449
+ }
450
+
451
+ function isBodyForbidden(status: number): boolean {
452
+ return status === 204 || status === 205 || status === 304;
453
+ }
454
+
455
+ function errorResponse(error: NamedBodyErrorCode, status: number, method = 'GET'): Response {
456
+ return new Response(method === 'HEAD' ? null : JSON.stringify({error}), {
457
+ status,
458
+ headers: {'Content-Type': 'application/json; charset=utf-8'}
459
+ });
460
+ }
461
+
462
+ function withoutResponseBody(response: Response): Response {
463
+ return new Response(null, {status: response.status, statusText: response.statusText, headers: response.headers});
464
+ }
465
+
466
+ function providerErrorResponse(error: unknown): Response | null {
467
+ if (typeof error !== 'object' || error === null || !('code' in error)) return null;
468
+ const code = (error as {code?: unknown}).code;
469
+ if (typeof code !== 'string' || !isNamedDataErrorCode(code)) return null;
470
+ return errorResponse(code, statusForNamedDataError(code));
471
+ }
472
+
473
+ function namedBodyError(code: NamedBodyErrorCode): Error & {code: NamedBodyErrorCode} {
474
+ return Object.assign(new Error(code), {code});
475
+ }
476
+
477
+ function isNamedDataErrorCode(value: string): value is NamedDataErrorCode {
478
+ return (NAMED_DATA_ERROR_CODES as readonly string[]).includes(value);
479
+ }
480
+
481
+ function statusForNamedDataError(code: NamedBodyErrorCode): number {
482
+ if (code === 'NAMED_DATA_NOT_FOUND') return 404;
483
+ if (code === 'NAMED_DATA_PROVIDER_NOT_FOUND') return 501;
484
+ if (code === 'NAMED_DATA_REPRESENTATION_UNSUPPORTED') return 415;
485
+ if (code === 'NAMED_DATA_INVALID_METADATA') return 502;
486
+ if (code === 'NAMED_DATA_BODY_TOO_LARGE') return 413;
487
+ if (code === 'NAMED_DATA_ABORTED') return 499;
488
+ if (code === 'NAMED_DATA_PROVIDER_RELEASED') return 503;
489
+ if (code === 'NAMED_DATA_INVALID_REGISTRY' || code === 'NAMED_DATA_PROVIDER_CONFLICT') return 500;
490
+ return 400;
491
+ }
492
+
493
+ function toArrayBuffer(bytes: Uint8Array): ArrayBuffer {
494
+ return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
495
+ }
@@ -0,0 +1,6 @@
1
+ /** Canonical namespace syntax shared with the Named Data contract. */
2
+ export const NAMED_DATA_NAMESPACE_PATTERN = /^[a-z][a-z0-9.-]{0,63}$/u;
3
+
4
+ export function isNamedDataNamespace(value: unknown): value is string {
5
+ return typeof value === 'string' && NAMED_DATA_NAMESPACE_PATTERN.test(value);
6
+ }
package/src/protocol.ts CHANGED
@@ -15,7 +15,20 @@ export interface BridgeUnsupportedBody {
15
15
  reason: string;
16
16
  }
17
17
 
18
- export type BridgeBody = BridgeTextBody | BridgeEmptyBody | BridgeUnsupportedBody;
18
+ export interface BridgeNamedBody {
19
+ kind: 'named';
20
+ reference: {
21
+ namespace: string;
22
+ name: string;
23
+ kind: 'structured' | 'document' | 'binary' | 'asset';
24
+ scope: 'target' | 'project';
25
+ };
26
+ representation: 'json' | 'yaml' | 'html' | 'markdown' | 'raw';
27
+ targetId?: string;
28
+ maxBytes: number;
29
+ }
30
+
31
+ export type BridgeBody = BridgeTextBody | BridgeEmptyBody | BridgeUnsupportedBody | BridgeNamedBody;
19
32
 
20
33
  export interface BridgeAuthContext {
21
34
  type: string;
@@ -127,6 +140,42 @@ export function requireBridgeBody(value: unknown): BridgeBody {
127
140
  if (typeof value !== 'object' || value === null || Array.isArray(value)) return {kind: 'empty'};
128
141
  const record = value as Record<string, unknown>;
129
142
  if (record.kind === 'text') return {kind: 'text', text: String(record.text ?? '')};
143
+ if (record.kind === 'named') return requireNamedBridgeBody(record);
130
144
  if (record.kind === 'unsupported') return {kind: 'unsupported', reason: String(record.reason ?? '')};
131
145
  return {kind: 'empty'};
132
146
  }
147
+
148
+ function requireNamedBridgeBody(record: Record<string, unknown>): BridgeBody {
149
+ const reference = record.reference;
150
+ if (typeof reference !== 'object' || reference === null || Array.isArray(reference)) {
151
+ return {kind: 'unsupported', reason: 'invalid_named_body'};
152
+ }
153
+ const value = reference as Record<string, unknown>;
154
+ const kinds = ['structured', 'document', 'binary', 'asset'] as const;
155
+ const scopes = ['target', 'project'] as const;
156
+ const representations = ['json', 'yaml', 'html', 'markdown', 'raw'] as const;
157
+ if (
158
+ typeof value.namespace !== 'string' ||
159
+ typeof value.name !== 'string' ||
160
+ !kinds.includes(value.kind as (typeof kinds)[number]) ||
161
+ !scopes.includes(value.scope as (typeof scopes)[number]) ||
162
+ !representations.includes(record.representation as (typeof representations)[number]) ||
163
+ !Number.isSafeInteger(record.maxBytes) ||
164
+ (record.maxBytes as number) < 1 ||
165
+ (record.targetId !== undefined && typeof record.targetId !== 'string')
166
+ ) {
167
+ return {kind: 'unsupported', reason: 'invalid_named_body'};
168
+ }
169
+ return {
170
+ kind: 'named',
171
+ reference: {
172
+ namespace: value.namespace,
173
+ name: value.name,
174
+ kind: value.kind as (typeof kinds)[number],
175
+ scope: value.scope as (typeof scopes)[number]
176
+ },
177
+ representation: record.representation as (typeof representations)[number],
178
+ ...(record.targetId === undefined ? {} : {targetId: record.targetId}),
179
+ maxBytes: record.maxBytes as number
180
+ };
181
+ }
@@ -0,0 +1,106 @@
1
+ import type {
2
+ NamedBodyMetadata,
3
+ NamedBodyProvider,
4
+ NamedBodyRequest,
5
+ NamedDataErrorCode
6
+ } from './named-body.js';
7
+ import {isNamedDataNamespace} from './named-data-namespace.js';
8
+ import type {ResourceCapability, ResourceMetadata, ResourceSnapshot} from './server.js';
9
+
10
+ export interface AssetManagerNamedBodyProviderOptions {
11
+ namespace?: string;
12
+ projectRouteName?: string;
13
+ }
14
+
15
+ const DEFAULT_NAMESPACE = 'asset';
16
+
17
+ /** Adapts the public Asset Manager resource capability without reading extension-private state. */
18
+ export function createAssetManagerNamedBodyProvider(
19
+ resources: ResourceCapability,
20
+ options: AssetManagerNamedBodyProviderOptions = {}
21
+ ): NamedBodyProvider {
22
+ const namespace = options.namespace ?? DEFAULT_NAMESPACE;
23
+ const projectRouteName = options.projectRouteName ?? '';
24
+ if (!isNamedDataNamespace(namespace)) throw new TypeError('Asset Manager provider namespace is invalid.');
25
+
26
+ return {
27
+ canResolve: (request) =>
28
+ request.reference.namespace === namespace && request.reference.kind === 'asset',
29
+ async stat(request, signal) {
30
+ assertSupportedRequest(request);
31
+ throwIfAborted(signal);
32
+ const routeName = routeNameFor(request, projectRouteName);
33
+ if ((await resources.isNamespacePublished?.(routeName)) === false) return null;
34
+ throwIfAborted(signal);
35
+
36
+ if (resources.listResources !== undefined) {
37
+ const items = await resources.listResources(routeName);
38
+ throwIfAborted(signal);
39
+ const metadata = items.find((item) => item.name === request.reference.name);
40
+ return metadata === undefined ? null : namedMetadata(metadata, request);
41
+ }
42
+
43
+ const snapshot = await resources.getResource(routeName, request.reference.name);
44
+ throwIfAborted(signal);
45
+ return snapshot === null ? null : snapshotMetadata(snapshot, request);
46
+ },
47
+ async openBody(request, signal) {
48
+ assertSupportedRequest(request);
49
+ throwIfAborted(signal);
50
+ const routeName = routeNameFor(request, projectRouteName);
51
+ if ((await resources.isNamespacePublished?.(routeName)) === false) return null;
52
+ throwIfAborted(signal);
53
+ const snapshot = await resources.getResource(routeName, request.reference.name);
54
+ throwIfAborted(signal);
55
+ if (snapshot === null) return null;
56
+ const bytes = snapshot.bytes.slice();
57
+ return {
58
+ metadata: {...snapshotMetadata(snapshot, request), byteLength: bytes.byteLength},
59
+ body: bytes,
60
+ release: () => undefined
61
+ };
62
+ }
63
+ };
64
+ }
65
+
66
+ function assertSupportedRequest(request: NamedBodyRequest): void {
67
+ if (request.reference.kind !== 'asset') {
68
+ throw namedDataError('NAMED_DATA_KIND_MISMATCH');
69
+ }
70
+ if (request.representation !== 'raw') {
71
+ throw namedDataError('NAMED_DATA_REPRESENTATION_UNSUPPORTED');
72
+ }
73
+ }
74
+
75
+ function routeNameFor(request: NamedBodyRequest, projectRouteName: string): string {
76
+ if (request.reference.scope === 'project') return projectRouteName;
77
+ if (request.targetId === undefined) throw namedDataError('NAMED_DATA_SCOPE_MISMATCH');
78
+ return request.targetId;
79
+ }
80
+
81
+ function snapshotMetadata(snapshot: ResourceSnapshot, request: NamedBodyRequest): NamedBodyMetadata {
82
+ return namedMetadata({...snapshot, byteLength: snapshot.bytes.byteLength}, request);
83
+ }
84
+
85
+ function namedMetadata(resource: ResourceMetadata, request: NamedBodyRequest): NamedBodyMetadata {
86
+ const revision = resource.replacementId ?? resource.etag;
87
+ if (revision === undefined) throw namedDataError('NAMED_DATA_INVALID_METADATA');
88
+ return {
89
+ reference: {...request.reference},
90
+ nativeRepresentation: 'raw',
91
+ representation: 'raw',
92
+ mediaType: resource.mimeType,
93
+ ...(resource.byteLength === undefined ? {} : {byteLength: resource.byteLength}),
94
+ ...(resource.etag === undefined ? {} : {etag: resource.etag}),
95
+ revision,
96
+ replayable: true
97
+ };
98
+ }
99
+
100
+ function throwIfAborted(signal: AbortSignal): void {
101
+ if (signal.aborted) throw namedDataError('NAMED_DATA_ABORTED');
102
+ }
103
+
104
+ function namedDataError(code: NamedDataErrorCode): Error & {code: NamedDataErrorCode} {
105
+ return Object.assign(new Error(code), {code});
106
+ }