@syntropika/tembra-sdk 0.2.1 → 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 (241) hide show
  1. package/README.md +43 -17
  2. package/dist/authoring/types.d.ts +64 -3
  3. package/dist/authoring/wit.d.ts +6 -0
  4. package/dist/bridge/commands.d.ts +1190 -0
  5. package/dist/bridge/identifiers.d.ts +2 -0
  6. package/dist/bridge/kernel.d.ts +18 -107
  7. package/dist/bridge/protocol.d.ts +3 -138
  8. package/dist/browser.d.ts +14 -1
  9. package/dist/browser.js +141 -3298
  10. package/dist/chunks/browser-b8jamxw2.js +3399 -0
  11. package/dist/chunks/execution-nsqc6nrt.js +1419 -0
  12. package/dist/chunks/index-01zk0xqx.js +160 -0
  13. package/dist/chunks/index-3fjdfdfd.js +152 -0
  14. package/dist/chunks/index-aaymjn7v.js +787 -0
  15. package/dist/chunks/index-c1w7z9hx.js +356 -0
  16. package/dist/chunks/index-h8t0n42q.js +738 -0
  17. package/dist/chunks/index-hfds9mzp.js +308 -0
  18. package/dist/chunks/index-kr4x67wt.js +177 -0
  19. package/dist/chunks/index-kr6bnh34.js +117 -0
  20. package/dist/chunks/index-kyt9dj0a.js +1421 -0
  21. package/dist/chunks/index-n1wxzc9w.js +830 -0
  22. package/dist/chunks/index-pvac426d.js +74 -0
  23. package/dist/chunks/index-smyds5ce.js +3234 -0
  24. package/dist/chunks/index-sse8aapb.js +121 -0
  25. package/dist/chunks/index-v6heph77.js +643 -0
  26. package/dist/chunks/index-xrdvnv37.js +3448 -0
  27. package/dist/chunks/index-za4mg94e.js +26 -0
  28. package/dist/chunks/index-zkqmnjj8.js +167 -0
  29. package/dist/coordinator.js +9 -500
  30. package/dist/error.d.ts +2 -0
  31. package/dist/errors.d.ts +3 -0
  32. package/dist/guest.d.ts +173 -0
  33. package/dist/guest.js +26 -0
  34. package/dist/host.d.ts +36 -30
  35. package/dist/host.js +37 -3276
  36. package/dist/http/bytes.d.ts +8 -0
  37. package/dist/http/events.d.ts +7 -0
  38. package/dist/http.d.ts +45 -0
  39. package/dist/http.js +291 -0
  40. package/dist/index.d.ts +2 -0
  41. package/dist/index.js +49 -862
  42. package/dist/infrastructure/rpc/client.d.ts +2 -1
  43. package/dist/infrastructure/rpc/resources.d.ts +28 -0
  44. package/dist/interpreter/abi.d.ts +54 -0
  45. package/dist/interpreter/acquire.d.ts +18 -0
  46. package/dist/interpreter/browser-network.d.ts +52 -0
  47. package/dist/interpreter/browser-port.d.ts +55 -0
  48. package/dist/interpreter/browser.d.ts +79 -0
  49. package/dist/interpreter/cli.d.ts +5 -0
  50. package/dist/interpreter/codec.d.ts +42 -0
  51. package/dist/interpreter/component/execution.d.ts +42 -0
  52. package/dist/interpreter/component/host.d.ts +69 -0
  53. package/dist/interpreter/component/instance.d.ts +40 -0
  54. package/dist/interpreter/component/kernel.d.ts +120 -0
  55. package/dist/interpreter/component/names.d.ts +5 -0
  56. package/dist/interpreter/component/port.d.ts +85 -0
  57. package/dist/interpreter/component/prepared.d.ts +97 -0
  58. package/dist/interpreter/component/resources.d.ts +45 -0
  59. package/dist/interpreter/component/revision.d.ts +87 -0
  60. package/dist/interpreter/component/scope.d.ts +116 -0
  61. package/dist/interpreter/component/streams.d.ts +28 -0
  62. package/dist/interpreter/component/values.d.ts +79 -0
  63. package/dist/interpreter/component/wasi-filesystem.d.ts +21 -0
  64. package/dist/interpreter/component/wasi-host.d.ts +64 -0
  65. package/dist/interpreter/component/wasi-http.d.ts +33 -0
  66. package/dist/interpreter/component/wasi-sockets.d.ts +183 -0
  67. package/dist/interpreter/component/wasi.d.ts +41 -0
  68. package/dist/interpreter/core.d.ts +64 -0
  69. package/dist/interpreter/fetch-http-provider.d.ts +17 -0
  70. package/dist/interpreter/filesystem/contract.d.ts +85 -0
  71. package/dist/interpreter/filesystem/memory.d.ts +3 -0
  72. package/dist/interpreter/filesystem/opfs.d.ts +3 -0
  73. package/dist/interpreter/filesystem/scope.d.ts +35 -0
  74. package/dist/interpreter/filesystem.d.ts +8 -0
  75. package/dist/interpreter/gate.d.ts +6 -0
  76. package/dist/interpreter/host-protocol.d.ts +100 -0
  77. package/dist/interpreter/http-ingress-fetch.d.ts +7 -0
  78. package/dist/interpreter/http-ingress.d.ts +96 -0
  79. package/dist/interpreter/http-provider.d.ts +85 -0
  80. package/dist/interpreter/io.d.ts +20 -0
  81. package/dist/interpreter/mobile.d.ts +149 -0
  82. package/dist/interpreter/native-ingress.d.ts +95 -0
  83. package/dist/interpreter/node-port.d.ts +25 -0
  84. package/dist/interpreter/node.d.ts +36 -0
  85. package/dist/interpreter/revision.d.ts +64 -0
  86. package/dist/interpreter/scope.d.ts +89 -0
  87. package/dist/interpreter/socket-addresses.d.ts +50 -0
  88. package/dist/interpreter/socket-provider.d.ts +110 -0
  89. package/dist/interpreter/standard-cli.d.ts +34 -0
  90. package/dist/interpreter/standard-codec.d.ts +96 -0
  91. package/dist/interpreter/standard-filesystem.d.ts +47 -0
  92. package/dist/interpreter/standard-host.d.ts +71 -0
  93. package/dist/interpreter/standard-http-values.d.ts +159 -0
  94. package/dist/interpreter/standard-http.d.ts +9 -0
  95. package/dist/interpreter/standard-ingress.d.ts +63 -0
  96. package/dist/interpreter/standard-sockets.d.ts +177 -0
  97. package/dist/interpreter/standard-streams.d.ts +218 -0
  98. package/dist/interpreter/standard-system.d.ts +35 -0
  99. package/dist/interpreter/standard-utf8.d.ts +4 -0
  100. package/dist/interpreter/standard.d.ts +18 -0
  101. package/dist/interpreter/types.d.ts +152 -0
  102. package/dist/interpreter/wit-shape.d.ts +92 -0
  103. package/dist/manager.js +5 -332
  104. package/dist/msgpack.js +9 -615
  105. package/dist/node.d.ts +8 -1
  106. package/dist/node.js +248 -3287
  107. package/dist/rpc.js +196 -699
  108. package/dist/runtime/adapters.d.ts +120 -0
  109. package/dist/runtime/adapters.js +38 -0
  110. package/dist/runtime/calls.d.ts +9 -3
  111. package/dist/runtime/lifecycle.d.ts +3 -1
  112. package/dist/runtime/orbs.d.ts +5 -4
  113. package/dist/runtime/references.d.ts +27 -1
  114. package/dist/runtime/reload.d.ts +5 -3
  115. package/dist/runtime/scopes.d.ts +1 -1
  116. package/dist/runtime/signals.d.ts +4 -0
  117. package/dist/runtime/wit-client.d.ts +38 -0
  118. package/dist/telemetry.js +4 -25
  119. package/dist/tooling/build.d.ts +2 -2
  120. package/dist/tooling/client-resources.d.ts +23 -0
  121. package/dist/tooling/client.d.ts +10 -0
  122. package/dist/tooling/component-glue.d.ts +17 -0
  123. package/dist/tooling/component.d.ts +11 -0
  124. package/dist/tooling/index.d.ts +3 -1
  125. package/dist/tooling/index.js +1155 -102
  126. package/dist/tooling/resolver.d.ts +4 -4
  127. package/dist/tooling/typecheck.d.ts +2 -1
  128. package/dist/tooling/types.d.ts +27 -12
  129. package/dist/tooling/wit.d.ts +9 -0
  130. package/dist/wasi/wasi-clocks-types.d.ts +2 -0
  131. package/dist/wasi/wasi-http-client.d.ts +5 -0
  132. package/dist/wasi/wasi-http-types.d.ts +285 -0
  133. package/dist/wasi/wasi-sockets-ip-name-lookup.d.ts +23 -0
  134. package/dist/wasi/wasi-sockets-types.d.ts +146 -0
  135. package/package.json +62 -35
  136. package/src/authoring/declaration.ts +1 -1
  137. package/src/authoring/types.ts +53 -3
  138. package/src/authoring/wit.ts +15 -0
  139. package/src/bridge/commands.ts +1105 -0
  140. package/src/bridge/identifiers.ts +2 -0
  141. package/src/bridge/kernel.ts +56 -98
  142. package/src/bridge/protocol.ts +3 -142
  143. package/src/browser.ts +90 -6
  144. package/src/context-key.ts +4 -7
  145. package/src/error.ts +1 -1
  146. package/src/errors.ts +7 -0
  147. package/src/guest.ts +327 -0
  148. package/src/host.ts +128 -23
  149. package/src/http/bytes.ts +87 -0
  150. package/src/http/events.ts +34 -0
  151. package/src/http.ts +272 -0
  152. package/src/index.ts +3 -0
  153. package/src/infrastructure/rpc/client.ts +136 -17
  154. package/src/infrastructure/rpc/resources.ts +123 -0
  155. package/src/interpreter/abi.ts +69 -0
  156. package/src/interpreter/acquire.ts +58 -0
  157. package/src/interpreter/browser-network.ts +170 -0
  158. package/src/interpreter/browser-port.ts +425 -0
  159. package/src/interpreter/browser.ts +340 -0
  160. package/src/interpreter/cli.ts +30 -0
  161. package/src/interpreter/codec.ts +298 -0
  162. package/src/interpreter/component/execution.ts +264 -0
  163. package/src/interpreter/component/host.ts +409 -0
  164. package/src/interpreter/component/instance.ts +138 -0
  165. package/src/interpreter/component/kernel.ts +611 -0
  166. package/src/interpreter/component/names.ts +13 -0
  167. package/src/interpreter/component/port.ts +598 -0
  168. package/src/interpreter/component/prepared.ts +194 -0
  169. package/src/interpreter/component/resources.ts +345 -0
  170. package/src/interpreter/component/revision.ts +702 -0
  171. package/src/interpreter/component/scope.ts +447 -0
  172. package/src/interpreter/component/streams.ts +180 -0
  173. package/src/interpreter/component/values.ts +254 -0
  174. package/src/interpreter/component/wasi-filesystem.ts +472 -0
  175. package/src/interpreter/component/wasi-host.ts +197 -0
  176. package/src/interpreter/component/wasi-http.ts +939 -0
  177. package/src/interpreter/component/wasi-sockets.ts +958 -0
  178. package/src/interpreter/component/wasi.ts +238 -0
  179. package/src/interpreter/core.ts +386 -0
  180. package/src/interpreter/fetch-http-provider.ts +98 -0
  181. package/src/interpreter/filesystem/contract.ts +138 -0
  182. package/src/interpreter/filesystem/memory.ts +180 -0
  183. package/src/interpreter/filesystem/opfs.ts +294 -0
  184. package/src/interpreter/filesystem/scope.ts +390 -0
  185. package/src/interpreter/filesystem.ts +20 -0
  186. package/src/interpreter/gate.ts +55 -0
  187. package/src/interpreter/host-protocol.ts +242 -0
  188. package/src/interpreter/http-ingress-fetch.ts +133 -0
  189. package/src/interpreter/http-ingress.ts +203 -0
  190. package/src/interpreter/http-provider.ts +105 -0
  191. package/src/interpreter/io.ts +66 -0
  192. package/src/interpreter/mobile.ts +385 -0
  193. package/src/interpreter/native-ingress.ts +550 -0
  194. package/src/interpreter/node-port.ts +218 -0
  195. package/src/interpreter/node.ts +114 -0
  196. package/src/interpreter/revision.ts +450 -0
  197. package/src/interpreter/scope.ts +453 -0
  198. package/src/interpreter/socket-addresses.ts +246 -0
  199. package/src/interpreter/socket-provider.ts +126 -0
  200. package/src/interpreter/standard-cli.ts +184 -0
  201. package/src/interpreter/standard-codec.ts +403 -0
  202. package/src/interpreter/standard-filesystem.ts +545 -0
  203. package/src/interpreter/standard-host.ts +840 -0
  204. package/src/interpreter/standard-http-values.ts +624 -0
  205. package/src/interpreter/standard-http.ts +622 -0
  206. package/src/interpreter/standard-ingress.ts +344 -0
  207. package/src/interpreter/standard-sockets.ts +847 -0
  208. package/src/interpreter/standard-streams.ts +710 -0
  209. package/src/interpreter/standard-system.ts +182 -0
  210. package/src/interpreter/standard-utf8.ts +72 -0
  211. package/src/interpreter/standard.ts +283 -0
  212. package/src/interpreter/types.ts +163 -0
  213. package/src/interpreter/wit-shape.ts +175 -0
  214. package/src/node.ts +43 -14
  215. package/src/runtime/activities.ts +6 -6
  216. package/src/runtime/adapters.ts +314 -0
  217. package/src/runtime/calls.ts +218 -56
  218. package/src/runtime/context.ts +7 -7
  219. package/src/runtime/lifecycle.ts +36 -17
  220. package/src/runtime/orbs.ts +81 -39
  221. package/src/runtime/programs.ts +16 -8
  222. package/src/runtime/references.ts +128 -11
  223. package/src/runtime/reload.ts +71 -30
  224. package/src/runtime/resources.ts +2 -2
  225. package/src/runtime/scopes.ts +17 -17
  226. package/src/runtime/session.ts +3 -1
  227. package/src/runtime/signals.ts +31 -0
  228. package/src/runtime/wit-client.ts +228 -0
  229. package/src/tooling/build.ts +152 -54
  230. package/src/tooling/client-resources.ts +74 -0
  231. package/src/tooling/client.ts +531 -0
  232. package/src/tooling/component-glue.ts +288 -0
  233. package/src/tooling/component.ts +225 -0
  234. package/src/tooling/index.ts +3 -7
  235. package/src/tooling/resolver.ts +42 -25
  236. package/src/tooling/typecheck.ts +59 -4
  237. package/src/tooling/types.ts +27 -12
  238. package/src/tooling/wit.ts +188 -0
  239. package/dist/embedded.d.ts +0 -1
  240. package/dist/embedded.js +0 -1
  241. package/src/embedded.ts +0 -293
@@ -0,0 +1,710 @@
1
+ /**
2
+ * Generic ownership pieces of the browser standard WASI host: the services an implementation
3
+ * may use, revision-owned resources, one-shot futures, host-to-guest output streams and
4
+ * guest-to-host input streams. Nothing here knows a WASI interface; method implementations
5
+ * (`standard-filesystem.ts`, `standard-system.ts`) compose these pieces.
6
+ */
7
+ import { METHODS, RESOURCES, type WasiMethod } from "./standard.ts";
8
+ import { STREAM_CHUNK, Writer } from "./standard-codec.ts";
9
+
10
+ /**
11
+ * Implementation key of a generated method: resource functions are qualified by their resource
12
+ * (`<package>/<interface>#<resource>.<name>`), so `new`, `clone` or `consume-body` of different
13
+ * resources never collide. Free functions use `<interface>#<name>`.
14
+ */
15
+ export function methodKey(method: WasiMethod): string {
16
+ return method.resource === undefined
17
+ ? `${method.interface}#${method.name}`
18
+ : `${RESOURCES[method.resource]}.${method.name}`;
19
+ }
20
+
21
+ /** A WIT constructor or static function: the call, then its decoded parameters. */
22
+ export type StaticImplementation = (call: StandardCall, ...args: any[]) => unknown;
23
+
24
+ /**
25
+ * Bind every generated function of one resource: constructors and statics to `statics` by
26
+ * generated name, methods to the same-named method of the borrowed `self`, which receives the
27
+ * decoded parameters followed by the call. A generated function without an implementation
28
+ * fails construction instead of a later call.
29
+ */
30
+ export function bindResource(
31
+ contract: string,
32
+ resource: string,
33
+ prototype: object,
34
+ statics: Readonly<Record<string, StaticImplementation>>,
35
+ ): Record<string, Implementation> {
36
+ const implementations: Record<string, Implementation> = {};
37
+ const qualified = `${contract}#${resource}`;
38
+ for (const method of METHODS) {
39
+ if (method.resource === undefined || RESOURCES[method.resource] !== qualified) continue;
40
+ const name = method.name;
41
+ if (method.kind !== undefined) {
42
+ if (!Object.hasOwn(statics, name)) throw new Error(`${qualified}.${name} is unbound`);
43
+ const implementation = statics[name]!;
44
+ implementations[methodKey(method)] = (call, args: unknown[]) => implementation(call, ...args);
45
+ } else {
46
+ if (typeof (prototype as Record<string, unknown>)[name] !== "function")
47
+ throw new Error(`${qualified}.${name} is unbound`);
48
+ implementations[methodKey(method)] = (call, [self, ...args]: unknown[]) =>
49
+ (self as Record<string, (...values: unknown[]) => unknown>)[name]!(...args, call);
50
+ }
51
+ }
52
+ return implementations;
53
+ }
54
+
55
+ /** Host services available to a method implementation. */
56
+ export interface StandardServices {
57
+ readonly packetBytes: number;
58
+ /** Whether the revision is retired; physical work is then refused. */
59
+ readonly closed: boolean;
60
+ /** Run an uncancellable provider operation under the revision's physical accounting. */
61
+ physical<T>(signal: AbortSignal | undefined, operation: () => Promise<T>): Promise<T>;
62
+ /** Track a destructor-like operation even while the revision is retiring. */
63
+ cleanup(operation: () => unknown): void;
64
+ }
65
+
66
+ /** One decoded call: the host services plus the owning callback's cancellation signal. */
67
+ export interface StandardCall {
68
+ readonly host: StandardServices;
69
+ readonly signal?: AbortSignal | undefined;
70
+ }
71
+
72
+ /** One method implementation; it receives decoded jco-convention arguments. */
73
+ export type Implementation = (call: StandardCall, args: any) => unknown;
74
+
75
+ /** A host value behind an `own`/`borrow` handle; streams and calls retain it independently. */
76
+ export interface StandardResource {
77
+ /** Pending asynchronous calls that borrowed this resource. */
78
+ borrows: number;
79
+ retain(): void;
80
+ /** Release one user; the last release closes the underlying value. */
81
+ release(): void;
82
+ }
83
+
84
+ export const cancelled = (): Error => new Error("Operation cancelled");
85
+
86
+ /** Reject when `signal` aborts, without abandoning the physical operation's accounting. */
87
+ export function abortable<T>(operation: Promise<T>, signal?: AbortSignal): Promise<T> {
88
+ if (!signal) return operation;
89
+ if (signal.aborted) return Promise.reject(cancelled());
90
+ return new Promise<T>((resolve, reject) => {
91
+ const abort = () => reject(cancelled());
92
+ signal.addEventListener("abort", abort, { once: true });
93
+ operation.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
94
+ });
95
+ }
96
+
97
+ /**
98
+ * A one-shot host-to-guest WIT future. `cancel` runs when the reply that would publish it, or
99
+ * the read that would deliver its value, can never reach the guest. A guest dropping the handle
100
+ * does not cancel the work behind it (as upstream `write-via-stream` results do not); the host
101
+ * only releases the value's owned resources when it arrives.
102
+ */
103
+ export class HostFuture<T = unknown> {
104
+ constructor(
105
+ readonly value: Promise<T>,
106
+ readonly cancel?: () => void,
107
+ ) {}
108
+
109
+ /** A future whose payload is already known. */
110
+ static of<T>(value: T): HostFuture<T> {
111
+ return new HostFuture(Promise.resolve(value));
112
+ }
113
+ }
114
+
115
+ /** The readable end of a guest-written future, held by the call it was passed to. */
116
+ export interface FutureReader<T = unknown> {
117
+ /** The value once written; ownership of any resources inside it moves to the caller. */
118
+ take(): Promise<T>;
119
+ /** The consumer stopped: a written or later value is released, never delivered. */
120
+ close(): void;
121
+ }
122
+
123
+ /**
124
+ * A guest-to-host one-shot future created by FUTURE_NEW. One handle names its writer end
125
+ * (FUTURE_WRITE, DROP) and, until it is passed once as a call parameter, its readable end. A
126
+ * writer that ends unwritten (dropped, or its callback ended) resolves to `abandoned`, so a
127
+ * consumer never mistakes a vanished producer for a completed one.
128
+ */
129
+ export class WritableFuture<T = unknown> implements FutureReader<T> {
130
+ /** Set once the readable end was passed to a successful call. */
131
+ transferred = false;
132
+ #written = false;
133
+ #taken = false;
134
+ #closed = false;
135
+ #value: { readonly value: T } | undefined;
136
+ #deliver: ((value: T) => void) | undefined;
137
+
138
+ /**
139
+ * @param type the generated `TYPES` index of this future
140
+ * @param abandoned the value an unwritten writer resolves to; it carries no resources
141
+ * @param release releases the resources inside a value nobody will take
142
+ */
143
+ constructor(
144
+ readonly type: number,
145
+ readonly abandoned: T,
146
+ readonly release: (value: T) => void,
147
+ ) {}
148
+
149
+ /** Whether the writer end has ended (written or abandoned). */
150
+ get written(): boolean {
151
+ return this.#written;
152
+ }
153
+
154
+ /** Accept the one value; the caller has already claimed every resource inside it. */
155
+ write(value: T): void {
156
+ if (this.#written) throw new Error("future was already written");
157
+ this.#written = true;
158
+ this.#settle(value);
159
+ }
160
+
161
+ /** The writer ended without a value. */
162
+ abandon(): void {
163
+ if (this.#written) return;
164
+ this.#written = true;
165
+ this.#settle(this.abandoned);
166
+ }
167
+
168
+ #settle(value: T): void {
169
+ if (this.#closed) return this.release(value);
170
+ if (this.#deliver) {
171
+ const deliver = this.#deliver;
172
+ this.#deliver = undefined;
173
+ return deliver(value);
174
+ }
175
+ this.#value = { value };
176
+ }
177
+
178
+ take(): Promise<T> {
179
+ if (this.#taken || this.#closed) return Promise.reject(new Error("future was already read"));
180
+ this.#taken = true;
181
+ const stored = this.#value;
182
+ this.#value = undefined;
183
+ if (stored) return Promise.resolve(stored.value);
184
+ return new Promise<T>((resolve) => {
185
+ this.#deliver = resolve;
186
+ });
187
+ }
188
+
189
+ close(): void {
190
+ if (this.#closed) return;
191
+ this.#closed = true;
192
+ this.#deliver = undefined;
193
+ const stored = this.#value;
194
+ this.#value = undefined;
195
+ if (stored) this.release(stored.value);
196
+ }
197
+ }
198
+
199
+ /**
200
+ * How a host-to-guest stream ended: its producer reached the end (`eof`), the guest or the
201
+ * retiring revision dropped it first (`dropped`), or production failed (`failed`).
202
+ */
203
+ export type StreamEnd = "eof" | "dropped" | "failed";
204
+
205
+ /** Producer of a `stream<u8>` output. `close` runs once, at the end with its reason. */
206
+ export interface ByteProducer {
207
+ /**
208
+ * At most `limit` bytes. `undefined` or an empty chunk is end of stream, so a producer whose
209
+ * source may yield empty chunks must skip them. A failure ends the stream.
210
+ */
211
+ next(limit: number): Promise<Uint8Array | undefined>;
212
+ close(end?: StreamEnd): void;
213
+ }
214
+
215
+ /** Producer of a typed `stream<T>` output, one item at a time. */
216
+ export interface ItemProducer {
217
+ /** The next item, or `undefined` at end of stream. */
218
+ next(): Promise<unknown>;
219
+ close(end?: StreamEnd): void;
220
+ }
221
+
222
+ /**
223
+ * A host-to-guest stream. Reads are serialized; a read whose callback was cancelled keeps its
224
+ * produced data for the next read instead of losing it. A pending read fails immediately when
225
+ * the stream is dropped, while the producer's physical call stays tracked by its producer.
226
+ */
227
+ export class OutputStream {
228
+ #queue: Promise<unknown> = Promise.resolve();
229
+ readonly #dropped = new AbortController();
230
+ #ended = false;
231
+ #closed = false;
232
+ #abandoned = false;
233
+ /** Produced but undelivered bytes, or encoded items. */
234
+ #stash: Uint8Array[] = [];
235
+ /** The producer call whose reader was cancelled; the next read takes its result. */
236
+ #inflight: Promise<Uint8Array | undefined> | undefined;
237
+ /**
238
+ * Owned-item mode: the one producer call in flight, or its result held for the next read. It
239
+ * belongs to the stream (the revision), not to the read that started it.
240
+ */
241
+ #pending: Promise<{ value: unknown } | undefined> | undefined;
242
+
243
+ /**
244
+ * @param producer a byte producer for `stream<u8>`, an item producer for typed streams
245
+ * @param settle reports how the stream ended, with the producer's failure for `failed`
246
+ * @param release owned-item streams only: releases a produced value no read will deliver
247
+ */
248
+ constructor(
249
+ readonly producer: ByteProducer | ItemProducer,
250
+ readonly settle: (failure: unknown, end: StreamEnd) => void,
251
+ readonly release?: (value: unknown) => void,
252
+ ) {}
253
+
254
+ /** End once: settle the paired future and release the producer, both told why. */
255
+ #end(end: StreamEnd, failure?: unknown): void {
256
+ if (this.#ended) return;
257
+ this.#ended = true;
258
+ this.settle(failure, end);
259
+ this.producer.close(end);
260
+ }
261
+
262
+ /** Drop by the guest or revision retirement. */
263
+ close(): void {
264
+ if (this.#closed) return;
265
+ this.#closed = true;
266
+ this.#dropped.abort();
267
+ this.#stash = [];
268
+ this.#inflight = undefined;
269
+ // A held or late owned value has no reader any more; it is released when it exists.
270
+ const pending = this.#pending;
271
+ this.#pending = undefined;
272
+ pending?.then(
273
+ (taken) => taken && this.release?.(taken.value),
274
+ () => {},
275
+ );
276
+ this.#end("dropped");
277
+ }
278
+
279
+ /** Whether the guest dropped the stream or the revision retired it. */
280
+ get closed(): boolean {
281
+ return this.#closed;
282
+ }
283
+
284
+ /** A produced read never reached its guest; later reads must not silently skip its data. */
285
+ abandon(): void {
286
+ this.#abandoned = true;
287
+ this.#end("failed", new Error("stream read was abandoned"));
288
+ this.close();
289
+ }
290
+
291
+ /**
292
+ * Owned-item mode: serve one STREAM_READ with exactly one produced value, or `undefined` at
293
+ * end of stream. The value is not encoded and owns no handle yet: the host encodes and issues
294
+ * it in the reply. A read cancelled while the producer call runs leaves that call to the
295
+ * stream, and the next read takes its value, so a value is neither lost nor taken twice.
296
+ */
297
+ take(signal?: AbortSignal): Promise<{ value: unknown } | undefined> {
298
+ const next = this.#queue.then(async () => {
299
+ if (this.#abandoned) throw new Error("stream read was abandoned");
300
+ if (this.#closed) throw new Error("stream was dropped");
301
+ if (signal?.aborted) throw cancelled();
302
+ if (!this.#pending) {
303
+ if (this.#ended) return undefined;
304
+ this.#pending = (async () => {
305
+ try {
306
+ const value = await (this.producer as ItemProducer).next();
307
+ if (value !== undefined) return { value };
308
+ this.#end("eof");
309
+ } catch (error) {
310
+ this.#end("failed", error);
311
+ }
312
+ return undefined;
313
+ })();
314
+ }
315
+ const pending = this.#pending;
316
+ try {
317
+ const taken = await abortable(abortable(pending, this.#dropped.signal), signal);
318
+ // `close()` may run after the value resolved but before this continuation. It then
319
+ // captured `#pending` and owns the value's release, so this read must not deliver it.
320
+ if (this.#abandoned) throw new Error("stream read was abandoned");
321
+ if (this.#closed) throw new Error("stream was dropped");
322
+ this.#pending = undefined;
323
+ return taken;
324
+ } catch (error) {
325
+ if (this.#abandoned) throw new Error("stream read was abandoned");
326
+ if (this.#closed) throw new Error("stream was dropped");
327
+ throw error;
328
+ }
329
+ });
330
+ this.#queue = next.then(
331
+ () => {},
332
+ () => {},
333
+ );
334
+ return next;
335
+ }
336
+
337
+ /**
338
+ * Serve one STREAM_READ: the full reply (`u8 0` + chunk or `u8 1`). `limit` is a byte bound
339
+ * for byte streams and an item bound for typed streams; `bound` is the reply byte bound.
340
+ * `encodeItem`, supplied by the host from the stream's generated item type, selects the
341
+ * typed batch layout.
342
+ */
343
+ read(
344
+ limit: number,
345
+ bound: number,
346
+ signal?: AbortSignal,
347
+ encodeItem?: (item: unknown) => Uint8Array,
348
+ ): Promise<Uint8Array> {
349
+ const next = this.#queue.then(() => this.#serve(limit, bound, signal, encodeItem));
350
+ this.#queue = next.then(
351
+ () => {},
352
+ () => {},
353
+ );
354
+ return next;
355
+ }
356
+
357
+ async #serve(
358
+ limit: number,
359
+ bound: number,
360
+ signal?: AbortSignal,
361
+ encodeItem?: (item: unknown) => Uint8Array,
362
+ ): Promise<Uint8Array> {
363
+ const writer = new Writer();
364
+ if (this.#abandoned) throw new Error("stream read was abandoned");
365
+ if (this.#closed) throw new Error("stream was dropped");
366
+ if (signal?.aborted) throw cancelled();
367
+ if (!encodeItem) {
368
+ const chunk = this.#stash.shift() ?? (await this.#produce(limit, signal));
369
+ if (!chunk) {
370
+ writer.u8(1);
371
+ return writer.finish();
372
+ }
373
+ if (chunk.byteLength > limit) this.#stash.unshift(chunk.subarray(limit));
374
+ writer.u8(0);
375
+ writer.bytes(chunk.subarray(0, limit));
376
+ return writer.finish();
377
+ }
378
+ const items: Uint8Array[] = [];
379
+ let size = 5;
380
+ try {
381
+ while (items.length < limit) {
382
+ const item = this.#stash.shift() ?? (await this.#produce(1, signal, encodeItem));
383
+ if (!item) break;
384
+ if (size + item.byteLength > bound) {
385
+ if (!items.length) {
386
+ this.#end("failed", new Error("stream item exceeds the packet bound"));
387
+ throw new Error("stream item exceeds the packet bound");
388
+ }
389
+ this.#stash.unshift(item);
390
+ break;
391
+ }
392
+ items.push(item);
393
+ size += item.byteLength;
394
+ }
395
+ } catch (error) {
396
+ // No reply exists yet. Preserve the already assembled prefix for the next callback.
397
+ if (!this.#closed) this.#stash.unshift(...items);
398
+ throw error;
399
+ }
400
+ if (!items.length) {
401
+ writer.u8(1);
402
+ return writer.finish();
403
+ }
404
+ writer.u8(0);
405
+ writer.u32(items.length);
406
+ for (const item of items) writer.raw(item);
407
+ return writer.finish();
408
+ }
409
+
410
+ /**
411
+ * Produce one chunk or encoded item. Production is never concurrent: a read cancelled while
412
+ * its producer call runs leaves that call in flight, and the next read takes its result.
413
+ */
414
+ async #produce(
415
+ limit: number,
416
+ signal?: AbortSignal,
417
+ encodeItem?: (item: unknown) => Uint8Array,
418
+ ): Promise<Uint8Array | undefined> {
419
+ let inflight = this.#inflight;
420
+ if (!inflight) {
421
+ if (this.#ended) return undefined;
422
+ inflight = this.#inflight = (async () => {
423
+ try {
424
+ if (!encodeItem) {
425
+ const chunk = await (this.producer as ByteProducer).next(limit);
426
+ if (chunk?.byteLength) return chunk;
427
+ this.#end("eof");
428
+ return undefined;
429
+ }
430
+ const item = await (this.producer as ItemProducer).next();
431
+ if (item !== undefined) return encodeItem(item);
432
+ this.#end("eof");
433
+ return undefined;
434
+ } catch (error) {
435
+ this.#end("failed", error);
436
+ return undefined;
437
+ }
438
+ })();
439
+ }
440
+ try {
441
+ const value = await abortable(abortable(inflight, this.#dropped.signal), signal);
442
+ this.#inflight = undefined;
443
+ return value;
444
+ } catch (error) {
445
+ if (this.#abandoned) throw new Error("stream read was abandoned");
446
+ if (this.#closed) throw new Error("stream was dropped");
447
+ throw error;
448
+ }
449
+ }
450
+ }
451
+
452
+ /** Accepted input bytes per revision across all writers, matching the native budget. */
453
+ export const INPUT_BUDGET = 1 << 20;
454
+
455
+ /**
456
+ * The revision's aggregate budget of accepted guest input. A chunk is reserved before it is
457
+ * copied out of its packet and stays reserved while it is buffered or waiting for room in its
458
+ * stream; it is released when its consumer takes it or the stream discards it. Waiters are
459
+ * served in order, so a large chunk is not starved by smaller ones.
460
+ */
461
+ export class InputBudget {
462
+ #used = 0;
463
+ /** Streams that hold, or may still take, reservations of this budget. */
464
+ readonly #streams = new Set<InputStream>();
465
+ readonly #waiters: { bytes: number; grant(): void }[] = [];
466
+
467
+ constructor(readonly limit = INPUT_BUDGET) {}
468
+
469
+ /** Reserved bytes; never above `limit`. */
470
+ get used(): number {
471
+ return this.#used;
472
+ }
473
+
474
+ /**
475
+ * Reserve `bytes`, waiting for capacity. `signal` (the callback) rejects with a cancellation;
476
+ * `interrupt` (the stream) rejects with its own reason. A rejected wait reserves nothing.
477
+ */
478
+ reserve(bytes: number, signal?: AbortSignal, interrupt?: AbortSignal): Promise<void> {
479
+ if (signal?.aborted) return Promise.reject(cancelled());
480
+ if (interrupt?.aborted) return Promise.reject(interrupt.reason);
481
+ if (!this.#waiters.length && this.#used + bytes <= this.limit) {
482
+ this.#used += bytes;
483
+ return Promise.resolve();
484
+ }
485
+ return new Promise<void>((resolve, reject) => {
486
+ const detach = () => {
487
+ signal?.removeEventListener("abort", onSignal);
488
+ interrupt?.removeEventListener("abort", onInterrupt);
489
+ };
490
+ const waiter = {
491
+ bytes,
492
+ grant: () => {
493
+ detach();
494
+ resolve();
495
+ },
496
+ };
497
+ const leave = (error: unknown) => {
498
+ const at = this.#waiters.indexOf(waiter);
499
+ if (at < 0) return;
500
+ this.#waiters.splice(at, 1);
501
+ detach();
502
+ reject(error);
503
+ // A removed head may unblock smaller waiters behind it.
504
+ this.#drain();
505
+ };
506
+ const onSignal = () => leave(cancelled());
507
+ const onInterrupt = () => leave(interrupt!.reason);
508
+ signal?.addEventListener("abort", onSignal, { once: true });
509
+ interrupt?.addEventListener("abort", onInterrupt, { once: true });
510
+ this.#waiters.push(waiter);
511
+ });
512
+ }
513
+
514
+ release(bytes: number): void {
515
+ this.#used -= bytes;
516
+ this.#drain();
517
+ }
518
+
519
+ /** Account `stream` until it finished; `discard` reaches it until then. */
520
+ attach(stream: InputStream): void {
521
+ this.#streams.add(stream);
522
+ }
523
+
524
+ detach(stream: InputStream): void {
525
+ this.#streams.delete(stream);
526
+ }
527
+
528
+ /**
529
+ * Revision retirement, after every consumer had its turn: cancel each stream that still
530
+ * holds bytes for a consumer that will never come, so the budget returns to zero.
531
+ */
532
+ discard(): void {
533
+ for (const stream of [...this.#streams]) stream.cancel();
534
+ }
535
+
536
+ #drain(): void {
537
+ while (this.#waiters.length && this.#used + this.#waiters[0]!.bytes <= this.limit) {
538
+ const waiter = this.#waiters.shift()!;
539
+ this.#used += waiter.bytes;
540
+ waiter.grant();
541
+ }
542
+ }
543
+ }
544
+
545
+ /**
546
+ * A guest-to-host `stream<u8>`: one bounded buffer of at most `STREAM_CHUNK` bytes, written by
547
+ * the guest through STREAM_WRITE and consumed by the method it was transferred to. Every
548
+ * buffered or pending byte holds a reservation in the revision's `InputBudget`.
549
+ */
550
+ export class InputStream {
551
+ /** Set once the readable end was passed to a successful call. */
552
+ transferred = false;
553
+ #chunks: Uint8Array[] = [];
554
+ #buffered = 0;
555
+ #eof = false;
556
+ #cancelled = false;
557
+ /** The write in progress (waiting for budget or for room); close/cancel interrupt it. */
558
+ #writing: AbortController | undefined;
559
+ #pending: { chunk: Uint8Array; resolve(): void } | undefined;
560
+ #wake: (() => void) | undefined;
561
+ readonly #stopped = new AbortController();
562
+
563
+ /** @param type the generated `TYPES` index of this stream */
564
+ constructor(
565
+ readonly type: number,
566
+ readonly budget: InputBudget,
567
+ ) {
568
+ budget.attach(this);
569
+ }
570
+
571
+ /** Aborts when the consumer stopped (`cancel`), including revision retirement. */
572
+ get stopped(): AbortSignal {
573
+ return this.#stopped.signal;
574
+ }
575
+
576
+ /** Bytes accepted but not yet consumed; never above `STREAM_CHUNK`. */
577
+ get buffered(): number {
578
+ return this.#buffered;
579
+ }
580
+
581
+ /** Whether the consumer stopped. */
582
+ get cancelled(): boolean {
583
+ return this.#cancelled;
584
+ }
585
+
586
+ #notify(): void {
587
+ const wake = this.#wake;
588
+ this.#wake = undefined;
589
+ wake?.();
590
+ }
591
+
592
+ #accept(chunk: Uint8Array): void {
593
+ if (!chunk.byteLength) return;
594
+ this.#chunks.push(chunk);
595
+ this.#buffered += chunk.byteLength;
596
+ this.#notify();
597
+ }
598
+
599
+ /**
600
+ * Accept one whole chunk of `length` bytes. State is checked first; then the chunk is
601
+ * reserved in the aggregate budget, and only then copied with `copy`. One write may be in
602
+ * progress per stream; it completes once the chunk fits this stream's buffer.
603
+ */
604
+ async write(length: number, copy: () => Uint8Array, signal?: AbortSignal): Promise<void> {
605
+ if (length > STREAM_CHUNK) throw new Error("stream write exceeds the 64 KiB chunk bound");
606
+ if (this.#eof) throw new Error("stream was dropped");
607
+ if (this.#cancelled) throw new Error("stream reader was dropped");
608
+ if (this.#writing) throw new Error("a stream write is already pending");
609
+ if (signal?.aborted) throw cancelled();
610
+ const writing = (this.#writing = new AbortController());
611
+ try {
612
+ await this.budget.reserve(length, signal, writing.signal);
613
+ // Either side may have stopped while the grant was being delivered.
614
+ if (writing.signal.aborted || signal?.aborted) {
615
+ this.budget.release(length);
616
+ throw writing.signal.aborted ? writing.signal.reason : cancelled();
617
+ }
618
+ const chunk = copy();
619
+ if (this.#buffered + length <= STREAM_CHUNK) return this.#accept(chunk);
620
+ await new Promise<void>((resolve, reject) => {
621
+ const stop = (error: unknown) => {
622
+ if (this.#pending?.chunk !== chunk) return;
623
+ this.#pending = undefined;
624
+ this.budget.release(length);
625
+ signal?.removeEventListener("abort", onSignal);
626
+ reject(error);
627
+ };
628
+ const onSignal = () => stop(cancelled());
629
+ signal?.addEventListener("abort", onSignal, { once: true });
630
+ writing.signal.addEventListener("abort", () => stop(writing.signal.reason), {
631
+ once: true,
632
+ });
633
+ this.#pending = {
634
+ chunk,
635
+ resolve: () => {
636
+ signal?.removeEventListener("abort", onSignal);
637
+ resolve();
638
+ },
639
+ };
640
+ });
641
+ } finally {
642
+ if (this.#writing === writing) this.#writing = undefined;
643
+ }
644
+ }
645
+
646
+ /** Writer drop: end of stream after buffered bytes; a pending chunk is not delivered. */
647
+ close(): void {
648
+ if (this.#eof) return;
649
+ this.#eof = true;
650
+ this.#writing?.abort(new Error("stream was dropped"));
651
+ if (!this.transferred) {
652
+ this.#discard();
653
+ this.budget.detach(this);
654
+ }
655
+ this.#notify();
656
+ }
657
+
658
+ /** The consumer stopped: later writes fail and buffered bytes are discarded. */
659
+ cancel(): void {
660
+ if (this.#cancelled) return;
661
+ this.#cancelled = true;
662
+ this.#writing?.abort(new Error("stream reader was dropped"));
663
+ this.#discard();
664
+ this.budget.detach(this);
665
+ this.#stopped.abort();
666
+ this.#notify();
667
+ }
668
+
669
+ #discard(): void {
670
+ this.budget.release(this.#buffered);
671
+ this.#chunks = [];
672
+ this.#buffered = 0;
673
+ }
674
+
675
+ /** Next buffered bytes (at most `STREAM_CHUNK`), or `undefined` at end of stream. */
676
+ async read(): Promise<Uint8Array | undefined> {
677
+ while (!this.#buffered) {
678
+ if (this.#eof || this.#cancelled) {
679
+ this.budget.detach(this);
680
+ return undefined;
681
+ }
682
+ await new Promise<void>((resolve) => {
683
+ this.#wake = resolve;
684
+ });
685
+ }
686
+ const chunks = this.#chunks;
687
+ const total = this.#buffered;
688
+ this.#chunks = [];
689
+ this.#buffered = 0;
690
+ // The consumer owns these bytes now; their reservation returns to the revision.
691
+ this.budget.release(total);
692
+ let bytes = chunks[0]!;
693
+ if (chunks.length > 1) {
694
+ bytes = new Uint8Array(total);
695
+ let offset = 0;
696
+ for (const chunk of chunks) {
697
+ bytes.set(chunk, offset);
698
+ offset += chunk.byteLength;
699
+ }
700
+ }
701
+ // The emptied buffer admits the pending write whole, as the writer was promised.
702
+ const pending = this.#pending;
703
+ if (pending) {
704
+ this.#pending = undefined;
705
+ this.#accept(pending.chunk);
706
+ pending.resolve();
707
+ }
708
+ return bytes;
709
+ }
710
+ }