@crouton-kit/crouter 0.3.39 → 0.3.41

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

@@ -1,386 +0,0 @@
-import { setTimeout as delay } from 'node:timers/promises';
-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';
-// recreate-race-fix.md §3.2 — a volume GET is one cheap API call; 1s resolution is plenty
-// against an expected seconds-scale detach.
-const VOLUME_DETACH_POLL_MS = 1_000;
-// Expected wait is seconds (observed live); 120s is ~20-60x headroom over that, so this still
-// fails deterministically inside one wake's lifetime rather than hanging forever on a genuine
-// platform-side stuck detach.
-const VOLUME_DETACH_TIMEOUT_MS = 120_000;
-// orphan-cleanup-fix.md §4 — pause before the single bounded retry of a create that failed on a
-// server-side deployment transient, to let the platform-side condition clear.
-const CREATE_RETRY_DELAY_MS = 5_000;
-function stableRouteName(sandboxId) {
-    return `${sandboxId}-web`;
-}
-/** Mint a fresh per-generation sandbox name. `providerVolumeId` is the home's stable base
- *  (never suffixed), so names stay bounded: `hearth-zt-test-1-gmchq3x2a`. Sequential recreates
- *  are seconds apart, so a ms timestamp cannot collide for one home (recreate-race-fix.md §3.2). */
-function mintSandboxName(providerVolumeId) {
-    return `${providerVolumeId}-g${Date.now().toString(36)}`;
-}
-/** Escape a volumeId for safe use inside a RegExp so the generation-family anchor is exact —
- *  a home base name is user-influenced, so a literal `.` or `+` in it must not become a
- *  wildcard (orphan-cleanup-fix.md §3.1). */
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-/** Predicate matching every generation of a home's name family: the stable base itself, or a
- *  `<base>-g<suffix>` generation. The `-g` anchor is load-bearing — it prevents `<base>0-g…`
- *  (e.g. `hearth-zt-test-10-g…`) from matching base `hearth-zt-test-1` (orphan-cleanup-fix.md
- *  §3.1). Suffix chars are base36 (lowercase alnum), matching `mintSandboxName`. */
-function generationFamilyMatcher(volumeId) {
-    const gen = new RegExp(`^${escapeRegExp(volumeId)}-g[0-9a-z]+$`);
-    return (name) => name === volumeId || gen.test(name);
-}
-/** Serialize an arbitrary rejection to a non-empty marker string. `JSON.stringify` RETURNS
- *  `undefined` (does not throw) for `undefined`, a function, or a symbol — falling through to
- *  that would omit the `error` field from the marker's JSON line entirely, so fall back to
- *  `String(...)` whenever it yields `undefined` (matches wake.ts/relay.ts `serializeError`). */
-function serialize(error) {
-    if (error instanceof Error)
-        return error.message;
-    try {
-        const json = JSON.stringify(error);
-        return json === undefined ? String(error) : json;
-    }
-    catch {
-        return String(error);
-    }
-}
-/** Emit one structured stderr line for a recreate-lifecycle marker (sweep / volume_wait /
- *  cleanup_failed / create_retry). Single writer for all four so the JSON shape stays uniform
- *  and ops log-alerting keys on `marker` (orphan-cleanup-fix.md §3.3/§3.4/§4). */
-function emitMarker(marker, fields, level = 'info') {
-    process.stderr.write(`${JSON.stringify({ level, marker, ...fields })}\n`);
-}
-/** Classify a failed create+deploy as a retryable server-side deployment transient
- *  (orphan-cleanup-fix.md §4). Retryable IFF `status_code >= 500` OR `code === 'DEPLOYMENT_FAILED'`
- *  on the rejection object, with a message-substring fallback for Error-wrapped variants whose
- *  structured fields were flattened into `.message`. NEVER on 4xx — a 409 here is a real name
- *  conflict the design must surface, not absorb, so an explicit 4xx status vetoes the retry even
- *  if a `DEPLOYMENT_FAILED` code is also present. */
-function isRetryableDeploymentError(error) {
-    if (error !== null && typeof error === 'object') {
-        // Only the canonical HTTP-status keys — NOT a bare `status`, which is an overloaded field
-        // name some envelopes use for a non-HTTP state enum/count (MINOR-2).
-        const obj = error;
-        const status = [obj.status_code, obj.statusCode].find((v) => typeof v === 'number');
-        if (typeof status === 'number') {
-            if (status >= 400 && status < 500)
-                return false; // 4xx: real conflict, never absorb
-            if (status >= 500)
-                return true;
-        }
-        if (obj.code === 'DEPLOYMENT_FAILED')
-            return true;
-    }
-    // Fallback for Error-wrapped variants: only POSITIVE server-side signals, never inferring a 4xx.
-    const message = error instanceof Error ? error.message : typeof error === 'string' ? error : '';
-    if (message !== '') {
-        if (/DEPLOYMENT_FAILED/.test(message))
-            return true;
-        if (/\bstatus[_ ]?code\b\D{0,8}5\d\d/i.test(message))
-            return true;
-    }
-    return false;
-}
-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, sandboxId, machine) {
-    return {
-        providerName: 'blaxel',
-        providerSandboxId: sandboxId,
-        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 });
-            }
-            const route = await this.provider.publishHttpPort(current.providerSandboxId, {
-                machineId: current.providerSandboxId,
-                targetPort: this.config.webPort,
-                routeName: stableRouteName(current.providerSandboxId),
-                routeId: stableRouteName(current.providerSandboxId),
-            });
-            return refreshedPointers(current, this.provider, route, 'running', current.providerSandboxId, await this.getMachine(current.providerSandboxId));
-        }
-        // Terminated-machine branch (recreate-race-fix.md §3.4, orphan-cleanup-fix.md §3.3/§3.4):
-        // the crash-recovery path for a sandbox deleted recently out-of-band OR by a crashed/failed
-        // roll (a Fly redeploy restarting the CP mid-roll lands here on the next wake).
-        // `sweepAndReleaseVolume` destroys EVERY generation in this home's name family — including
-        // an unpointed leftover a crashed roll left holding the volume, which the old point-in-time
-        // attachedTo read could miss once Blaxel autonomously detached it on idle→STANDBY — then
-        // polls until the volume is confirmed free before minting a fresh name and creating.
-        await this.sweepAndReleaseVolume(current.providerVolumeId, current.homeId);
-        const { sandboxName, route, machine: created } = await this.createGeneration({
-            homeId: current.homeId,
-            tenantId: current.tenantId,
-            volumeId: current.providerVolumeId,
-            bootstrapScript,
-        });
-        return refreshedPointers(current, this.provider, route, 'running', sandboxName, created);
-    }
-    /** Destroy EVERY generation of this home via a deterministic name-family sweep — never a
-     *  point-in-time `attachedTo` read, which Blaxel's autonomous idle→STANDBY detach can race
-     *  ahead of, leaving a live orphan the read cannot see (orphan-cleanup-fix.md §1/§3.3). Then
-     *  poll until the platform reports the volume detached. Safe because at sweep time the
-     *  replacement does not exist yet (its name is minted after) and any live family member is by
-     *  construction either the generation being replaced or an uncommitted leftover — the home's
-     *  durable state is the volume, never a sandbox; one wake per home runs at a time. */
-    async sweepAndReleaseVolume(volumeId, homeId) {
-        // Scope the list to sandboxes Hearth tagged for THIS home (externalId = volumeId), then keep
-        // the name-family matcher as an AND-intersection on top (orphan-cleanup-fix MAJOR-1). The
-        // destroy set requires BOTH keys to agree — the tag says "Hearth created this for home X",
-        // the name says "it is in X's generation family" — so a single fault (a mistagged create, a
-        // future API silently ignoring the filter param) cannot widen the blast radius back onto a
-        // foreign home. Fail-safe defense-in-depth on a destructive op, NOT a lenient fallback.
-        const inFamily = generationFamilyMatcher(volumeId);
-        const doomed = (await this.provider.listMachines({ externalId: volumeId })).map((m) => m.machineId).filter(inFamily);
-        for (const name of doomed)
-            await this.provider.destroy(name); // sequential; destroy tolerates not_found
-        if (doomed.length > 0)
-            emitMarker('hearth.recreate.sweep', { home_id: homeId, volume_id: volumeId, destroyed: doomed });
-        await this.pollVolumeDetached(volumeId, homeId);
-    }
-    /** Poll the volume until the platform reports it detached — the create-precondition gate
-     *  (recreate-race-fix.md §3.2). Reads only; never destroys. Emits `hearth.recreate.volume_wait`
-     *  whenever it actually had to wait, so the re-proof can quantify headroom against the budget. */
-    async pollVolumeDetached(volumeId, homeId) {
-        const pollStartedAt = Date.now();
-        const deadline = pollStartedAt + VOLUME_DETACH_TIMEOUT_MS;
-        let waited = false;
-        for (;;) {
-            const attached = await this.provider.getVolumeAttachment(volumeId);
-            if (attached === null)
-                break;
-            waited = true;
-            if (Date.now() >= deadline) {
-                throw general(`volume ${volumeId} still attached to ${attached} after ${VOLUME_DETACH_TIMEOUT_MS}ms — cannot recreate home ${homeId}`, {
-                    homeId,
-                    volumeId,
-                    attached,
-                });
-            }
-            await delay(VOLUME_DETACH_POLL_MS);
-        }
-        if (waited) {
-            emitMarker('hearth.recreate.volume_wait', { home_id: homeId, volume_id: volumeId, waited_ms: Date.now() - pollStartedAt });
-        }
-    }
-    /** Create one fresh generation and bring it to a serving state (create → bootstrap exec →
-     *  waitForPort → publish → getMachine), with provider self-cleanup and a single bounded
-     *  retry (orphan-cleanup-fix.md §3.4/§4). Each attempt destroys the generation IT created if
-     *  anything from `createMachine` through the final `getMachine` fails — no code path exits
-     *  leaving a live generation it created and did not return — then rethrows the ORIGINAL error
-     *  (cleanup never masks it). On the first failure, if the error is a genuine server-side
-     *  deployment transient, pause, re-run ONLY the volume-free poll (the sweep already ran once),
-     *  mint a NEW name, and retry exactly once; a second failure throws. The sweep is the caller's
-     *  responsibility and runs before the first attempt only. */
-    async createGeneration(args) {
-        const attempt = async (sandboxName) => {
-            try {
-                await this.provider.createMachine({
-                    tenantId: args.tenantId,
-                    name: sandboxName,
-                    // Tag EVERY generation (first-name and retry-name alike) with the home's stable volume
-                    // id so the sweep's filtered list only ever sees this home's family (MAJOR-1).
-                    externalId: args.volumeId,
-                    ...(args.image === undefined ? {} : { image: args.image }),
-                    envs: guestEnv(this.config),
-                    volumeMount: { volumeName: args.volumeId, path: this.config.guestHome },
-                    ports: [{ target: this.config.webPort, protocol: 'HTTP' }],
-                });
-                await this.provider.exec(sandboxName, { command: args.bootstrapScript, background: true, cwd: this.config.guestHome });
-                await this.provider.waitForPort(sandboxName, this.config.webPort, { maxWaitMs: 60_000 });
-                const route = await this.provider.publishHttpPort(sandboxName, {
-                    machineId: sandboxName,
-                    targetPort: this.config.webPort,
-                    routeName: stableRouteName(sandboxName),
-                    routeId: stableRouteName(sandboxName),
-                });
-                return { route, machine: await this.getMachine(sandboxName) };
-            }
-            catch (error) {
-                // §3.4 self-cleanup: destroy the generation this attempt created; never mask the original.
-                await this.provider
-                    .destroy(sandboxName)
-                    .catch((cleanupErr) => emitMarker('hearth.recreate.cleanup_failed', { home_id: args.homeId, sandbox: sandboxName, error: serialize(cleanupErr) }, 'warn'));
-                throw error;
-            }
-        };
-        const firstName = mintSandboxName(args.volumeId);
-        try {
-            return { sandboxName: firstName, ...(await attempt(firstName)) };
-        }
-        catch (error) {
-            if (!isRetryableDeploymentError(error))
-                throw error;
-            emitMarker('hearth.recreate.create_retry', { home_id: args.homeId, discarded_generation: firstName, error: serialize(error) }, 'warn');
-            await delay(CREATE_RETRY_DELAY_MS);
-            // Re-run ONLY the poll — NOT a re-sweep. This sits outside attempt()'s try/catch, so a
-            // poll-timeout here would otherwise mask the ORIGINAL deployment error (MINOR-3). The
-            // original is what the caller must see (it is already recorded in the create_retry
-            // marker above); on a poll failure during the retry path, rethrow it, not the timeout.
-            try {
-                await this.pollVolumeDetached(args.volumeId, args.homeId);
-            }
-            catch {
-                throw error;
-            }
-            const secondName = mintSandboxName(args.volumeId);
-            return { sandboxName: secondName, ...(await attempt(secondName)) }; // second failure throws (self-cleaned)
-        }
-    }
-    /** Targeted destroy→recreate onto a SPECIFIC image (auto-upgrade roll and
-     *  rollback, design §4/§5). Unlike `wake()`'s standby-resume path, this is the ONE path
-     *  that force-destroys the home's sandboxes before recreating. Cleanup is a deterministic
-     *  name-family sweep (orphan-cleanup-fix.md §3.3): every generation of this home is destroyed
-     *  before the fresh one is minted, so a failed roll-forward generation can never survive as a
-     *  live orphan even after Blaxel autonomously detaches it from the volume. The recreate lands
-     *  on a FRESH sandbox name every call — a name that has never existed cannot 409 against a
-     *  lingering same-name delete. The durable volume is a separate resource and is NEVER touched
-     *  (flow-D durability) — user state is byte-identical across the flip, which is exactly what
-     *  makes both the upgrade and the rollback lossless. The new `providerSandboxId` is returned on
-     *  the refresh; callers persist it (`refreshProviderPointers` treats it as a refreshable
-     *  pointer). `templateVersion` is baked into the bootstrap's fail-fast version assert (the
-     *  baked crtr must match) AND reported back so the CP records the target version — the caller
-     *  still independently asserts `crtr sys version` in-guest before trusting it (wake.ts
-     *  `rollHome`/`rollbackHome`, against `refresh.providerSandboxId`, never a stale captured
-     *  name). */
-    async recreateOnImage(homeInput, imageRef, templateVersion) {
-        const current = ensureReadyHome(homeInput);
-        if (imageRef.trim() === '') {
-            throw general(`recreateOnImage for home ${current.homeId} requires a non-empty image ref`, { homeId: current.homeId });
-        }
-        if (templateVersion.trim() === '') {
-            throw general(`recreateOnImage for home ${current.homeId} requires a non-empty template version`, { homeId: current.homeId });
-        }
-        // Sweep the whole name family (destroys the failed roll-forward generation whether or not it
-        // still holds the volume — the exact Run-3 orphan gap) then wait until the volume is confirmed
-        // detached before minting a fresh name and creating (orphan-cleanup-fix.md §3.3).
-        await this.sweepAndReleaseVolume(current.providerVolumeId, current.homeId);
-        const bootstrapScript = buildBootstrapScript({
-            guestHome: this.config.guestHome,
-            crtrVersion: templateVersion,
-            relayToken: current.relayToken,
-            webPort: this.config.webPort,
-            nodeId: current.homeAgentTarget,
-            piAuthJson: this.config.piAuthJson,
-            piPackages: this.config.piPackages,
-            isFirstProvision: false,
-        });
-        const { sandboxName, route, machine } = await this.createGeneration({
-            homeId: current.homeId,
-            tenantId: current.tenantId,
-            volumeId: current.providerVolumeId,
-            bootstrapScript,
-            image: imageRef,
-        });
-        // Report the TARGET version, not the provider's construction-time value:
-        // the sandbox was recreated on `imageRef`, whose baked crtr is `templateVersion`.
-        return {
-            ...refreshedPointers(current, this.provider, route, 'running', sandboxName, machine),
-            templateVersion,
-        };
-    }
-    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, current.providerSandboxId, 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

@@ -1,36 +0,0 @@
-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 function isMissingResourceError(error: unknown): boolean;
-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>;
-    listMachines(filter?: {
-        externalId?: string;
-    }): 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>;
-    getVolumeAttachment(volumeId: string): Promise<string | null>;
-}
-export {};