@phreshos/server 0.1.0

package/dist/events.js

@@ -0,0 +1,92 @@
+export const defaultTimeout = 10_000;
+/**
+ * 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 {
+    listen;
+    listenAll;
+    constructor(listen, listenAll) {
+        this.listen = listen;
+        this.listenAll = listenAll;
+    }
+    subscribe(event, subscriber) {
+        return this.listen(event, subscriber);
+    }
+    waitFor(event, timeout = defaultTimeout) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let stop = () => undefined;
+            const finish = (settle) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                stop();
+                settle();
+            };
+            const timer = setTimeout(() => {
+                finish(() => reject(new Error(`Event promise timeout ${timeout}ms`)));
+            }, timeout);
+            stop = this.listen(event, message => finish(() => resolve(message)), error => finish(() => reject(error)));
+        });
+    }
+    events(event, 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");
+        }
+        const listen = this.listen;
+        return (async function* () {
+            const queue = [];
+            let ended = false;
+            let failure = null;
+            let wake = null;
+            const stop = listen(event, message => {
+                if (ended || failure)
+                    return;
+                if (queue.length >= capacity) {
+                    failure = new Error(`Event queue exceeded its capacity of ${capacity}`);
+                }
+                else {
+                    queue.push(message);
+                }
+                wake?.();
+                wake = null;
+            }, error => {
+                if (ended || failure)
+                    return;
+                failure = error;
+                wake?.();
+                wake = null;
+            });
+            const abort = () => {
+                ended = true;
+                wake?.();
+                wake = null;
+            };
+            options.signal?.addEventListener("abort", abort, { once: true });
+            try {
+                while (!ended) {
+                    if (queue.length) {
+                        yield queue.shift();
+                        continue;
+                    }
+                    if (failure)
+                        throw failure;
+                    await new Promise(resolve => { wake = resolve; });
+                }
+            }
+            finally {
+                ended = true;
+                stop();
+                options.signal?.removeEventListener("abort", abort);
+            }
+        })();
+    }
+    observe(observer) {
+        return this.listenAll((event, message) => observer({ event, message }));
+    }
+}

package/dist/host.d.ts

@@ -0,0 +1,65 @@
+import type { Exit, Layer, Position, ServedFile, Size, Subscribable } from "@phreshos/core";
+import { type Process, type Program } from "./domain.js";
+export type ServerDescription = Readonly<{
+    location: string;
+    start?: boolean;
+    installCommand?: string;
+    startCommand: string;
+}>;
+export type ClientDescription = Readonly<{
+    location: string;
+    start?: boolean;
+    title?: string;
+    size?: Size;
+    position?: Position;
+    layer?: Layer;
+    minimize?: boolean;
+}>;
+type Description = Readonly<{
+    identity: string;
+    name?: string;
+    version?: string;
+    description?: string;
+    apiDocs?: string;
+    icons?: string;
+    storage: string;
+}>;
+export type ProgramDescription = Description & (Readonly<{
+    server: ServerDescription;
+    client?: ClientDescription;
+}> | Readonly<{
+    server?: ServerDescription;
+    client: ClientDescription;
+}>);
+export type HostServerStop = Omit<Exit, "status"> & Readonly<{
+    process: Process;
+}>;
+export type HostProgramUninstall = Readonly<{
+    program: Program;
+    everythingRemoved: boolean;
+}>;
+export type HostProcessExit = Exit & Readonly<{
+    process: Process;
+}>;
+export type HostEvents = {
+    serverStart: Process;
+    serverStop: HostServerStop;
+    clientStart: Process;
+    clientStop: Process;
+    programCreate: Program;
+    programForget: Program;
+    programInstall: Program;
+    programUninstall: HostProgramUninstall;
+    processCreate: Process;
+    processExit: HostProcessExit;
+};
+export interface Host<Events extends object = {}> extends Subscribable<HostEvents & Events, never> {
+    serve(value: unknown): Promise<ServedFile>;
+    programs(onlyInstalled?: boolean): Promise<Program[]>;
+    getProgram(identity: string): Promise<Program>;
+    createProgram(source: ProgramDescription | string): Promise<Program>;
+    processes(): Promise<Process[]>;
+    getProcess(identity: string): Promise<Process>;
+}
+export declare const host: Host;
+export {};

package/dist/host.js

@@ -0,0 +1,54 @@
+import Events from "./events.js";
+import { exit, process, program } from "./domain.js";
+import serve from "./served.js";
+import wire from "./wire.js";
+class ServerHost extends Events {
+    constructor() {
+        super((event, listener, impossible) => wire.on("host-end", event, (...values) => listener(hostEvent(event, values)), null, impossible), observer => wire.onAll("host-end", (event, ...values) => {
+            if (typeof event === "string")
+                observer(event, hostEvent(event, values));
+        }));
+    }
+    serve(value) { return serve(value); }
+    async programs(onlyInstalled = false) {
+        const answer = await wire.request(["programs", onlyInstalled]);
+        return answer[0].map(program);
+    }
+    async getProgram(identity) {
+        const answer = await wire.request(["program", identity]);
+        return program(answer[0]);
+    }
+    async createProgram(source) {
+        const answer = await wire.request(["create-program", source]);
+        return program(answer[0]);
+    }
+    async processes() {
+        const answer = await wire.request(["processes"]);
+        return answer[0].map(process);
+    }
+    async getProcess(identity) {
+        const answer = await wire.request(["process", identity]);
+        return process(answer[0]);
+    }
+}
+function hostEvent(event, values) {
+    if (event === "serverStart" || event === "clientStart" || event === "clientStop" || event === "processCreate") {
+        return process(values[1]);
+    }
+    if (event === "serverStop") {
+        return { process: process(values[1]), code: numberOrNull(values[2]), signal: stringOrNull(values[3]) };
+    }
+    if (event === "processExit") {
+        return { process: process(values[1]), ...exit(values[2], values[3]) };
+    }
+    if (event === "programCreate" || event === "programForget" || event === "programInstall") {
+        return program(values[1]);
+    }
+    if (event === "programUninstall") {
+        return { program: program(values[1]), everythingRemoved: values[2] === true };
+    }
+    return values[0];
+}
+function numberOrNull(value) { return typeof value === "number" ? value : null; }
+function stringOrNull(value) { return typeof value === "string" ? value : null; }
+export const host = new ServerHost();

package/dist/main.d.ts

@@ -0,0 +1,5 @@
+export { host, type Host, type ClientDescription, type HostEvents, type HostProcessExit, type HostProgramUninstall, type HostServerStop, type ProgramDescription, type ServerDescription } from "./host.js";
+export { current, type Current, type CurrentClient } from "./current.js";
+export { type Answerer, type Channel } from "./channel.js";
+export { Client, Endpoint, Process, Program, Server, Window, type ProgramArea } from "./domain.js";
+export type { AnswerCapture, AnswerMessage, AnswerObserver, Askable, AskCapture, AskMessage, AskObserver, Capture, Captures, ChannelCapture, ChannelEvents, ChannelMessage, ClientTraffic, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointTraffic, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, Position, ProgramEvents, ProgramProcessExit, ProgramServerStop, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, ServerTraffic, Size, Subscribable, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, WindowEvents, WindowState } from "@phreshos/core";

package/dist/main.js

@@ -0,0 +1,4 @@
+export { host } from "./host.js";
+export { current } from "./current.js";
+export {} from "./channel.js";
+export { Client, Endpoint, Process, Program, Server, Window } from "./domain.js";

package/dist/served.d.ts

@@ -0,0 +1,3 @@
+import type { ServedFile } from "@phreshos/core";
+/** Writes one public value directly into the host-managed served-file area. */
+export default function serve(value: unknown): Promise<ServedFile>;

package/dist/served.js

@@ -0,0 +1,41 @@
+import { randomUUID } from "node:crypto";
+import { createWriteStream, mkdirSync, statSync } from "node:fs";
+import { rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { content } from "./storage.js";
+import wire from "./wire.js";
+/** Writes one public value directly into the host-managed served-file area. */
+export default async function serve(value) {
+    const answer = await wire.request(["serve"]);
+    const [root, limit] = answer;
+    const source = content(value);
+    const identity = randomUUID();
+    const file = `${identity}.${source.extension}`;
+    const temporary = join(root, `.${identity}.serving`);
+    const destination = join(root, file);
+    let size = 0;
+    mkdirSync(root, { recursive: true });
+    try {
+        await pipeline(Readable.fromWeb(source.stream), async function* (chunks) {
+            for await (const chunk of chunks) {
+                size += chunk.byteLength;
+                if (size > limit)
+                    throw new Error(`The served value exceeds ${limit / 1024 / 1024 / 1024} GB`);
+                yield chunk;
+            }
+        }, createWriteStream(temporary, { flags: "wx" }));
+        await rename(temporary, destination);
+    }
+    catch (error) {
+        await rm(temporary, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    return {
+        file,
+        type: source.type,
+        size,
+        time: Math.round(statSync(destination).mtimeMs)
+    };
+}

package/dist/storage.d.ts

@@ -0,0 +1,14 @@
+import type { ProgramArea, ProgramSql, ProgramStore } from "@phreshos/core";
+export interface ServerArea extends ProgramArea {
+    path(): Promise<string>;
+    resolve(...path: string[]): Promise<string>;
+}
+/** Server-local implementation of one Program-owned filesystem area. */
+export declare function area(program: string, which: "data" | "cache"): ServerArea;
+export declare function store(program: string): ProgramStore;
+export declare function sql(kind: "database" | "logs", program: string): ProgramSql;
+export declare function content(value: unknown): {
+    stream: ReadableStream<Uint8Array>;
+    extension: string;
+    type: string;
+};

package/dist/storage.js

@@ -0,0 +1,172 @@
+import { randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+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";
+import wire from "./wire.js";
+/** Server-local implementation of one Program-owned filesystem area. */
+export function area(program, which) {
+    async function path() {
+        const answer = await wire.request([which, program, "path"]);
+        return answer[0];
+    }
+    async function resolve(...parts) {
+        const root = await path();
+        const destination = join(root, ...parts);
+        const step = relative(root, destination);
+        if (step === ".." || step.startsWith(`..${sep}`) || isAbsolute(step)) {
+            throw new Error("A storage path may not leave its area");
+        }
+        return destination;
+    }
+    async function stream(...parts) {
+        const destination = await resolve(...parts);
+        const found = describe(destination);
+        if (!found)
+            throw new Error(`There is no ${parts.join("/")} in this Program's ${which}`);
+        if (found.kind !== "file")
+            throw new Error(`${parts.join("/")} is not a file`);
+        return Readable.toWeb(createReadStream(destination));
+    }
+    async function write(...args) {
+        if (args.length < 2)
+            throw new Error("Writing takes a file name and what to write");
+        const parts = args.slice(0, -1);
+        const destination = await resolve(...parts);
+        const temporary = join(dirname(destination), `.${randomUUID()}.writing`);
+        mkdirSync(dirname(destination), { recursive: true });
+        try {
+            await pipeline(Readable.fromWeb(content(args.at(-1)).stream), createWriteStream(temporary, { flags: "wx" }));
+            renameSync(temporary, destination);
+        }
+        catch (error) {
+            await rm(temporary, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+    return {
+        path,
+        resolve,
+        stream,
+        async bytes(...parts) {
+            return new Uint8Array(await new Response(await stream(...parts)).arrayBuffer());
+        },
+        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(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(await resolve(...parts), { recursive: true, force: true });
+        },
+        async clear() {
+            const root = await path();
+            rmSync(root, { recursive: true, force: true });
+            mkdirSync(root, { recursive: true });
+        }
+    };
+}
+export function store(program) {
+    async function ask(operation, ...values) {
+        const answer = await wire.request(["store", program, operation, ...values]);
+        return answer[0];
+    }
+    return {
+        get: (key) => ask("get", key),
+        set: (key, value, ttl) => ask("set", key, value, ttl),
+        delete: (key) => ask("delete", key),
+        has: (key) => ask("has", key),
+        clear: () => ask("clear")
+    };
+}
+export function sql(kind, program) {
+    return {
+        async query(statement, ...rest) {
+            const [text, values] = written(statement, rest);
+            const answer = await wire.request([kind, program, text, values]);
+            return answer[0];
+        }
+    };
+}
+export function content(value) {
+    const binary = "application/octet-stream";
+    if (typeof File !== "undefined" && value instanceof File) {
+        const type = value.type || binary;
+        return { stream: value.stream(), extension: extension(value.name, type), type };
+    }
+    if (value instanceof Blob) {
+        const type = value.type || binary;
+        return { stream: value.stream(), extension: extension("", type), type };
+    }
+    if (value instanceof ReadableStream)
+        return { stream: value, extension: "bin", type: binary };
+    if (typeof value === "string")
+        return { stream: new Blob([value]).stream(), extension: "txt", type: "text/plain" };
+    if (value instanceof ArrayBuffer)
+        return { stream: new Blob([value]).stream(), extension: "bin", type: binary };
+    if (ArrayBuffer.isView(value)) {
+        const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+        return { stream: new Blob([bytes.slice()]).stream(), extension: "bin", type: binary };
+    }
+    const json = JSON.stringify(value);
+    if (json === undefined)
+        throw new Error("This value cannot be written as JSON");
+    return { stream: new Blob([json]).stream(), extension: "json", type: "application/json" };
+}
+function describe(path) {
+    let found;
+    try {
+        found = statSync(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    const modifiedAt = Math.round(found.mtimeMs);
+    if (found.isFile())
+        return { kind: "file", size: found.size, modifiedAt };
+    if (found.isDirectory())
+        return { kind: "directory", modifiedAt };
+    return { kind: "other", modifiedAt };
+}
+function written(statement, rest) {
+    if (typeof statement === "string")
+        return [statement, Array.isArray(rest[0]) ? rest[0] : []];
+    return [statement.raw.join("?"), rest];
+}
+const extensions = {
+    "application/gzip": "gz",
+    "application/javascript": "js",
+    "application/json": "json",
+    "application/pdf": "pdf",
+    "application/wasm": "wasm",
+    "application/zip": "zip",
+    "audio/mpeg": "mp3",
+    "image/gif": "gif",
+    "image/jpeg": "jpg",
+    "image/png": "png",
+    "image/svg+xml": "svg",
+    "image/webp": "webp",
+    "text/css": "css",
+    "text/csv": "csv",
+    "text/html": "html",
+    "text/javascript": "js",
+    "text/plain": "txt",
+    "video/mp4": "mp4"
+};
+function extension(name, type) {
+    const named = name.match(/\.([A-Za-z0-9]+)$/)?.[1];
+    return named?.toLowerCase() ?? extensions[type.split(";", 1)[0].toLowerCase()] ?? "bin";
+}

package/dist/wire.d.ts

@@ -0,0 +1,38 @@
+import type { Cleanup } from "@phreshos/core";
+import Deadline from "./deadline.js";
+type Handler = (...values: unknown[]) => unknown;
+type Failure = (error: Error) => void;
+type TrafficKind = "publish" | "ask" | "answer";
+/** The server endpoint's sole IPC adapter. */
+declare class Wire {
+    private readonly pending;
+    private readonly subscribers;
+    private readonly every;
+    private readonly answerers;
+    private readonly waiting;
+    private readonly impossible;
+    readonly identity: Promise<{
+        process: string;
+        program: string;
+    }>;
+    constructor();
+    send(route: string, ...values: unknown[]): void;
+    request(values: unknown[], timeout?: number): Promise<unknown>;
+    requestWithin(values: unknown[], deadline: Deadline): Promise<unknown>;
+    expectWithin(question: string, deadline: Deadline): Promise<unknown>;
+    forget(question: string): void;
+    on(route: string, event: string, handler: Handler, subject?: string | null, impossible?: Failure): Cleanup;
+    onAll(route: string, handler: Handler, subject?: string | null): Cleanup;
+    answer(route: string, event: string, handler: Handler): Cleanup;
+    observe(target: string, half: "server" | "client", kind: TrafficKind, event: string | null, handler: Handler, impossible?: Failure): Cleanup;
+    private register;
+    private unregister;
+    private deliver;
+    private receiveQuestion;
+    private sendAnswer;
+    private releaseWaiting;
+    private forgetIncoming;
+    private settle;
+}
+declare const _default: Wire;
+export default _default;