@phreshos/server 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# `@phreshos/server`
+
+The Server SDK defines the contextual capabilities available inside a
+Program's server endpoint.
+
+## Package status
+
+This package is one component of a larger architecture that is still under
+active testing. The architecture's components will be released in stages as
+their contracts and integrations are verified.
+
+`@phreshos/server` is not intended to be used on its own. It requires the
+shared contracts from `@phreshos/core` and a compatible system host to provide
+its runtime boundary.
+
+It uses the domain objects and shared contracts from `@phreshos/core` through
+a peer dependency. It does not redefine those objects, own client-side
+capabilities, or contain host and transport implementations.
+
+Its `Host` contract exposes authoritative Program and Process discovery,
+runtime Program creation, lifecycle events, and publicly served values.
+
+Its JavaScript entry point adapts the Process IPC boundary to these contracts.
+The SDK owns callbacks, waits, queues, and their cleanup; the boundary owns
+only the forwarding registrations requested by the SDK.
+
+`Current` combines navigation into the executing Server's Process with its
+inbound subscription and answer Channel. The paired Client is explicitly named
+as `current.client`; its publishing, existence, lifecycle, and Window operations
+never masquerade as properties of `current`. `current.stop()` stops the
+executing Server, while complete Process exit remains available only through
+`current.process()`.
+
+The package provides two contextual values rather than constructors:
+
+```ts
+import { host, current } from "@phreshos/server"
+```
+
+The current Server's Channel is composed directly into `current`. It receives
+addressed events and registers answerers for questions arriving at this Server.
+Answer registration returns its sole cleanup function. Publishing to the paired
+Client belongs to `current.client`.
+
+`server.ask()` does not route a question before the addressed Server
+incarnation is ready. The Server SDK owns one deadline across readiness and the
+answer; absence or incarnation loss rejects without turning a boundary into a
+waiter.
+
+Server Program handles add `install()` and `fork()`. Their filesystem areas
+also expose `path()` and traversal-safe `resolve()`, because filesystem work is
+performed locally in the Server SDK after the Host supplies only the area root.
+Object descriptions passed to `host.createProgram()` therefore require an
+explicit absolute storage root as well as at least one declared Endpoint.

package/dist/channel.d.ts

@@ -0,0 +1,6 @@
+import type { Channel as CoreChannel, ChannelMessage, Cleanup } from "@phreshos/core";
+export type Answerer<Payload = unknown, Result = unknown> = (message: ChannelMessage<Payload>) => Result | Promise<Result>;
+export interface Channel<Events extends object = {}> extends CoreChannel<Events> {
+    answer<Payload = unknown, Result = unknown>(event: string, answerer: Answerer<Payload, Result>): Cleanup;
+}
+export declare const channel: Channel;

package/dist/channel.js

@@ -0,0 +1,19 @@
+import { endpoint } from "./domain.js";
+import Events from "./events.js";
+import wire from "./wire.js";
+class ServerChannel extends Events {
+    constructor() {
+        super((event, listener, impossible) => wire.on("end-end", event, value => listener(message(value)), null, impossible), observer => wire.onAll("end-end", (event, value) => {
+            if (typeof event === "string")
+                observer(event, message(value));
+        }));
+    }
+    answer(event, answerer) {
+        return wire.answer("end-end", event, value => answerer(message(value)));
+    }
+}
+function message(value) {
+    const raw = value;
+    return { from: endpoint(raw.from), payload: raw.payload };
+}
+export const channel = new ServerChannel();

package/dist/current.d.ts

@@ -0,0 +1,21 @@
+import type { Channel as CoreChannel, LaunchClient, Publishable } from "@phreshos/core";
+import { type Answerer } from "./channel.js";
+import { type Process, type Program, type Window } from "./domain.js";
+/** The paired Client as addressed from the currently executing Server. */
+export interface CurrentClient extends Publishable {
+    exists(): Promise<boolean>;
+    start(overrides?: LaunchClient): Promise<void>;
+    stop(): Promise<void>;
+    window(): Promise<Window>;
+}
+/** Current Server context: its inbound Channel, owner hierarchy, and paired Client. */
+export interface Current<Events extends object = {}> extends CoreChannel<Events> {
+    readonly client: CurrentClient;
+    answer<Payload = unknown, Result = unknown>(event: string, answerer: Answerer<Payload, Result>): () => void;
+    process(): Promise<Process>;
+    parent(): Promise<Process | null>;
+    program(): Promise<Program>;
+    option(name: string): Promise<string | undefined>;
+    stop(): Promise<void>;
+}
+export declare const current: Current;

package/dist/current.js

@@ -0,0 +1,50 @@
+import { channel } from "./channel.js";
+import { process, program } from "./domain.js";
+import wire from "./wire.js";
+class PairedClient {
+    publish(event, payload) { wire.send("end-end", event, payload); }
+    async exists() {
+        const answer = await wire.request(["exists", "client"]);
+        return answer[0];
+    }
+    async start(overrides = {}) {
+        await wire.request(["start-endpoint", undefined, "client", overrides]);
+    }
+    async stop() { await wire.request(["stop-endpoint", undefined, "client"]); }
+    async window() { return (await current.process()).client.window(); }
+}
+class ServerCurrent {
+    client = new PairedClient();
+    constructor() {
+        bindChannel(this, channel);
+    }
+    answer(event, answerer) {
+        return channel.answer(event, answerer);
+    }
+    async process() {
+        const answer = await wire.request(["process"]);
+        return process(answer[0]);
+    }
+    async parent() {
+        const answer = await wire.request(["parent"]);
+        return answer[0] ? process(answer[0]) : null;
+    }
+    async program() {
+        const answer = await wire.request(["program"]);
+        return program(answer[0]);
+    }
+    async option(name) {
+        const answer = await wire.request(["option", undefined, name]);
+        return answer[0];
+    }
+    async stop() { await wire.request(["stop-current"]); }
+}
+function bindChannel(target, source) {
+    Object.assign(target, {
+        subscribe: source.subscribe.bind(source),
+        waitFor: source.waitFor.bind(source),
+        events: source.events.bind(source),
+        observe: source.observe.bind(source)
+    });
+}
+export const current = new ServerCurrent();

package/dist/deadline.d.ts

@@ -0,0 +1,7 @@
+/** One SDK-owned deadline shared by every stage of an asynchronous operation. */
+export default class Deadline {
+    readonly milliseconds: number;
+    private readonly expiresAt;
+    constructor(milliseconds?: number);
+    remaining(): number;
+}

package/dist/deadline.js

@@ -0,0 +1,13 @@
+import { defaultTimeout } from "./events.js";
+/** One SDK-owned deadline shared by every stage of an asynchronous operation. */
+export default class Deadline {
+    milliseconds;
+    expiresAt;
+    constructor(milliseconds = defaultTimeout) {
+        this.milliseconds = milliseconds;
+        this.expiresAt = Date.now() + milliseconds;
+    }
+    remaining() {
+        return Math.max(0, this.expiresAt - Date.now());
+    }
+}

package/dist/domain.d.ts

@@ -0,0 +1,91 @@
+import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, Window as CoreWindow, type ClientDeclaration, type EndpointDeclaration, type Exit, type Launch, type ProgramArea as CoreProgramArea, type TrafficMessage } from "@phreshos/core";
+import Events from "./events.js";
+/** Server-side filesystem storage with access to its resolved host path. */
+export interface ProgramArea extends CoreProgramArea {
+    path(): Promise<string>;
+    resolve(...path: string[]): Promise<string>;
+}
+/** Client-safe Program data transported by the authoritative host. */
+export interface ProgramRecord {
+    identity: string;
+    installed?: boolean;
+    name: string;
+    version: string | null;
+    description: string | null;
+    icons?: boolean;
+    server: EndpointDeclaration | null;
+    client: ClientDeclaration | null;
+}
+/** Process data transported with every Endpoint reference. */
+export interface ProcessRecord {
+    identity: string;
+    name: string | null;
+    program: ProgramRecord;
+    options: Record<string, string>;
+    startedAt: string | Date;
+    server: Record<string, never> | null;
+    client: Record<string, never> | null;
+}
+export interface EndpointReference {
+    kind: "server" | "client";
+    process: ProcessRecord;
+}
+/** Server-visible Program handle and privileged Program operations. */
+export interface Program<Events extends object = {}> extends CoreProgram<Events> {
+    readonly data: ProgramArea;
+    readonly cache: ProgramArea;
+    processes(): Promise<Process[]>;
+    getProcess(identityOrName: string): Promise<Process | null>;
+    createProcess(launch?: Launch): Promise<Process>;
+    install(): Promise<this>;
+    fork(identity: string): Promise<Program>;
+}
+/** Server-visible Process handle. */
+export interface Process<Events extends object = {}> extends CoreProcess<Events> {
+    readonly server: Server;
+    readonly client: Client;
+    program(): Program;
+    parent(): Promise<Process | null>;
+}
+/** Server-visible common Endpoint handle. */
+export interface Endpoint<Events extends object = {}> extends CoreEndpoint<Events> {
+    process(): Process;
+}
+/** Server-visible Server handle. */
+export interface Server<Events extends object = {}> extends CoreServer<Events> {
+    process(): Process;
+}
+/** Server-visible Client handle. */
+export interface Client<Events extends object = {}> extends CoreClient<Events> {
+    process(): Process;
+    window(): Promise<Window>;
+}
+/** Server-visible authoritative Window handle. */
+export interface Window<Events extends object = {}> extends CoreWindow<Events> {
+    client(): Client;
+}
+export declare function scoped(route: string, subject: string | null, convert: (event: string, values: unknown[]) => unknown): Events;
+export declare function exit(code: unknown, signal: unknown): Exit;
+export declare function trafficMessage(value: unknown): TrafficMessage;
+export declare function bindEvents(target: object, events: Events): void;
+export declare function program(record: ProgramRecord): Program;
+export declare function process(record: ProcessRecord): Process;
+export declare function endpoint(reference: EndpointReference | undefined): Endpoint;
+export declare const Program: {
+    new <Events extends object = {}>(): Program<Events>;
+};
+export declare const Process: {
+    new <Events extends object = {}>(): Process<Events>;
+};
+export declare const Endpoint: {
+    new <Events extends object = {}>(): Endpoint<Events>;
+};
+export declare const Server: {
+    new <Events extends object = {}>(): Server<Events>;
+};
+export declare const Client: {
+    new <Events extends object = {}>(): Client<Events>;
+};
+export declare const Window: {
+    new <Events extends object = {}>(): Window<Events>;
+};

package/dist/domain.js

@@ -0,0 +1,313 @@
+import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, Window as CoreWindow } from "@phreshos/core";
+import { randomUUID } from "node:crypto";
+import Events from "./events.js";
+import Deadline from "./deadline.js";
+import { area, sql, store } from "./storage.js";
+import wire from "./wire.js";
+const ProgramBase = CoreProgram;
+const ProcessBase = CoreProcess;
+const ServerBase = CoreServer;
+const ClientBase = CoreClient;
+const WindowBase = CoreWindow;
+class ProgramHandle extends ProgramBase {
+    identity;
+    name;
+    version;
+    description;
+    server;
+    client;
+    data;
+    cache;
+    store;
+    logs;
+    database;
+    constructor(record) {
+        super();
+        this.identity = record.identity;
+        this.name = record.name;
+        this.version = record.version;
+        this.description = record.description;
+        this.server = record.server;
+        this.client = record.client;
+        this.data = area(record.identity, "data");
+        this.cache = area(record.identity, "cache");
+        this.store = store(record.identity);
+        this.logs = sql("logs", record.identity);
+        this.database = sql("database", record.identity);
+        bindEvents(this, scoped("host-end", record.identity, programEvent));
+    }
+    async processes() {
+        const answer = await wire.request(["processes", this.identity]);
+        return answer[0].map(process);
+    }
+    async getProcess(identityOrName) {
+        const answer = await wire.request(["program-process", this.identity, identityOrName]);
+        return answer[0] ? process(answer[0]) : null;
+    }
+    async createProcess(launch = {}) {
+        const answer = await wire.request(["create-process", this.identity, launch]);
+        return process(answer[0]);
+    }
+    async apiDocs() {
+        const answer = await wire.request(["api-docs", this.identity]);
+        return answer[0];
+    }
+    async installed() {
+        const answer = await wire.request(["installed", this.identity]);
+        return answer[0];
+    }
+    async install() {
+        await wire.request(["install", this.identity]);
+        return this;
+    }
+    async fork(identity) {
+        const answer = await wire.request(["fork", this.identity, identity]);
+        return program(answer[0]);
+    }
+    async uninstall(everything = false) {
+        await wire.request(["uninstall", this.identity, everything]);
+    }
+    async forget() {
+        await wire.request(["forget", this.identity]);
+    }
+    async exitAll() {
+        const answer = await wire.request(["exit-all", this.identity]);
+        return answer[0];
+    }
+}
+class ProcessHandle extends ProcessBase {
+    identity;
+    name;
+    startedAt;
+    server;
+    client;
+    ownerProgram;
+    options;
+    constructor(record) {
+        super();
+        this.identity = record.identity;
+        this.name = record.name;
+        this.startedAt = new Date(record.startedAt);
+        this.ownerProgram = program(record.program);
+        this.options = record.options;
+        this.server = new ServerHandle(this);
+        this.client = new ClientHandle(this);
+        bindEvents(this, scoped("process-host", record.identity, processEvent));
+    }
+    program() { return this.ownerProgram; }
+    async parent() {
+        const answer = await wire.request(["parent", this.identity]);
+        return answer[0] ? process(answer[0]) : null;
+    }
+    async option(name) {
+        if (name in this.options)
+            return this.options[name];
+        const answer = await wire.request(["option", this.identity, name]);
+        return answer[0];
+    }
+    async exit() {
+        await wire.request(["exit", this.identity]);
+    }
+    async exited() {
+        const answer = await wire.request(["exited", this.identity]);
+        return answer[0];
+    }
+}
+class TrafficHandle extends Events {
+    owner;
+    kind;
+    constructor(owner, kind) {
+        super((event, listener, impossible) => wire.observe(owner.identity, kind, "publish", event, value => {
+            listener(trafficMessage(value));
+        }, impossible), observer => wire.observe(owner.identity, kind, "publish", null, (event, value) => {
+            if (typeof event === "string")
+                observer(event, trafficMessage(value));
+        }));
+        this.owner = owner;
+        this.kind = kind;
+    }
+    observeAsks(observer) {
+        return wire.observe(this.owner.identity, this.kind, "ask", null, (event, questionId, message) => {
+            if (typeof event !== "string" || typeof questionId !== "string")
+                return;
+            observer({ event, questionId, message: trafficMessage(message) });
+        });
+    }
+}
+class ServerTrafficHandle extends TrafficHandle {
+    observeAnswers(observer) {
+        return wire.observe(this.owner.identity, "server", "answer", null, (event, questionId, message) => {
+            if (typeof event !== "string" || typeof questionId !== "string")
+                return;
+            const raw = message;
+            observer({
+                event,
+                questionId,
+                message: { to: endpoint(raw.to), outcome: raw.outcome }
+            });
+        });
+    }
+}
+class ServerHandle extends ServerBase {
+    owner;
+    traffic;
+    constructor(owner) {
+        super();
+        this.owner = owner;
+        this.traffic = new ServerTrafficHandle(owner, "server");
+    }
+    process() { return this.owner; }
+    publish(event, payload) {
+        wire.send("end-host", "send", this.owner.identity, "server", event, payload);
+    }
+    async exists() {
+        const answer = await wire.request(["exists", "server", this.owner.identity]);
+        return answer[0];
+    }
+    async start() { await wire.request(["start-endpoint", this.owner.identity, "server"]); }
+    async stop() { await wire.request(["stop-endpoint", this.owner.identity, "server"]); }
+    async waitReady(timeout) {
+        await wire.request(["wait-ready", this.owner.identity], timeout);
+    }
+    async ask(event, payload) {
+        return this.askWithin(undefined, event, payload);
+    }
+    timeout(milliseconds) {
+        return { ask: (event, payload) => this.askWithin(milliseconds, event, payload) };
+    }
+    async askWithin(timeout, event, payload) {
+        const deadline = new Deadline(timeout);
+        await wire.requestWithin(["wait-ready", this.owner.identity, true], deadline);
+        const identity = await wire.identity;
+        const address = `server:${identity.process}:${randomUUID()}`;
+        const questionId = randomUUID();
+        const waiting = wire.expectWithin(address, deadline);
+        wire.send("end-host", "ask", this.owner.identity, "server", address, questionId, event, payload);
+        try {
+            return await waiting;
+        }
+        finally {
+            wire.forget(address);
+        }
+    }
+}
+class ClientHandle extends ClientBase {
+    owner;
+    traffic;
+    constructor(owner) {
+        super();
+        this.owner = owner;
+        this.traffic = new TrafficHandle(owner, "client");
+    }
+    process() { return this.owner; }
+    publish(event, payload) { wire.send("end-host", "send", this.owner.identity, "client", event, payload); }
+    async exists() {
+        const answer = await wire.request(["exists", "client", this.owner.identity]);
+        return answer[0];
+    }
+    async start(overrides = {}) {
+        await wire.request(["start-endpoint", this.owner.identity, "client", overrides]);
+    }
+    async stop() { await wire.request(["stop-endpoint", this.owner.identity, "client"]); }
+    async window() {
+        await wire.request(["window", this.owner.identity]);
+        return new WindowHandle(this);
+    }
+}
+class WindowHandle extends WindowBase {
+    owner;
+    constructor(owner) {
+        super();
+        this.owner = owner;
+        bindEvents(this, scoped("host-end", owner.process().identity, (_event, values) => values[0]));
+    }
+    client() { return this.owner; }
+    async state() {
+        const answer = await wire.request(["window", this.owner.process().identity]);
+        return answer[0];
+    }
+    async title() { return (await this.state()).title; }
+    async position() { return (await this.state()).position; }
+    async size() { return (await this.state()).size; }
+    async minimized() { return (await this.state()).minimized; }
+    async front() { return (await this.state()).front; }
+    async layer() { return (await this.state()).layer; }
+    async location() { return (await this.state()).location; }
+    async move(position) { await wire.request(["move", this.owner.process().identity, position]); }
+    async resize(size) { await wire.request(["resize", this.owner.process().identity, size]); }
+    async minimize(minimized = true) { await wire.request(["minimize", this.owner.process().identity, minimized]); }
+    async changeTitle(title) { await wire.request(["changeTitle", this.owner.process().identity, title]); }
+    async raise() { await wire.request(["raise", this.owner.process().identity]); }
+}
+export function scoped(route, subject, convert) {
+    return new Events((event, listener, impossible) => wire.on(route, event, (...values) => {
+        const message = unscoped(subject, values);
+        if (message)
+            listener(convert(event, message));
+    }, subject, impossible), observer => wire.onAll(route, (event, ...values) => {
+        if (typeof event !== "string")
+            return;
+        const message = unscoped(subject, values);
+        if (message)
+            observer(event, convert(event, message));
+    }, subject));
+}
+function unscoped(subject, values) {
+    if (subject === null)
+        return values;
+    return values[0] === subject ? values.slice(1) : null;
+}
+function programEvent(event, values) {
+    if (event === "serverStart" || event === "clientStart" || event === "clientStop" || event === "processCreate")
+        return process(values[0]);
+    if (event === "serverStop")
+        return { process: process(values[0]), code: numberOrNull(values[1]), signal: stringOrNull(values[2]) };
+    if (event === "processExit")
+        return { process: process(values[0]), ...exit(values[1], values[2]) };
+    if (event === "uninstall")
+        return { everythingRemoved: values[0] === true };
+    return undefined;
+}
+function processEvent(event, values) {
+    if (event === "serverStop")
+        return { code: numberOrNull(values[0]), signal: stringOrNull(values[1]) };
+    if (event === "exit")
+        return exit(values[0], values[1]);
+    return undefined;
+}
+export function exit(code, signal) {
+    const namedSignal = stringOrNull(signal);
+    return { status: namedSignal === null ? "exited" : "signaled", code: numberOrNull(code), signal: namedSignal };
+}
+function numberOrNull(value) { return typeof value === "number" ? value : null; }
+function stringOrNull(value) { return typeof value === "string" ? value : null; }
+export function trafficMessage(value) {
+    const raw = value;
+    return { to: endpoint(raw.to), payload: raw.payload };
+}
+export function bindEvents(target, events) {
+    Object.assign(target, {
+        subscribe: events.subscribe.bind(events),
+        waitFor: events.waitFor.bind(events),
+        events: events.events.bind(events),
+        observe: events.observe.bind(events)
+    });
+}
+export function program(record) {
+    return new ProgramHandle(record);
+}
+export function process(record) {
+    return new ProcessHandle(record);
+}
+export function endpoint(reference) {
+    if (!reference)
+        throw new Error("The boundary returned an invalid Endpoint reference");
+    const owner = new ProcessHandle(reference.process);
+    return reference.kind === "server" ? owner.server : owner.client;
+}
+export const Program = CoreProgram;
+export const Process = CoreProcess;
+export const Endpoint = CoreEndpoint;
+export const Server = CoreServer;
+export const Client = CoreClient;
+export const Window = CoreWindow;

package/dist/events.d.ts

@@ -0,0 +1,21 @@
+import type { Capture, Cleanup, EventOptions } from "@phreshos/core";
+export declare const defaultTimeout = 10000;
+type Failure = (error: Error) => void;
+type Listener = (message: unknown) => unknown;
+type Observer = (event: string, message: unknown) => unknown;
+/**
+ * SDK-owned subscription behavior over one boundary registration source.
+ *
+ * The boundary owns forwarding state only. Promises, deadlines, queues and
+ * callbacks remain here, inside the endpoint that requested the data.
+ */
+export default class Events {
+    private readonly listen;
+    private readonly listenAll;
+    constructor(listen: (event: string, listener: Listener, impossible?: Failure) => Cleanup, listenAll: (observer: Observer) => Cleanup);
+    subscribe(event: string, subscriber: Listener): Cleanup;
+    waitFor(event: string, timeout?: number): Promise<unknown>;
+    events(event: string, options?: EventOptions): AsyncIterableIterator<unknown>;
+    observe(observer: (capture: Capture<string, unknown>) => unknown): Cleanup;
+}
+export {};