@immediately-run/worker-transport 0.1.0

package/README.md

@@ -0,0 +1,43 @@
+# @immediately-run/worker-transport
+
+The same-origin **worker MessagePort transport** for immediately.run: the
+`WorkerMessageBus` request/response protocol and the one-time `{ type: 'connect' }`
+MessagePort handshake, extracted into a leaf package so a **worker-owning service
+package** can ship its own worker entry without depending on `sandbox`.
+
+## Why a dedicated leaf package (not the SDK)
+
+The transport is imported by the worker-owning packages (today
+`@immediately-run/transpiler`'s Babel worker; later the `tsc`/`eslint`/`prettier`
+authoring services per R3-107) **and** by `sandbox`. Routing it through the SDK would
+pull the *host* (`immediately-run-site-main`) into a build dependency on the app-facing
+client library — which the host↔SDK design deliberately avoids (the SDK is fetched at
+runtime, never a host build input; `SDK_PACKAGING_SPEC §5`). A leaf package keeps the
+transport entanglement-free. See `SIMPLIFIED_DEPLOYMENT_SPEC §14` / roadmap **R3-149**.
+
+## API
+
+- `WorkerMessageBus` — the channel-scoped request/response bus over any
+  `MessageEndpoint` (a `Worker`, a `MessagePort`, or `self` in a worker).
+- `bindWorkerMessageBus(self, opts)` — installs the `{ type: 'connect' }` handshake on a
+  worker's `self`: waits for the parent to transfer a `MessagePort`, starts it, and binds
+  a `WorkerMessageBus` on it. This is the exact handshake sandbox's `babel-worker.ts` used,
+  generalized so every worker entry installs it identically.
+
+```ts
+import { bindWorkerMessageBus } from '@immediately-run/worker-transport';
+
+bindWorkerMessageBus(self, {
+  channel: 'sandpack-babel',
+  handleRequest: (method, data) =>
+    method === 'transform' ? doTransform(data) : Promise.reject(new Error('Unknown method')),
+});
+```
+
+## Runtime topology
+
+The worker is spawned by the **parent page** (not the sandboxed iframe) so the iframe can
+drop `allow-same-origin`. The parent transfers a `MessagePort` entangled with one handed
+into the iframe, so transform requests flow directly between the iframe and the worker
+(the MessagePort identity rule, `HOST_ORIGIN_HARDENING_SPEC §2.4`). This package only owns
+the wire protocol; where the bytes are served from is the consumer's concern.

package/dist/WorkerMessageBus.d.ts

@@ -0,0 +1,34 @@
+export type RequestHandlerFn = (method: string, ...params: any[]) => Promise<any>;
+export type NotificationHandlerFn = (method: string, data: any) => Promise<any>;
+export type ErrorHandlerFn = (error: Error) => Promise<any>;
+export interface MessageEndpoint {
+    postMessage(message: any, ...params: any[]): void;
+    addEventListener(type: string, listener: (ev: any) => any): any;
+    removeEventListener(type: string, listener: (ev: any) => any): any;
+}
+export interface WorkerMessageBusOpts {
+    /** name for the channel */
+    channel: string;
+    endpoint: MessageEndpoint;
+    handleRequest: RequestHandlerFn;
+    handleNotification: NotificationHandlerFn;
+    handleError: ErrorHandlerFn;
+    timeoutMs: number;
+}
+export interface PendingRequest {
+    resolve: (result: any) => void;
+    reject: (err: Error) => void;
+}
+export declare class WorkerMessageBus {
+    private endpoint;
+    private handleRequest;
+    private handleNotification;
+    private handleError;
+    private channel;
+    private timeoutMs;
+    private pendingRequests;
+    private _messageId;
+    constructor(opts: WorkerMessageBusOpts);
+    nextMessageId(): number;
+    request(method: string, ...params: any): Promise<any>;
+}

package/dist/WorkerMessageBus.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WorkerMessageBus = void 0;
+// The transport is a leaf package (the @immediately-run/platform-constants shape):
+// it must not depend on any consumer's logger. Error logging here only affects the
+// diagnostics channel, never the bytes a request handler returns, so a plain
+// console.error is behaviour-equivalent to the sandbox's log-level-gated logger.
+const logError = (...data) => {
+    console.error(...data);
+};
+const serializeError = (originalError) => {
+    if (typeof originalError !== 'object') {
+        return { message: originalError };
+    }
+    else {
+        return {
+            message: originalError.message,
+            name: originalError.name,
+            stack: originalError.stack,
+            ...originalError,
+        };
+    }
+};
+const parseError = (serializedError) => {
+    const error = new Error(serializedError.message);
+    for (const key of Object.keys(serializedError)) {
+        // @ts-expect-error indexing Error with a dynamic key to rehydrate custom fields
+        error[key] = serializedError[key];
+    }
+    return error;
+};
+class WorkerMessageBus {
+    endpoint;
+    handleRequest;
+    handleNotification;
+    handleError;
+    channel;
+    timeoutMs;
+    pendingRequests = new Map();
+    _messageId = 0;
+    constructor(opts) {
+        this.channel = opts.channel;
+        this.endpoint = opts.endpoint;
+        this.handleRequest = opts.handleRequest;
+        this.handleNotification = opts.handleNotification;
+        this.handleError = opts.handleError;
+        this.timeoutMs = opts.timeoutMs;
+        this.endpoint.addEventListener('message', async (evt) => {
+            const data = evt.data;
+            if (data.channel !== this.channel) {
+                return;
+            }
+            const messageId = data.id;
+            if (data.method) {
+                if (messageId == null) {
+                    this.handleNotification(data.method, data.data);
+                }
+                else if (data.method && data.params) {
+                    // It's a request
+                    try {
+                        const result = await this.handleRequest(data.method, ...data.params);
+                        this.endpoint.postMessage({
+                            id: messageId,
+                            channel: this.channel,
+                            result,
+                        });
+                    }
+                    catch (err) {
+                        logError(err);
+                        this.endpoint.postMessage({
+                            id: messageId,
+                            channel: this.channel,
+                            error: serializeError(err),
+                        });
+                    }
+                }
+            }
+            else if (messageId != null) {
+                // It's a response
+                const pendingRequest = this.pendingRequests.get(messageId);
+                if (!pendingRequest) {
+                    return;
+                }
+                if (data.error !== undefined) {
+                    pendingRequest.reject(parseError(data.error));
+                }
+                else {
+                    pendingRequest.resolve(data.result);
+                }
+            }
+        });
+        this.endpoint.addEventListener('error', (err) => this.handleError(err));
+    }
+    nextMessageId() {
+        this._messageId++;
+        return this._messageId;
+    }
+    request(method, ...params) {
+        const messageId = this.nextMessageId();
+        const message = {
+            channel: this.channel,
+            id: messageId,
+            method,
+            params,
+        };
+        const promise = new Promise((resolve, reject) => {
+            const timeoutRef = setTimeout(() => {
+                this.pendingRequests.delete(messageId);
+                reject(new Error(`Request on channel ${this.channel} timed out`));
+            }, this.timeoutMs);
+            this.pendingRequests.set(messageId, {
+                resolve: (data) => {
+                    clearTimeout(timeoutRef);
+                    resolve(data);
+                },
+                reject: (err) => {
+                    clearTimeout(timeoutRef);
+                    reject(err);
+                },
+            });
+        });
+        this.endpoint.postMessage(message);
+        return promise;
+    }
+}
+exports.WorkerMessageBus = WorkerMessageBus;

package/dist/connect.d.ts

@@ -0,0 +1,13 @@
+import { type RequestHandlerFn, type NotificationHandlerFn, type ErrorHandlerFn } from './WorkerMessageBus';
+export interface BindWorkerMessageBusOpts {
+    /** channel name — must match the main-thread bus (e.g. 'sandpack-babel') */
+    channel: string;
+    handleRequest: RequestHandlerFn;
+    handleNotification?: NotificationHandlerFn;
+    handleError?: ErrorHandlerFn;
+    timeoutMs?: number;
+}
+export declare function bindWorkerMessageBus(self: {
+    addEventListener(type: string, listener: (ev: any) => any): any;
+    removeEventListener(type: string, listener: (ev: any) => any): any;
+}, opts: BindWorkerMessageBusOpts): void;

package/dist/connect.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bindWorkerMessageBus = bindWorkerMessageBus;
+const WorkerMessageBus_1 = require("./WorkerMessageBus");
+// The one-time `{ type: 'connect' }` MessagePort handshake, extracted verbatim
+// from sandbox's babel-worker.ts so every worker-owning package (transpiler's
+// Babel worker, later the authoring services) installs it identically.
+//
+// This worker is created by the *parent* page (not the sandboxed iframe) so the
+// iframe can drop `allow-same-origin`. The parent hands the worker a `MessagePort`
+// entangled with one transferred into the iframe, so transform requests flow
+// directly between the iframe and this worker without the parent relaying them.
+// We wait for that one-time `{ type: 'connect' }` handshake, then talk over the
+// transferred port instead of `self`.
+function bindWorkerMessageBus(self, opts) {
+    const { channel, handleRequest, handleNotification = () => Promise.resolve(), handleError = () => Promise.resolve(), timeoutMs = 30000, } = opts;
+    self.addEventListener('message', function onConnect(evt) {
+        if (evt.data && evt.data.type === 'connect') {
+            const port = evt.ports && evt.ports[0];
+            if (port) {
+                self.removeEventListener('message', onConnect);
+                port.start();
+                new WorkerMessageBus_1.WorkerMessageBus({
+                    channel,
+                    endpoint: port,
+                    handleRequest,
+                    handleNotification,
+                    handleError,
+                    timeoutMs,
+                });
+            }
+        }
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { WorkerMessageBus, type MessageEndpoint, type WorkerMessageBusOpts, type RequestHandlerFn, type NotificationHandlerFn, type ErrorHandlerFn, type PendingRequest, } from './WorkerMessageBus';
+export { bindWorkerMessageBus, type BindWorkerMessageBusOpts, } from './connect';

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+// @immediately-run/worker-transport — the leaf package that owns the same-origin
+// worker MessagePort transport, so a worker-owning service package (the transpiler's
+// Babel worker; later tsc/eslint/prettier per R3-107) can ship its own worker entry
+// without depending on `sandbox`. A leaf package, NOT the SDK: routing the transport
+// through the SDK would pull the *host* (immediately-run-site-main) into a build
+// dependency on the app-facing client lib, which the host↔SDK design deliberately
+// avoids (SDK_PACKAGING_SPEC §5). See SIMPLIFIED_DEPLOYMENT_SPEC §14 / R3-149.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bindWorkerMessageBus = exports.WorkerMessageBus = void 0;
+var WorkerMessageBus_1 = require("./WorkerMessageBus");
+Object.defineProperty(exports, "WorkerMessageBus", { enumerable: true, get: function () { return WorkerMessageBus_1.WorkerMessageBus; } });
+var connect_1 = require("./connect");
+Object.defineProperty(exports, "bindWorkerMessageBus", { enumerable: true, get: function () { return connect_1.bindWorkerMessageBus; } });

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@immediately-run/worker-transport",
+  "version": "0.1.0",
+  "description": "The same-origin worker MessagePort transport (WorkerMessageBus + the {type:'connect'} handshake), extracted so a worker-owning service package can ship its own worker entry without depending on `sandbox`. A leaf package, NOT the SDK (SIMPLIFIED_DEPLOYMENT_SPEC §14 / R3-149).",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/immediately-run/immediately-run-worker-transport.git"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "jest",
+    "lint": "eslint src test",
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.18.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.17.0",
+    "eslint": "^9.18.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.5",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.20.0"
+  }
+}