@phreshos/node 0.1.12 → 0.1.14

package/dist/traffic.d.ts

@@ -1,27 +1,27 @@
 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;
         questionId: string;
         message: Readonly<{
-            to: import("@phreshos/core").Server<{}, unknown> | null;
+            to: import("@phreshos/core").ServerEndpoint<{}, unknown> | null;
             payload: Payload;
         }>;
     }>>;
     protected follow<Capture>(kind: Kind, convert: (value: unknown) => Capture, subscriber: (capture: Capture) => unknown, impossible?: (error: Error) => void): Cleanup;
 }
-/** Directed traffic originating from one canonical Server. */
+/** Directed traffic originating from one canonical Server Endpoint. */
 export declare class ServerTrafficHandle<Definitions extends object = {}> extends EndpointTrafficHandle<Definitions> implements ServerTraffic<Definitions> {
     subscribeAnswers<Result = unknown>(subscriber: AnswerSubscriber<Result>): Cleanup;
     answers<Result = unknown>(options?: EventOptions): AsyncIterableIterator<Readonly<{
@@ -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,32 +25,16 @@ 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. */
+/** Directed traffic originating from one canonical Server Endpoint. */
 export class ServerTrafficHandle extends EndpointTrafficHandle {
     subscribeAnswers(subscriber) {
         return this.follow("answer", value => answer(value, this.resolveEndpoint), subscriber);

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 Program lifecycle operation until the System completes it. */
-export declare function streamProgram(path: string, 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,119 +1,115 @@
-import { connect } from "node:net";
-/** 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 Program lifecycle operation until the System completes it. */
-export function streamProgram(path, 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: "program", 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()) {
-                const event = JSON.parse(line);
-                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/uploads.d.ts

@@ -3,8 +3,10 @@ type Ask = (request: object) => Promise<unknown>;
 /** Owner-local implementation of the System's opaque upload collection. */
 export default class Uploads implements SystemUploads {
     private readonly ask;
+    private readonly lifetime;
     private accessPromise;
-    constructor(ask: Ask);
+    constructor(ask: Ask, lifetime: () => AbortSignal);
+    path(): Promise<string>;
     write(value: unknown): Promise<Upload>;
     stream(file: string): Promise<ReadableStream<Uint8Array<ArrayBufferLike>>>;
     bytes(file: string): Promise<Uint8Array<ArrayBuffer>>;
@@ -17,5 +19,6 @@ export default class Uploads implements SystemUploads {
         time: number;
     }> | null>;
     private access;
+    private active;
 }
 export {};

package/dist/uploads.js

@@ -2,17 +2,23 @@ import { isUploadFile } from "@phreshos/core";
 import { randomUUID } from "node:crypto";
 import { createReadStream, createWriteStream, mkdirSync } from "node:fs";
 import { rename, rm } from "node:fs/promises";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 /** Owner-local implementation of the System's opaque upload collection. */
 export default class Uploads {
     ask;
+    lifetime;
     accessPromise = null;
-    constructor(ask) {
+    constructor(ask, lifetime) {
         this.ask = ask;
+        this.lifetime = lifetime;
+    }
+    async path() {
+        return (await this.access()).path;
     }
     async write(value) {
+        const signal = this.active();
         const access = await this.access();
         const source = content(value);
         const identity = randomUUID();
@@ -29,7 +35,8 @@ export default class Uploads {
                         throw new Error(`The upload exceeds ${access.limit / 1024 / 1024 / 1024} GB`);
                     yield chunk;
                 }
-            }, createWriteStream(temporary, { flags: "wx" }));
+            }, createWriteStream(temporary, { flags: "wx" }), { signal });
+            signal.throwIfAborted();
             await rename(temporary, destination);
         }
         catch (error) {
@@ -42,22 +49,25 @@ export default class Uploads {
         return upload;
     }
     async stream(file) {
+        const signal = this.active();
         requireFile(file);
         const access = await this.access();
-        return Readable.toWeb(createReadStream(join(access.path, file)));
+        return Readable.toWeb(createReadStream(join(access.path, file), { signal }));
     }
     async bytes(file) { return new Uint8Array(await new Response(await this.stream(file)).arrayBuffer()); }
     async text(file) { return new Response(await this.stream(file)).text(); }
     async json(file) { return JSON.parse(await this.text(file)); }
     async stat(file) {
+        this.active();
         requireFile(file);
         return await this.ask({ capability: "uploads", operation: "stat", file });
     }
     access() {
+        this.active();
         if (!this.accessPromise) {
             const resolving = this.ask({ capability: "uploads", operation: "access" }).then(value => {
                 const access = value;
-                if (!access || typeof access.path !== "string" || typeof access.limit !== "number")
+                if (!access || typeof access.path !== "string" || !isAbsolute(access.path) || typeof access.limit !== "number")
                     throw new Error("The System returned invalid upload access");
                 return { path: access.path, limit: access.limit };
             });
@@ -70,6 +80,11 @@ export default class Uploads {
         }
         return this.accessPromise;
     }
+    active() {
+        const signal = this.lifetime();
+        signal.throwIfAborted();
+        return signal;
+    }
 }
 function requireFile(file) {
     if (!isUploadFile(file))

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.12",
+  "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.36",
+    "@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"
   },