@phreshos/node 0.1.13 → 0.1.14

package/dist/traffic.d.ts

@@ -1,15 +1,15 @@
 import type { AnswerSubscriber, AskSubscriber, Cleanup, Endpoint, EventOptions, ServerTraffic, TrafficEvents } from "@phreshos/core";
 import Events from "./events.js";
+import type SystemRepresentation from "./representation.js";
 type Kind = "publish" | "ask" | "answer";
-type Request = (value: object, signal?: AbortSignal) => Promise<unknown>;
 type ResolveEndpoint = (value: unknown) => Endpoint;
 /** Directed traffic originating from one canonical Endpoint. */
 export declare class EndpointTrafficHandle<Definitions extends object = {}> extends Events<TrafficEvents<Definitions>, never> {
-    private readonly request;
+    private readonly representation;
     private readonly process;
     private readonly endpoint;
     protected readonly resolveEndpoint: ResolveEndpoint;
-    constructor(request: Request, process: string, endpoint: "server" | "client", resolveEndpoint: ResolveEndpoint);
+    constructor(representation: SystemRepresentation, process: string, endpoint: "server" | "client", resolveEndpoint: ResolveEndpoint);
     subscribeAsks<Payload = unknown>(subscriber: AskSubscriber<Payload>): Cleanup;
     asks<Payload = unknown>(options?: EventOptions): AsyncIterableIterator<Readonly<{
         event: string;
@@ -29,7 +29,7 @@ export declare class ServerTrafficHandle<Definitions extends object = {}> extend
         questionId: string;
         message: Readonly<{
             to: Endpoint<{}, unknown> | null;
-            outcome: import("@phreshos/core").Outcome<Result>;
+            outcome: import("@phreshos/core").AnswerOutcome<Result>;
         }>;
     }>>;
 }

package/dist/traffic.js

@@ -1,21 +1,19 @@
 import Events, { stream } from "./events.js";
 /** Directed traffic originating from one canonical Endpoint. */
 export class EndpointTrafficHandle extends Events {
-    request;
+    representation;
     process;
     endpoint;
     resolveEndpoint;
-    constructor(request, process, endpoint, resolveEndpoint) {
-        super([], (event, signal, timeout) => request({
-            capability: "traffic",
-            operation: "wait",
+    constructor(representation, process, endpoint, resolveEndpoint) {
+        super([], (event, subscriber, impossible) => representation.follow({
+            scope: "traffic",
             process,
             endpoint,
             kind: "publish",
-            event,
-            timeout
-        }, signal).then(value => publication(value, resolveEndpoint, event === null)));
-        this.request = request;
+            event
+        }, (received, values) => subscriber(publication({ event: received, values }, resolveEndpoint, event === null)), impossible));
+        this.representation = representation;
         this.process = process;
         this.endpoint = endpoint;
         this.resolveEndpoint = resolveEndpoint;
@@ -27,29 +25,13 @@ export class EndpointTrafficHandle extends Events {
         return stream((subscriber, impossible) => this.follow("ask", value => question(value, this.resolveEndpoint), subscriber, impossible), options);
     }
     follow(kind, convert, subscriber, impossible) {
-        const controller = new AbortController();
-        void (async () => {
-            while (!controller.signal.aborted) {
-                try {
-                    const value = await this.request({
-                        capability: "traffic",
-                        operation: "wait",
-                        process: this.process,
-                        endpoint: this.endpoint,
-                        kind,
-                        event: null,
-                        timeout: 86_400_000
-                    }, controller.signal);
-                    subscriber(convert(value));
-                }
-                catch (error) {
-                    if (!controller.signal.aborted)
-                        impossible?.(error instanceof Error ? error : new Error(String(error)));
-                    controller.abort();
-                }
-            }
-        })();
-        return () => controller.abort();
+        return this.representation.follow({
+            scope: "traffic",
+            process: this.process,
+            endpoint: this.endpoint,
+            kind,
+            event: null
+        }, (event, values) => subscriber(convert({ event, values })), impossible);
     }
 }
 /** Directed traffic originating from one canonical Server Endpoint. */

package/dist/transport.d.ts

@@ -1,11 +1,21 @@
-import { type Socket } from "node:net";
-export interface TransportEvent {
-    event?: string;
-    [key: string]: unknown;
+/** One persistent owner-local IPC connection to the System Link Manager. */
+export declare class GatewayConnection {
+    private readonly link;
+    session: unknown;
+    private active;
+    private readonly queued;
+    private readonly subscribers;
+    private constructor();
+    static open(path: string): Promise<GatewayConnection>;
+    onDisconnect(subscriber: (error: Error) => void): () => void;
+    disconnect(): Promise<void>;
+    /** Invoke one operation exposed by the connected System Link Manager. */
+    call<Result = unknown>(event: string, ...values: unknown[]): Promise<Result>;
+    /** Observe one live event emitted by the connected System Link Manager. */
+    subscribe(event: string, subscriber: (...values: unknown[]) => unknown): () => void;
+    /** Begin delivery after the connected representation has installed its listeners. */
+    activate(): void;
+    private deliver;
 }
-/** Open and retain one owner-local System connection. */
-export declare function openConnection(path: string): Promise<Socket>;
-/** Execute one short authoritative System-control request. */
-export declare function request(path: string, target: "api" | "system", request: unknown, signal?: AbortSignal): Promise<unknown>;
-/** Stream one long-running authoritative System operation. */
-export declare function stream(path: string, target: "program", request: unknown, signal?: AbortSignal): AsyncGenerator<TransportEvent, void, unknown>;
+/** Open and authenticate one owner-local System connection. */
+export declare function openConnection(path: string): Promise<GatewayConnection>;

package/dist/transport.js

@@ -1,133 +1,115 @@
-import { connect } from "node:net";
-const maximumStreamQueue = 256;
-/** Open and retain one owner-local System connection. */
-export function openConnection(path) {
-    return new Promise((resolve, reject) => {
-        const socket = connect(path);
-        const failed = () => reject(unavailable(path));
-        socket.once("connect", () => {
-            socket.off("error", failed);
-            socket.on("error", () => undefined);
-            resolve(socket);
-        });
-        socket.once("error", failed);
-    });
-}
-/** Execute one short authoritative System-control request. */
-export function request(path, target, request, signal) {
-    return new Promise((resolve, reject) => {
-        const socket = connect(path);
-        let buffer = "";
-        let settled = false;
-        const finish = (work) => {
-            if (settled)
+import { SocketClient } from "@the-link/ipc/socket-client";
+import messagepack from "@the-link/messagepack";
+const events = {
+    ready: "/gateway/ready"
+};
+/** One persistent owner-local IPC connection to the System Link Manager. */
+export class GatewayConnection {
+    link;
+    session = null;
+    active = false;
+    queued = [];
+    subscribers = new Map();
+    constructor(link) {
+        this.link = link;
+        link.$inbound.forwardTo((event, ...values) => {
+            if (event === events.ready)
                 return;
-            settled = true;
-            signal?.removeEventListener("abort", cancel);
-            socket.destroy();
-            work();
-        };
-        const cancel = () => finish(() => reject(signal?.reason instanceof Error ? signal.reason : new Error("The request was cancelled")));
-        signal?.addEventListener("abort", cancel, { once: true });
-        socket.on("connect", () => socket.write(`${JSON.stringify({ target, request })}\n`));
-        socket.on("data", chunk => {
-            buffer += String(chunk);
-            const boundary = buffer.indexOf("\n");
-            if (boundary < 0)
-                return;
-            let outcome;
-            try {
-                outcome = JSON.parse(buffer.slice(0, boundary));
-            }
-            catch {
-                return finish(() => reject(new Error("The System returned an invalid response")));
-            }
-            if (outcome.success)
-                finish(() => resolve(outcome.result));
+            if (!this.active)
+                this.queued.push({ event, values });
             else
-                finish(() => reject(new Error(outcome.error)));
+                this.deliver(event, values);
         });
-        socket.on("error", () => finish(() => reject(unavailable(path))));
-        socket.on("close", () => finish(() => reject(new Error("The System closed the request without an answer"))));
-        if (signal?.aborted)
-            cancel();
-    });
-}
-/** Stream one long-running authoritative System operation. */
-export function stream(path, target, request, signal) {
-    const events = [];
-    let wake = null;
-    let ended = false;
-    let failure = null;
-    const socket = connect(path);
-    const cancel = () => socket.destroy(signal?.reason instanceof Error ? signal.reason : undefined);
-    if (signal?.aborted)
-        cancel();
-    else
-        signal?.addEventListener("abort", cancel, { once: true });
-    let buffer = "";
-    socket.on("connect", () => socket.write(`${JSON.stringify({ target, request })}\n`));
-    socket.on("data", chunk => {
-        buffer += String(chunk);
-        const lines = buffer.split("\n");
-        buffer = lines.pop() ?? "";
-        for (const line of lines)
-            if (line.trim()) {
-                if (events.length >= maximumStreamQueue) {
-                    failure = new Error(`System stream queue exceeded its capacity of ${maximumStreamQueue}`);
-                    socket.destroy();
-                    break;
-                }
-                let event;
-                try {
-                    event = JSON.parse(line);
-                }
-                catch {
-                    failure = new Error("The System returned an invalid stream event");
-                    socket.destroy();
-                    break;
-                }
-                if (event.event === "error")
-                    failure = new Error(String(event.message));
-                else
-                    events.push(event);
-            }
-        wake?.();
-        wake = null;
-    });
-    socket.on("error", error => {
-        failure = signal?.aborted
-            ? signal.reason instanceof Error ? signal.reason : new Error("The operation was cancelled")
-            : error;
-        wake?.();
-        wake = null;
-    });
-    socket.on("close", () => {
-        ended = true;
-        signal?.removeEventListener("abort", cancel);
-        wake?.();
-        wake = null;
-    });
-    return (async function* () {
+    }
+    static async open(path) {
+        const link = new SocketClient(path);
+        const connection = new GatewayConnection(link);
+        link.setSerialize(messagepack.serialize);
+        link.setDeserialize(messagepack.deserialize);
+        const readiness = ready(link);
         try {
-            while (true) {
-                if (events.length) {
-                    yield events.shift();
-                    continue;
-                }
-                if (failure)
-                    throw failure;
-                if (ended)
-                    return;
-                await new Promise(resolve => { wake = resolve; });
+            await link.connect();
+        }
+        catch (error) {
+            readiness.cancel();
+            await link.disconnect();
+            throw unavailable(path, error);
+        }
+        try {
+            connection.session = await readiness.promise;
+            return connection;
+        }
+        catch (error) {
+            await link.disconnect();
+            throw new Error("The System Gateway did not establish an owner session", { cause: error });
+        }
+    }
+    onDisconnect(subscriber) {
+        return this.link.$internal.subscribe("disconnect", subscriber);
+    }
+    disconnect() {
+        return this.link.disconnect();
+    }
+    /** Invoke one operation exposed by the connected System Link Manager. */
+    call(event, ...values) {
+        return this.link.$outbound.publishFirst(event, ...values);
+    }
+    /** Observe one live event emitted by the connected System Link Manager. */
+    subscribe(event, subscriber) {
+        const subscribers = this.subscribers.get(event) ?? new Set();
+        subscribers.add(subscriber);
+        this.subscribers.set(event, subscribers);
+        return () => {
+            subscribers.delete(subscriber);
+            if (!subscribers.size)
+                this.subscribers.delete(event);
+        };
+    }
+    /** Begin delivery after the connected representation has installed its listeners. */
+    activate() {
+        if (this.active)
+            return;
+        this.active = true;
+        for (const { event, values } of this.queued.splice(0))
+            this.deliver(event, values);
+    }
+    deliver(event, values) {
+        for (const subscriber of this.subscribers.get(event) ?? []) {
+            try {
+                subscriber(...values);
             }
+            catch { /* One local observer cannot break boundary delivery. */ }
         }
-        finally {
-            signal?.removeEventListener("abort", cancel);
-            socket.destroy();
+    }
+}
+function ready(link) {
+    let received = () => undefined;
+    let disconnected = () => undefined;
+    const promise = new Promise((resolve, reject) => {
+        received = link.$inbound.subscribeOnce(events.ready, value => {
+            disconnected();
+            resolve(value);
+        });
+        disconnected = link.$internal.subscribeOnce("disconnect", error => {
+            received();
+            reject(exception(error));
+        });
+    });
+    return {
+        promise,
+        cancel() {
+            received();
+            disconnected();
         }
-    })();
+    };
 }
-function unavailable(path) {
-    return new Error(`No System is listening at ${path} — start PhreshOS first`);
+function exception(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function unavailable(path, cause) {
+    return new Error(`No System is listening at ${path} — start PhreshOS first`, { cause });
+}
+/** Open and authenticate one owner-local System connection. */
+export function openConnection(path) {
+    return GatewayConnection.open(path);
 }

package/dist/websocket.d.ts

@@ -0,0 +1,2 @@
+/** Open a native WebSocket owned by one connected System lifetime. */
+export default function websocket(url: string | URL, protocols: string | string[] | undefined, signal: AbortSignal): Promise<WebSocket>;

package/dist/websocket.js

@@ -0,0 +1,15 @@
+/** Open a native WebSocket owned by one connected System lifetime. */
+export default async function websocket(url, protocols, signal) {
+    if (signal.aborted)
+        throw signal.reason;
+    const socket = protocols === undefined
+        ? new WebSocket(url)
+        : new WebSocket(url, protocols);
+    const close = () => socket.close();
+    const release = () => signal.removeEventListener("abort", close);
+    signal.addEventListener("abort", close, { once: true });
+    socket.addEventListener("close", release, { once: true });
+    if (signal.aborted)
+        close();
+    return socket;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/node",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Node.js access to PhreshOS and Program projects.",
   "type": "module",
   "main": "dist/main.js",
@@ -36,7 +36,9 @@
     "prepack": "node --run build"
   },
   "dependencies": {
-    "@phreshos/core": "^0.1.37",
+    "@phreshos/core": "^0.1.39",
+    "@the-link/ipc": "^0.2.1",
+    "@the-link/messagepack": "^0.1.0",
     "adm-zip": "^0.6.0",
     "jiti": "^2.7.0"
   },