@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,294 @@
1
+ import {
2
+ type EntryType,
3
+ type FileStat,
4
+ type FilesystemErrorCode,
5
+ type FilesystemProvider,
6
+ FilesystemError,
7
+ fail,
8
+ } from "./contract.ts";
9
+ import { type Store, provider } from "./scope.ts";
10
+
11
+ // OPFS storage: direct handle operations, fresh range reads and per-entry writer queues.
12
+
13
+ type OpfsHandle = FileSystemFileHandle | FileSystemDirectoryHandle;
14
+
15
+ /** Members some engines lack or that the bundled DOM types omit; each use is feature-checked. */
16
+ interface OpfsExtensions {
17
+ move?(destination: FileSystemDirectoryHandle, name: string): Promise<void>;
18
+ entries?(): AsyncIterableIterator<[string, OpfsHandle]>;
19
+ }
20
+
21
+ const DOM_ERRORS: Readonly<Record<string, FilesystemErrorCode>> = {
22
+ NotFoundError: "no-entry",
23
+ TypeMismatchError: "not-directory",
24
+ InvalidModificationError: "not-empty",
25
+ NotAllowedError: "access",
26
+ SecurityError: "access",
27
+ QuotaExceededError: "insufficient-space",
28
+ NoModificationAllowedError: "busy",
29
+ NotSupportedError: "unsupported",
30
+ TypeError: "invalid",
31
+ };
32
+
33
+ /** Map a platform failure to a WASI code without retaining its object graph. */
34
+ function platformError(
35
+ error: unknown,
36
+ overrides: Readonly<Record<string, FilesystemErrorCode>> = {},
37
+ ): never {
38
+ if (error instanceof FilesystemError) throw error;
39
+ const name = String((error as { name?: unknown })?.name);
40
+ const message = error instanceof Error ? error.message : String(error);
41
+ throw new FilesystemError(overrides[name] ?? DOM_ERRORS[name] ?? "io", message);
42
+ }
43
+
44
+ function opfsStore(root: FileSystemDirectoryHandle): Store<OpfsHandle> {
45
+ /** Canonical handle objects shared by descriptors, grouped by name to bound comparisons. */
46
+ const retained = new Map<string, { handle: OpfsHandle; count: number }[]>();
47
+ /** Tail of the provider's serialized writer operations per canonical file handle. */
48
+ const queues = new WeakMap<OpfsHandle, Promise<unknown>>();
49
+ let registry: Promise<unknown> = Promise.resolve();
50
+
51
+ const guard = async <T>(
52
+ operation: () => Promise<T>,
53
+ overrides?: Readonly<Record<string, FilesystemErrorCode>>,
54
+ ): Promise<T> => {
55
+ try {
56
+ return await operation();
57
+ } catch (error) {
58
+ return platformError(error, overrides);
59
+ }
60
+ };
61
+ const serialize = <T>(handle: OpfsHandle, operation: () => Promise<T>): Promise<T> => {
62
+ const result = (queues.get(handle) ?? Promise.resolve()).then(operation);
63
+ queues.set(
64
+ handle,
65
+ result.catch(() => {}),
66
+ );
67
+ return result;
68
+ };
69
+ const canonical = async (handle: OpfsHandle) => {
70
+ for (const entry of retained.get(handle.name) ?? [])
71
+ if (await entry.handle.isSameEntry(handle)) return entry;
72
+ return undefined;
73
+ };
74
+ const optional = async (parent: FileSystemDirectoryHandle, name: string) => {
75
+ try {
76
+ return await lookup(parent, name);
77
+ } catch (error) {
78
+ if (error instanceof FilesystemError && error.code === "no-entry") return undefined;
79
+ throw error;
80
+ }
81
+ };
82
+ const lookup = (parent: OpfsHandle, name: string, expected: EntryType = "file") =>
83
+ guard(async (): Promise<OpfsHandle> => {
84
+ const directory = parent as FileSystemDirectoryHandle;
85
+ const first = () =>
86
+ expected === "file" ? directory.getFileHandle(name) : directory.getDirectoryHandle(name);
87
+ const second = () =>
88
+ expected === "file" ? directory.getDirectoryHandle(name) : directory.getFileHandle(name);
89
+ try {
90
+ return await first();
91
+ } catch (error) {
92
+ if ((error as { name?: unknown })?.name !== "TypeMismatchError") throw error;
93
+ return second();
94
+ }
95
+ });
96
+ /** One positioned writer session; the swap file is committed only by a successful close. */
97
+ const writeAt = (
98
+ handle: FileSystemFileHandle,
99
+ edit: (writer: FileSystemWritableFileStream) => Promise<void>,
100
+ ) =>
101
+ guard(async () => {
102
+ const writer = await handle.createWritable({ keepExistingData: true });
103
+ try {
104
+ await edit(writer);
105
+ await writer.close();
106
+ } catch (error) {
107
+ await writer.abort().catch(() => {});
108
+ throw error;
109
+ }
110
+ });
111
+
112
+ return {
113
+ root,
114
+ limit: Number.MAX_SAFE_INTEGER,
115
+ type: (node) => (node.kind === "file" ? "file" : "directory"),
116
+ lookup,
117
+ async create(parent, name, type) {
118
+ const directory = parent as FileSystemDirectoryHandle;
119
+ // Check-then-create: exclusive within this provider, not across other tabs.
120
+ if (await optional(directory, name)) fail("exist", "Entry already exists");
121
+ return guard<OpfsHandle>(() =>
122
+ type === "file"
123
+ ? directory.getFileHandle(name, { create: true })
124
+ : directory.getDirectoryHandle(name, { create: true }),
125
+ );
126
+ },
127
+ // Serialized so concurrent opens of one entry cannot register two canonical handles.
128
+ retain(node) {
129
+ const result = registry.then(async () => {
130
+ const entry = await canonical(node);
131
+ if (entry) {
132
+ entry.count++;
133
+ return entry.handle;
134
+ }
135
+ retained.set(node.name, [...(retained.get(node.name) ?? []), { handle: node, count: 1 }]);
136
+ return node;
137
+ });
138
+ registry = result.catch(() => {});
139
+ return result;
140
+ },
141
+ release(node) {
142
+ const entry = retained.get(node.name)?.find((candidate) => candidate.handle === node);
143
+ if (!entry || --entry.count) return;
144
+ // Keep the handle canonical until its queued writes settle, so a later opener queues behind.
145
+ void (queues.get(node) ?? Promise.resolve()).then(() => {
146
+ const group = retained.get(node.name);
147
+ if (entry.count || !group?.includes(entry)) return;
148
+ group.splice(group.indexOf(entry), 1);
149
+ if (!group.length) retained.delete(node.name);
150
+ });
151
+ },
152
+ stat: (node) =>
153
+ guard(async (): Promise<FileStat> => {
154
+ if (node.kind !== "file") return { type: "directory", size: 0n };
155
+ const value = await node.getFile();
156
+ return { type: "file", size: BigInt(value.size), modified: value.lastModified };
157
+ }),
158
+ same: (a, b) => guard(() => a.isSameEntry(b)),
159
+ async *entries(node) {
160
+ const iterate = (node as OpfsExtensions).entries;
161
+ if (typeof iterate !== "function")
162
+ fail("unsupported", "Directory enumeration is unavailable");
163
+ const source = iterate.call(node);
164
+ try {
165
+ while (true) {
166
+ const step = await guard(() => source.next());
167
+ if (step.done) return;
168
+ const [name, handle] = step.value;
169
+ yield { name, type: handle.kind === "file" ? "file" : "directory" };
170
+ }
171
+ } finally {
172
+ await source.return?.();
173
+ }
174
+ },
175
+ // Each read slices a fresh snapshot, so memory stays bounded by the requested range.
176
+ read: (node, offset, length) =>
177
+ guard(async () => {
178
+ const value = await (node as FileSystemFileHandle).getFile();
179
+ if (offset >= value.size) return new Uint8Array(0);
180
+ return new Uint8Array(await value.slice(offset, offset + length).arrayBuffer());
181
+ }),
182
+ write: (node, offset, data) =>
183
+ serialize(node, async () => {
184
+ const handle = node as FileSystemFileHandle;
185
+ const position = offset ?? (await guard(() => handle.getFile())).size;
186
+ if (position + data.byteLength > Number.MAX_SAFE_INTEGER)
187
+ fail("file-too-large", "File size limit exceeded");
188
+ await writeAt(handle, (writer) =>
189
+ writer.write({ type: "write", position, data: data as Uint8Array<ArrayBuffer> }),
190
+ );
191
+ }),
192
+ // One writer per stream: per-chunk createWritable copies the whole file each time (quadratic).
193
+ // The entry queue is held until commit, so the swap file is never raced by provider writers.
194
+ writeStream: (node, offset, chunks) =>
195
+ serialize(node, async () => {
196
+ const handle = node as FileSystemFileHandle;
197
+ let position = offset;
198
+ let writer: FileSystemWritableFileStream | undefined;
199
+ let failure: { error: unknown } | undefined;
200
+ try {
201
+ for await (const chunk of chunks) {
202
+ position ??= (await guard(() => handle.getFile())).size;
203
+ if (position + chunk.byteLength > Number.MAX_SAFE_INTEGER)
204
+ fail("file-too-large", "File size limit exceeded");
205
+ writer ??= await guard(() => handle.createWritable({ keepExistingData: true }));
206
+ const active = writer;
207
+ const at = position;
208
+ await guard(() =>
209
+ active.write({ type: "write", position: at, data: chunk as Uint8Array<ArrayBuffer> }),
210
+ ).catch(async (error: unknown) => {
211
+ // A failed writer cannot commit; discard this stream's uncommitted bytes.
212
+ writer = undefined;
213
+ await active.abort().catch(() => {});
214
+ throw error;
215
+ });
216
+ position += chunk.byteLength;
217
+ }
218
+ } catch (error) {
219
+ failure = { error };
220
+ }
221
+ // Accepted bytes are committed even when the producer failed or the descriptor closed.
222
+ if (writer) {
223
+ const active = writer;
224
+ await guard(() => active.close()).catch(async (error: unknown) => {
225
+ await active.abort().catch(() => {});
226
+ throw error;
227
+ });
228
+ }
229
+ if (failure) throw failure.error;
230
+ }),
231
+ resize: (node, size) =>
232
+ serialize(node, () =>
233
+ writeAt(node as FileSystemFileHandle, (writer) => writer.truncate(size)),
234
+ ),
235
+ // Writes commit when their writer closes; sync waits for this provider's queued writes.
236
+ sync: async (node) => {
237
+ await queues.get(node);
238
+ },
239
+ async remove(parent, name, type) {
240
+ const directory = parent as FileSystemDirectoryHandle;
241
+ const node = await lookup(directory, name, type);
242
+ if (node.kind !== (type === "file" ? "file" : "directory"))
243
+ fail(type === "file" ? "is-directory" : "not-directory", "Entry has another type");
244
+ await guard(() => directory.removeEntry(name));
245
+ },
246
+ async rename(fromNode, fromName, toNode, toName) {
247
+ const from = fromNode as FileSystemDirectoryHandle;
248
+ const to = toNode as FileSystemDirectoryHandle;
249
+ const source = await lookup(from, fromName);
250
+ const move = (source as OpfsExtensions).move;
251
+ if (typeof move !== "function") fail("unsupported", "This browser cannot move OPFS entries");
252
+ const replaced = await optional(to, toName);
253
+ if (replaced) {
254
+ if (await guard(() => replaced.isSameEntry(source))) return;
255
+ if (source.kind === "file" && replaced.kind === "directory")
256
+ fail("is-directory", "Target is a directory");
257
+ if (source.kind === "directory" && replaced.kind === "file")
258
+ fail("not-directory", "Target is not a directory");
259
+ if (replaced.kind === "directory") {
260
+ const children = (replaced as OpfsExtensions).entries?.call(replaced);
261
+ const first = children ? await guard(() => children.next()) : undefined;
262
+ await children?.return?.();
263
+ if (first && !first.done) fail("not-empty", "Target directory is not empty");
264
+ fail("unsupported", "Replacing a directory cannot be done atomically in OPFS");
265
+ }
266
+ }
267
+ if (source.kind === "directory") {
268
+ const inside = await guard(() => (source as FileSystemDirectoryHandle).resolve(to));
269
+ if (inside) fail("invalid", "Cannot move a directory into itself");
270
+ }
271
+ // Move the shared handle so descriptors of this entry follow it, after its queued writes.
272
+ const entry = await canonical(source);
273
+ const handle = entry?.handle ?? source;
274
+ const previous = handle.name;
275
+ await serialize(handle, () =>
276
+ guard(() => move.call(handle, to, toName), { InvalidModificationError: "unsupported" }),
277
+ );
278
+ // The moved handle reports its new name; regroup it so later lookups still find it.
279
+ if (entry && handle.name !== previous) {
280
+ const group = retained.get(previous) ?? [];
281
+ group.splice(group.indexOf(entry), 1);
282
+ if (!group.length) retained.delete(previous);
283
+ retained.set(handle.name, [...(retained.get(handle.name) ?? []), entry]);
284
+ }
285
+ },
286
+ };
287
+ }
288
+
289
+ /** Resolve every operation from the directory handle supplied by the embedding host. */
290
+ export async function opfsFilesystem(
291
+ directory: FileSystemDirectoryHandle,
292
+ ): Promise<FilesystemProvider> {
293
+ return provider(opfsStore(directory));
294
+ }
@@ -0,0 +1,390 @@
1
+ import {
2
+ type Descriptor,
3
+ type DirectoryDescriptor,
4
+ type DirectoryEntry,
5
+ type EntryType,
6
+ type FileDescriptor,
7
+ type FileStat,
8
+ type FilesystemProvider,
9
+ type MountedFilesystem,
10
+ type OpenOptions,
11
+ FilesystemError,
12
+ fail,
13
+ } from "./contract.ts";
14
+
15
+ /**
16
+ * Node-level primitives of one storage. Names are single, already confined components; the
17
+ * scope layer owns rights, lifetime, path resolution and argument validation.
18
+ */
19
+ export interface Store<N> {
20
+ readonly root: N;
21
+ /** Largest file size in bytes. */
22
+ readonly limit: number;
23
+ type(node: N): EntryType;
24
+ /** An existing child, trying `expected` first where lookups are type-specific. */
25
+ lookup(parent: N, name: string, expected?: EntryType): Promise<N>;
26
+ /** Create a new child; `exist` when any entry already has the name. */
27
+ create(parent: N, name: string, type: EntryType): Promise<N>;
28
+ /** Canonical node retained by a descriptor until `release`. */
29
+ retain(node: N): Promise<N>;
30
+ release(node: N): void;
31
+ stat(node: N): Promise<FileStat>;
32
+ same(a: N, b: N): Promise<boolean>;
33
+ entries(directory: N): AsyncIterator<DirectoryEntry>;
34
+ read(file: N, offset: number, length: number): Promise<Uint8Array>;
35
+ /** Write at `offset`, or append when it is undefined. */
36
+ write(file: N, offset: number | undefined, data: Uint8Array): Promise<void>;
37
+ resize(file: N, size: number): Promise<void>;
38
+ /**
39
+ * Optional one-writer stream at `offset` (append when undefined). The chunks are validated,
40
+ * non-empty and re-check the descriptor; without it, chunks go through `write` one by one.
41
+ */
42
+ writeStream?(
43
+ file: N,
44
+ offset: number | undefined,
45
+ chunks: AsyncIterable<Uint8Array>,
46
+ ): Promise<void>;
47
+ sync(node: N): Promise<void>;
48
+ remove(parent: N, name: string, type: EntryType): Promise<void>;
49
+ rename(from: N, fromName: string, to: N, toName: string): Promise<void>;
50
+ }
51
+
52
+ /** Per-descriptor state; the descriptor object itself exposes only the public interface. */
53
+ interface Opened<N> {
54
+ readonly scope: Scope<N>;
55
+ readonly node: N;
56
+ readonly writable: boolean;
57
+ readonly retained: boolean;
58
+ closed: boolean;
59
+ }
60
+
61
+ const owners = new WeakMap<object, Opened<unknown>>();
62
+
63
+ /** One `provider.open` result: rights, descriptor ownership and in-flight settlement. */
64
+ class Scope<N> implements MountedFilesystem {
65
+ #closed = false;
66
+ readonly #opened = new Set<Opened<N>>();
67
+ readonly #pending = new Set<Promise<unknown>>();
68
+
69
+ constructor(
70
+ readonly store: Store<N>,
71
+ readonly writable: boolean,
72
+ ) {}
73
+
74
+ openRoot(): DirectoryDescriptor {
75
+ if (this.#closed) fail("bad-descriptor", "Filesystem mount is closed");
76
+ return this.adopt(this.store.root, this.writable, false) as DirectoryDescriptor;
77
+ }
78
+
79
+ async dispose(): Promise<void> {
80
+ if (!this.#closed) {
81
+ this.#closed = true;
82
+ for (const opened of this.#opened) this.close(opened);
83
+ }
84
+ await Promise.allSettled([...this.#pending]);
85
+ }
86
+
87
+ /** Wrap a node in a descriptor; on a scope closed meanwhile, the caller releases the node. */
88
+ adopt(node: N, writable: boolean, retained: boolean): Descriptor {
89
+ if (this.#closed) fail("bad-descriptor", "Filesystem mount is closed");
90
+ const opened: Opened<N> = { scope: this, node, writable, retained, closed: false };
91
+ this.#opened.add(opened);
92
+ const descriptor =
93
+ this.store.type(node) === "file" ? fileDescriptor(opened) : directoryDescriptor(opened);
94
+ owners.set(descriptor, opened as Opened<unknown>);
95
+ return descriptor;
96
+ }
97
+
98
+ close(opened: Opened<N>): void {
99
+ if (opened.closed) return;
100
+ opened.closed = true;
101
+ this.#opened.delete(opened);
102
+ if (opened.retained) this.store.release(opened.node);
103
+ }
104
+
105
+ /** Check liveness and rights before any backend effect, then track the call until it settles. */
106
+ run<T>(
107
+ opened: Opened<N>,
108
+ mutate: boolean,
109
+ operation: (store: Store<N>, node: N) => Promise<T>,
110
+ ): Promise<T> {
111
+ let promise: Promise<T>;
112
+ try {
113
+ live(opened);
114
+ if (mutate && !opened.writable) fail("not-permitted", "Descriptor is read-only");
115
+ promise = operation(this.store, opened.node);
116
+ } catch (error) {
117
+ return Promise.reject(error);
118
+ }
119
+ this.#pending.add(promise);
120
+ const forget = () => this.#pending.delete(promise);
121
+ promise.then(forget, forget);
122
+ return promise;
123
+ }
124
+ }
125
+
126
+ function live(opened: Opened<unknown>): void {
127
+ if (opened.closed) fail("bad-descriptor", "Descriptor is closed");
128
+ }
129
+
130
+ /** Validate a non-negative `filesize` inside the storage limit. */
131
+ function size(value: bigint, limit: number, extra = 0): number {
132
+ if (typeof value !== "bigint" || value < 0n) fail("invalid", "Invalid file position");
133
+ if (value + BigInt(extra) > BigInt(limit)) fail("file-too-large", "File size limit exceeded");
134
+ return Number(value);
135
+ }
136
+
137
+ function bytes(data: Uint8Array): Uint8Array {
138
+ if (!(data instanceof Uint8Array)) fail("invalid", "File data must be a Uint8Array");
139
+ return data;
140
+ }
141
+
142
+ interface Resolved<N> {
143
+ /** Directory holding `name`, or the named directory itself when `name` is absent. */
144
+ readonly parent: N;
145
+ readonly name?: string;
146
+ /** A trailing `/` requires a directory. */
147
+ readonly directory: boolean;
148
+ }
149
+
150
+ /** Resolve component by component from the descriptor's own node; `..` never leaves it. */
151
+ async function resolve<N>(store: Store<N>, base: N, path: string): Promise<Resolved<N>> {
152
+ if (typeof path !== "string" || path.includes("\0")) fail("invalid", "Invalid path");
153
+ if (path === "") fail("no-entry", "Empty path");
154
+ if (path.startsWith("/")) fail("not-permitted", "Absolute paths are not permitted");
155
+ const parts = path.split("/").filter((part) => part !== "" && part !== ".");
156
+ const stack = [base];
157
+ const directory = path.endsWith("/");
158
+ for (const [index, part] of parts.entries()) {
159
+ if (part === "..") {
160
+ if (stack.length === 1) fail("not-permitted", "Path escapes the opened directory");
161
+ stack.pop();
162
+ } else if (index === parts.length - 1) {
163
+ return { parent: stack.at(-1)!, name: part, directory };
164
+ } else {
165
+ const child = await store.lookup(stack.at(-1)!, part, "directory");
166
+ if (store.type(child) !== "directory") fail("not-directory", "Path component is a file");
167
+ stack.push(child);
168
+ }
169
+ }
170
+ return { parent: stack.at(-1)!, directory };
171
+ }
172
+
173
+ /** Resolve an existing entry, honoring a trailing `/`. */
174
+ async function existing<N>(store: Store<N>, base: N, path: string): Promise<N> {
175
+ const target = await resolve(store, base, path);
176
+ if (target.name === undefined) return target.parent;
177
+ const node = await store.lookup(target.parent, target.name);
178
+ if (target.directory && store.type(node) !== "directory")
179
+ fail("not-directory", "Path is not a directory");
180
+ return node;
181
+ }
182
+
183
+ /** Resolve a path that must name an entry inside a directory rather than the base itself. */
184
+ async function named<N>(
185
+ store: Store<N>,
186
+ base: N,
187
+ path: string,
188
+ ): Promise<Resolved<N> & { name: string }> {
189
+ const target = await resolve(store, base, path);
190
+ if (target.name === undefined) fail("invalid", "Path names the opened directory itself");
191
+ return target as Resolved<N> & { name: string };
192
+ }
193
+
194
+ function descriptorBase<N>(opened: Opened<N>) {
195
+ const { scope } = opened;
196
+ return {
197
+ writable: opened.writable,
198
+ stat: () => scope.run(opened, false, (store, node) => store.stat(node)),
199
+ isSameObject: (other: Descriptor) =>
200
+ scope.run(opened, false, async (store, node) => {
201
+ const target = owners.get(other) as Opened<N> | undefined;
202
+ if (!target || target.scope.store !== store) return false;
203
+ live(target);
204
+ return store.same(node, target.node);
205
+ }),
206
+ sync: () => scope.run(opened, false, (store, node) => store.sync(node)),
207
+ close: () => scope.close(opened),
208
+ };
209
+ }
210
+
211
+ function fileDescriptor<N>(opened: Opened<N>): FileDescriptor {
212
+ const { scope } = opened;
213
+ return Object.freeze({
214
+ type: "file" as const,
215
+ ...descriptorBase(opened),
216
+ read: (offset: bigint, length: number) =>
217
+ scope.run(opened, false, async (store, node) => {
218
+ if (
219
+ typeof offset !== "bigint" ||
220
+ offset < 0n ||
221
+ !Number.isSafeInteger(length) ||
222
+ length < 0
223
+ )
224
+ fail("invalid", "Invalid file range");
225
+ if (length === 0 || offset > BigInt(store.limit)) return new Uint8Array(0);
226
+ return store.read(node, Number(offset), length);
227
+ }),
228
+ write: (offset: bigint, data: Uint8Array) =>
229
+ scope.run(opened, true, async (store, node) => {
230
+ const position = size(offset, store.limit, bytes(data).byteLength);
231
+ if (data.byteLength) await store.write(node, position, data);
232
+ }),
233
+ append: (data: Uint8Array) =>
234
+ scope.run(opened, true, async (store, node) => {
235
+ if (bytes(data).byteLength) await store.write(node, undefined, data);
236
+ }),
237
+ setSize: (value: bigint) =>
238
+ scope.run(opened, true, (store, node) => store.resize(node, size(value, store.limit))),
239
+ writeStream: (chunks: AsyncIterable<Uint8Array>, offset?: bigint) =>
240
+ scope.run(opened, true, async (store, node) => {
241
+ let position = offset === undefined ? undefined : size(offset, store.limit);
242
+ // Lazy: `chunks` is untouched until the store pulls, i.e. after admission succeeded.
243
+ const checked = (async function* () {
244
+ for await (const chunk of chunks) {
245
+ live(opened);
246
+ if (bytes(chunk).byteLength) yield chunk;
247
+ }
248
+ })();
249
+ if (store.writeStream) return store.writeStream(node, position, checked);
250
+ for await (const chunk of checked) {
251
+ if (position !== undefined && position + chunk.byteLength > store.limit)
252
+ fail("file-too-large", "File size limit exceeded");
253
+ await store.write(node, position, chunk);
254
+ if (position !== undefined) position += chunk.byteLength;
255
+ }
256
+ }),
257
+ });
258
+ }
259
+
260
+ function directoryDescriptor<N>(opened: Opened<N>): DirectoryDescriptor {
261
+ const { scope } = opened;
262
+ const base = descriptorBase(opened);
263
+ return Object.freeze({
264
+ type: "directory" as const,
265
+ ...base,
266
+ openAt: (path: string, options: OpenOptions = {}) => {
267
+ const { create = false, exclusive = false, truncate = false, write = false } = options;
268
+ return scope.run(opened, create || truncate || write, async (store, node) => {
269
+ if (truncate && !write) fail("invalid", "Truncation requires write access");
270
+ if (create && options.directory) fail("invalid", "Use createDirectoryAt for directories");
271
+ const target = await resolve(store, node, path);
272
+ const directory = options.directory === true || target.directory;
273
+ let child: N;
274
+ if (target.name === undefined) {
275
+ if (create && exclusive) fail("exist", "Path names an existing directory");
276
+ child = target.parent;
277
+ } else if (create && exclusive) {
278
+ child = await store.create(target.parent, target.name, "file");
279
+ } else {
280
+ child = await openExisting(store, target.parent, target.name, create, directory);
281
+ }
282
+ const type = store.type(child);
283
+ if (directory && type !== "directory") fail("not-directory", "Path is not a directory");
284
+ if (truncate && type === "directory") fail("is-directory", "Cannot truncate a directory");
285
+ const retained = await store.retain(child);
286
+ try {
287
+ if (truncate) await store.resize(retained, 0);
288
+ return scope.adopt(retained, write, true);
289
+ } catch (error) {
290
+ store.release(retained);
291
+ throw error;
292
+ }
293
+ });
294
+ },
295
+ statAt: (path: string) =>
296
+ scope.run(opened, false, async (store, node) =>
297
+ store.stat(await existing(store, node, path)),
298
+ ),
299
+ readDirectory: () => entries(opened),
300
+ createDirectoryAt: (path: string) =>
301
+ scope.run(opened, true, async (store, node) => {
302
+ const target = await resolve(store, node, path);
303
+ if (target.name === undefined) fail("exist", "Directory already exists");
304
+ await store.create(target.parent, target.name, "directory");
305
+ }),
306
+ removeDirectoryAt: (path: string) =>
307
+ scope.run(opened, true, async (store, node) => {
308
+ const target = await named(store, node, path);
309
+ await store.remove(target.parent, target.name, "directory");
310
+ }),
311
+ unlinkFileAt: (path: string) =>
312
+ scope.run(opened, true, async (store, node) => {
313
+ const target = await named(store, node, path);
314
+ if (target.directory) {
315
+ const child = await store.lookup(target.parent, target.name);
316
+ fail(store.type(child) === "file" ? "not-directory" : "is-directory", "Not a file path");
317
+ }
318
+ await store.remove(target.parent, target.name, "file");
319
+ }),
320
+ renameAt: (oldPath: string, newDirectory: DirectoryDescriptor, newPath: string) =>
321
+ scope.run(opened, true, async (store, node) => {
322
+ const target = owners.get(newDirectory) as Opened<N> | undefined;
323
+ if (!target || target.scope.store !== store)
324
+ fail("cross-device", "Rename target belongs to another storage");
325
+ live(target);
326
+ if (store.type(target.node) !== "directory") fail("not-directory", "Target is a file");
327
+ if (!target.writable) fail("not-permitted", "Target directory is read-only");
328
+ const from = await named(store, node, oldPath);
329
+ const to = await named(store, target.node, newPath);
330
+ await store.rename(from.parent, from.name, to.parent, to.name);
331
+ }),
332
+ });
333
+ }
334
+
335
+ /** Open an existing entry, creating a file when requested and absent. */
336
+ async function openExisting<N>(
337
+ store: Store<N>,
338
+ parent: N,
339
+ name: string,
340
+ create: boolean,
341
+ directory: boolean,
342
+ ): Promise<N> {
343
+ const expected = directory ? "directory" : "file";
344
+ try {
345
+ return await store.lookup(parent, name, expected);
346
+ } catch (error) {
347
+ if (!create || !(error instanceof FilesystemError) || error.code !== "no-entry") throw error;
348
+ }
349
+ try {
350
+ return await store.create(parent, name, "file");
351
+ } catch (error) {
352
+ // Another call created it between lookup and creation; open what now exists.
353
+ if (!(error instanceof FilesystemError) || error.code !== "exist") throw error;
354
+ return store.lookup(parent, name, expected);
355
+ }
356
+ }
357
+
358
+ /** A lazy listing whose every step re-checks the descriptor and is tracked by its scope. */
359
+ function entries<N>(opened: Opened<N>): AsyncIterableIterator<DirectoryEntry> {
360
+ let source: AsyncIterator<DirectoryEntry> | undefined;
361
+ let done = false;
362
+ const finished = { done: true, value: undefined } as const;
363
+ const iterator: AsyncIterableIterator<DirectoryEntry> = {
364
+ next() {
365
+ if (done) return Promise.resolve(finished);
366
+ return opened.scope.run(opened, false, async (store, node) => {
367
+ source ??= store.entries(node);
368
+ const step = await source.next();
369
+ if (step.done) done = true;
370
+ return step;
371
+ });
372
+ },
373
+ async return() {
374
+ done = true;
375
+ await source?.return?.();
376
+ return finished;
377
+ },
378
+ [Symbol.asyncIterator]() {
379
+ return iterator;
380
+ },
381
+ };
382
+ return iterator;
383
+ }
384
+
385
+ /** Expose one storage as a provider whose every `open` is an independent scope. */
386
+ export function provider<N>(store: Store<N>): FilesystemProvider {
387
+ return Object.freeze({
388
+ open: (_mount: string, writable: boolean): MountedFilesystem => new Scope(store, writable),
389
+ });
390
+ }