@seanhogg/builderforce-webcontainers 2026.10.7 → 2026.10.9

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 (107) hide show
  1. package/dist/assets.js +3 -3
  2. package/dist/cdnModules.d.ts +16 -0
  3. package/dist/cdnModules.d.ts.map +1 -0
  4. package/dist/cdnModules.js +25 -0
  5. package/dist/cdnModules.js.map +1 -0
  6. package/dist/componentCompilers.d.ts +5 -5
  7. package/dist/componentCompilers.d.ts.map +1 -1
  8. package/dist/componentCompilers.js +5 -23
  9. package/dist/componentCompilers.js.map +1 -1
  10. package/dist/host.d.ts +17 -3
  11. package/dist/host.d.ts.map +1 -1
  12. package/dist/host.js +36 -22
  13. package/dist/host.js.map +1 -1
  14. package/dist/index.d.ts +9 -2
  15. package/dist/index.d.ts.map +1 -1
  16. package/dist/index.js +5 -1
  17. package/dist/index.js.map +1 -1
  18. package/dist/node/childRelay.d.ts +22 -0
  19. package/dist/node/childRelay.d.ts.map +1 -0
  20. package/dist/node/childRelay.js +54 -0
  21. package/dist/node/childRelay.js.map +1 -0
  22. package/dist/node/index.d.ts +4 -8
  23. package/dist/node/index.d.ts.map +1 -1
  24. package/dist/node/index.js +1 -25
  25. package/dist/node/index.js.map +1 -1
  26. package/dist/node/portResponder.d.ts +45 -0
  27. package/dist/node/portResponder.d.ts.map +1 -0
  28. package/dist/node/portResponder.js +136 -0
  29. package/dist/node/portResponder.js.map +1 -0
  30. package/dist/node/processHost.d.ts +13 -2
  31. package/dist/node/processHost.d.ts.map +1 -1
  32. package/dist/node/processHost.js +79 -47
  33. package/dist/node/processHost.js.map +1 -1
  34. package/dist/node/protocol.d.ts +69 -13
  35. package/dist/node/protocol.d.ts.map +1 -1
  36. package/dist/node/protocol.js.map +1 -1
  37. package/dist/node/responseWire.d.ts +27 -0
  38. package/dist/node/responseWire.d.ts.map +1 -0
  39. package/dist/node/responseWire.js +99 -0
  40. package/dist/node/responseWire.js.map +1 -0
  41. package/dist/node/worker.js +145 -126
  42. package/dist/node/workerProcess.d.ts +3 -1
  43. package/dist/node/workerProcess.d.ts.map +1 -1
  44. package/dist/node/workerProcess.js +79 -22
  45. package/dist/node/workerProcess.js.map +1 -1
  46. package/dist/previewBridge.d.ts +37 -0
  47. package/dist/previewBridge.d.ts.map +1 -0
  48. package/dist/previewBridge.js +116 -0
  49. package/dist/previewBridge.js.map +1 -0
  50. package/dist/previewMessages.d.ts +5 -0
  51. package/dist/previewMessages.d.ts.map +1 -1
  52. package/dist/previewMessages.js +18 -11
  53. package/dist/previewMessages.js.map +1 -1
  54. package/dist/previewUpdates.d.ts +10 -0
  55. package/dist/previewUpdates.d.ts.map +1 -0
  56. package/dist/previewUpdates.js +27 -0
  57. package/dist/previewUpdates.js.map +1 -0
  58. package/dist/process-worker.js +145 -126
  59. package/dist/protocol.d.ts +25 -3
  60. package/dist/protocol.d.ts.map +1 -1
  61. package/dist/protocol.js +10 -2
  62. package/dist/protocol.js.map +1 -1
  63. package/dist/relay.html +1 -1
  64. package/dist/snapshotStore.d.ts +30 -0
  65. package/dist/snapshotStore.d.ts.map +1 -0
  66. package/dist/snapshotStore.js +115 -0
  67. package/dist/snapshotStore.js.map +1 -0
  68. package/dist/styleCompilers.d.ts +19 -0
  69. package/dist/styleCompilers.d.ts.map +1 -0
  70. package/dist/styleCompilers.js +22 -0
  71. package/dist/styleCompilers.js.map +1 -0
  72. package/dist/sw.js +1 -1
  73. package/dist/swRouter.d.ts +8 -1
  74. package/dist/swRouter.d.ts.map +1 -1
  75. package/dist/swRouter.js +40 -5
  76. package/dist/swRouter.js.map +1 -1
  77. package/dist/transport.d.ts +3 -2
  78. package/dist/transport.d.ts.map +1 -1
  79. package/dist/transport.js +4 -4
  80. package/dist/transport.js.map +1 -1
  81. package/dist/worker.d.ts +6 -2
  82. package/dist/worker.d.ts.map +1 -1
  83. package/dist/worker.js +5 -5
  84. package/dist/worker.js.map +1 -1
  85. package/package.json +3 -2
  86. package/src/cdnModules.ts +34 -0
  87. package/src/componentCompilers.ts +8 -32
  88. package/src/host.ts +51 -25
  89. package/src/index.ts +9 -2
  90. package/src/node/childRelay.ts +63 -0
  91. package/src/node/index.ts +4 -23
  92. package/src/node/portResponder.ts +175 -0
  93. package/src/node/processHost.ts +96 -46
  94. package/src/node/protocol.ts +46 -9
  95. package/src/node/responseWire.ts +97 -0
  96. package/src/node/workerProcess.ts +88 -28
  97. package/src/previewBridge.ts +148 -0
  98. package/src/previewMessages.ts +17 -9
  99. package/src/previewUpdates.ts +28 -0
  100. package/src/protocol.ts +37 -3
  101. package/src/relay.ts +6 -5
  102. package/src/snapshotStore.ts +135 -0
  103. package/src/styleCompilers.ts +45 -0
  104. package/src/sw.ts +2 -0
  105. package/src/swRouter.ts +35 -6
  106. package/src/transport.ts +7 -6
  107. package/src/worker.ts +5 -5
@@ -5,24 +5,35 @@
5
5
  * write reaches the page, then every other worker). Children a worker spawns
6
6
  * (the shell running `node`, `child_process`) are started here too, so every
7
7
  * process — however deep — can be killed by terminating its worker.
8
+ *
9
+ * Responses from a worker's servers stream through here chunk by chunk (see
10
+ * responseWire.ts), and upgraded connections (WebSockets) are relayed as raw
11
+ * bytes between the client end the caller holds and the server's worker.
8
12
  */
9
13
  import {
10
14
  DEFAULT_ENV,
11
15
  PortRegistry,
12
16
  ServerEvents,
13
17
  allocatePid,
18
+ createIpcEndpoint,
14
19
  runArguments,
20
+ textResponse,
15
21
  toRuntimeProcess,
22
+ type ByteChannel,
16
23
  type ChildHandle,
17
24
  type FsChange,
18
25
  type HttpRequestData,
19
26
  type HttpResponseData,
27
+ type HttpStreamResponse,
20
28
  type ProcessOptions,
21
29
  type RuntimeProcess,
30
+ type StdioChunk,
22
31
  type VirtualFileSystem,
23
32
  } from '@seanhogg/builderforce-webcontainers-core';
24
33
  import type { FsOp, HostToWorker, WorkerToHost } from './protocol.js';
25
34
  import { portPath } from './protocol.js';
35
+ import { ResponseReceiver, sendResponse } from './responseWire.js';
36
+ import { ChildRelay, isChildMessage } from './childRelay.js';
26
37
 
27
38
  /** The part of `Worker` the host uses — a real Worker, or an in-thread fake in tests. */
28
39
  export interface WorkerLike {
@@ -66,16 +77,26 @@ interface Proc {
66
77
  pid: number;
67
78
  info: Omit<ProcessInfo, 'ports'>;
68
79
  worker: WorkerLike;
69
- stdout: Set<(chunk: string) => void>;
70
- stderr: Set<(chunk: string) => void>;
80
+ stdout: Set<(chunk: StdioChunk) => void>;
81
+ stderr: Set<(chunk: StdioChunk) => void>;
71
82
  exited: boolean;
72
83
  resolveExit(code: number): void;
73
84
  registrations: Map<number, { close(): void }>;
74
- children: Map<number, ChildHandle>;
75
- pendingHttp: Map<number, (response: HttpResponseData) => void>;
85
+ /** The children its Worker spawned, relayed back to it. */
86
+ children: ChildRelay;
87
+ /** Its message channel to whoever spawned it with `ipc`: the parent's side. */
88
+ ipc?: ReturnType<typeof createIpcEndpoint>;
89
+ /** Responses its servers are streaming back to requests forwarded here. */
90
+ responses: ResponseReceiver;
91
+ /** Its loopback requests being answered, by the worker's request id: cancel functions. */
92
+ loopbacks: Map<number, () => void>;
93
+ /** Upgraded connections to its servers: the page-side end of each, by connection id. */
94
+ sockets: Map<number, ByteChannel>;
76
95
  outbox: FsOp[];
77
96
  }
78
97
 
98
+ const EXITED = 'The server process exited.';
99
+
79
100
  export class ProcessHost {
80
101
  readonly ports = new PortRegistry();
81
102
  /** Servers listening, ports opening and closing. */
@@ -84,6 +105,7 @@ export class ProcessHost {
84
105
  private applyingFrom?: Proc;
85
106
  private flushScheduled = false;
86
107
  private nextReq = 1;
108
+ private nextConn = 1;
87
109
  private readonly unwatch: () => void;
88
110
  private readonly stopPorts: () => void;
89
111
 
@@ -127,10 +149,16 @@ export class ProcessHost {
127
149
  resolveExit(code);
128
150
  },
129
151
  registrations: new Map(),
130
- children: new Map(),
131
- pendingHttp: new Map(),
152
+ children: new ChildRelay((childCommand, childArgs, childOptions) => {
153
+ this.flushOutboxes(); // the child must see every write made so far
154
+ return this.spawnChild(childCommand, childArgs, childOptions);
155
+ }, (message) => this.post(proc, message)),
156
+ responses: new ResponseReceiver(),
157
+ loopbacks: new Map(),
158
+ sockets: new Map(),
132
159
  outbox: [],
133
160
  };
161
+ if (options.ipc) proc.ipc = createIpcEndpoint((data) => this.post(proc, { type: 'ipc', data }), () => this.post(proc, { type: 'ipc-disconnect' }));
134
162
  this.procs.add(proc);
135
163
  worker.onmessage = (event) => this.onWorkerMessage(proc, event.data as WorkerToHost);
136
164
  worker.onerror = (event) => {
@@ -146,6 +174,8 @@ export class ProcessHost {
146
174
  cwd: options.cwd ?? '/',
147
175
  env: { ...DEFAULT_ENV, ...this.options.env, ...options.env },
148
176
  terminal: options.terminal,
177
+ ipc: options.ipc,
178
+ thread: options.thread,
149
179
  files: fs.list().map((path) => [path, fs.readFile(path)!]),
150
180
  dirs: fs.explicitDirectories(),
151
181
  ports: this.ports.ports(),
@@ -165,6 +195,7 @@ export class ProcessHost {
165
195
  kill: (signal = 'SIGTERM') => this.kill(proc, signal),
166
196
  resize: (cols, rows) => this.post(proc, { type: 'resize', cols, rows }),
167
197
  exit,
198
+ ipc: proc.ipc?.endpoint,
168
199
  };
169
200
  }
170
201
 
@@ -173,11 +204,21 @@ export class ProcessHost {
173
204
  return [...this.procs].map((proc) => ({ ...proc.info, args: [...proc.info.args], ports: [...proc.registrations.keys()] }));
174
205
  }
175
206
 
176
- /** Dispatch an HTTP request to the server on `port` (the preview service worker's `/__port/<port>/` path). */
207
+ /** Dispatch an HTTP request to the server on `port` and wait for the whole response. */
177
208
  request(port: number, request: HttpRequestData): Promise<HttpResponseData | undefined> {
209
+ return this.ports.requestBuffered(port, request);
210
+ }
211
+
212
+ /** Dispatch an HTTP request to the server on `port` (the preview's `/__port/<port>/` path); resolves at the head, the body streaming. */
213
+ requestStream(port: number, request: HttpRequestData): Promise<HttpStreamResponse | undefined> {
178
214
  return this.ports.request(port, request);
179
215
  }
180
216
 
217
+ /** Open an upgraded connection (a WebSocket) to the server on `port`; returns the client end. */
218
+ upgrade(port: number, request: HttpRequestData): ByteChannel | undefined {
219
+ return this.ports.upgrade(port, request);
220
+ }
221
+
181
222
  dispose(): void {
182
223
  for (const proc of [...this.procs]) {
183
224
  proc.worker.terminate();
@@ -206,8 +247,12 @@ export class ProcessHost {
206
247
  private cleanup(proc: Proc): void {
207
248
  for (const registration of proc.registrations.values()) registration.close();
208
249
  proc.registrations.clear();
209
- for (const respond of proc.pendingHttp.values()) respond({ status: 502, headers: { 'content-type': 'text/plain' }, body: new TextEncoder().encode('The server process exited.') });
210
- proc.pendingHttp.clear();
250
+ proc.responses.abort(() => textResponse(502, EXITED), EXITED);
251
+ for (const cancel of [...proc.loopbacks.values()]) cancel();
252
+ proc.loopbacks.clear();
253
+ for (const socket of proc.sockets.values()) socket.close();
254
+ proc.sockets.clear();
255
+ proc.ipc?.closed();
211
256
  this.procs.delete(proc);
212
257
  queueMicrotask(() => proc.worker.terminate());
213
258
  }
@@ -235,6 +280,7 @@ export class ProcessHost {
235
280
  }
236
281
 
237
282
  private onWorkerMessage(proc: Proc, message: WorkerToHost): void {
283
+ if (isChildMessage(message)) return proc.children.receive(message);
238
284
  switch (message.type) {
239
285
  case 'stdout':
240
286
  for (const l of proc.stdout) l(message.data);
@@ -258,36 +304,17 @@ export class ProcessHost {
258
304
  }
259
305
  return;
260
306
  }
261
- case 'spawn': {
262
- this.flushOutboxes();
263
- let child: ChildHandle;
264
- try {
265
- child = this.spawnChild(message.command, message.args, { cwd: message.cwd, env: message.env, terminal: message.terminal });
266
- } catch (error) {
267
- return this.post(proc, { type: 'child-error', childId: message.childId, code: (error as { code?: string }).code ?? 'EFAIL', message: (error as Error).message });
268
- }
269
- proc.children.set(message.childId, child);
270
- child.onStdout((data) => this.post(proc, { type: 'child-out', childId: message.childId, stream: 'stdout', data }));
271
- child.onStderr((data) => this.post(proc, { type: 'child-out', childId: message.childId, stream: 'stderr', data }));
272
- void child.exit.then((code) => {
273
- proc.children.delete(message.childId);
274
- this.post(proc, { type: 'child-exit', childId: message.childId, code });
275
- });
276
- return;
277
- }
278
- case 'child-stdin': {
279
- const child = proc.children.get(message.childId);
280
- if (message.data === null) child?.closeStdin();
281
- else child?.write(message.data);
282
- return;
283
- }
284
- case 'child-kill':
285
- return proc.children.get(message.childId)?.kill(message.signal);
286
- case 'child-resize':
287
- return proc.children.get(message.childId)?.resize?.(message.cols, message.rows);
307
+ case 'ipc':
308
+ return proc.ipc?.receive(message.data);
309
+ case 'ipc-disconnect':
310
+ return proc.ipc?.closed();
288
311
  case 'listen': {
289
312
  try {
290
- const registration = this.ports.listen(message.port, (request) => this.forward(proc, message.port, request));
313
+ const registration = this.ports.listen(
314
+ message.port,
315
+ (request) => this.forward(proc, message.port, request),
316
+ (request, socket) => this.forwardUpgrade(proc, message.port, request, socket),
317
+ );
291
318
  proc.registrations.set(message.port, registration);
292
319
  } catch (error) {
293
320
  for (const l of proc.stderr) l(`${(error as Error).message}\n`);
@@ -298,12 +325,23 @@ export class ProcessHost {
298
325
  proc.registrations.get(message.port)?.close();
299
326
  proc.registrations.delete(message.port);
300
327
  return;
301
- case 'http-response':
302
- proc.pendingHttp.get(message.reqId)?.(message.response);
303
- proc.pendingHttp.delete(message.reqId);
328
+ case 'response-head':
329
+ case 'response-chunk':
330
+ case 'response-end':
331
+ return proc.responses.receive(message);
332
+ case 'loopback': {
333
+ const { reqId } = message;
334
+ const cancel = sendResponse((reply) => this.post(proc, reply), reqId, this.ports.request(message.port, message.request), () => proc.loopbacks.delete(reqId));
335
+ proc.loopbacks.set(reqId, cancel);
304
336
  return;
305
- case 'loopback':
306
- void this.ports.request(message.port, message.request).then((response) => this.post(proc, { type: 'loopback-response', reqId: message.reqId, response: response ?? null }));
337
+ }
338
+ case 'request-cancel':
339
+ return proc.loopbacks.get(message.reqId)?.();
340
+ case 'socket-data':
341
+ return proc.sockets.get(message.connId)?.send(message.data);
342
+ case 'socket-close':
343
+ proc.sockets.get(message.connId)?.close();
344
+ proc.sockets.delete(message.connId);
307
345
  return;
308
346
  case 'listening':
309
347
  this.servers.announce({ port: message.port, url: message.url });
@@ -311,11 +349,23 @@ export class ProcessHost {
311
349
  }
312
350
  }
313
351
 
314
- private forward(proc: Proc, port: number, request: HttpRequestData): Promise<HttpResponseData> {
352
+ private async forward(proc: Proc, port: number, request: HttpRequestData): Promise<HttpStreamResponse> {
353
+ if (proc.exited) return textResponse(502, EXITED);
315
354
  const reqId = this.nextReq++;
316
- return new Promise((resolve) => {
317
- proc.pendingHttp.set(reqId, resolve);
318
- this.post(proc, { type: 'http-request', reqId, port, request });
355
+ const response = proc.responses.expect(reqId, () => this.post(proc, { type: 'request-cancel', reqId }));
356
+ this.post(proc, { type: 'http-request', reqId, port, request });
357
+ return (await response) ?? textResponse(502, `Nothing is listening on port ${port}.`);
358
+ }
359
+
360
+ /** Relay an upgraded connection: `socket` is the server end; its bytes go to the worker, and the worker's come back. */
361
+ private forwardUpgrade(proc: Proc, port: number, request: HttpRequestData, socket: ByteChannel): void {
362
+ if (proc.exited) return socket.close();
363
+ const connId = this.nextConn++;
364
+ proc.sockets.set(connId, socket);
365
+ socket.onData((data) => this.post(proc, { type: 'socket-data', connId, data }));
366
+ socket.onClose(() => {
367
+ if (proc.sockets.delete(connId)) this.post(proc, { type: 'socket-close', connId });
319
368
  });
369
+ this.post(proc, { type: 'socket-open', connId, port, request });
320
370
  }
321
371
  }
@@ -2,8 +2,19 @@
2
2
  * Messages between the page (the process host, which owns the master file
3
3
  * system and the port table) and one process Worker. Everything is plain
4
4
  * structured-clone data; file contents travel as strings or bytes.
5
+ *
6
+ * HTTP responses stream in both directions with the same three messages: a
7
+ * `response-head`, `response-chunk`s as the server writes, a `response-end`.
8
+ * Worker → page they answer an `http-request` (ids the page allocated); page →
9
+ * worker they answer a `loopback` (ids the worker allocated). `request-cancel`
10
+ * goes the other way: the reader hung up. Upgraded connections (WebSockets)
11
+ * are opened by the page (`socket-open`) and carry raw bytes both ways.
12
+ *
13
+ * A message channel (fork, worker threads) is `ipc` / `ipc-disconnect` between a
14
+ * process and the page (its parent's side), and `child-ipc` /
15
+ * `child-ipc-disconnect` between a parent process and the page (its child's side).
5
16
  */
6
- import type { FileContent, HttpRequestData, HttpResponseData } from '@seanhogg/builderforce-webcontainers-core';
17
+ import type { FileContent, HttpRequestData, HttpResponseHead, StdioChunk, ThreadInfo } from '@seanhogg/builderforce-webcontainers-core';
7
18
 
8
19
  export type FsOp = { op: 'write'; path: string; content: FileContent } | { op: 'remove'; path: string } | { op: 'mkdir'; path: string };
9
20
 
@@ -15,6 +26,9 @@ export interface StartMessage {
15
26
  cwd: string;
16
27
  env: Record<string, string>;
17
28
  terminal?: { cols: number; rows: number };
29
+ /** A message channel to the parent is open (`process.send`, a thread's `parentPort`). */
30
+ ipc?: boolean;
31
+ thread?: ThreadInfo;
18
32
  files: Array<[string, FileContent]>;
19
33
  dirs: string[];
20
34
  /** Ports already listening anywhere in the runtime (so `listen` can fail fast with EADDRINUSE). */
@@ -28,34 +42,57 @@ export interface StartMessage {
28
42
  packageCache: boolean;
29
43
  }
30
44
 
45
+ /** A streamed response, chunk by chunk; `head: null` means nothing listens on that port (loopback only). */
46
+ export type ResponseMessage =
47
+ | { type: 'response-head'; reqId: number; head: HttpResponseHead | null }
48
+ | { type: 'response-chunk'; reqId: number; data: Uint8Array }
49
+ | { type: 'response-end'; reqId: number; error?: string };
50
+
51
+ /** Raw bytes of an upgraded connection, either way; ids allocated by the page. */
52
+ export type SocketMessage = { type: 'socket-data'; connId: number; data: Uint8Array } | { type: 'socket-close'; connId: number };
53
+
54
+ /** Message-channel traffic: to/from this process's parent (`ipc`), or one of its children (`child-ipc`). */
55
+ export type IpcMessage =
56
+ | { type: 'ipc'; data: unknown }
57
+ | { type: 'ipc-disconnect' }
58
+ | { type: 'child-ipc'; childId: number; data: unknown }
59
+ | { type: 'child-ipc-disconnect'; childId: number };
60
+
31
61
  /** page → worker */
32
62
  export type HostToWorker =
33
63
  | StartMessage
34
- | { type: 'stdin'; data: string | null }
64
+ | { type: 'stdin'; data: StdioChunk | null }
35
65
  | { type: 'kill'; signal: string }
36
66
  | { type: 'resize'; cols: number; rows: number }
37
67
  | { type: 'fs'; ops: FsOp[] }
38
68
  | { type: 'ports'; open: number[]; closed: number[] }
39
- | { type: 'child-out'; childId: number; stream: 'stdout' | 'stderr'; data: string }
69
+ | { type: 'child-out'; childId: number; stream: 'stdout' | 'stderr'; data: StdioChunk }
40
70
  | { type: 'child-exit'; childId: number; code: number }
41
71
  | { type: 'child-error'; childId: number; code: string; message: string }
42
72
  | { type: 'http-request'; reqId: number; port: number; request: HttpRequestData }
43
- | { type: 'loopback-response'; reqId: number; response: HttpResponseData | null };
73
+ | { type: 'request-cancel'; reqId: number }
74
+ | { type: 'socket-open'; connId: number; port: number; request: HttpRequestData }
75
+ | ResponseMessage
76
+ | SocketMessage
77
+ | IpcMessage;
44
78
 
45
79
  /** worker → page */
46
80
  export type WorkerToHost =
47
- | { type: 'stdout' | 'stderr'; data: string }
81
+ | { type: 'stdout' | 'stderr'; data: StdioChunk }
48
82
  | { type: 'exit'; code: number }
49
83
  | { type: 'fs'; ops: FsOp[] }
50
- | { type: 'spawn'; childId: number; command: string; args: string[]; cwd?: string; env?: Record<string, string>; terminal?: { cols: number; rows: number } }
51
- | { type: 'child-stdin'; childId: number; data: string | null }
84
+ | { type: 'spawn'; childId: number; command: string; args: string[]; cwd?: string; env?: Record<string, string>; terminal?: { cols: number; rows: number }; ipc?: boolean; thread?: ThreadInfo }
85
+ | { type: 'child-stdin'; childId: number; data: StdioChunk | null }
52
86
  | { type: 'child-kill'; childId: number; signal: string }
53
87
  | { type: 'child-resize'; childId: number; cols: number; rows: number }
54
88
  | { type: 'listen'; port: number }
55
89
  | { type: 'unlisten'; port: number }
56
- | { type: 'http-response'; reqId: number; response: HttpResponseData }
57
90
  | { type: 'loopback'; reqId: number; port: number; request: HttpRequestData }
58
- | { type: 'listening'; port: number; url: string };
91
+ | { type: 'request-cancel'; reqId: number }
92
+ | { type: 'listening'; port: number; url: string }
93
+ | ResponseMessage
94
+ | SocketMessage
95
+ | IpcMessage;
59
96
 
60
97
  /** The preview-relative URL a virtual server on `port` is reachable at. */
61
98
  export function portPath(previewBase: string, port: number): string {
@@ -0,0 +1,97 @@
1
+ /**
2
+ * Streamed HTTP responses over postMessage, used on both sides of the
3
+ * page ↔ process-worker boundary: the side that holds a response sends it as
4
+ * head / chunk / end messages as the server writes it, and the side that asked
5
+ * rebuilds an `HttpStreamResponse` whose body stream is fed by them. A reader
6
+ * that cancels the body sends `request-cancel` back, so the server hears the
7
+ * client hang up.
8
+ */
9
+ import { drainBody, headOf, pushStream, type HttpStreamResponse, type PushStream } from '@seanhogg/builderforce-webcontainers-core';
10
+ import type { ResponseMessage } from './protocol.js';
11
+
12
+ const encoder = new TextEncoder();
13
+
14
+ /**
15
+ * Send `response` as messages once it resolves (`undefined`: nothing listens).
16
+ * A rejected handler becomes a 500 carrying the error. Returns a cancel for
17
+ * when the requester hangs up; `onDone` runs once, when the exchange is over.
18
+ */
19
+ export function sendResponse(post: (message: ResponseMessage) => void, reqId: number, response: Promise<HttpStreamResponse | undefined>, onDone?: () => void): () => void {
20
+ let finished = false;
21
+ let stop: (() => void) | undefined;
22
+ const done = () => {
23
+ if (finished) return;
24
+ finished = true;
25
+ onDone?.();
26
+ };
27
+ response.then(
28
+ (res) => {
29
+ if (finished) return void res?.body.cancel().catch(() => undefined);
30
+ if (!res) {
31
+ post({ type: 'response-head', reqId, head: null });
32
+ return done();
33
+ }
34
+ post({ type: 'response-head', reqId, head: headOf(res) });
35
+ stop = drainBody(res.body, {
36
+ chunk: (data) => post({ type: 'response-chunk', reqId, data }),
37
+ end: (error) => {
38
+ post(error ? { type: 'response-end', reqId, error } : { type: 'response-end', reqId });
39
+ done();
40
+ },
41
+ });
42
+ },
43
+ (error: unknown) => {
44
+ if (finished) return;
45
+ post({ type: 'response-head', reqId, head: { status: 500, headers: { 'content-type': 'text/plain' } } });
46
+ post({ type: 'response-chunk', reqId, data: encoder.encode(String(error instanceof Error ? error.stack : error)) });
47
+ post({ type: 'response-end', reqId });
48
+ done();
49
+ },
50
+ );
51
+ return () => {
52
+ stop?.();
53
+ done();
54
+ };
55
+ }
56
+
57
+ /** Rebuilds streamed responses from the messages answering requests this side sent. */
58
+ export class ResponseReceiver {
59
+ private readonly heads = new Map<number, { resolve(response: HttpStreamResponse | undefined): void; cancel(): void }>();
60
+ private readonly bodies = new Map<number, PushStream>();
61
+
62
+ /** The response to request `reqId`; `cancel` runs if its reader hangs up before the end. */
63
+ expect(reqId: number, cancel: () => void): Promise<HttpStreamResponse | undefined> {
64
+ return new Promise((resolve) => this.heads.set(reqId, { resolve, cancel }));
65
+ }
66
+
67
+ receive(message: ResponseMessage): void {
68
+ const { reqId } = message;
69
+ if (message.type === 'response-head') {
70
+ const waiting = this.heads.get(reqId);
71
+ this.heads.delete(reqId);
72
+ if (!waiting) return;
73
+ if (!message.head) return waiting.resolve(undefined);
74
+ const body = pushStream(() => {
75
+ this.bodies.delete(reqId);
76
+ waiting.cancel();
77
+ });
78
+ this.bodies.set(reqId, body);
79
+ waiting.resolve({ ...message.head, body: body.stream });
80
+ } else if (message.type === 'response-chunk') {
81
+ this.bodies.get(reqId)?.push(message.data);
82
+ } else {
83
+ const body = this.bodies.get(reqId);
84
+ this.bodies.delete(reqId);
85
+ if (message.error) body?.fail(new Error(message.error));
86
+ else body?.end();
87
+ }
88
+ }
89
+
90
+ /** The other side is gone: waiting requests get `fallback`, bodies in flight break off with `reason`. */
91
+ abort(fallback: () => HttpStreamResponse | undefined, reason: string): void {
92
+ for (const { resolve } of this.heads.values()) resolve(fallback());
93
+ this.heads.clear();
94
+ for (const body of this.bodies.values()) body.fail(new Error(reason));
95
+ this.bodies.clear();
96
+ }
97
+ }
@@ -1,25 +1,34 @@
1
1
  /**
2
2
  * The worker side of one process: mirror the file system, build a `System`
3
3
  * whose spawn/listen/loopback are relayed to the page, run the program, and
4
- * stream its output back. No worker globals in here — `post` and the message
4
+ * stream its output back. Its servers' responses stream to the page as they
5
+ * are written, and connections the page upgrades reach the server's `upgrade`
6
+ * handler as a byte pipe. No worker globals in here — `post` and the message
5
7
  * feed are injected — so the same code runs in a real Worker (worker.ts) and
6
8
  * in-thread in tests.
7
9
  */
8
10
  import {
9
11
  VirtualFileSystem,
10
12
  commandNotFound,
13
+ createChannelPair,
14
+ createIpcEndpoint,
11
15
  defaultPrograms,
12
16
  resolveCommand,
13
17
  runProgram,
18
+ textResponse,
19
+ type ByteChannel,
14
20
  type ChildHandle,
15
21
  type FsChange,
16
22
  type HttpHandler,
17
- type HttpResponseData,
18
23
  type PackageCache,
24
+ type ProcessOptions,
25
+ type StdioChunk,
19
26
  type System,
27
+ type UpgradeHandler,
20
28
  } from '@seanhogg/builderforce-webcontainers-core';
21
29
  import type { FsOp, HostToWorker, StartMessage, WorkerToHost } from './protocol.js';
22
30
  import { portPath } from './protocol.js';
31
+ import { ResponseReceiver, sendResponse } from './responseWire.js';
23
32
 
24
33
  export interface WorkerProcessDeps {
25
34
  post(message: WorkerToHost): void;
@@ -35,10 +44,17 @@ const EPHEMERAL = 49152;
35
44
 
36
45
  export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message: HostToWorker): void } {
37
46
  const fs = new VirtualFileSystem();
38
- const handlers = new Map<number, HttpHandler>();
47
+ const handlers = new Map<number, { handler: HttpHandler; upgrade?: UpgradeHandler }>();
39
48
  const knownPorts = new Set<number>();
40
- const children = new Map<number, { stdout: Set<(s: string) => void>; stderr: Set<(s: string) => void>; exit: (code: number) => void }>();
41
- const loopbacks = new Map<number, (response: HttpResponseData | undefined) => void>();
49
+ const children = new Map<number, { stdout: Set<(chunk: StdioChunk) => void>; stderr: Set<(chunk: StdioChunk) => void>; exit: (code: number) => void; ipc?: ReturnType<typeof createIpcEndpoint> }>();
50
+ /** This process's channel to its parent, when it was spawned with `ipc`. */
51
+ let parentChannel: ReturnType<typeof createIpcEndpoint> | undefined;
52
+ /** Responses to this process's loopback requests, streaming in from the page. */
53
+ const loopbacks = new ResponseReceiver();
54
+ /** Responses this process's servers are streaming to the page, by the page's request id. */
55
+ const serving = new Map<number, () => void>();
56
+ /** Upgraded connections the page opened, by its connection id (our end of the pipe to the server). */
57
+ const sockets = new Map<number, ByteChannel>();
42
58
  let nextChild = 1;
43
59
  let nextReq = 1;
44
60
  let applying = false;
@@ -78,15 +94,18 @@ export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message:
78
94
  }
79
95
  };
80
96
 
81
- function remoteChild(command: string, args: string[], options: { cwd?: string; env?: Record<string, string>; terminal?: { cols: number; rows: number } } = {}): ChildHandle {
97
+ function remoteChild(command: string, args: string[], options: ProcessOptions = {}): ChildHandle {
82
98
  flush(); // the child must see every write made so far
83
99
  const childId = nextChild++;
84
- const stdout = new Set<(s: string) => void>();
85
- const stderr = new Set<(s: string) => void>();
100
+ const stdout = new Set<(chunk: StdioChunk) => void>();
101
+ const stderr = new Set<(chunk: StdioChunk) => void>();
86
102
  let resolveExit!: (code: number) => void;
87
103
  const exit = new Promise<number>((resolve) => (resolveExit = resolve));
88
- children.set(childId, { stdout, stderr, exit: resolveExit });
89
- deps.post({ type: 'spawn', childId, command, args, cwd: options.cwd, env: options.env, terminal: options.terminal });
104
+ const ipc = options.ipc
105
+ ? createIpcEndpoint((data) => deps.post({ type: 'child-ipc', childId, data }), () => deps.post({ type: 'child-ipc-disconnect', childId }))
106
+ : undefined;
107
+ children.set(childId, { stdout, stderr, exit: resolveExit, ipc });
108
+ deps.post({ type: 'spawn', childId, command, args, cwd: options.cwd, env: options.env, terminal: options.terminal, ipc: options.ipc, thread: options.thread });
90
109
  return {
91
110
  pid: childId,
92
111
  onStdout: (l) => (stdout.add(l), () => stdout.delete(l)),
@@ -96,6 +115,7 @@ export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message:
96
115
  kill: (signal = 'SIGTERM') => deps.post({ type: 'child-kill', childId, signal }),
97
116
  resize: (cols, rows) => deps.post({ type: 'child-resize', childId, cols, rows }),
98
117
  exit,
118
+ ipc: ipc?.endpoint,
99
119
  };
100
120
  }
101
121
 
@@ -117,17 +137,18 @@ export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message:
117
137
  if (!resolveCommand(fs, programs, command, args, cwd, env)) throw commandNotFound(command);
118
138
  return remoteChild(command, args, { ...options, cwd, env });
119
139
  },
120
- listen(port, handler) {
140
+ listen(port, handler, upgrade) {
121
141
  let actual = port;
122
142
  if (!actual) for (actual = EPHEMERAL + (message.pid % 1000) * 8; knownPorts.has(actual); actual++);
123
143
  if (knownPorts.has(actual)) throw Object.assign(new Error(`listen EADDRINUSE: address already in use :::${actual}`), { code: 'EADDRINUSE', errno: -98, syscall: 'listen', port: actual });
124
144
  knownPorts.add(actual);
125
- handlers.set(actual, handler);
145
+ const entry = { handler, upgrade };
146
+ handlers.set(actual, entry);
126
147
  deps.post({ type: 'listen', port: actual });
127
148
  return {
128
149
  port: actual,
129
150
  close() {
130
- if (handlers.get(actual) !== handler) return;
151
+ if (handlers.get(actual) !== entry) return;
131
152
  handlers.delete(actual);
132
153
  knownPorts.delete(actual);
133
154
  deps.post({ type: 'unlisten', port: actual });
@@ -136,12 +157,11 @@ export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message:
136
157
  },
137
158
  loopback(port, request) {
138
159
  const local = handlers.get(port);
139
- if (local) return local(request);
160
+ if (local) return local.handler(request);
140
161
  const reqId = nextReq++;
141
- return new Promise((resolve) => {
142
- loopbacks.set(reqId, resolve);
143
- deps.post({ type: 'loopback', reqId, port, request });
144
- });
162
+ const response = loopbacks.expect(reqId, () => deps.post({ type: 'request-cancel', reqId }));
163
+ deps.post({ type: 'loopback', reqId, port, request });
164
+ return response;
145
165
  },
146
166
  serverUrl: (port) => new URL(portPath(message.previewBase, port), message.previewOrigin).href,
147
167
  announceServer: (port, url) => deps.post({ type: 'listening', port, url }),
@@ -158,7 +178,18 @@ export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message:
158
178
  deps.post({ type: 'exit', code: 127 });
159
179
  return;
160
180
  }
161
- process = runProgram({ program: resolved.program, args: resolved.args, system, cwd: message.cwd, env: message.env, terminal: message.terminal, pid: message.pid });
181
+ if (message.ipc) parentChannel = createIpcEndpoint((data) => deps.post({ type: 'ipc', data }), () => deps.post({ type: 'ipc-disconnect' }));
182
+ process = runProgram({
183
+ program: resolved.program,
184
+ args: resolved.args,
185
+ system,
186
+ cwd: message.cwd,
187
+ env: message.env,
188
+ terminal: message.terminal,
189
+ pid: message.pid,
190
+ thread: message.thread,
191
+ channel: parentChannel?.endpoint,
192
+ });
162
193
  process.onStdout((data) => deps.post({ type: 'stdout', data }));
163
194
  process.onStderr((data) => deps.post({ type: 'stderr', data }));
164
195
  void process.exit.then((code) => {
@@ -190,9 +221,18 @@ export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message:
190
221
  for (const l of children.get(message.childId)?.[message.stream] ?? []) l(message.data);
191
222
  return;
192
223
  case 'child-exit':
224
+ children.get(message.childId)?.ipc?.closed();
193
225
  children.get(message.childId)?.exit(message.code);
194
226
  children.delete(message.childId);
195
227
  return;
228
+ case 'child-ipc':
229
+ return children.get(message.childId)?.ipc?.receive(message.data);
230
+ case 'child-ipc-disconnect':
231
+ return children.get(message.childId)?.ipc?.closed();
232
+ case 'ipc':
233
+ return parentChannel?.receive(message.data);
234
+ case 'ipc-disconnect':
235
+ return parentChannel?.closed();
196
236
  case 'child-error': {
197
237
  const child = children.get(message.childId);
198
238
  for (const l of child?.stderr ?? []) l(`${message.message}\n`);
@@ -201,17 +241,37 @@ export function createWorkerProcess(deps: WorkerProcessDeps): { receive(message:
201
241
  return;
202
242
  }
203
243
  case 'http-request': {
204
- const handler = handlers.get(message.port);
205
- const respond = (response: HttpResponseData) => deps.post({ type: 'http-response', reqId: message.reqId, response });
206
- if (!handler) return respond({ status: 502, headers: { 'content-type': 'text/plain' }, body: new TextEncoder().encode(`Nothing is listening on port ${message.port}.`) });
207
- void handler(message.request).then(respond, (error: unknown) =>
208
- respond({ status: 500, headers: { 'content-type': 'text/plain' }, body: new TextEncoder().encode(String(error instanceof Error ? error.stack : error)) }),
209
- );
244
+ const { reqId } = message;
245
+ const entry = handlers.get(message.port);
246
+ const response = entry ? entry.handler(message.request) : Promise.resolve(textResponse(502, `Nothing is listening on port ${message.port}.`));
247
+ serving.set(reqId, sendResponse(deps.post, reqId, response, () => serving.delete(reqId)));
248
+ return;
249
+ }
250
+ case 'request-cancel':
251
+ return serving.get(message.reqId)?.();
252
+ case 'response-head':
253
+ case 'response-chunk':
254
+ case 'response-end':
255
+ return loopbacks.receive(message);
256
+ case 'socket-open': {
257
+ const { connId } = message;
258
+ const upgrade = handlers.get(message.port)?.upgrade;
259
+ if (!upgrade) return deps.post({ type: 'socket-close', connId });
260
+ const [ours, server] = createChannelPair();
261
+ sockets.set(connId, ours);
262
+ ours.onData((data) => deps.post({ type: 'socket-data', connId, data }));
263
+ ours.onClose(() => {
264
+ sockets.delete(connId);
265
+ deps.post({ type: 'socket-close', connId });
266
+ });
267
+ upgrade(message.request, server);
210
268
  return;
211
269
  }
212
- case 'loopback-response':
213
- loopbacks.get(message.reqId)?.(message.response ?? undefined);
214
- loopbacks.delete(message.reqId);
270
+ case 'socket-data':
271
+ return sockets.get(message.connId)?.send(message.data);
272
+ case 'socket-close':
273
+ sockets.get(message.connId)?.close();
274
+ sockets.delete(message.connId);
215
275
  return;
216
276
  }
217
277
  },