@plurnk/plurnk-schemes-http 1.16.4 → 1.17.0

package/dist/Ws.js

@@ -22,21 +22,10 @@ class Ws {
         channels: { [MESSAGES]: "text/plain" },
         defaultChannel: MESSAGES,
         category: "data",
-        entryOwner: "worker",
-        inherit: "none",
         writableBy: ["model", "client"],
         volatile: true,
         modelVisible: true,
         glyph: "🔌",
-        example: [
-            "### READ0 (wss://api.example.com/feed)",
-            "",
-            "### EDIT0 (wss://api.example.com/feed)",
-            '{"type":"subscribe","channel":"updates"}',
-            "",
-            "### SEND0 (wss://api.example.com/feed)",
-            '{"type":"message","text":"Hello"}',
-        ].join("\n"),
         documentation,
         traits: ["web"],
     };
@@ -66,12 +55,13 @@ class Ws {
             return address;
         const { url } = address;
         const pathname = request.pathname;
-        const key = _a.#key(ctx.workerId, address);
+        const key = _a.#key(ctx.workspaceId, address);
         const existing = this.#sockets.get(key);
         if (existing !== undefined) {
-            return { status: 200, connectionState: existing.state };
+            return existing.opened ? { status: 200, connectionState: existing.state } : existing.acquisition;
         }
         const done = Promise.withResolvers();
+        const shared = Promise.withResolvers();
         const owner = {
             socket: null,
             state: "claimed",
@@ -80,241 +70,246 @@ class Ws {
             shutdownRequested: false,
             async shutdown() { },
             done: done.promise,
+            acquisition: shared.promise,
         };
         this.#sockets.set(key, owner);
-        let retained = false;
-        let settled = false;
-        try {
-            // {§ws-lifecycle} Seed the declared channel before subscription open.
-            const written = await ctx.entries.write(pathname, _a.#seedEntry());
-            if (Results.isErrorStatus(written.status))
-                return _a.#passthrough(written);
-            if (owner.shutdownRequested)
-                return _a.#cancelled(url);
-            let requestCancel = () => { owner.shutdownRequested = true; };
-            const handle = { cancel: () => requestCancel() };
-            const subscription = await ctx.subscriptions.open(pathname, handle);
-            if (owner.shutdownRequested) {
-                const cancelled = _a.#cancelled(url);
-                await subscription.close(cancelled, "WebSocket execution was cancelled.");
-                return cancelled;
-            }
-            let socket;
+        const acquire = async () => {
+            let retained = false;
+            let settled = false;
             try {
-                socket = this.#connect(url);
-            }
-            catch (err) {
-                console.error("WebSocket connection failed", { url, err });
-                const detail = `The WebSocket connection to ${url} failed.`;
-                const result = _a.#bad(502, "connect-failed", detail, {
-                    target: url,
-                    stage: "connection",
-                    retryable: true,
-                });
-                await subscription.close(result, detail);
-                return result;
-            }
-            owner.socket = socket;
-            owner.state = "connecting";
-            const acquisition = Promise.withResolvers();
-            let messages = 0;
-            let settlement = null;
-            let frameFailure = null;
-            const pending = new Set();
-            const settle = (terminal, summary, transportClose, initial = terminal) => {
-                if (settled)
-                    return settlement ?? Promise.resolve();
-                settled = true;
-                owner.state = "settling";
-                subscription.removeEventListener("abort", onAbort);
-                settlement = (async () => {
-                    const errors = [];
-                    try {
-                        await Promise.allSettled([...pending]);
-                        const failedFrame = frameFailure;
-                        const effectiveTerminal = !Results.isErrorStatus(terminal.status) && failedFrame !== null
-                            ? failedFrame.result
-                            : terminal;
-                        const effectiveSummary = !Results.isErrorStatus(terminal.status) && failedFrame !== null
-                            ? failedFrame.summary
-                            : typeof summary === "function" ? summary() : summary;
-                        if (transportClose !== undefined) {
+                // {§ws-lifecycle} Seed the declared channel before subscription open.
+                const written = await ctx.entries.write(pathname, _a.#seedEntry());
+                if (Results.isErrorStatus(written.status))
+                    return _a.#passthrough(written);
+                if (owner.shutdownRequested)
+                    return _a.#cancelled(url);
+                let requestCancel = () => { owner.shutdownRequested = true; };
+                const handle = { cancel: () => requestCancel() };
+                const subscription = await ctx.subscriptions.open(pathname, handle);
+                if (owner.shutdownRequested) {
+                    const cancelled = _a.#cancelled(url);
+                    await subscription.close(cancelled, "WebSocket execution was cancelled.");
+                    return cancelled;
+                }
+                let socket;
+                try {
+                    socket = this.#connect(url);
+                }
+                catch (err) {
+                    console.error("WebSocket connection failed", { url, err });
+                    const detail = `The WebSocket connection to ${url} failed.`;
+                    const result = _a.#bad(502, "connect-failed", detail, {
+                        target: url,
+                        stage: "connection",
+                        retryable: true,
+                    });
+                    await subscription.close(result, detail);
+                    return result;
+                }
+                owner.socket = socket;
+                owner.state = "connecting";
+                const acquisition = Promise.withResolvers();
+                let messages = 0;
+                let settlement = null;
+                let frameFailure = null;
+                const pending = new Set();
+                const settle = (terminal, summary, transportClose, initial = terminal) => {
+                    if (settled)
+                        return settlement ?? Promise.resolve();
+                    settled = true;
+                    owner.state = "settling";
+                    subscription.removeEventListener("abort", onAbort);
+                    settlement = (async () => {
+                        const errors = [];
+                        try {
+                            await Promise.allSettled([...pending]);
+                            const failedFrame = frameFailure;
+                            const effectiveTerminal = !Results.isErrorStatus(terminal.status) && failedFrame !== null
+                                ? failedFrame.result
+                                : terminal;
+                            const effectiveSummary = !Results.isErrorStatus(terminal.status) && failedFrame !== null
+                                ? failedFrame.summary
+                                : typeof summary === "function" ? summary() : summary;
+                            if (transportClose !== undefined) {
+                                try {
+                                    socket.close(transportClose.code, transportClose.reason);
+                                }
+                                catch (error) {
+                                    errors.push(error);
+                                }
+                            }
                             try {
-                                socket.close(transportClose.code, transportClose.reason);
+                                await subscription.close(effectiveTerminal, effectiveSummary);
+                                if (!owner.opened)
+                                    acquisition.resolve(initial);
                             }
                             catch (error) {
+                                if (!owner.opened)
+                                    acquisition.reject(error);
                                 errors.push(error);
                             }
                         }
-                        try {
-                            await subscription.close(effectiveTerminal, effectiveSummary);
-                            if (!owner.opened)
-                                acquisition.resolve(initial);
+                        finally {
+                            if (this.#sockets.get(key) === owner)
+                                this.#sockets.delete(key);
+                            done.resolve();
                         }
-                        catch (error) {
-                            if (!owner.opened)
-                                acquisition.reject(error);
-                            errors.push(error);
+                        if (errors.length === 1)
+                            throw errors[0];
+                        if (errors.length > 1)
+                            throw new AggregateError(errors, "WebSocket terminal cleanup failed");
+                    })();
+                    return settlement;
+                };
+                const reportCleanupFailure = (error) => {
+                    console.error("WebSocket terminal cleanup failed", { url, error });
+                };
+                const track = (task) => {
+                    pending.add(task);
+                    void task.then(() => pending.delete(task), () => pending.delete(task));
+                    return task;
+                };
+                const cancelled = () => _a.#cancelled(url);
+                requestCancel = () => {
+                    owner.shutdownRequested = true;
+                    const result = cancelled();
+                    void settle(result, "WebSocket execution was cancelled.", {
+                        code: SOCKET_CLOSE_NORMAL,
+                        reason: "cancelled",
+                    }).catch(reportCleanupFailure);
+                };
+                owner.shutdown = () => {
+                    const result = cancelled();
+                    return settle(result, () => `ws closed (${SOCKET_CLOSE_NORMAL}); ${messages} messages`, {
+                        code: SOCKET_CLOSE_NORMAL,
+                        reason: "shutdown",
+                    });
+                };
+                const onAbort = () => requestCancel();
+                subscription.addEventListener("abort", onAbort, { once: true });
+                const setChannelState = ctx.channels.setState.bind(ctx.channels);
+                const streamEvent = ctx.notify.streamEvent.bind(ctx.notify);
+                let nativeOpened = false;
+                let activation = Promise.resolve();
+                let persistenceTail = Promise.resolve();
+                socket.addEventListener("open", () => {
+                    if (owner.state !== "connecting")
+                        return;
+                    nativeOpened = true;
+                    activation = track((async () => {
+                        try {
+                            const activated = await setChannelState(pathname, MESSAGES, "active");
+                            if (Results.isErrorStatus(activated.status)) {
+                                const result = _a.#passthrough(activated);
+                                void settle(result, result.problem?.detail ?? "WebSocket channel activation failed.", { code: SOCKET_CLOSE_INTERNAL_ERROR, reason: "activation failed" }).catch(reportCleanupFailure);
+                                return;
+                            }
+                            if (owner.state !== "connecting")
+                                return;
+                            streamEvent(pathname, MESSAGES, "active", 0);
+                            owner.opened = true;
+                            owner.state = "open";
+                            acquisition.resolve({ shape: "passthrough", status: 102 });
                         }
-                    }
-                    finally {
-                        if (this.#sockets.get(key) === owner)
-                            this.#sockets.delete(key);
-                        done.resolve();
-                    }
-                    if (errors.length === 1)
-                        throw errors[0];
-                    if (errors.length > 1)
-                        throw new AggregateError(errors, "WebSocket terminal cleanup failed");
-                })();
-                return settlement;
-            };
-            const reportCleanupFailure = (error) => {
-                console.error("WebSocket terminal cleanup failed", { url, error });
-            };
-            const track = (task) => {
-                pending.add(task);
-                void task.then(() => pending.delete(task), () => pending.delete(task));
-                return task;
-            };
-            const cancelled = () => _a.#cancelled(url);
-            requestCancel = () => {
-                owner.shutdownRequested = true;
-                const result = cancelled();
-                void settle(result, "WebSocket execution was cancelled.", {
-                    code: SOCKET_CLOSE_NORMAL,
-                    reason: "cancelled",
-                }).catch(reportCleanupFailure);
-            };
-            owner.shutdown = () => {
-                const result = cancelled();
-                return settle(result, () => `ws closed (${SOCKET_CLOSE_NORMAL}); ${messages} messages`, {
-                    code: SOCKET_CLOSE_NORMAL,
-                    reason: "shutdown",
-                });
-            };
-            const onAbort = () => requestCancel();
-            subscription.addEventListener("abort", onAbort, { once: true });
-            const setChannelState = ctx.channels.setState.bind(ctx.channels);
-            const streamEvent = ctx.notify.streamEvent.bind(ctx.notify);
-            let nativeOpened = false;
-            let activation = Promise.resolve();
-            let persistenceTail = Promise.resolve();
-            socket.addEventListener("open", () => {
-                if (owner.state !== "connecting")
-                    return;
-                nativeOpened = true;
-                activation = track((async () => {
-                    try {
-                        const activated = await setChannelState(pathname, MESSAGES, "active");
-                        if (Results.isErrorStatus(activated.status)) {
-                            const result = _a.#passthrough(activated);
+                        catch (err) {
+                            console.error("WebSocket channel activation failed", { url, err });
+                            const result = _a.#bad(500, "channel-activation-failed", "The WebSocket message channel could not enter its active state.", {
+                                target: url,
+                                stage: "persistence",
+                                retryable: false,
+                            });
                             void settle(result, result.problem?.detail ?? "WebSocket channel activation failed.", { code: SOCKET_CLOSE_INTERNAL_ERROR, reason: "activation failed" }).catch(reportCleanupFailure);
-                            return;
                         }
-                        if (owner.state !== "connecting")
-                            return;
-                        streamEvent(pathname, MESSAGES, "active", 0);
-                        owner.opened = true;
-                        owner.state = "open";
-                        acquisition.resolve({ shape: "passthrough", status: 102 });
-                    }
-                    catch (err) {
-                        console.error("WebSocket channel activation failed", { url, err });
-                        const result = _a.#bad(500, "channel-activation-failed", "The WebSocket message channel could not enter its active state.", {
-                            target: url,
-                            stage: "persistence",
-                            retryable: false,
-                        });
-                        void settle(result, result.problem?.detail ?? "WebSocket channel activation failed.", { code: SOCKET_CLOSE_INTERNAL_ERROR, reason: "activation failed" }).catch(reportCleanupFailure);
-                    }
-                })());
-            }, { once: true });
-            // {§ws-lifecycle} One owner chain makes transport order independent
-            // of the subscription implementation's asynchronous scheduler.
-            socket.addEventListener("message", (event) => {
-                if (!nativeOpened || settled || frameFailure !== null)
-                    return;
-                const data = event.data;
-                const persistence = persistenceTail.then(async () => {
-                    await activation;
-                    if (!owner.opened || frameFailure !== null)
+                    })());
+                }, { once: true });
+                // {§ws-lifecycle} One owner chain makes transport order independent
+                // of the subscription implementation's asynchronous scheduler.
+                socket.addEventListener("message", (event) => {
+                    if (!nativeOpened || settled || frameFailure !== null)
                         return;
-                    if (typeof data !== "string") {
-                        const detail = "The received WebSocket frame is binary; the messages channel accepts text only.";
-                        const result = _a.#bad(415, "binary-frame-unsupported", detail, {
-                            target: url,
-                            stage: "materialization",
-                            retryable: false,
-                        });
-                        frameFailure = { result, summary: detail };
-                        void settle(result, detail, { code: SOCKET_CLOSE_UNSUPPORTED_DATA, reason: "binary unsupported" }).catch(reportCleanupFailure);
-                        return;
-                    }
-                    try {
-                        await subscription.notifyChunk(MESSAGES, data, "text/plain");
-                        messages += 1;
-                    }
-                    catch (err) {
-                        if (frameFailure !== null)
+                    const data = event.data;
+                    const persistence = persistenceTail.then(async () => {
+                        await activation;
+                        if (!owner.opened || frameFailure !== null)
                             return;
-                        console.error("WebSocket message persistence failed", { url, err });
-                        const result = _a.#bad(500, "message-persistence-failed", "The received WebSocket message could not be persisted.", {
-                            target: url,
-                            stage: "persistence",
-                            retryable: false,
-                        });
-                        const failureSummary = result.problem?.detail ?? "WebSocket message persistence failed.";
-                        frameFailure = { result, summary: failureSummary };
-                        void settle(result, failureSummary, { code: SOCKET_CLOSE_INTERNAL_ERROR, reason: "persistence failed" }).catch(reportCleanupFailure);
-                    }
-                });
-                persistenceTail = persistence;
-                void track(persistence);
-            });
-            socket.addEventListener("error", (event) => {
-                console.error("WebSocket transport failed", { url, message: event.message });
-                const detail = `The WebSocket connection to ${url} failed.`;
-                const result = _a.#bad(502, "connection-failed", detail, {
-                    target: url,
-                    stage: "connection",
-                    retryable: true,
+                        if (typeof data !== "string") {
+                            const detail = "The received WebSocket frame is binary; the messages channel accepts text only.";
+                            const result = _a.#bad(415, "binary-frame-unsupported", detail, {
+                                target: url,
+                                stage: "materialization",
+                                retryable: false,
+                            });
+                            frameFailure = { result, summary: detail };
+                            void settle(result, detail, { code: SOCKET_CLOSE_UNSUPPORTED_DATA, reason: "binary unsupported" }).catch(reportCleanupFailure);
+                            return;
+                        }
+                        try {
+                            await subscription.notifyChunk(MESSAGES, data, "text/plain");
+                            messages += 1;
+                        }
+                        catch (err) {
+                            if (frameFailure !== null)
+                                return;
+                            console.error("WebSocket message persistence failed", { url, err });
+                            const result = _a.#bad(500, "message-persistence-failed", "The received WebSocket message could not be persisted.", {
+                                target: url,
+                                stage: "persistence",
+                                retryable: false,
+                            });
+                            const failureSummary = result.problem?.detail ?? "WebSocket message persistence failed.";
+                            frameFailure = { result, summary: failureSummary };
+                            void settle(result, failureSummary, { code: SOCKET_CLOSE_INTERNAL_ERROR, reason: "persistence failed" }).catch(reportCleanupFailure);
+                        }
+                    });
+                    persistenceTail = persistence;
+                    void track(persistence);
                 });
-                void settle(result, detail, {
-                    code: SOCKET_CLOSE_INTERNAL_ERROR,
-                    reason: "transport failed",
-                }).catch(reportCleanupFailure);
-            });
-            socket.addEventListener("close", (event) => {
-                if (!owner.opened && !owner.killRequested && !subscription.aborted) {
-                    const detail = `The WebSocket connection to ${url} closed before it opened.`;
+                socket.addEventListener("error", (event) => {
+                    console.error("WebSocket transport failed", { url, message: event.message });
+                    const detail = `The WebSocket connection to ${url} failed.`;
                     const result = _a.#bad(502, "connection-failed", detail, {
                         target: url,
                         stage: "connection",
                         retryable: true,
                     });
-                    void settle(result, detail).catch(reportCleanupFailure);
-                    return;
+                    void settle(result, detail, {
+                        code: SOCKET_CLOSE_INTERNAL_ERROR,
+                        reason: "transport failed",
+                    }).catch(reportCleanupFailure);
+                });
+                socket.addEventListener("close", (event) => {
+                    if (!owner.opened && !owner.killRequested && !subscription.aborted) {
+                        const detail = `The WebSocket connection to ${url} closed before it opened.`;
+                        const result = _a.#bad(502, "connection-failed", detail, {
+                            target: url,
+                            stage: "connection",
+                            retryable: true,
+                        });
+                        void settle(result, detail).catch(reportCleanupFailure);
+                        return;
+                    }
+                    const summary = () => `ws closed (${event.code ?? 0}); ${messages} messages`;
+                    const initial = subscription.aborted ? cancelled() : { shape: "passthrough", status: 102 };
+                    const terminal = subscription.aborted ? initial : { shape: "passthrough", status: 200 };
+                    void settle(terminal, summary, undefined, initial).catch(reportCleanupFailure);
+                });
+                if (owner.shutdownRequested || subscription.aborted)
+                    requestCancel();
+                const result = await acquisition.promise;
+                if (owner.opened && result.status === 102)
+                    retained = true;
+                return result;
+            }
+            finally {
+                if (!retained && !settled) {
+                    if (this.#sockets.get(key) === owner)
+                        this.#sockets.delete(key);
+                    done.resolve();
                 }
-                const summary = () => `ws closed (${event.code ?? 0}); ${messages} messages`;
-                const initial = subscription.aborted ? cancelled() : { shape: "passthrough", status: 102 };
-                const terminal = subscription.aborted ? initial : { shape: "passthrough", status: 200 };
-                void settle(terminal, summary, undefined, initial).catch(reportCleanupFailure);
-            });
-            if (owner.shutdownRequested || subscription.aborted)
-                requestCancel();
-            const result = await acquisition.promise;
-            if (owner.opened && result.status === 102)
-                retained = true;
-            return result;
-        }
-        finally {
-            if (!retained && !settled) {
-                if (this.#sockets.get(key) === owner)
-                    this.#sockets.delete(key);
-                done.resolve();
             }
-        }
+        };
+        void acquire().then(shared.resolve, shared.reject);
+        return shared.promise;
     }
     async close() {
         const owners = [...this.#sockets.values()];
@@ -370,7 +365,7 @@ class Ws {
         }
         return this.#write(statement.target, statement.body ?? "", ctx, "EDIT");
     }
-    // A disposition label never reaches the scheme ({§send-label}); a KILL closes the owner.
+    // {§turn-disposition} — SEND is messaging; a KILL closes the owner.
     async send(statement, ctx) {
         if (statement.metadata !== null)
             return _a.#metadataUnsupported();
@@ -381,20 +376,13 @@ class Ws {
                 retryable: false,
             });
         }
-        const status = statement.status;
-        if (status === null)
-            return this.#write(statement.target, statement.body?.raw ?? "", ctx, "SEND");
-        return _a.#bad(501, "send-status-unsupported", `The WebSocket scheme does not interpret SEND status ${status}.`, {
-            requestedStatus: status,
-            stage: "dispatch",
-            retryable: false,
-        });
+        return this.#write(statement.target, statement.body?.raw ?? "", ctx, "SEND");
     }
     async #write(target, body, ctx, operation) {
         const address = _a.#address(target);
         if (!(address instanceof NetworkAddress))
             return address;
-        const owner = this.#sockets.get(_a.#key(ctx.workerId, address));
+        const owner = this.#sockets.get(_a.#key(ctx.workspaceId, address));
         if (owner === undefined) {
             return _a.#bad(409, "no-open-socket", `No WebSocket connection is open for ${address.url}.`, {
                 target: address.url,
@@ -448,7 +436,7 @@ class Ws {
         const address = _a.#address(statement.target);
         if (!(address instanceof NetworkAddress))
             return address;
-        const owner = this.#sockets.get(_a.#key(ctx.workerId, address));
+        const owner = this.#sockets.get(_a.#key(ctx.workspaceId, address));
         if (owner === undefined) {
             return _a.#bad(404, "no-open-socket", `No WebSocket connection is open for ${address.url}.`, {
                 target: address.url,
@@ -473,7 +461,7 @@ class Ws {
             return { shape: "passthrough", status: 200 };
         }
         catch (err) {
-            if (this.#sockets.get(_a.#key(ctx.workerId, address)) === owner) {
+            if (this.#sockets.get(_a.#key(ctx.workspaceId, address)) === owner) {
                 owner.killRequested = false;
                 owner.state = priorState;
             }
@@ -485,10 +473,9 @@ class Ws {
             });
         }
     }
-    // The durable entry is Worker-owned ({§manifest-entry-owner}); the live handle
-    // shares that principal, and a Worker id already determines its workspace.
-    static #key(workerId, address) {
-        return `${workerId}:${address.scheme}:${address.pathname}`;
+    // {§runtime-resource-binding}: all workspace callers address the same live connection.
+    static #key(workspaceId, address) {
+        return `${workspaceId}:${address.url}`;
     }
     static #address(target) {
         let address;