@phreshos/node 0.1.0 → 0.1.2

package/dist/system.js

@@ -1,33 +1,92 @@
-import { ClientServiceHandler as CoreClientServiceHandler, ServerServiceHandler as CoreServerServiceHandler } from "@phreshos/core";
+import { Client as CoreClient, ClientServiceHandler as CoreClientServiceHandler, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, ServerServiceHandler as CoreServerServiceHandler } from "@phreshos/core";
 import { homedir } from "node:os";
+import { gatewayAddress } from "./address.js";
 import Events from "./events.js";
+import HandleRegistry from "./handle-registry.js";
+import { resolveHome } from "./home.js";
 import { filesystemStorage } from "./storage.js";
+import { openConnection, request, streamProgram } from "./transport.js";
 import Uploads from "./uploads.js";
-/** Build the exact shared System contract over an owner-local Gateway transport. */
-export function gatewaySystem(transport) {
-    return new GatewaySystem(transport);
-}
-class GatewaySystem {
-    transport;
+const ProgramBase = CoreProgram;
+const ProcessBase = CoreProcess;
+const ServerBase = CoreServer;
+const ClientBase = CoreClient;
+/** One connected owner-local implementation of the shared System contract. */
+export class System {
+    connection;
+    home;
+    address;
     storage = filesystemStorage(homedir(), "the native home directory");
     appearance;
     program;
     process;
     uploads;
-    constructor(transport) {
-        this.transport = transport;
-        this.appearance = new GatewayAppearance(transport);
+    transport;
+    closed = false;
+    lifetime = new AbortController();
+    handles = new HandleRegistry();
+    constructor(home, address, connection) {
+        this.connection = connection;
+        this.home = home;
+        this.address = address;
+        this.transport = {
+            control: (value, signal) => request(address, "system", value, this.signal(signal)),
+            api: (value, signal) => request(address, "api", value, this.signal(signal)),
+            lifecycle: (value, signal) => streamProgram(address, value, this.signal(signal))
+        };
+        this.appearance = new SystemAppearance(this.transport);
         this.program = new ProgramRegistry(this);
         this.process = new ProcessRegistry(this);
-        this.uploads = new Uploads(request => transport.api(request));
+        this.uploads = new Uploads(value => this.transport.api(value));
+    }
+    /** Connect to the System selected by argument, environment, or owner default. */
+    static async connect(home) {
+        const resolved = resolveHome(home);
+        const address = gatewayAddress(resolved);
+        return new System(resolved, address, await openConnection(address));
+    }
+    /** Atomically replace one runtime Program without touching its installed form. */
+    async forceCreateProgram(source) {
+        this.requireConnected();
+        for await (const event of this.transport.lifecycle({ word: "force-create", program: source })) {
+            if (event.event === "created")
+                return this.programHandle(required(event.program));
+        }
+        throw new Error("The System did not confirm the created Program");
+    }
+    /** Close this owner connection and abort every attached operation it owns. */
+    async disconnect() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.lifetime.abort(new Error("This System connection is closed"));
+        this.connection.destroy();
+        this.handles.clear();
     }
     service(key) {
+        this.requireConnected();
         return key.endpoint === "server"
             ? new ServerService(this, key)
             : new ClientService(this, key);
     }
+    programHandle(snapshot) {
+        const handle = this.handles.obtain(`program:${snapshot.reference}`, () => new ProgramHandle(this, snapshot));
+        handle.update(snapshot);
+        return handle;
+    }
+    processHandle(snapshot) {
+        return this.handles.obtain(`process:${snapshot.reference}`, () => new ProcessHandle(this, snapshot));
+    }
+    signal(signal) {
+        this.requireConnected();
+        return signal ? AbortSignal.any([signal, this.lifetime.signal]) : this.lifetime.signal;
+    }
+    requireConnected() {
+        if (this.closed)
+            throw new Error("This System connection is closed");
+    }
 }
-class GatewayAppearance extends Events {
+class SystemAppearance extends Events {
     transport;
     constructor(transport) {
         super(["change"], (_event, signal) => transport.api({ capability: "appearance", operation: "wait" }, signal));
@@ -56,7 +115,7 @@ class ProgramRegistry extends Events {
                 operation: "list",
                 input: { installedOnly: onlyInstalled, limit: 100, offset }
             });
-            programs.push(...page.data.map(snapshot => new ProgramHandle(this.system, snapshot)));
+            programs.push(...page.data.map(snapshot => this.system.programHandle(snapshot)));
             offset += page.data.length;
             if (!page.truncated || !page.data.length)
                 return programs;
@@ -65,7 +124,7 @@ class ProgramRegistry extends Events {
     async find(identity) {
         try {
             const snapshot = await this.system.transport.control({ capability: "program", operation: "inspect", input: { program: identity } });
-            return new ProgramHandle(this.system, snapshot);
+            return this.system.programHandle(snapshot);
         }
         catch (error) {
             if (unknown(error, "Program"))
@@ -74,57 +133,61 @@ class ProgramRegistry extends Events {
         }
     }
     async create(source) {
-        let identity = null;
         for await (const event of this.system.transport.lifecycle({ word: "create", program: source })) {
             if (event.event === "created")
-                identity = String(event.identity);
+                return this.system.programHandle(required(event.program));
         }
-        if (!identity)
-            throw new Error("The System did not confirm the created Program");
-        const program = await this.find(identity);
-        if (!program)
-            throw new Error("The created Program cannot be found");
-        return program;
+        throw new Error("The System did not confirm the created Program");
     }
     async event(value) {
         const waited = value;
         if (waited.event === "uninstall") {
             const payload = waited.payload;
-            return { program: new ProgramHandle(this.system, required(payload.program)), everythingRemoved: payload.everythingRemoved === true };
+            return { program: this.system.programHandle(required(payload.program)), everythingRemoved: payload.everythingRemoved === true };
         }
-        return new ProgramHandle(this.system, required(waited.payload));
+        return this.system.programHandle(required(waited.payload));
     }
 }
-class ProgramHandle extends Events {
+class ProgramHandle extends ProgramBase {
     system;
+    reference;
     identity;
-    name;
-    version;
-    description;
-    hasAgent;
-    server;
-    client;
     process;
+    startup;
+    snapshot;
     constructor(system, snapshot) {
-        super(["forget", "uninstall"], (event, signal, timeout) => system.transport.control({
-            capability: "program", operation: "wait", input: { program: snapshot.identity, event, timeout }
-        }, signal).then(value => value.payload));
+        super();
         this.system = system;
+        this.snapshot = snapshot;
+        bindEvents(this, new Events(["forget", "uninstall"], (event, signal, timeout) => system.transport.control({
+            capability: "program", operation: "wait", input: { program: snapshot.identity, event, timeout }
+        }, signal).then(value => value.payload)));
+        this.reference = snapshot.reference;
         this.identity = snapshot.identity;
-        this.name = snapshot.name;
-        this.version = snapshot.version;
-        this.description = snapshot.description;
-        this.hasAgent = snapshot.hasAgent;
-        this.server = snapshot.server ? Object.freeze({ start: snapshot.server.start }) : null;
-        this.client = snapshot.client ? Object.freeze({
-            start: snapshot.client.start,
-            title: snapshot.client.title,
-            size: snapshot.client.size,
-            position: snapshot.client.position,
-            layer: snapshot.client.layer,
-            minimize: snapshot.client.minimize
-        }) : null;
         this.process = new ProgramProcesses(system, this);
+        this.startup = new ProgramStartup(system, this);
+    }
+    get name() { return this.snapshot.name; }
+    get version() { return this.snapshot.version; }
+    get description() { return this.snapshot.description; }
+    get hasAgent() { return this.snapshot.hasAgent; }
+    get server() {
+        return this.snapshot.server ? Object.freeze({ start: this.snapshot.server.start }) : null;
+    }
+    get client() {
+        return this.snapshot.client ? Object.freeze({
+            start: this.snapshot.client.start,
+            title: this.snapshot.client.title,
+            size: this.snapshot.client.size,
+            position: this.snapshot.client.position,
+            layer: this.snapshot.client.layer,
+            minimize: this.snapshot.client.minimize
+        }) : null;
+    }
+    update(snapshot) {
+        if (snapshot.reference !== this.reference)
+            throw new Error("A Program handle cannot become another Program");
+        this.snapshot = snapshot;
     }
     async agent() {
         if (!this.hasAgent)
@@ -133,15 +196,49 @@ class ProgramHandle extends Events {
         return typeof value.content === "string" ? value.content : null;
     }
     async installed() {
-        const value = await this.system.transport.control({ capability: "program", operation: "inspect", input: { program: this.identity } });
-        if (typeof value.installed !== "boolean")
-            throw new Error("The System returned no Program installation state");
-        return value.installed;
+        for await (const event of this.system.transport.lifecycle({ word: "installed", handle: this.address() })) {
+            if (event.event === "installedState")
+                return event.installed === true;
+        }
+        throw new Error("The System returned no Program installation state");
     }
-    install() { return command(this.system, { word: "install-existing", identity: this.identity }); }
-    uninstall(everything = false) { return command(this.system, { word: "uninstall-existing", identity: this.identity, everything }); }
+    install() { return command(this.system, { word: "install-existing", handle: this.address() }); }
+    uninstall(everything = false) { return command(this.system, { word: "uninstall-existing", handle: this.address(), everything }); }
     async forget() {
-        for await (const _event of this.system.transport.lifecycle({ word: "forget", identity: this.identity })) { /* consume completion */ }
+        for await (const _event of this.system.transport.lifecycle({ word: "forget", handle: this.address() })) { /* consume completion */ }
+    }
+    address() { return Object.freeze({ identity: this.identity, reference: this.reference }); }
+}
+class ProgramStartup {
+    system;
+    program;
+    constructor(system, program) {
+        this.system = system;
+        this.program = program;
+    }
+    async get() {
+        for await (const event of this.system.transport.lifecycle({
+            word: "startup", handle: this.program.address(), operation: "get"
+        })) {
+            if (event.event === "startup")
+                return event.launch;
+        }
+        throw new Error("The System returned no Program startup state");
+    }
+    async enable(launch = {}) {
+        await this.change("enable", launch);
+    }
+    async disable() {
+        await this.change("disable");
+    }
+    async change(operation, launch) {
+        for await (const event of this.system.transport.lifecycle({
+            word: "startup", handle: this.program.address(), operation, launch
+        })) {
+            if (event.event === "startup")
+                return;
+        }
+        throw new Error("The System did not confirm the Program startup change");
     }
 }
 class ProgramProcesses extends Events {
@@ -161,13 +258,62 @@ class ProgramProcesses extends Events {
         const found = (await this.list()).find(process => process.identity === identityOrName || process.name === identityOrName);
         return found ?? null;
     }
-    create(launch = {}) { return createProcess(this.system, "create", this.program.identity, launch); }
-    findOrCreate(launch) { return createProcess(this.system, "findOrCreate", this.program.identity, launch); }
+    create(launch = {}) { return this.createExact("create-process", launch); }
+    async *run(launch = {}, options = {}) {
+        let process = null;
+        for await (const event of this.system.transport.lifecycle({
+            word: "run-process",
+            handle: this.program.address(),
+            launch
+        }, options.signal)) {
+            if (event.event === "started") {
+                process = this.system.processHandle(required(event.process));
+                yield Object.freeze({ event: "started", process });
+            }
+            else if (event.event === "output") {
+                if ((event.stream !== "stdout" && event.stream !== "stderr") || typeof event.text !== "string") {
+                    throw new Error("The System returned an invalid Process output event");
+                }
+                yield Object.freeze({
+                    event: "output",
+                    stream: event.stream,
+                    text: event.text
+                });
+            }
+            else if (event.event === "exited") {
+                if (!process)
+                    throw new Error("The System ended a Process before confirming its start");
+                const value = event.exit;
+                if (!value
+                    || (value.status !== "exited" && value.status !== "signaled")
+                    || (value.code !== null && typeof value.code !== "number")
+                    || (value.signal !== null && typeof value.signal !== "string")) {
+                    throw new Error("The System returned an invalid Process exit event");
+                }
+                const exit = Object.freeze({
+                    status: value.status,
+                    code: value.code,
+                    signal: value.signal
+                });
+                yield Object.freeze({ event: "exited", process, exit });
+            }
+            else
+                throw new Error("The System returned an unknown Process run event");
+        }
+    }
+    findOrCreate(launch) { return this.createExact("find-or-create-process", launch); }
     async exitAll() {
         const processes = await this.list();
         await Promise.all(processes.map(process => process.exit()));
         return processes.map(process => process.identity);
     }
+    async createExact(word, launch) {
+        for await (const event of this.system.transport.lifecycle({ word, handle: this.program.address(), launch })) {
+            if (event.event === "createdProcess")
+                return this.system.processHandle(required(event.process));
+        }
+        throw new Error("The System did not confirm the created Process");
+    }
 }
 class ProcessRegistry extends Events {
     system;
@@ -181,7 +327,7 @@ class ProcessRegistry extends Events {
     async find(identity) {
         try {
             const snapshot = await this.system.transport.control({ capability: "process", operation: "inspect", input: { process: identity } });
-            return new ProcessHandle(this.system, snapshot);
+            return this.system.processHandle(snapshot);
         }
         catch (error) {
             if (unknown(error, "Process"))
@@ -190,7 +336,7 @@ class ProcessRegistry extends Events {
         }
     }
 }
-class ProcessHandle extends Events {
+class ProcessHandle extends ProcessBase {
     system;
     snapshot;
     identity;
@@ -199,26 +345,28 @@ class ProcessHandle extends Events {
     server;
     client;
     constructor(system, snapshot) {
-        super(["endpointStart", "endpointStop", "exit"], (event, signal, timeout) => system.transport.control({
-            capability: "process", operation: "wait", input: { process: snapshot.identity, event, timeout }
-        }, signal).then(value => processEvent(system, value)));
+        super();
         this.system = system;
         this.snapshot = snapshot;
+        bindEvents(this, new Events(["endpointStart", "endpointStop", "exit"], (event, signal, timeout) => system.transport.control({
+            capability: "process", operation: "wait", input: { process: snapshot.identity, event, timeout }
+        }, signal).then(value => processEvent(system, value))));
         this.identity = snapshot.identity;
         this.name = snapshot.name;
         this.startedAt = new Date(snapshot.startedAt);
         this.server = new ServerEndpoint(system, this);
         this.client = new ClientEndpoint(system, this);
     }
-    program() { return new ProgramHandle(this.system, required(this.snapshot.programSnapshot, this.snapshot.program)); }
+    program() { return this.system.programHandle(required(this.snapshot.programSnapshot, this.snapshot.program)); }
     async exit() {
         await this.system.transport.control({ capability: "process", operation: "exit", input: { process: this.identity } });
     }
     async exited() { return await this.system.process.find(this.identity) === null; }
 }
-class EndpointHandle extends Events {
+class EndpointOperations extends Events {
     system;
     owner;
+    endpoint;
     constructor(system, owner, endpoint) {
         super([], (event, signal, timeout) => event === null
             ? system.transport.api({ capability: "endpoint", operation: "wait", process: owner.identity, endpoint, event, timeout }, signal)
@@ -227,13 +375,14 @@ class EndpointHandle extends Events {
             }, signal).then(value => value.payload));
         this.system = system;
         this.owner = owner;
+        this.endpoint = endpoint;
     }
     process() { return Promise.resolve(this.owner); }
     async exists() {
         const value = await this.inspect();
         return value.running;
     }
-    async start() { await this.operation("start"); }
+    async start(client) { await this.operation("start", client); }
     async stop() { await this.operation("stop"); }
     async service() {
         const key = await this.system.transport.api({ capability: "endpoint", operation: "service", process: this.owner.identity, endpoint: this.endpoint });
@@ -255,9 +404,23 @@ class EndpointHandle extends Events {
             } });
     }
 }
-class ServerEndpoint extends EndpointHandle {
+class ServerEndpoint extends ServerBase {
+    system;
+    owner;
     endpoint = "server";
-    constructor(system, owner) { super(system, owner, "server"); }
+    base;
+    constructor(system, owner) {
+        super();
+        this.system = system;
+        this.owner = owner;
+        this.base = new EndpointOperations(system, owner, "server");
+        bindEvents(this, this.base);
+    }
+    process() { return this.base.process(); }
+    exists() { return this.base.exists(); }
+    start() { return this.base.start(); }
+    stop() { return this.base.stop(); }
+    publish(event, payload) { return this.base.publish(event, payload); }
     async ask(event, payload) {
         return await this.system.transport.control({ capability: "endpoint", operation: "ask", input: {
                 process: this.owner.identity, endpoint: "server", event, payload
@@ -272,22 +435,29 @@ class ServerEndpoint extends EndpointHandle {
         await this.system.transport.control({ capability: "endpoint", operation: "waitReady", input: { process: this.owner.identity, endpoint: "server", timeout } });
     }
     async service() {
-        return await super.service();
+        return await this.base.service();
     }
 }
-class ClientEndpoint extends EndpointHandle {
+class ClientEndpoint extends ClientBase {
     endpoint = "client";
     window;
+    base;
     constructor(system, owner) {
-        super(system, owner, "client");
-        this.window = new GatewayWindow(system, owner);
-    }
-    async start(overrides) { await this.operation("start", overrides); }
+        super();
+        this.base = new EndpointOperations(system, owner, "client");
+        bindEvents(this, this.base);
+        this.window = new SystemWindow(system, owner);
+    }
+    process() { return this.base.process(); }
+    exists() { return this.base.exists(); }
+    start(overrides) { return this.base.start(overrides); }
+    stop() { return this.base.stop(); }
+    publish(event, payload) { return this.base.publish(event, payload); }
     async service() {
-        return await super.service();
+        return await this.base.service();
     }
 }
-class GatewayWindow extends Events {
+class SystemWindow extends Events {
     system;
     process;
     constructor(system, process) {
@@ -387,16 +557,12 @@ async function listProcesses(system, program) {
     let offset = 0;
     while (true) {
         const page = await system.transport.control({ capability: "process", operation: "list", input: { program, limit: 100, offset } });
-        processes.push(...page.data.map(snapshot => new ProcessHandle(system, snapshot)));
+        processes.push(...page.data.map(snapshot => system.processHandle(snapshot)));
         offset += page.data.length;
         if (!page.truncated || !page.data.length)
             return processes;
     }
 }
-async function createProcess(system, operation, program, launch) {
-    const snapshot = await system.transport.control({ capability: "process", operation, input: { program, launch } });
-    return new ProcessHandle(system, snapshot);
-}
 async function* command(system, request) {
     for await (const event of system.transport.lifecycle(request)) {
         if (event.event === "output")
@@ -411,19 +577,22 @@ function processEvent(system, value) {
     const payload = waited.payload;
     if (waited.event === "exit" && payload)
         return {
-            process: new ProcessHandle(system, required(payload.processSnapshot, String(payload.process ?? ""))),
+            process: system.processHandle(required(payload.processSnapshot, String(payload.process ?? ""))),
             status: payload.status,
             code: payload.code,
             signal: payload.signal
         };
     if ((waited.event === "endpointStart" || waited.event === "endpointStop") && payload?.processSnapshot) {
-        const process = new ProcessHandle(system, payload.processSnapshot);
+        const process = system.processHandle(payload.processSnapshot);
         return payload.endpoint === "client" ? process.client : process.server;
     }
     if (payload && typeof payload.identity === "string")
-        return new ProcessHandle(system, payload);
+        return system.processHandle(payload);
     return payload;
 }
+function bindEvents(target, events) {
+    Object.assign(target, eventsOf(events));
+}
 function eventsOf(events) {
     return {
         subscribe: events.subscribe,
@@ -439,3 +608,8 @@ function required(value, identity = "") {
         return value;
     throw new Error(`The System returned no ${identity ? `${identity} ` : ""}snapshot`);
 }
+export const Program = CoreProgram;
+export const Process = CoreProcess;
+export const Endpoint = CoreEndpoint;
+export const Server = CoreServer;
+export const Client = CoreClient;

package/dist/transport.d.ts

@@ -1,11 +1,11 @@
 import { type Socket } from "node:net";
-export interface GatewayEvent {
+export interface TransportEvent {
     event?: string;
     [key: string]: unknown;
 }
-/** Open and retain one owner-local Gateway connection. */
+/** 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<GatewayEvent, void, unknown>;
+export declare function streamProgram(path: string, request: unknown, signal?: AbortSignal): AsyncGenerator<TransportEvent, void, unknown>;

package/dist/transport.js

@@ -1,5 +1,5 @@
 import { connect } from "node:net";
-/** Open and retain one owner-local Gateway connection. */
+/** Open and retain one owner-local System connection. */
 export function openConnection(path) {
     return new Promise((resolve, reject) => {
         const socket = connect(path);
@@ -39,7 +39,7 @@ export function request(path, target, request, signal) {
                 outcome = JSON.parse(buffer.slice(0, boundary));
             }
             catch {
-                return finish(() => reject(new Error("The System returned an invalid Gateway response")));
+                return finish(() => reject(new Error("The System returned an invalid response")));
             }
             if (outcome.success)
                 finish(() => resolve(outcome.result));
@@ -47,7 +47,7 @@ export function request(path, target, request, signal) {
                 finish(() => reject(new Error(outcome.error)));
         });
         socket.on("error", () => finish(() => reject(unavailable(path))));
-        socket.on("close", () => finish(() => reject(new Error("The System closed the Gateway request without an answer"))));
+        socket.on("close", () => finish(() => reject(new Error("The System closed the request without an answer"))));
         if (signal?.aborted)
             cancel();
     });
@@ -95,19 +95,25 @@ export function streamProgram(path, request, signal) {
         wake = null;
     });
     return (async function* () {
-        while (true) {
-            if (events.length) {
-                yield events.shift();
-                continue;
+        try {
+            while (true) {
+                if (events.length) {
+                    yield events.shift();
+                    continue;
+                }
+                if (failure)
+                    throw failure;
+                if (ended)
+                    return;
+                await new Promise(resolve => { wake = resolve; });
             }
-            if (failure)
-                throw failure;
-            if (ended)
-                return;
-            await new Promise(resolve => { wake = resolve; });
+        }
+        finally {
+            signal?.removeEventListener("abort", cancel);
+            socket.destroy();
         }
     })();
 }
 function unavailable(path) {
-    return new Error(`No System Gateway is listening at ${path} — start PhreshOS first`);
+    return new Error(`No System is listening at ${path} — start PhreshOS first`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/node",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Node.js access to PhreshOS and Program projects.",
   "type": "module",
   "main": "dist/main.js",
@@ -32,7 +32,7 @@
     "prepack": "node --run build"
   },
   "dependencies": {
-    "@phreshos/core": "^0.1.21",
+    "@phreshos/core": "^0.1.23",
     "adm-zip": "^0.6.0",
     "jiti": "^2.7.0"
   },

package/dist/client-development.d.ts

@@ -1,29 +0,0 @@
-import type { ClientDevelopment } from "@phreshos/core";
-import type { GatewayEvent } from "./transport.js";
-/** One client development server owned by a Gateway development run. */
-export declare class DevelopmentClient {
-    private readonly child;
-    private readonly output;
-    private stopped;
-    private result;
-    private outputWaiter;
-    private readonly completion;
-    constructor(command: string, directory: string);
-    drain(): GatewayEvent[];
-    exited(): Promise<CommandExit>;
-    exitResult(): CommandExit | null;
-    outputAvailable(): Promise<void>;
-    stop(): Promise<void>;
-    endingWasRequested(): boolean;
-    private push;
-}
-/** Refuse to claim a URL already served by an unrelated process. */
-export declare function assertAvailable(url: string): Promise<void>;
-/** Wait until a development Client can be loaded by a sandboxed Program iframe. */
-export declare function waitForDevelopmentClient(config: ClientDevelopment, client?: DevelopmentClient, signal?: AbortSignal): AsyncGenerator<GatewayEvent, void, unknown>;
-export declare function commandFailure(exit: CommandExit): Error;
-export interface CommandExit {
-    code: number | null;
-    signal: NodeJS.Signals | null;
-    error: Error | null;
-}