@sealant/sdk 0.13.5 → 0.14.0

package/dist/facade/workspace.js

@@ -189,6 +189,99 @@ export const makeWorkspace = (ctx, init) => {
                 ...(ttl === undefined ? {} : { ttlSeconds: ttl === null ? null : parseTtlSeconds(ttl) }),
             }));
         },
+        forward: (port) => openForward(ctx, init.id, port),
     };
     return workspace;
 };
+/**
+ * Open the held-WebSocket port forward (the byte-pipe data plane, mirroring
+ * the session attachment): binary frames are payload bytes in both
+ * directions; text frames are control JSON — `{"t":"eof"}` up for half-close,
+ * `{"t":"end"}` down when the remote closes. Auth rides the connect
+ * (`?token=` / `?ownerUserId=`), never per frame. The server refuses the
+ * upgrade with a plain HTTP status when nothing listens on the port, which
+ * surfaces here as the connect rejection.
+ */
+const openForward = (ctx, workspaceId, port) => {
+    const config = ctx.config;
+    const url = new URL(`/v1/workspaces/${workspaceId}/forward`, config.baseUrl);
+    url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    url.searchParams.set("port", String(port));
+    if (config.apiKey === undefined) {
+        url.searchParams.set("ownerUserId", config.hostLocal.ownerUserId);
+    }
+    else {
+        url.searchParams.set("token", config.apiKey);
+    }
+    return new Promise((resolve, reject) => {
+        const ws = new WebSocket(url);
+        ws.binaryType = "arraybuffer";
+        // Push-queue bridging WS message events to the pull-based async iterable.
+        const pending = [];
+        let wake;
+        let finished = false;
+        const closedResolver = Promise.withResolvers();
+        const closed = closedResolver.promise;
+        const finish = (reason) => {
+            if (finished) {
+                return;
+            }
+            finished = true;
+            closedResolver.resolve(reason);
+            wake?.();
+        };
+        ws.addEventListener("message", (event) => {
+            if (typeof event.data === "string") {
+                try {
+                    const frame = JSON.parse(event.data);
+                    if (frame.t === "end") {
+                        finish("end");
+                    }
+                }
+                catch {
+                    // Unknown text frame — ignore.
+                }
+                return;
+            }
+            pending.push(new Uint8Array(event.data));
+            wake?.();
+        });
+        ws.addEventListener("close", () => finish("closed"));
+        const output = {
+            [Symbol.asyncIterator]: () => ({
+                next: async () => {
+                    for (;;) {
+                        const chunk = pending.shift();
+                        if (chunk !== undefined) {
+                            return { done: false, value: chunk };
+                        }
+                        if (finished) {
+                            return { done: true, value: undefined };
+                        }
+                        await new Promise((r) => {
+                            wake = r;
+                        });
+                        wake = undefined;
+                    }
+                },
+            }),
+        };
+        const forward = {
+            send: (input) => {
+                // Copy into a plain ArrayBuffer-backed view (WebSocket.send rejects SharedArrayBuffer views).
+                ws.send(new Uint8Array(input).buffer);
+            },
+            eof: () => {
+                ws.send(JSON.stringify({ t: "eof" }));
+            },
+            output,
+            closed,
+            close: () => {
+                finish("closed");
+                ws.close();
+            },
+        };
+        ws.addEventListener("open", () => resolve(forward), { once: true });
+        ws.addEventListener("error", () => reject(new Error(`workspace forward failed: could not connect to ${url.host} (is anything listening on 127.0.0.1:${port} in the workspace?)`)), { once: true });
+    });
+};

package/dist/types.d.ts

@@ -220,6 +220,31 @@ export interface Workspace {
     expire(options?: {
         readonly in?: string | null;
     }): Promise<void>;
+    /**
+     * Open a raw TCP byte pipe to `127.0.0.1:port` INSIDE the workspace — the
+     * primitive for reaching a dev server or database the workspace runs.
+     * Protocol-agnostic: nothing inspects or records the payload. One held
+     * WebSocket per forward; rejects when nothing accepts the connection. The
+     * target host is fixed at loopback by design.
+     */
+    forward(port: number): Promise<WorkspaceForward>;
+}
+/**
+ * A live port forward — one WebSocket, held until `close()` or the remote
+ * closes. A raw duplex byte stream: write with `send`, read from `output`,
+ * signal outbound EOF with `eof` (half-close; inbound keeps flowing).
+ */
+export interface WorkspaceForward {
+    /** Write bytes toward the workspace port on the held socket. */
+    send(input: Uint8Array): void;
+    /** Half-close: no more outbound bytes; the remote's response keeps flowing. */
+    eof(): void;
+    /** Bytes from the workspace port, until the remote closes or `close()`. */
+    readonly output: AsyncIterable<Uint8Array>;
+    /** Resolves when the forward ends: the remote closed (`"end"`) or the socket closed. */
+    readonly closed: Promise<"end" | "closed">;
+    /** Tear the forward down. */
+    close(): void;
 }
 export interface RunOptions {
     /** Cancel the run by aborting this signal. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/sdk",
-  "version": "0.13.5",
+  "version": "0.14.0",
   "description": "The fluent public SDK for Sealant — create a workspace, run a harness, replay the record.",
   "license": "Apache-2.0",
   "repository": {
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@sealant/api-contracts": "^0.13.5"
+    "@sealant/api-contracts": "^0.14.0"
   },
   "devDependencies": {
     "@effect/vitest": "4.0.0-beta.85",