@phreshos/node 0.1.0 → 0.1.2

package/dist/client-development.js

@@ -1,199 +0,0 @@
-import { spawn } from "node:child_process";
-import { connect } from "node:net";
-import { delimiter, join } from "node:path";
-const readinessTimeout = 15_000;
-const pollingInterval = 200;
-const reportingInterval = 2_000;
-const sandboxedClientOrigin = "null";
-/** One client development server owned by a Gateway development run. */
-export class DevelopmentClient {
-    child;
-    output = [];
-    stopped = false;
-    result = null;
-    outputWaiter = null;
-    completion;
-    constructor(command, directory) {
-        this.child = spawn(command, {
-            cwd: directory,
-            env: commandEnvironment(directory),
-            shell: true,
-            stdio: ["ignore", "pipe", "pipe"],
-            detached: true
-        });
-        this.child.stdout?.on("data", chunk => this.push(outputEvent("out", chunk)));
-        this.child.stderr?.on("data", chunk => this.push(outputEvent("err", chunk)));
-        this.completion = new Promise(resolve => {
-            let settled = false;
-            const finish = (exit) => {
-                if (settled)
-                    return;
-                settled = true;
-                this.result = exit;
-                this.outputWaiter?.();
-                this.outputWaiter = null;
-                resolve(exit);
-            };
-            this.child.once("error", error => finish({ code: null, signal: null, error }));
-            this.child.once("exit", (code, signal) => finish({ code, signal, error: null }));
-        });
-    }
-    drain() { return this.output.splice(0); }
-    exited() { return this.completion; }
-    exitResult() { return this.result; }
-    outputAvailable() {
-        if (this.output.length || this.result)
-            return Promise.resolve();
-        return new Promise(resolve => { this.outputWaiter = resolve; });
-    }
-    async stop() {
-        if (this.stopped)
-            return;
-        this.stopped = true;
-        if (!running(this.child))
-            return;
-        terminate(this.child, "SIGTERM");
-        await waitUntilStopped(this.child, 1_000);
-        if (running(this.child))
-            terminate(this.child, "SIGKILL");
-        await waitUntilStopped(this.child, 1_000);
-    }
-    endingWasRequested() { return this.stopped; }
-    push(event) {
-        this.output.push(event);
-        this.outputWaiter?.();
-        this.outputWaiter = null;
-    }
-}
-/** Refuse to claim a URL already served by an unrelated process. */
-export async function assertAvailable(url) {
-    if (!await occupied(url))
-        return;
-    throw new Error(`Client development URL is already in use: ${url}`);
-}
-/** Wait until a development Client can be loaded by a sandboxed Program iframe. */
-export async function* waitForDevelopmentClient(config, client, signal) {
-    const began = Date.now();
-    let nextReport = began + reportingInterval;
-    while (Date.now() - began < readinessTimeout) {
-        throwIfAborted(signal);
-        for (const event of client?.drain() ?? [])
-            yield event;
-        const exit = client?.exitResult();
-        if (exit && !client?.endingWasRequested())
-            throw commandFailure(exit);
-        const availability = await inspect(config.url, readinessTimeout - (Date.now() - began));
-        if (availability === "ready")
-            return;
-        if (availability === "cors-blocked") {
-            throw new Error([
-                `Client development URL responded, but does not allow the sandboxed Client origin: ${config.url}`,
-                "Enable CORS so the response includes Access-Control-Allow-Origin: *."
-            ].join("\n"));
-        }
-        const now = Date.now();
-        if (now >= nextReport) {
-            yield { event: "waiting", subject: "client", url: config.url };
-            while (nextReport <= now)
-                nextReport += reportingInterval;
-        }
-        await pause(Math.min(pollingInterval, readinessTimeout - (now - began)), signal);
-    }
-    throw new Error(`Client development URL did not respond within 15 seconds: ${config.url}`);
-}
-export function commandFailure(exit) {
-    if (exit.error)
-        return new Error(`Client development command failed: ${exit.error.message}`);
-    if (exit.signal)
-        return new Error(`Client development command ended on ${exit.signal}`);
-    return new Error(`Client development command exited with ${exit.code ?? 0}`);
-}
-function outputEvent(stream, chunk) {
-    return { event: "output", source: "client-development", stream, text: String(chunk) };
-}
-function commandEnvironment(directory) {
-    const key = Object.keys(process.env).find(name => name.toLowerCase() === "path") ?? "PATH";
-    const inherited = process.env[key];
-    return { ...process.env, [key]: [join(directory, "node_modules", ".bin"), inherited].filter(Boolean).join(delimiter) };
-}
-async function occupied(url) {
-    const location = new URL(url);
-    const port = Number(location.port || (location.protocol === "https:" ? 443 : 80));
-    return await new Promise(resolve => {
-        const socket = connect({ host: location.hostname, port });
-        let done = false;
-        const finish = (value) => {
-            if (done)
-                return;
-            done = true;
-            socket.destroy();
-            resolve(value);
-        };
-        socket.setTimeout(500);
-        socket.once("connect", () => finish(true));
-        socket.once("error", () => finish(false));
-        socket.once("timeout", () => finish(false));
-    });
-}
-async function inspect(url, remaining) {
-    try {
-        const response = await fetch(url, {
-            headers: { origin: sandboxedClientOrigin },
-            signal: AbortSignal.timeout(Math.max(1, Math.min(500, remaining)))
-        });
-        const allowedOrigin = response.headers.get("access-control-allow-origin")?.trim();
-        await response.body?.cancel();
-        return allowedOrigin === "*" || allowedOrigin === sandboxedClientOrigin ? "ready" : "cors-blocked";
-    }
-    catch {
-        return "unavailable";
-    }
-}
-function terminate(child, signal) {
-    if (!child.pid)
-        return;
-    try {
-        process.kill(-child.pid, signal);
-    }
-    catch {
-        child.kill(signal);
-    }
-}
-function running(child) {
-    if (!child.pid)
-        return false;
-    try {
-        process.kill(-child.pid, 0);
-        return true;
-    }
-    catch {
-        return child.exitCode === null && child.signalCode === null;
-    }
-}
-async function waitUntilStopped(child, milliseconds) {
-    const deadline = Date.now() + milliseconds;
-    while (running(child) && Date.now() < deadline)
-        await new Promise(resolve => setTimeout(resolve, 20));
-}
-function pause(milliseconds, signal) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(finish, Math.max(0, milliseconds));
-        const cancel = () => {
-            cleanup();
-            reject(signal?.reason instanceof Error ? signal.reason : new Error("The operation was cancelled"));
-        };
-        const cleanup = () => {
-            clearTimeout(timer);
-            signal?.removeEventListener("abort", cancel);
-        };
-        function finish() { cleanup(); resolve(); }
-        if (signal?.aborted)
-            cancel();
-        else
-            signal?.addEventListener("abort", cancel, { once: true });
-    });
-}
-function throwIfAborted(signal) {
-    if (signal?.aborted)
-        throw signal.reason instanceof Error ? signal.reason : new Error("The operation was cancelled");
-}

package/dist/gateway.d.ts

@@ -1,49 +0,0 @@
-import type { ProgramDescription, System, SystemControlClient, SystemControlRequest } from "@phreshos/core";
-import { Project, type PackedProject } from "./project.js";
-import { type GatewayEvent } from "./transport.js";
-/** One explicit owner-local connection to a running PhreshOS System. */
-export declare class Gateway implements SystemControlClient {
-    private readonly connection;
-    readonly home: string;
-    readonly address: string;
-    readonly system: System;
-    private closed;
-    private readonly lifetime;
-    private constructor();
-    /** Connect to an already running System selected by argument, environment, or owner default. */
-    static open(home?: string): Promise<Gateway>;
-    /** Execute one operation from the transport-neutral System-control vocabulary. */
-    execute(request: SystemControlRequest, signal?: AbortSignal): Promise<unknown>;
-    /** Build and package one local Program project. */
-    pack(project: Project): Promise<PackedProject>;
-    /** Install one local Program project in this Gateway's System. */
-    install(source: Project | ProgramDescription, options?: InstallOptions): AsyncGenerator<GatewayEvent, void, void>;
-    /** Build and start one local production Program, attached to this Gateway. */
-    start(project: Project, options?: RunOptions): AsyncGenerator<GatewayEvent, void, unknown>;
-    /** Start one local Program in development, including its declared Client development server. */
-    dev(project: Project, options?: RunOptions): AsyncGenerator<GatewayEvent, void, unknown>;
-    /** Uninstall one Program by identity or local Project. */
-    uninstall(program: string | Project, options?: UninstallOptions): AsyncGenerator<GatewayEvent, void, void>;
-    /** Close this Gateway without stopping the System. */
-    close(): Promise<void>;
-    private runProject;
-    private program;
-    private control;
-    private api;
-    private lifecycle;
-    private signal;
-    private requireOpen;
-}
-export interface InstallOptions {
-    run?: boolean;
-    startup?: boolean;
-    signal?: AbortSignal;
-}
-export interface RunOptions {
-    options?: Record<string, string>;
-    signal?: AbortSignal;
-}
-export interface UninstallOptions {
-    everything?: boolean;
-    signal?: AbortSignal;
-}

package/dist/gateway.js

@@ -1,151 +0,0 @@
-import { gatewayAddress } from "./address.js";
-import { resolveHome } from "./home.js";
-import { Project } from "./project.js";
-import { openConnection, request as gatewayRequest, streamProgram } from "./transport.js";
-import { gatewaySystem } from "./system.js";
-import { assertAvailable, commandFailure, DevelopmentClient, waitForDevelopmentClient } from "./client-development.js";
-/** One explicit owner-local connection to a running PhreshOS System. */
-export class Gateway {
-    connection;
-    home;
-    address;
-    system;
-    closed = false;
-    lifetime = new AbortController();
-    constructor(home, address, connection) {
-        this.connection = connection;
-        this.home = home;
-        this.address = address;
-        this.system = gatewaySystem({
-            control: (request, signal) => this.control(request, signal),
-            api: (request, signal) => this.api(request, signal),
-            lifecycle: (request, signal) => this.lifecycle(request, signal)
-        });
-    }
-    /** Connect to an already running System selected by argument, environment, or owner default. */
-    static async open(home) {
-        const resolvedHome = resolveHome(home);
-        const address = gatewayAddress(resolvedHome);
-        const connection = await openConnection(address);
-        return new Gateway(resolvedHome, address, connection);
-    }
-    /** Execute one operation from the transport-neutral System-control vocabulary. */
-    execute(request, signal) {
-        this.requireOpen();
-        return this.control(request, signal);
-    }
-    /** Build and package one local Program project. */
-    pack(project) {
-        this.requireOpen();
-        return project.pack();
-    }
-    /** Install one local Program project in this Gateway's System. */
-    async *install(source, options = {}) {
-        this.requireOpen();
-        if (source instanceof Project)
-            await source.build();
-        const program = source instanceof Project ? source.description("production") : source;
-        yield* this.program({
-            word: "install",
-            program,
-            run: options.run === true,
-            startup: options.startup === true
-        }, options.signal);
-    }
-    /** Build and start one local production Program, attached to this Gateway. */
-    start(project, options = {}) {
-        this.requireOpen();
-        return this.runProject(project, "production", options);
-    }
-    /** Start one local Program in development, including its declared Client development server. */
-    dev(project, options = {}) {
-        this.requireOpen();
-        return this.runProject(project, "development", options);
-    }
-    /** Uninstall one Program by identity or local Project. */
-    uninstall(program, options = {}) {
-        this.requireOpen();
-        const identity = typeof program === "string" ? program : program.config.identity;
-        return this.program({ word: "uninstall", identity, everything: options.everything === true }, options.signal);
-    }
-    /** Close this Gateway without stopping the System. */
-    async close() {
-        if (this.closed)
-            return;
-        this.closed = true;
-        this.lifetime.abort(new Error("This Gateway is closed"));
-        this.connection.destroy();
-    }
-    async *runProject(project, mode, options) {
-        if (mode === "production")
-            await project.build();
-        const program = project.description(mode);
-        const development = mode === "development" && program.client && (program.client.start ?? true)
-            ? project.config.client?.development
-            : undefined;
-        const command = development?.startCommand;
-        if (command)
-            await assertAvailable(development.url);
-        const client = command ? new DevelopmentClient(command, project.directory) : undefined;
-        const controller = new AbortController();
-        const signal = this.signal(options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal);
-        try {
-            if (development)
-                yield* waitForDevelopmentClient(development, client, signal);
-            const lifecycle = this.program({ word: "run", program, options: options.options ?? {} }, signal);
-            const iterator = lifecycle[Symbol.asyncIterator]();
-            let lifecycleNext = iterator.next();
-            let exit = client?.exited();
-            let output = client?.outputAvailable();
-            while (true) {
-                for (const event of client?.drain() ?? [])
-                    yield event;
-                const outcome = await Promise.race([
-                    lifecycleNext.then(result => ({ source: "system", result })),
-                    ...(exit ? [exit.then(result => ({ source: "client", result }))] : []),
-                    ...(output ? [output.then(() => ({ source: "output" }))] : [])
-                ]);
-                if (outcome.source === "output") {
-                    output = client?.outputAvailable();
-                    continue;
-                }
-                if (outcome.source === "client") {
-                    exit = undefined;
-                    if (!client?.endingWasRequested())
-                        throw commandFailure(outcome.result);
-                    continue;
-                }
-                if (outcome.result.done)
-                    return;
-                yield outcome.result.value;
-                lifecycleNext = iterator.next();
-            }
-        }
-        finally {
-            controller.abort(new Error("The local Program run ended"));
-            await client?.stop();
-        }
-    }
-    program(request, signal) {
-        return this.lifecycle(request, signal);
-    }
-    control(request, signal) {
-        this.requireOpen();
-        return gatewayRequest(this.address, "system", request, this.signal(signal));
-    }
-    api(request, signal) {
-        this.requireOpen();
-        return gatewayRequest(this.address, "api", request, this.signal(signal));
-    }
-    lifecycle(request, signal) {
-        this.requireOpen();
-        return streamProgram(this.address, request, this.signal(signal));
-    }
-    signal(signal) {
-        return signal ? AbortSignal.any([signal, this.lifetime.signal]) : this.lifetime.signal;
-    }
-    requireOpen() {
-        if (this.closed)
-            throw new Error("This Gateway is closed");
-    }
-}