@crouton-kit/crouter 0.3.32 → 0.3.34

package/dist/core/hearth/providers/blaxel-home.js

@@ -0,0 +1,136 @@
+import { general } from '../../errors.js';
+import { nowIso } from '../../fs-utils.js';
+import { guestEnv } from '../guest-env.js';
+import { buildBootstrapScript } from './blaxel-bootstrap.js';
+import { BlaxelMachineProvider } from './blaxel.js';
+function stableRouteName(home) {
+    return `${home.providerSandboxId}-web`;
+}
+function ensureReadyHome(input) {
+    if (input.providerName !== 'blaxel') {
+        throw general(`unsupported Hearth home provider ${input.providerName}`, { providerName: input.providerName });
+    }
+    if (typeof input.providerSandboxId !== 'string' || input.providerSandboxId === '') {
+        throw general(`home ${input.homeId} is missing providerSandboxId`, { homeId: input.homeId });
+    }
+    if (typeof input.providerVolumeId !== 'string' || input.providerVolumeId === '') {
+        throw general(`home ${input.homeId} is missing providerVolumeId`, { homeId: input.homeId });
+    }
+    if (typeof input.homeAgentTarget !== 'string' || input.homeAgentTarget === '') {
+        throw general(`home ${input.homeId} is missing homeAgentTarget`, { homeId: input.homeId });
+    }
+    if (typeof input.relayToken !== 'string' || input.relayToken === '') {
+        throw general(`home ${input.homeId} is missing resolved relayToken`, { homeId: input.homeId });
+    }
+    return input;
+}
+function isRunningMachine(machine) {
+    return machine !== null && machine.state !== 'terminated';
+}
+function previewEndpoint(route, fallback) {
+    return route.concreteUrl ?? route.url ?? fallback ?? null;
+}
+function refreshedPointers(home, provider, route, status, machine) {
+    return {
+        providerName: 'blaxel',
+        providerSandboxId: home.providerSandboxId,
+        providerVolumeId: home.providerVolumeId,
+        previewEndpoint: route === null ? (home.previewEndpoint ?? null) : previewEndpoint(route, home.previewEndpoint),
+        route,
+        homeAgentTarget: home.homeAgentTarget,
+        relayAuthRef: home.relayAuthRef ?? null,
+        templateVersion: provider.templateVersion,
+        status,
+        machine,
+        updatedAt: nowIso(),
+    };
+}
+export class BlaxelHomeBackend {
+    config;
+    provider;
+    constructor(config, provider) {
+        this.config = config;
+        this.provider = provider ?? new BlaxelMachineProvider({ image: config.imageRef, templateVersion: config.templateVersion, volumeSizeGb: config.volumeSizeGb });
+    }
+    async wake(homeInput) {
+        const current = ensureReadyHome(homeInput);
+        const machine = await this.getMachine(current.providerSandboxId);
+        const bootstrapScript = buildBootstrapScript({
+            guestHome: this.config.guestHome,
+            crtrVersion: this.provider.templateVersion,
+            relayToken: current.relayToken,
+            webPort: this.config.webPort,
+            nodeId: current.homeAgentTarget,
+            piAuthJson: this.config.piAuthJson,
+            piPackages: this.config.piPackages,
+            isFirstProvision: false,
+        });
+        if (isRunningMachine(machine)) {
+            // Standby resume (R-SUSP-2/R-WAKE-3): the sandbox already exists — never call
+            // createMachine() here. Probing the port is enough to make Blaxel transparently restore
+            // a snapshot-paused sandbox; the broker pid inside the guest is untouched either way, and
+            // nothing on this host-side path invokes reviveNode() (that launcher is for crtr's own
+            // node engine, not a guest process — the provider layer never imports it). The exec
+            // fallback below only re-runs the idempotent in-guest bootstrap when the port still isn't
+            // answering after a snapshot-resume window; it is not a recreate.
+            try {
+                await this.provider.waitForPort(current.providerSandboxId, this.config.webPort, { maxWaitMs: 30_000 });
+            }
+            catch {
+                await this.provider.exec(current.providerSandboxId, { command: bootstrapScript, background: true, cwd: this.config.guestHome });
+                await this.provider.waitForPort(current.providerSandboxId, this.config.webPort, { maxWaitMs: 30_000 });
+            }
+        }
+        else {
+            await this.provider.createMachine({
+                tenantId: current.tenantId,
+                name: current.providerSandboxId,
+                envs: guestEnv(this.config),
+                volumeMount: { volumeName: current.providerVolumeId, path: this.config.guestHome },
+                ports: [{ target: this.config.webPort, protocol: 'HTTP' }],
+            });
+            await this.provider.exec(current.providerSandboxId, { command: bootstrapScript, background: true, cwd: this.config.guestHome });
+            await this.provider.waitForPort(current.providerSandboxId, this.config.webPort, { maxWaitMs: 60_000 });
+        }
+        const route = await this.provider.publishHttpPort(current.providerSandboxId, {
+            machineId: current.providerSandboxId,
+            targetPort: this.config.webPort,
+            routeName: stableRouteName(current),
+            routeId: stableRouteName(current),
+        });
+        return refreshedPointers(current, this.provider, route, 'running', await this.getMachine(current.providerSandboxId));
+    }
+    async suspend(homeInput) {
+        const current = ensureReadyHome(homeInput);
+        const machine = await this.getMachine(current.providerSandboxId);
+        // Snapshot-never-kill (P3.4): this method must never call `provider.destroy()` or
+        // `provider.createMachine()` — those are the only ways the underlying sandbox is torn down
+        // or relaunched, and neither belongs on the suspend path. Blaxel (@blaxel/core 0.2.94) has
+        // no imperative pause/standby call to invoke here; `snapshotEnabled` (set at create time in
+        // blaxel.ts) is the only discoverable seam, and it makes idle snapshot-pause a platform-
+        // managed background behavior rather than something this method triggers. So suspend() does
+        // not fabricate a 'suspended' status the way a real pause API's response would justify —
+        // doing so would tell the CP registry a snapshot happened when nothing was asked of the
+        // provider. It fails closed instead: assert the sandbox still exists (a missing/terminated
+        // sandbox cannot be "suspended", it must be re-provisioned through wake()), and return the
+        // provider's own observed status untouched so the CP can tell "confirmed paused" from
+        // "still running, waiting on Blaxel's own idle timer" rather than trusting an invented one.
+        if (machine === null) {
+            throw general(`cannot suspend home ${current.homeId}: backing sandbox ${current.providerSandboxId} is not present`, {
+                homeId: current.homeId,
+                providerSandboxId: current.providerSandboxId,
+            });
+        }
+        return refreshedPointers(current, this.provider, null, machine.state, machine);
+    }
+    async getMachine(machineId) {
+        const machine = await this.provider.getMachine(machineId);
+        return machine.state === 'terminated' ? null : machine;
+    }
+    /** P2.6 stdin-capable exec seam, passed through verbatim — the `HomeBackend` interface is the
+     *  only door CP code uses to reach it (see `provider.ts`), so callers never import
+     *  `BlaxelMachineProvider` directly. */
+    async exec(machineId, input) {
+        return this.provider.exec(machineId, input);
+    }
+}

package/dist/core/hearth/providers/blaxel.d.ts

@@ -0,0 +1,31 @@
+import type { MachineRef, RouteRef } from '../types.js';
+import type { CreateMachineInput, DestroyOutcome, ExecInput, ExecResult, HealthResult, MachineProvider, PublishHttpPortInput, VolumeRef } from './types.js';
+interface BlaxelMachineProviderOptions {
+    region?: string;
+    memory?: number;
+    image?: string;
+    templateVersion?: string;
+    volumeSizeGb?: number;
+}
+export declare class BlaxelMachineProvider implements MachineProvider {
+    readonly providerName: "blaxel";
+    readonly imageRef: string;
+    readonly templateVersion: string;
+    readonly volumeSizeGb: number;
+    private readonly config;
+    constructor(options?: BlaxelMachineProviderOptions);
+    createVolume(input: {
+        name: string;
+    }): Promise<VolumeRef>;
+    createMachine(input: CreateMachineInput): Promise<MachineRef>;
+    getMachine(machineId: string): Promise<MachineRef>;
+    exec(machineId: string, input: ExecInput): Promise<ExecResult>;
+    waitForPort(machineId: string, port: number, opts?: {
+        maxWaitMs?: number;
+    }): Promise<void>;
+    publishHttpPort(machineId: string, input: PublishHttpPortInput): Promise<RouteRef>;
+    health(): Promise<HealthResult>;
+    destroy(machineId: string): Promise<DestroyOutcome>;
+    destroyVolume(volumeId: string): Promise<DestroyOutcome>;
+}
+export {};

package/dist/core/hearth/providers/blaxel.js

@@ -0,0 +1,282 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { SandboxInstance, VolumeInstance } from '@blaxel/core';
+import { general } from '../../errors.js';
+const TERMINATED_STATES = new Set(['TERMINATED', 'DELETING', 'DEACTIVATED', 'DEACTIVATING', 'FAILED']);
+const PROVISIONING_STATES = new Set(['UPLOADING', 'BUILDING', 'DEPLOYING', 'BUILT']);
+function readCrtrVersion() {
+    const file = new URL('../../../../package.json', import.meta.url);
+    const pkg = JSON.parse(readFileSync(file, 'utf8'));
+    if (typeof pkg.version !== 'string' || pkg.version.trim() === '') {
+        throw general('missing crtr package version', { packageJson: file.pathname });
+    }
+    return pkg.version;
+}
+function defaultImageRef(templateVersion) {
+    return `crouter-hearth-home-${templateVersion.replace(/\./g, '-')}`;
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function shStatus(status) {
+    if (status === undefined || status === null || status === '')
+        return 'unknown';
+    const normalized = status.toUpperCase();
+    if (normalized === 'DEPLOYED')
+        return 'running';
+    if (normalized === 'RUNNING' || normalized === 'STANDBY')
+        return 'running';
+    if (TERMINATED_STATES.has(normalized))
+        return 'terminated';
+    if (PROVISIONING_STATES.has(normalized))
+        return 'provisioning';
+    if (normalized === 'PAUSED' || normalized === 'SUSPENDED')
+        return 'paused';
+    return status;
+}
+function record(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    return value;
+}
+function rawFromSandbox(sandbox) {
+    return {
+        metadata: sandbox.metadata,
+        status: sandbox.status ?? null,
+        spec: sandbox.spec,
+    };
+}
+function rawFromVolume(volume) {
+    return {
+        metadata: volume.metadata,
+        status: volume.status ?? null,
+        spec: volume.spec,
+    };
+}
+function toEnvVars(envs) {
+    if (envs === undefined)
+        return undefined;
+    return Object.entries(envs)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([name, value]) => ({ name, value }));
+}
+function resolveExecCommand(input) {
+    const hasCommand = typeof input.command === 'string';
+    const hasArgv = input.argv !== undefined;
+    if (hasCommand === hasArgv) {
+        throw general('provider exec requires exactly one of command or argv', { hasCommand, hasArgv });
+    }
+    if (hasCommand) {
+        const command = input.command?.trim() ?? '';
+        if (command === '')
+            throw general('provider exec command must not be empty');
+        return command;
+    }
+    const argv = input.argv ?? [];
+    if (argv.length === 0)
+        throw general('provider exec argv must not be empty');
+    for (const arg of argv) {
+        if (typeof arg !== 'string' || arg === '')
+            throw general('provider exec argv contains an empty argument');
+    }
+    return argv.map(shellQuote).join(' ');
+}
+function isMissingResourceError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /\b(not found|404|does not exist|missing)\b/i.test(message);
+}
+function toMachineRef(sandbox) {
+    const metadata = sandbox.metadata;
+    const status = sandbox.status ?? undefined;
+    return {
+        providerName: 'blaxel',
+        machineId: metadata.name,
+        state: shStatus(status),
+        updatedAt: metadata.updatedAt ?? null,
+        raw: rawFromSandbox(sandbox),
+    };
+}
+function toRouteRef(machineId, targetPort, preview, raw) {
+    const url = preview.spec.url ?? null;
+    return {
+        routeId: preview.name,
+        machineId,
+        targetPort,
+        url,
+        concreteUrl: url,
+        concreteUrlSource: 'provider',
+        raw: raw ?? null,
+    };
+}
+export class BlaxelMachineProvider {
+    providerName = 'blaxel';
+    imageRef;
+    templateVersion;
+    volumeSizeGb;
+    config;
+    constructor(options = {}) {
+        const templateVersion = options.templateVersion ?? readCrtrVersion();
+        const volumeSizeGb = options.volumeSizeGb ?? 10;
+        if (!Number.isInteger(volumeSizeGb) || volumeSizeGb < 10) {
+            throw general('Blaxel Hearth home volume must be at least 10 GB', { volumeSizeGb });
+        }
+        this.imageRef = options.image ?? defaultImageRef(templateVersion);
+        this.templateVersion = templateVersion;
+        this.volumeSizeGb = volumeSizeGb;
+        this.config = {
+            region: options.region ?? 'us-west-2',
+            memory: options.memory ?? 2048,
+            image: this.imageRef,
+            templateVersion: this.templateVersion,
+            volumeSizeGb: this.volumeSizeGb,
+        };
+    }
+    async createVolume(input) {
+        const volume = await VolumeInstance.createIfNotExists({ name: input.name, size: this.config.volumeSizeGb * 1024, region: this.config.region });
+        return {
+            volumeId: volume.metadata.name ?? input.name,
+            name: input.name,
+            raw: rawFromVolume(volume),
+        };
+    }
+    async createMachine(input) {
+        const sandbox = await SandboxInstance.createIfNotExists({
+            name: input.name ?? input.tenantId,
+            image: this.config.image,
+            memory: this.config.memory,
+            region: this.config.region,
+            volumes: input.volumeMount === undefined || input.volumeMount === null ? undefined : [{ name: input.volumeMount.volumeName, mountPath: input.volumeMount.path, readOnly: false }],
+            envs: toEnvVars(input.envs),
+            ports: input.ports?.map((port) => ({ target: port.target, protocol: port.protocol })),
+            // Snapshot-never-kill (P3.4): this is the only discoverable Blaxel suspend/standby
+            // primitive (@blaxel/core 0.2.94) — there is no imperative pause()/standby() call, only
+            // this create-time runtime flag. Once set, Blaxel's platform idle timer snapshots and
+            // transparently restores the sandbox on the next request instead of tearing it down.
+            // Every Hearth home is created with this on; it is never optional per-home.
+            snapshotEnabled: true,
+        });
+        await sandbox.wait({ maxWait: 90_000, interval: 500 }).catch(() => sandbox);
+        return toMachineRef(sandbox);
+    }
+    async getMachine(machineId) {
+        try {
+            const sandbox = await SandboxInstance.get(machineId);
+            return toMachineRef(sandbox);
+        }
+        catch (error) {
+            if (!isMissingResourceError(error))
+                throw error;
+            return {
+                providerName: 'blaxel',
+                machineId,
+                state: 'terminated',
+                raw: { error: error instanceof Error ? error.message : String(error) },
+            };
+        }
+    }
+    async exec(machineId, input) {
+        if (input.stdin !== undefined && input.background === true) {
+            throw general('provider exec stdin is not supported for background commands', { machineId });
+        }
+        const sandbox = await SandboxInstance.get(machineId);
+        const stdinBody = input.stdin;
+        const stdinPath = stdinBody === undefined ? null : `/tmp/crtr-hearth-exec-${randomUUID()}.stdin`;
+        if (stdinPath !== null && stdinBody !== undefined) {
+            if (stdinBody instanceof Uint8Array) {
+                await sandbox.fs.writeBinary(stdinPath, stdinBody);
+            }
+            else {
+                await sandbox.fs.write(stdinPath, stdinBody);
+            }
+        }
+        const command = stdinPath === null ? resolveExecCommand(input) : `${resolveExecCommand(input)} < ${shellQuote(stdinPath)}`;
+        let response;
+        try {
+            response = await sandbox.process.exec({
+                command,
+                env: input.env,
+                timeout: Math.ceil((input.timeoutMs ?? 55_000) / 1000),
+                workingDir: input.cwd,
+                ...(input.background === true ? { waitForCompletion: false } : { waitForCompletion: true }),
+            });
+        }
+        finally {
+            if (stdinPath !== null)
+                await sandbox.fs.rm(stdinPath).catch(() => undefined);
+        }
+        const result = record(response) ?? {};
+        return {
+            exitCode: typeof result.exitCode === 'number' ? result.exitCode : null,
+            timedOut: false,
+            stdout: typeof result.stdout === 'string' ? result.stdout : typeof result.logs === 'string' ? result.logs : '',
+            stderr: typeof result.stderr === 'string' ? result.stderr : '',
+            raw: result,
+        };
+    }
+    async waitForPort(machineId, port, opts) {
+        const sandbox = await SandboxInstance.get(machineId);
+        try {
+            await sandbox.process.exec({
+                command: 'true',
+                waitForPorts: [port],
+                waitForCompletion: true,
+                timeout: Math.ceil((opts?.maxWaitMs ?? 60_000) / 1000),
+            });
+        }
+        catch (error) {
+            throw general(`blaxel sandbox ${machineId} never opened port ${port}`, {
+                machineId,
+                port,
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    async publishHttpPort(machineId, input) {
+        const sandbox = await SandboxInstance.get(machineId);
+        const previewName = input.routeName ?? input.routeId ?? `${machineId}-http`;
+        const preview = await sandbox.previews.createIfNotExists({
+            metadata: { name: previewName },
+            spec: { port: input.targetPort, public: true },
+        });
+        return toRouteRef(machineId, input.targetPort, { name: preview.name, spec: preview.spec }, {
+            preview: { metadata: preview.metadata, spec: preview.spec },
+            input,
+        });
+    }
+    async health() {
+        try {
+            await VolumeInstance.list();
+            return { ok: true, providerName: 'blaxel' };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                providerName: 'blaxel',
+                status: error instanceof Error ? error.message : String(error),
+                raw: { error: error instanceof Error ? error.message : String(error) },
+            };
+        }
+    }
+    async destroy(machineId) {
+        try {
+            await SandboxInstance.delete(machineId);
+            return { kind: 'destroyed' };
+        }
+        catch (error) {
+            if (isMissingResourceError(error))
+                return { kind: 'not_found' };
+            throw error;
+        }
+    }
+    async destroyVolume(volumeId) {
+        try {
+            await VolumeInstance.delete(volumeId);
+            return { kind: 'destroyed' };
+        }
+        catch (error) {
+            if (isMissingResourceError(error))
+                return { kind: 'not_found' };
+            throw error;
+        }
+    }
+}

package/dist/core/hearth/providers/types.d.ts

@@ -0,0 +1,77 @@
+import type { MachineId, MachineRef, MachineState, M0Config, RouteRef } from '../types.js';
+export interface ExecResult {
+    exitCode: number | null;
+    timedOut: boolean;
+    stdout: string;
+    stderr: string;
+    raw?: Record<string, unknown> | null;
+}
+export interface ExecInput {
+    command?: string;
+    argv?: readonly string[];
+    stdin?: string | Uint8Array;
+    timeoutMs?: number;
+    background?: boolean;
+    env?: Record<string, string>;
+    cwd?: string;
+}
+export interface VolumeRef {
+    volumeId: string;
+    name: string;
+    raw?: Record<string, unknown> | null;
+}
+export interface CreateMachineInput {
+    tenantId: string;
+    template?: string | null;
+    envs?: Record<string, string>;
+    enableNetwork?: boolean;
+    name?: string | null;
+    ports?: {
+        target: number;
+        protocol: 'HTTP';
+    }[];
+    volumeMount?: {
+        volumeName: string;
+        path: string;
+    } | null;
+    raw?: Record<string, unknown> | null;
+}
+export interface PublishHttpPortInput {
+    machineId: MachineId;
+    targetPort: number;
+    subdomain?: string | null;
+    routeId?: string | null;
+    routeName?: string | null;
+    raw?: Record<string, unknown> | null;
+}
+export interface HealthResult {
+    ok: boolean;
+    providerName: string;
+    status?: string | null;
+    raw?: Record<string, unknown> | null;
+}
+export type DestroyOutcome = {
+    kind: 'destroyed';
+} | {
+    kind: 'not_found';
+};
+export interface MachineProvider {
+    readonly providerName: 'blaxel';
+    readonly imageRef: string;
+    readonly templateVersion: string;
+    readonly volumeSizeGb: number;
+    createVolume(input: {
+        name: string;
+    }): Promise<VolumeRef>;
+    createMachine(input: CreateMachineInput): Promise<MachineRef>;
+    getMachine(machineId: MachineId): Promise<MachineRef>;
+    exec(machineId: MachineId, input: ExecInput): Promise<ExecResult>;
+    waitForPort(machineId: MachineId, port: number, opts?: {
+        maxWaitMs?: number;
+    }): Promise<void>;
+    publishHttpPort(machineId: MachineId, input: PublishHttpPortInput): Promise<RouteRef>;
+    health(): Promise<HealthResult>;
+    destroy(machineId: MachineId): Promise<DestroyOutcome>;
+    destroyVolume(volumeId: string): Promise<DestroyOutcome>;
+}
+export type { MachineState, M0Config, RouteRef };

package/dist/core/hearth/registry.d.ts

@@ -0,0 +1,15 @@
+import type { HomeRecord, TenantId } from './types.js';
+export type RegistryData = Record<TenantId, HomeRecord>;
+export declare class RegistryLockError extends Error {
+    readonly lockPath: string;
+    readonly holder: string;
+    readonly ageMs: number | null;
+    constructor(lockPath: string, holder: string, ageMs: number | null);
+}
+export declare function acquireRegistryLock(registryPath: string): () => void;
+export declare function readRegistry(registryPath: string): RegistryData;
+export declare function writeRegistry(registryPath: string, data: RegistryData): RegistryData;
+export declare function getHome(registryPath: string, tenantId: TenantId): HomeRecord | null;
+export declare function putHome(registryPath: string, home: HomeRecord): HomeRecord;
+export declare function updateHome(registryPath: string, tenantId: TenantId, mutate: (home: HomeRecord) => HomeRecord | void): HomeRecord;
+export declare function listHomes(registryPath: string): HomeRecord[];