@syntropika/tembra-sdk 0.2.2 → 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 -3332
  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 -3310
  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 -3321
  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 +7 -6
  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 +213 -90
  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 -301
package/src/http.ts ADDED
@@ -0,0 +1,272 @@
1
+ import { encodeHost, parseURL } from "ufo";
2
+ import { send } from "wasi:http/client@0.3.0";
3
+ import {
4
+ Fields,
5
+ Request,
6
+ RequestOptions,
7
+ Response,
8
+ type ErrorCode,
9
+ type HeaderError,
10
+ type RequestOptionsError,
11
+ type Method,
12
+ type Result,
13
+ } from "wasi:http/types@0.3.0";
14
+ import { readChunks, writeChunks } from "./guest.ts";
15
+ import { decodeText, encodeText, Utf8Decoder } from "./http/bytes.ts";
16
+ import { events, type ServerSentEvent } from "./http/events.ts";
17
+
18
+ export type { ServerSentEvent } from "./http/events.ts";
19
+
20
+ export type HeaderInput =
21
+ | Readonly<Record<string, string>>
22
+ | Iterable<readonly [string, string | Uint8Array]>;
23
+
24
+ /** A snapshot of standard HTTP fields. Iteration and getAll preserve duplicates and bytes. */
25
+ export class HttpHeaders implements Iterable<readonly [string, Uint8Array]> {
26
+ readonly #entries: readonly (readonly [string, Uint8Array])[];
27
+ constructor(entries: Iterable<readonly [string, Uint8Array]> = []) {
28
+ this.#entries = [...entries].map(
29
+ ([name, bytes]) => [name.toLowerCase(), bytes.slice()] as const,
30
+ );
31
+ }
32
+ get(name: string): string | undefined {
33
+ const value = this.#entries.find(([key]) => key === name.toLowerCase())?.[1];
34
+ return value === undefined ? undefined : new Utf8Decoder().decode(value, true);
35
+ }
36
+ getAll(name: string): readonly Uint8Array[] {
37
+ return this.#entries
38
+ .filter(([key]) => key === name.toLowerCase())
39
+ .map(([, bytes]) => bytes.slice());
40
+ }
41
+ *[Symbol.iterator](): IterableIterator<readonly [string, Uint8Array]> {
42
+ for (const [name, bytes] of this.#entries) yield [name, bytes.slice()];
43
+ }
44
+ }
45
+
46
+ export interface HttpRequest {
47
+ method?: string;
48
+ headers?: HeaderInput;
49
+ body?: string | Uint8Array | AsyncIterable<Uint8Array>;
50
+ /** Optional trailing fields; native HTTP/1 also requires their names in the Trailer header. */
51
+ trailers?: PromiseLike<HeaderInput | undefined>;
52
+ /** Standard WASI durations, in nanoseconds. */
53
+ timeouts?: { connect?: bigint; firstByte?: bigint; betweenBytes?: bigint };
54
+ }
55
+
56
+ /** Consume a response once. Call close when the body is no longer needed. */
57
+ export interface HttpResponse {
58
+ readonly status: number;
59
+ readonly ok: boolean;
60
+ readonly headers: HttpHeaders;
61
+ readonly body: AsyncIterable<Uint8Array>;
62
+ text(): Promise<string>;
63
+ json<T = unknown>(): Promise<T>;
64
+ events(): AsyncIterable<ServerSentEvent>;
65
+ /** Resolves after the response body has been consumed. */
66
+ trailers(): Promise<HttpHeaders>;
67
+ close(): Promise<void>;
68
+ }
69
+
70
+ /** A failed standard HTTP operation; its typed WIT error remains available as code. */
71
+ export class HttpError extends Error {
72
+ constructor(readonly code: ErrorCode | HeaderError | RequestOptionsError | undefined) {
73
+ super(`HTTP operation failed: ${code?.tag ?? "request rejected"}`);
74
+ this.name = "HttpError";
75
+ }
76
+ }
77
+
78
+ function fields(input: HeaderInput = {}): Fields {
79
+ const entries =
80
+ Symbol.iterator in input
81
+ ? [...(input as Iterable<readonly [string, string | Uint8Array]>)]
82
+ : Object.entries(input);
83
+ return Fields.fromList(
84
+ entries.map(([name, value]) => [name, typeof value === "string" ? encodeText(value) : value]),
85
+ );
86
+ }
87
+
88
+ /** Release only still-owned values; an accepted standard call has already moved its inputs. */
89
+ function drop(value: unknown): void {
90
+ try {
91
+ (value as Disposable | undefined)?.[Symbol.dispose]?.();
92
+ } catch {
93
+ // Transferred resources no longer have a guest handle.
94
+ }
95
+ }
96
+
97
+ function result<T>(value: Result<T, ErrorCode>): T {
98
+ if (value.tag === "err") throw new HttpError(value.val);
99
+ return value.val;
100
+ }
101
+
102
+ /** HTTP convenience over standard WASI imports. Network I/O and TLS belong to the host. */
103
+ export async function fetch(url: string, options: HttpRequest = {}): Promise<HttpResponse> {
104
+ const parsed = parseURL(url);
105
+ const scheme = parsed.protocol?.toLowerCase();
106
+ if ((scheme !== "http:" && scheme !== "https:") || !parsed.host || parsed.auth)
107
+ throw new TypeError("HTTP requires an absolute http or https URL without credentials");
108
+ let method = options.method ?? "GET";
109
+ const standard = ["DELETE", "GET", "HEAD", "OPTIONS", "POST", "PUT", "PATCH"];
110
+ if (standard.includes(method.toUpperCase())) method = method.toUpperCase();
111
+ if (["CONNECT", "TRACE", "TRACK"].includes(method.toUpperCase()))
112
+ throw new TypeError(`HTTP method ${method} is forbidden`);
113
+ if ((method === "GET" || method === "HEAD") && options.body !== undefined)
114
+ throw new TypeError(`${method} requests cannot have a body`);
115
+ if (
116
+ options.body !== undefined &&
117
+ typeof options.body !== "string" &&
118
+ !(options.body instanceof Uint8Array) &&
119
+ typeof options.body?.[Symbol.asyncIterator] !== "function"
120
+ )
121
+ throw new TypeError("HTTP body requires text, bytes or an AsyncIterable<Uint8Array>");
122
+
123
+ if (
124
+ [...parsed.host].some(
125
+ (character) => character.charCodeAt(0) <= 32 || character.charCodeAt(0) === 127,
126
+ )
127
+ )
128
+ throw new TypeError("HTTP URL host contains whitespace or controls");
129
+ let headers: Fields | undefined;
130
+ let timeouts: RequestOptions | undefined;
131
+ let request: Request | undefined;
132
+ let upload: PromiseLike<Result<void, ErrorCode>> | undefined;
133
+ try {
134
+ headers = fields(options.headers);
135
+ if (options.timeouts) {
136
+ timeouts = new RequestOptions();
137
+ timeouts.setConnectTimeout(options.timeouts.connect);
138
+ timeouts.setFirstByteTimeout(options.timeouts.firstByte);
139
+ timeouts.setBetweenBytesTimeout(options.timeouts.betweenBytes);
140
+ }
141
+ const body =
142
+ typeof options.body === "string"
143
+ ? [encodeText(options.body)]
144
+ : options.body instanceof Uint8Array
145
+ ? [options.body.slice()]
146
+ : options.body;
147
+ const trailers: Promise<Result<Fields | undefined, ErrorCode>> = Promise.resolve(
148
+ options.trailers,
149
+ ).then(
150
+ (value) => ({ tag: "ok", val: value ? fields(value) : undefined }),
151
+ (error) => ({ tag: "err", val: { tag: "internal-error", val: String(error) } }),
152
+ );
153
+ const [created, done] = Request.new(
154
+ headers,
155
+ body === undefined ? undefined : writeChunks(body),
156
+ trailers,
157
+ timeouts,
158
+ );
159
+ request = created;
160
+ // Keep the standard future lazy and revision-owned. Reading it here would bind its
161
+ // observation to this callback and break a response consumed in a later callback.
162
+ upload = done;
163
+ request.setMethod(
164
+ standard.includes(method)
165
+ ? ({ tag: method.toLowerCase() } as Method)
166
+ : { tag: "other", val: method },
167
+ );
168
+ request.setScheme({ tag: scheme === "https:" ? "HTTPS" : "HTTP" });
169
+ request.setAuthority(encodeHost(parsed.host));
170
+ request.setPathWithQuery((parsed.pathname || "/") + (parsed.search || ""));
171
+ const pending = send(request);
172
+ request = undefined;
173
+ return response(await pending, upload);
174
+ } catch (error) {
175
+ drop(request);
176
+ drop(upload);
177
+ // A standard resource/future error preserves its payload; transport traps remain traps.
178
+ if (error && typeof error === "object" && "payload" in error)
179
+ throw new HttpError(error.payload as HttpError["code"]);
180
+ throw error;
181
+ } finally {
182
+ drop(headers);
183
+ drop(timeouts);
184
+ }
185
+ }
186
+
187
+ /** Snapshot child fields before transferring the response to its body stream. */
188
+ function response(value: Response, upload: PromiseLike<Result<void, ErrorCode>>): HttpResponse {
189
+ const status = value.getStatusCode();
190
+ const fields = value.getHeaders();
191
+ let headers: HttpHeaders;
192
+ try {
193
+ headers = new HttpHeaders(fields.copyAll());
194
+ } finally {
195
+ drop(fields);
196
+ }
197
+ let finish!: (result: Result<void, ErrorCode>) => void;
198
+ const handled = new Promise<Result<void, ErrorCode>>((resolve) => {
199
+ finish = resolve;
200
+ });
201
+ let stream: AsyncIterable<number> | undefined;
202
+ let complete: PromiseLike<Result<Fields | undefined, ErrorCode>> | undefined;
203
+ let consumed = false;
204
+ let ended = false;
205
+ let closed = false;
206
+ let trailing: Promise<HttpHeaders> | undefined;
207
+ const trailers = (): Promise<HttpHeaders> => {
208
+ if (!complete)
209
+ return Promise.reject(new Error("Consume the HTTP body before reading trailers"));
210
+ return (trailing ??= Promise.resolve(complete).then((state) => {
211
+ const fields = result(state);
212
+ try {
213
+ return new HttpHeaders(fields?.copyAll());
214
+ } finally {
215
+ drop(fields);
216
+ }
217
+ }));
218
+ };
219
+ const close = async () => {
220
+ if (closed) return;
221
+ closed = true;
222
+ drop(upload);
223
+ if (!ended) {
224
+ finish({ tag: "err", val: { tag: "internal-error", val: "response closed" } });
225
+ if (stream) {
226
+ drop(stream);
227
+ drop(complete);
228
+ } else drop(value);
229
+ }
230
+ };
231
+ const body: AsyncIterable<Uint8Array> = {
232
+ async *[Symbol.asyncIterator]() {
233
+ if (consumed) throw new Error("HTTP body has already been consumed");
234
+ if (closed) throw new Error("HTTP response is closed");
235
+ consumed = true;
236
+ try {
237
+ // Keep an untouched response revision-owned across callbacks. The handling future
238
+ // belongs to the callback that actually consumes its body.
239
+ [stream, complete] = Response.consumeBody(value, handled);
240
+ yield* readChunks(stream);
241
+ finish({ tag: "ok", val: undefined });
242
+ await trailers();
243
+ result(await upload);
244
+ ended = true;
245
+ } finally {
246
+ await close();
247
+ }
248
+ },
249
+ };
250
+ return Object.freeze({
251
+ status,
252
+ ok: status >= 200 && status < 300,
253
+ headers,
254
+ body,
255
+ text: () => decodeText(body, 1 << 20),
256
+ json: async <T>() => JSON.parse(await decodeText(body, 1 << 20)) as T,
257
+ events: async function* () {
258
+ try {
259
+ if (
260
+ headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() !==
261
+ "text/event-stream"
262
+ )
263
+ throw new Error("SSE requires text/event-stream");
264
+ yield* events(body);
265
+ } finally {
266
+ await close();
267
+ }
268
+ },
269
+ trailers,
270
+ close,
271
+ });
272
+ }
package/src/index.ts CHANGED
@@ -20,3 +20,6 @@ export {
20
20
  export { Errors, type ErrorDescriptor } from "./errors.ts";
21
21
 
22
22
  export { ContextKey, ContextKind, opaqueFrom, type OpaqueContextValue } from "./context-key.ts";
23
+ export type { WitMethods } from "./authoring/wit.ts";
24
+
25
+ export { witClient, type WitResource, type WitClientSchema } from "./runtime/wit-client.ts";
@@ -1,3 +1,4 @@
1
+ import { checkSignal } from "../../runtime/signals.ts";
1
2
  import type { DynamicReference } from "../../authoring/types.ts";
2
3
  import { Status } from "../../bridge/identifiers.ts";
3
4
  import { RpcEvent, RpcOp } from "../../bridge/protocol.ts";
@@ -7,6 +8,10 @@ import type { Context } from "../../runtime/context.ts";
7
8
 
8
9
  import { Channel, type Limits, type Transport } from "./channel.ts";
9
10
  import { RemoteState } from "./state.ts";
11
+ import { bindWitReference } from "../../runtime/wit-client.ts";
12
+ import { resourceBackend, resource, type RpcResource } from "./resources.ts";
13
+ import type { CapturedInvocation } from "../../runtime/adapters.ts";
14
+ import type { AcquisitionOptions } from "../../authoring/types.ts";
10
15
 
11
16
  /** A lost connection revokes its references. Reconnect by creating a peer and acquiring current state. */
12
17
  export class RemoteHost {
@@ -15,6 +20,7 @@ export class RemoteHost {
15
20
  #pending = new Map<
16
21
  number,
17
22
  {
23
+ readonly control: boolean;
18
24
  /** Deliver the response to its pending caller. */
19
25
  resolve(value: any): void;
20
26
  /** Reject the caller when its request or connection fails. */
@@ -22,6 +28,14 @@ export class RemoteHost {
22
28
  }
23
29
  >();
24
30
  #states = new Map<number, RemoteState>();
31
+ #releases: {
32
+ payload: unknown;
33
+ bytes: number;
34
+ signal: AbortSignal | undefined;
35
+ resolve(value: unknown): void;
36
+ reject(error: unknown): void;
37
+ }[] = [];
38
+ #releaseBytes = 0;
25
39
 
26
40
  /** Attach response routing and revoke state on disconnect. */
27
41
  constructor(transport: Transport, options: Limits = {}) {
@@ -38,10 +52,14 @@ export class RemoteHost {
38
52
  this.#pending.delete(message.id!);
39
53
  if (message.error) pending.reject(new TembraError(message.error));
40
54
  else pending.resolve(message.ok);
55
+ this.#drainReleases();
41
56
  },
42
57
  (error) => {
43
58
  for (const pending of this.#pending.values()) pending.reject(error);
44
59
  this.#pending.clear();
60
+ for (const queued of this.#releases) queued.reject(error);
61
+ this.#releases = [];
62
+ this.#releaseBytes = 0;
45
63
  this.#states.clear();
46
64
  },
47
65
  );
@@ -49,7 +67,38 @@ export class RemoteHost {
49
67
 
50
68
  /** Correlate one bounded remote request with optional cancellation. */
51
69
  request(op: RpcOp, payload: unknown, signal?: AbortSignal): Promise<any> {
52
- return this.#request(op, payload, signal);
70
+ return op === RpcOp.Release
71
+ ? this.#queueRelease(payload, signal)
72
+ : this.#request(op, payload, signal);
73
+ }
74
+
75
+ /** Buffer release bursts within one frame's byte budget while control replies are pending. */
76
+ async #queueRelease(payload: unknown, signal?: AbortSignal): Promise<unknown> {
77
+ if (signal) checkSignal(signal);
78
+ if (this.channel.closed) throw new TembraError(Errors.Gone.Connection);
79
+ const bytes = this.channel.codec.serialize({ op: RpcOp.Release, payload }).length;
80
+ if (this.#releaseBytes + bytes > this.channel.maxFrame)
81
+ throw new TembraError(Errors.Exhausted.FrameSize);
82
+ return new Promise((resolve, reject) => {
83
+ this.#releases.push({ payload, bytes, signal, resolve, reject });
84
+ this.#releaseBytes += bytes;
85
+ this.#drainReleases();
86
+ });
87
+ }
88
+
89
+ /** Send queued releases as control slots become free without consuming ordinary capacity. */
90
+ #drainReleases(): void {
91
+ if (this.channel.closed) return;
92
+ let pending = 0;
93
+ for (const item of this.#pending.values()) if (item.control) pending++;
94
+ while (pending < this.channel.maxPending && this.#releases.length) {
95
+ const item = this.#releases.shift()!;
96
+ this.#releaseBytes -= item.bytes;
97
+ pending++;
98
+ void this.#request(RpcOp.Release, item.payload, item.signal)
99
+ .then(item.resolve, item.reject)
100
+ .finally(() => this.#drainReleases());
101
+ }
53
102
  }
54
103
 
55
104
  /** Apply a response before resolving its caller so following frames see acquired state. */
@@ -59,20 +108,38 @@ export class RemoteHost {
59
108
  signal?: AbortSignal,
60
109
  received?: (value: any) => void,
61
110
  ): Promise<any> {
62
- signal?.throwIfAborted();
63
- if (this.#pending.size >= this.channel.maxPending)
111
+ if (signal) checkSignal(signal);
112
+ // Releases use a separate, equally bounded window so ordinary work cannot block cleanup.
113
+ const control = op === RpcOp.Release;
114
+ let pendingCount = 0;
115
+ for (const pending of this.#pending.values()) if (pending.control === control) pendingCount++;
116
+ if (pendingCount >= this.channel.maxPending)
64
117
  throw new TembraError(Errors.Exhausted.PendingRequests);
65
118
  const id = ++this.#next;
66
119
  if (!Number.isSafeInteger(id)) throw new TembraError(Errors.Exhausted.RequestIds);
67
120
  let abort: (() => void) | undefined;
68
121
  const result = new Promise((resolve, reject) => {
69
122
  const pending = {
123
+ control,
70
124
  resolve: (value: any) => {
71
125
  try {
72
126
  received?.(value);
127
+ if (
128
+ op === RpcOp.Call &&
129
+ typeof payload === "object" &&
130
+ payload !== null &&
131
+ "capabilities" in payload &&
132
+ Array.isArray(value?.owned) &&
133
+ value.owned.length > 0
134
+ ) {
135
+ void this.channel
136
+ .send({ op: RpcOp.Accept, payload: { id } })
137
+ .catch((error) => this.channel.close(error));
138
+ }
73
139
  resolve(value);
74
140
  } catch (error) {
75
141
  if (op === RpcOp.Get) this.#release(value?.reference);
142
+ else if (op === RpcOp.Call) this.channel.close(error);
76
143
  reject(error);
77
144
  }
78
145
  },
@@ -81,9 +148,19 @@ export class RemoteHost {
81
148
  this.#pending.set(id, pending);
82
149
  abort = () => {
83
150
  if (this.#pending.get(id) !== pending) return;
84
- if (op === RpcOp.Get) {
151
+ if (
152
+ op === RpcOp.Get ||
153
+ (op === RpcOp.Call &&
154
+ typeof payload === "object" &&
155
+ payload !== null &&
156
+ "capabilities" in payload)
157
+ ) {
85
158
  this.#pending.set(id, {
86
- resolve: (value) => this.#release(value?.reference),
159
+ control,
160
+ resolve: (value) => {
161
+ if (op === RpcOp.Get) this.#release(value?.reference);
162
+ else this.#releaseResult(value);
163
+ },
87
164
  reject: () => {},
88
165
  });
89
166
  } else {
@@ -94,6 +171,15 @@ export class RemoteHost {
94
171
  };
95
172
  signal?.addEventListener("abort", abort, { once: true });
96
173
  void this.channel.send({ id, op, payload }).catch((error) => {
174
+ // A rejected send may already have delivered bytes, even if cancellation won first.
175
+ if (
176
+ op === RpcOp.Get ||
177
+ (op === RpcOp.Call &&
178
+ typeof payload === "object" &&
179
+ payload !== null &&
180
+ "capabilities" in payload)
181
+ )
182
+ this.channel.close(error);
97
183
  if (this.#pending.get(id) !== pending) return;
98
184
  this.#pending.delete(id);
99
185
  reject(error);
@@ -106,15 +192,34 @@ export class RemoteHost {
106
192
  }
107
193
  }
108
194
 
109
- /** Release a late or unusable acquisition within the normal pending-request budget. */
195
+ /** Release a late or unusable acquisition within the reserved control budget. */
110
196
  #release(reference: unknown): void {
111
197
  if (!Number.isSafeInteger(reference) || (reference as number) <= 0 || this.channel.closed)
112
198
  return;
113
- void this.request(RpcOp.Release, { reference }).catch((error) => {
114
- try {
115
- this.channel.options.onError?.(error);
116
- } catch {}
117
- });
199
+ void this.request(RpcOp.Release, { reference }).catch((error) => this.channel.close(error));
200
+ }
201
+
202
+ /** Close a late resource result that its cancelled caller can no longer accept. */
203
+ #releaseResult(value: unknown): void {
204
+ try {
205
+ if (
206
+ typeof value === "object" &&
207
+ value !== null &&
208
+ "owned" in value &&
209
+ Array.isArray(value.owned)
210
+ )
211
+ for (const item of value.owned) this.#releaseResource(resource(item));
212
+ } catch (error) {
213
+ this.channel.close(error);
214
+ }
215
+ }
216
+
217
+ /** Release one checked resource through the same RPC claim operation as service references. */
218
+ #releaseResource(item: RpcResource): void {
219
+ if (this.channel.closed) return;
220
+ void this.request(RpcOp.Release, { reference: item.reference, resource: item }).catch((error) =>
221
+ this.channel.close(error),
222
+ );
118
223
  }
119
224
 
120
225
  /** Request remote orb metadata without service activation. */
@@ -126,7 +231,7 @@ export class RemoteHost {
126
231
  async get(
127
232
  service: string,
128
233
  key: string | readonly string[],
129
- options: { signal?: AbortSignal } = {},
234
+ options: AcquisitionOptions & { signal?: AbortSignal } = {},
130
235
  ): Promise<DynamicReference> {
131
236
  let released = false;
132
237
  const check = () => {
@@ -136,7 +241,7 @@ export class RemoteHost {
136
241
  let state: RemoteState | undefined;
137
242
  const acquired = await this.#request(
138
243
  RpcOp.Get,
139
- { service, key: typeof key === "string" ? [key] : key },
244
+ { service, key: typeof key === "string" ? [key] : key, resources: 1 },
140
245
  options.signal,
141
246
  (value) => {
142
247
  if (
@@ -173,9 +278,7 @@ export class RemoteHost {
173
278
  if (released) return;
174
279
  released = true;
175
280
  this.#states.delete(id);
176
- void this.request(RpcOp.Release, { reference: id }).catch((error) =>
177
- this.channel.options.onError?.(error),
178
- );
281
+ this.#release(id);
179
282
  },
180
283
  /** Reject opaque resources that cannot cross the transport. */
181
284
  opaque() {
@@ -186,7 +289,7 @@ export class RemoteHost {
186
289
  },
187
290
  };
188
291
  const peer = this;
189
- return new Proxy(target, {
292
+ const reference = new Proxy(target, {
190
293
  /** Expose only methods included in the acquired remote contract. */
191
294
  get: (target, property, receiver) => {
192
295
  if (property === "then") return undefined;
@@ -207,6 +310,22 @@ export class RemoteHost {
207
310
  };
208
311
  },
209
312
  }) as DynamicReference;
313
+ bindWitReference(reference, (schema) =>
314
+ resourceBackend(
315
+ {
316
+ identity: this,
317
+ reference: id,
318
+ resources: acquired.resources as unknown,
319
+ signature: acquired.signature as unknown,
320
+ check,
321
+ request: async (payload, _capture: CapturedInvocation, received, signal) =>
322
+ this.#request(RpcOp.Call, payload, signal, received),
323
+ release: (item) => this.#releaseResource(item),
324
+ },
325
+ schema,
326
+ ),
327
+ );
328
+ return reference;
210
329
  }
211
330
 
212
331
  /** Close the connection and reject pending requests. */
@@ -0,0 +1,123 @@
1
+ /** RPC carries existing SDK resource owners through the same connection's references. */
2
+ import { Code } from "../../bridge/identifiers.ts";
3
+ import { TembraError } from "../../error.ts";
4
+ import { Errors } from "../../errors.ts";
5
+ import { encode } from "../../interpreter/codec.ts";
6
+ import { ResourceOwner } from "../../interpreter/component/resources.ts";
7
+ import type { CapturedInvocation } from "../../runtime/adapters.ts";
8
+ import type { WitClientBackend, WitClientSchema } from "../../runtime/wit-client.ts";
9
+
10
+ /** A descriptor is useful only on its original connection and never replaces host admission. */
11
+ export interface RpcResource {
12
+ readonly reference: number;
13
+ readonly token: string;
14
+ readonly interface: string;
15
+ readonly name: string;
16
+ readonly revision: string;
17
+ }
18
+
19
+ /** Validate server descriptors before giving the existing SDK owner authority to release them. */
20
+ export function resource(value: unknown): RpcResource {
21
+ if (typeof value !== "object" || value === null) throw new TembraError(Errors.Invalid.RpcFrame);
22
+ const item = value as Record<string, unknown>;
23
+ if (
24
+ !Number.isSafeInteger(item.reference) ||
25
+ (item.reference as number) <= 0 ||
26
+ typeof item.token !== "string" ||
27
+ !/^[a-f0-9]{64}$/.test(item.token) ||
28
+ typeof item.interface !== "string" ||
29
+ typeof item.name !== "string" ||
30
+ typeof item.revision !== "string" ||
31
+ !/^[1-9][0-9]*$/.test(item.revision)
32
+ )
33
+ throw new TembraError(Errors.Invalid.RpcFrame);
34
+ return item as unknown as RpcResource;
35
+ }
36
+
37
+ /** The RemoteHost supplies ordinary request, release and connection operations. */
38
+ interface RemoteDelivery {
39
+ readonly identity: object;
40
+ readonly reference: number;
41
+ readonly resources: unknown;
42
+ readonly signature: unknown;
43
+ /** Check service release only for calls that have no independent resource receiver. */
44
+ check(): void;
45
+ /** Correlate captured delivery with the existing RPC cancellation path. */
46
+ request(
47
+ payload: unknown,
48
+ capture: CapturedInvocation,
49
+ received: (value: unknown) => void,
50
+ signal?: AbortSignal,
51
+ ): Promise<unknown>;
52
+ /** Release through the existing connection claim table. */
53
+ release(resource: RpcResource): void;
54
+ }
55
+
56
+ /** Bind one generated client without a browser component or a second ownership implementation. */
57
+ export function resourceBackend(remote: RemoteDelivery, schema: WitClientSchema): WitClientBackend {
58
+ if (remote.resources !== 1 || remote.signature !== schema.signature)
59
+ throw new TembraError({
60
+ code: Code.Unsupported,
61
+ reason: "capabilities",
62
+ message: "Matching WIT resource delivery is required",
63
+ });
64
+ return {
65
+ identity: remote.identity,
66
+ run(ctx, operation) {
67
+ if (ctx) ctx.check();
68
+ return operation(ctx);
69
+ },
70
+ async invoke(method, _args, capture, ctx) {
71
+ if (!capture.receiver) remote.check();
72
+ const receiver = capture.receiver
73
+ ? resource(capture.receiver.redeem(remote.identity, 0, capture.receiver.nominal))
74
+ : undefined;
75
+ const owned = (capture.arguments?.owners ?? []).map((owner) =>
76
+ resource(owner.redeem(remote.identity, 0, owner.nominal)),
77
+ );
78
+ // Ownership stays revoked even if the request's delivery later becomes uncertain.
79
+ for (const owner of capture.arguments?.owners ?? [])
80
+ owner.take(remote.identity, owner.nominal);
81
+ capture.arguments?.accept();
82
+ try {
83
+ await remote.request(
84
+ {
85
+ reference: receiver?.reference ?? remote.reference,
86
+ method,
87
+ input: capture.input.text,
88
+ capabilities: { signature: schema.signature, receiver: receiver ?? null, owned },
89
+ },
90
+ capture,
91
+ (value) => {
92
+ if (
93
+ typeof value !== "object" ||
94
+ value === null ||
95
+ !Array.isArray((value as Record<string, unknown>).owned)
96
+ )
97
+ throw new TembraError(Errors.Invalid.RpcFrame);
98
+ const result = value as { output?: unknown; owned: unknown[] };
99
+ if (typeof result.output !== "string") throw new TembraError(Errors.Invalid.RpcFrame);
100
+ const descriptors = result.owned.map(resource);
101
+ if (new Set(descriptors.map((item) => item.reference)).size !== descriptors.length)
102
+ throw new TembraError(Errors.Invalid.RpcFrame);
103
+ capture.capabilities = descriptors.map(
104
+ (item) =>
105
+ new ResourceOwner(
106
+ { interface: item.interface, name: item.name },
107
+ remote.identity,
108
+ 0,
109
+ item,
110
+ () => remote.release(item),
111
+ ),
112
+ );
113
+ capture.output = encode(JSON.parse(result.output) as unknown);
114
+ },
115
+ ctx?.signal,
116
+ );
117
+ } catch (error) {
118
+ for (const item of owned) remote.release(item);
119
+ throw error;
120
+ }
121
+ },
122
+ };
123
+ }