@phreshos/node 0.1.7 → 0.1.8

package/dist/events.d.ts

@@ -1,5 +1,7 @@
-import type { Subscribable } from "@phreshos/core";
+import type { Cleanup, EventOptions, Subscribable } from "@phreshos/core";
 type Wait = (event: string | null, signal: AbortSignal, timeout?: number) => Promise<unknown>;
+type Failure = (error: Error) => void;
+type Register<Message> = (subscriber: (message: Message) => unknown, impossible?: Failure) => Cleanup;
 /** Adapts authoritative one-event waits into the shared Subscribable contract. */
 export default class Events<Definitions extends object, Fallback = never> {
     private readonly names;
@@ -10,4 +12,5 @@ export default class Events<Definitions extends object, Fallback = never> {
     readonly events: Subscribable<Definitions, Fallback>["events"];
     private listen;
 }
+export declare function stream<Message>(register: Register<Message>, options?: EventOptions): AsyncIterableIterator<Message>;
 export {};

package/dist/events.js

@@ -57,7 +57,7 @@ export default class Events {
         return () => controller.abort();
     }
 }
-function stream(register, options = {}) {
+export function stream(register, options = {}) {
     const capacity = options.capacity ?? 64;
     if (capacity !== Infinity && (!Number.isInteger(capacity) || capacity < 0)) {
         throw new Error("An event queue capacity must be a non-negative integer or Infinity");

package/dist/program-resources.d.ts

@@ -0,0 +1,7 @@
+import type { ProgramSql, ProgramStore } from "@phreshos/core";
+type Request = (value: object) => Promise<unknown>;
+/** Program-owned key-value storage carried through the owner-local Gateway. */
+export declare function programStore(request: Request, program: string): ProgramStore;
+/** Program-owned SQL capability carried through the owner-local Gateway. */
+export declare function programSql(request: Request, program: string, database: "database" | "logs"): ProgramSql;
+export {};

package/dist/program-resources.js

@@ -0,0 +1,33 @@
+/** Program-owned key-value storage carried through the owner-local Gateway. */
+export function programStore(request, program) {
+    const operate = (storeOperation, key, value, ttl) => request({
+        capability: "program",
+        operation: "store",
+        program,
+        storeOperation,
+        key,
+        value,
+        ttl
+    });
+    return {
+        get: (key) => operate("get", key),
+        set: (key, value, ttl) => operate("set", key, value, ttl),
+        delete: (key) => operate("delete", key),
+        has: (key) => operate("has", key),
+        clear: () => operate("clear")
+    };
+}
+/** Program-owned SQL capability carried through the owner-local Gateway. */
+export function programSql(request, program, database) {
+    return {
+        query(statement, ...rest) {
+            const [text, values] = written(statement, rest);
+            return request({ capability: "program", operation: "query", program, database, statement: text, values });
+        }
+    };
+}
+function written(statement, rest) {
+    if (typeof statement === "string")
+        return [statement, Array.isArray(rest[0]) ? rest[0] : []];
+    return [statement.raw.join("?"), rest];
+}

package/dist/storage.d.ts

@@ -1,3 +1,3 @@
 import type { Storage } from "@phreshos/core";
-/** Create one filesystem implementation bounded beneath an absolute root. */
-export declare function filesystemStorage(root: string, label: string): Storage;
+/** Create one filesystem implementation bounded beneath a resolved absolute root. */
+export declare function filesystemStorage(source: string | (() => Promise<string>), label: string): Storage;

package/dist/storage.js

@@ -4,13 +4,21 @@ import { rm } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, sep } from "node:path";
 import { Readable } from "node:stream";
 import { pipeline } from "node:stream/promises";
-/** Create one filesystem implementation bounded beneath an absolute root. */
-export function filesystemStorage(root, label) {
-    if (!isAbsolute(root))
-        throw new Error("A Storage root must be absolute");
-    const resolve = (...parts) => contained(root, parts);
+/** Create one filesystem implementation bounded beneath a resolved absolute root. */
+export function filesystemStorage(source, label) {
+    let root = null;
+    const resolveRoot = () => {
+        if (!root)
+            root = Promise.resolve(typeof source === "string" ? source : source()).then(value => {
+                if (!isAbsolute(value))
+                    throw new Error("A Storage root must be absolute");
+                return value;
+            });
+        return root;
+    };
+    const resolve = async (...parts) => contained(await resolveRoot(), parts);
     async function stream(...parts) {
-        const destination = resolve(...parts);
+        const destination = await resolve(...parts);
         const found = describe(destination);
         if (!found)
             throw new Error(`There is no ${parts.join("/")} in ${label}`);
@@ -20,7 +28,7 @@ export function filesystemStorage(root, label) {
     }
     async function write(...args) {
         const parts = args.slice(0, -1);
-        const destination = resolve(...parts);
+        const destination = await resolve(...parts);
         const temporary = join(dirname(destination), `.${randomUUID()}.writing`);
         mkdirSync(dirname(destination), { recursive: true });
         try {
@@ -38,15 +46,15 @@ export function filesystemStorage(root, label) {
         async text(...parts) { return new Response(await stream(...parts)).text(); },
         async json(...parts) { return JSON.parse(await new Response(await stream(...parts)).text()); },
         write,
-        async stat(...parts) { return describe(resolve(...parts)); },
-        async list(...parts) { return readdirSync(resolve(...parts)).sort(); },
+        async stat(...parts) { return describe(await resolve(...parts)); },
+        async list(...parts) { return readdirSync(await resolve(...parts)).sort(); },
         async delete(...parts) {
             if (!parts.length)
                 throw new Error("Emptying a place is clear, not delete");
-            rmSync(resolve(...parts), { recursive: true, force: true });
+            rmSync(await resolve(...parts), { recursive: true, force: true });
         },
         async clear(...parts) {
-            const destination = resolve(...parts);
+            const destination = await resolve(...parts);
             const found = describe(destination);
             if (found && found.kind !== "directory")
                 throw new Error("Only a Storage directory can be cleared");

package/dist/system.d.ts

@@ -1,4 +1,4 @@
-import { Client as CoreClient, ClientService as CoreClientService, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, ServerService as CoreServerService, type ProgramDefinition, type ProgramCommandChunk, type ServiceKey, type System as CoreSystem, type SystemClientEntity, type SystemEndpointEntity, type SystemProcessEntity, type SystemProcess, type SystemProgram, type SystemProgramEntity, type SystemServerEntity, type SystemUploads, type WritableAppearance } from "@phreshos/core";
+import { Client as CoreClient, ClientService as CoreClientService, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, ServerService as CoreServerService, type ProgramDefinition, type ProgramCommandChunk, type ServiceKey, type System as CoreSystem, type SystemClientEntity, type SystemEndpointEntity, type SystemProcessEntity, type SystemProcess, type SystemProgram, type SystemProgramEntity, type SystemServerEntity, type SystemUploads, type Storage, type WritableAppearance } from "@phreshos/core";
 export type ProgramProcessRunOptions = Readonly<{
     signal?: AbortSignal;
 }>;
@@ -14,7 +14,7 @@ export type ProgramProcessRunEvent = Readonly<{
 }>;
 /** One connected owner-local implementation of the shared System contract. */
 export declare class System implements CoreSystem {
-    readonly storage: import("@phreshos/core").Storage;
+    readonly storage: Storage;
     readonly appearance: WritableAppearance;
     readonly program: SystemProgram;
     readonly process: SystemProcess;

package/dist/system.js

@@ -5,6 +5,8 @@ import Events from "./events.js";
 import HandleRegistry from "./handle-registry.js";
 import { resolveHome } from "./home.js";
 import { filesystemStorage } from "./storage.js";
+import { programSql, programStore } from "./program-resources.js";
+import { EndpointTrafficHandle, ServerTrafficHandle } from "./traffic.js";
 import { openConnection, request, streamProgram } from "./transport.js";
 import Uploads from "./uploads.js";
 const systems = new WeakMap();
@@ -166,6 +168,11 @@ class ProgramHandle extends ProgramBase {
     system;
     reference;
     identity;
+    data;
+    cache;
+    store;
+    logs;
+    database;
     process;
     startup;
     snapshot;
@@ -178,6 +185,12 @@ class ProgramHandle extends ProgramBase {
         }, signal).then(value => programEntityEvent(event, value))));
         this.reference = snapshot.reference;
         this.identity = snapshot.identity;
+        const request = (value) => transport(system).api(value);
+        this.data = filesystemStorage(() => programStoragePath(system, this.identity, "data"), `Program "${this.identity}" data`);
+        this.cache = filesystemStorage(() => programStoragePath(system, this.identity, "cache"), `Program "${this.identity}" cache`);
+        this.store = programStore(request, this.identity);
+        this.logs = programSql(request, this.identity, "logs");
+        this.database = programSql(request, this.identity, "database");
         this.process = new ProgramProcesses(system, this);
         this.startup = new ProgramStartup(system, this);
     }
@@ -207,6 +220,12 @@ class ProgramHandle extends ProgramBase {
             throw new Error("A Program handle cannot become another Program");
         this.snapshot = snapshot;
     }
+    async icon(size = "medium") {
+        const value = await transport(this.system).api({ capability: "program", operation: "icon", program: this.identity, size });
+        if (!Array.isArray(value) || value.some(byte => typeof byte !== "number"))
+            throw new Error("The System returned an invalid Program icon");
+        return new Blob([Uint8Array.from(value)], { type: "image/png" });
+    }
     async agent() {
         if (!this.hasAgent)
             return null;
@@ -376,10 +395,22 @@ class ProcessHandle extends ProcessBase {
         this.client = new ClientEndpoint(system, this);
     }
     program() { return programHandle(this.system, required(this.snapshot.programSnapshot, this.snapshot.program)); }
+    async parent() {
+        if (!await this.exists())
+            throw new Error(`Process "${this.identity}" no longer exists`);
+        if (this.snapshot.parent === null)
+            return null;
+        const parent = await this.system.process.find(this.snapshot.parent);
+        if (!parent)
+            throw new Error("The parent Process no longer exists");
+        return parent;
+    }
+    async option(name) { return this.snapshot.options[name]; }
     async exit() {
         await transport(this.system).control({ capability: "process", operation: "exit", input: { process: this.identity } });
     }
     async exited() { return await this.system.process.find(this.identity) === null; }
+    async exists() { return !await this.exited(); }
 }
 class EndpointOperations extends Events {
     system;
@@ -431,6 +462,7 @@ class ServerEndpoint extends ServerBase {
     system;
     owner;
     endpoint = "server";
+    traffic;
     lifecycle;
     base;
     constructor(system, owner) {
@@ -438,6 +470,7 @@ class ServerEndpoint extends ServerBase {
         this.system = system;
         this.owner = owner;
         this.base = new EndpointOperations(system, owner, "server");
+        this.traffic = new ServerTrafficHandle((value, signal) => transport(system).api(value, signal), owner.identity, "server", value => endpointFromReference(system, value));
         this.lifecycle = this.base.lifecycle;
         bindEvents(this, this.base);
     }
@@ -463,12 +496,14 @@ class ServerEndpoint extends ServerBase {
 }
 class ClientEndpoint extends ClientBase {
     endpoint = "client";
+    traffic;
     lifecycle;
     window;
     base;
     constructor(system, owner) {
         super();
         this.base = new EndpointOperations(system, owner, "client");
+        this.traffic = new EndpointTrafficHandle((value, signal) => transport(system).api(value, signal), owner.identity, "client", value => endpointFromReference(system, value));
         this.lifecycle = this.base.lifecycle;
         bindEvents(this, this.base);
         this.window = new SystemWindow(system, owner);
@@ -645,6 +680,36 @@ function eventsOf(events) {
     };
 }
 function chronological(left, right) { return left.startedAt.getTime() - right.startedAt.getTime(); }
+async function programStoragePath(system, program, area) {
+    const value = await transport(system).api({ capability: "program", operation: "storagePath", program, area });
+    if (typeof value !== "string")
+        throw new Error("The System returned an invalid Program storage path");
+    return value;
+}
+function endpointFromReference(system, value) {
+    const reference = value;
+    if (!reference || (reference.kind !== "server" && reference.kind !== "client"))
+        throw new Error("The System returned an invalid Endpoint reference");
+    const owner = processHandle(system, snapshotFromReference(reference.process));
+    return reference.kind === "server" ? owner.server : owner.client;
+}
+function snapshotFromReference(reference) {
+    const owner = reference.program;
+    if (!owner || typeof owner.reference !== "string" || typeof owner.identity !== "string")
+        throw new Error("The System returned an invalid Process reference");
+    return {
+        reference: reference.reference,
+        identity: reference.identity,
+        name: reference.name,
+        program: owner.identity,
+        programSnapshot: owner,
+        parent: null,
+        options: reference.options,
+        startedAt: reference.startedAt,
+        server: { declared: owner.server !== null, running: reference.server !== null, service: reference.server?.service === true },
+        client: { declared: owner.client !== null, running: reference.client !== null, service: reference.client?.service === true }
+    };
+}
 function unknown(error, entity) { return error instanceof Error && error.message.startsWith(`Unknown ${entity}`); }
 function required(value, identity = "") {
     if (value !== undefined)

package/dist/traffic.d.ts

@@ -0,0 +1,36 @@
+import type { AnswerSubscriber, AskSubscriber, Cleanup, Endpoint, EventOptions, ServerTraffic, TrafficEvents, TrafficMessage } from "@phreshos/core";
+import Events from "./events.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>, keyof Definitions extends never ? TrafficMessage : never> {
+    private readonly request;
+    private readonly process;
+    private readonly endpoint;
+    protected readonly resolveEndpoint: ResolveEndpoint;
+    constructor(request: Request, 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<{}>;
+            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. */
+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<{
+        event: string;
+        questionId: string;
+        message: Readonly<{
+            to: Endpoint<{}>;
+            outcome: import("@phreshos/core").Outcome<Result>;
+        }>;
+    }>>;
+}
+export {};

package/dist/traffic.js

@@ -0,0 +1,101 @@
+import Events, { stream } from "./events.js";
+/** Directed traffic originating from one canonical Endpoint. */
+export class EndpointTrafficHandle extends Events {
+    request;
+    process;
+    endpoint;
+    resolveEndpoint;
+    constructor(request, process, endpoint, resolveEndpoint) {
+        super([], (event, signal, timeout) => request({
+            capability: "traffic",
+            operation: "wait",
+            process,
+            endpoint,
+            kind: "publish",
+            event,
+            timeout
+        }, signal).then(value => publication(value, resolveEndpoint, event === null)));
+        this.request = request;
+        this.process = process;
+        this.endpoint = endpoint;
+        this.resolveEndpoint = resolveEndpoint;
+    }
+    subscribeAsks(subscriber) {
+        return this.follow("ask", value => question(value, this.resolveEndpoint), subscriber);
+    }
+    asks(options) {
+        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();
+    }
+}
+/** Directed traffic originating from one canonical Server. */
+export class ServerTrafficHandle extends EndpointTrafficHandle {
+    subscribeAnswers(subscriber) {
+        return this.follow("answer", value => answer(value, this.resolveEndpoint), subscriber);
+    }
+    answers(options) {
+        return stream((subscriber, impossible) => this.follow("answer", value => answer(value, this.resolveEndpoint), subscriber, impossible), options);
+    }
+}
+function publication(value, resolve, captured) {
+    const received = traffic(value);
+    const message = directed(received.values[0], resolve);
+    return captured ? { event: received.event, payload: message } : message;
+}
+function question(value, resolve) {
+    const received = traffic(value);
+    if (typeof received.values[0] !== "string")
+        throw new Error("The System returned invalid question traffic");
+    return {
+        event: received.event,
+        questionId: received.values[0],
+        message: directed(received.values[1], resolve)
+    };
+}
+function answer(value, resolve) {
+    const received = traffic(value);
+    const raw = received.values[1];
+    if (typeof received.values[0] !== "string" || !raw || typeof raw !== "object")
+        throw new Error("The System returned invalid answer traffic");
+    return {
+        event: received.event,
+        questionId: received.values[0],
+        message: { to: resolve(raw.to), outcome: raw.outcome }
+    };
+}
+function directed(value, resolve) {
+    const raw = value;
+    if (!raw || typeof raw !== "object")
+        throw new Error("The System returned invalid Endpoint traffic");
+    return { to: resolve(raw.to), payload: raw.payload };
+}
+function traffic(value) {
+    const received = value;
+    if (!received || typeof received.event !== "string" || !Array.isArray(received.values))
+        throw new Error("The System returned invalid traffic");
+    return { event: received.event, values: received.values };
+}

package/package.json

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