@wenathlan/saddle 2.0.154 → 2.0.155

package/dist/sandboxqueue.js

@@ -1,201 +0,0 @@
-/**
- * sandboxqueue.ts — the sandbox lifecycle queue of saddle.
- *
- * one sandbox walks a single linear machine: creating -> starting ->
- * running -> stopping -> stopped, with the supervision states cancelled,
- * failed and timedout closing the paths out. every intermediate state
- * carries a per-state time budget; the health-check tick reaps entries
- * whose budget expired (the ttl reaper pattern of webserver.ts and the
- * pool reaper of opensandbox). transitions are validated by a pure
- * transition table so both callers and tests exercise the same guard.
- *
- * the module is deliberately pure: no timers of its own, no dom, no node
- * builtins, an injectable clock. hosts drive it — webserver.ts ramps
- * the api lifecycle with a timeout, the ttl reaper sweeps every minute,
- * and orchestrator.ts owns the fifteen state vm plane machine; this
- * module is the queue-level complement those surfaces can delegate to
- * (wire point documented in the webserver statemachine context: the
- * api states map as created->creating, expired->timedout,
- * destroyed->stopped).
- *
- * studied competitors shaping the contract: daytonaio/daytona (sandbox
- * states creating/starting/started/stopping/stopped/error with the
- * -ing intermediates) and opensandbox-group/opensandbox (Creating ->
- * Running -> Deleting -> Deleted with 409 on state conflicting
- * operations and a pool acquisition that fails fast with Retry-After).
- */
-/** phases that end the queue entry (no further transition is legal). */
-export const SANDBOXTERMINALPHASES = [
-    'stopped',
-    'cancelled',
-    'failed',
-    'timedout',
-];
-/** the legal transitions of the single lifecycle machine. */
-const sandboxtransitions = {
-    creating: ['starting', 'cancelled', 'failed', 'timedout'],
-    starting: ['running', 'cancelled', 'failed', 'timedout'],
-    running: ['stopping', 'cancelled', 'failed', 'timedout'],
-    stopping: ['stopped', 'failed', 'timedout'],
-    stopped: [],
-    cancelled: [],
-    failed: [],
-    timedout: [],
-};
-/** the typed queue failure, traceable to the entry and both phases. */
-export class sandboxqueueerror extends Error {
-    /** machine readable failure code. */
-    code;
-    /** the entry the failure belongs to. */
-    id;
-    /** the phase the entry was in (or from), when known. */
-    from;
-    /** the requested target phase, when known. */
-    to;
-    constructor(code, id, from, to, message) {
-        super(message ??
-            `sandbox queue ${code} for ${id}${from === null ? '' : ` (from ${from})`}${to === null ? '' : ` to ${to}`}`);
-        this.name = 'sandboxqueueerror';
-        this.code = code;
-        this.id = id;
-        this.from = from;
-        this.to = to;
-    }
-}
-/* ------------------------------------------------------------------ */
-/* pure guards                                                         */
-/* ------------------------------------------------------------------ */
-/** checks whether a phase change is legal on the single machine. */
-export function cansandboxstep(from, to) {
-    return sandboxtransitions[from].includes(to);
-}
-/** reports whether a phase is terminal. */
-export function issandboxterminal(phase) {
-    return SANDBOXTERMINALPHASES.includes(phase);
-}
-/**
- * creates the lifecycle queue. the queue validates every transition,
- * stamps deadlines from the budgets and reaps expired entries on the
- * health-check tick; the host decides when to tick.
- *
- * @param options the budgets and event ring capacity.
- * @returns the queue facade (add, step, cancel, healthcheck, status,
- *   list, events, size).
- */
-export function createsandboxqueue(options) {
-    const budgets = options?.budgets ?? {
-        creating: 125,
-        starting: 125,
-        stopping: 30000,
-    };
-    const eventcap = options?.eventcap ?? 100;
-    const entries = new Map();
-    const ring = [];
-    /** stamps one event into the bounded ring. */
-    function record(id, from, to, at, reason) {
-        ring.push({ id, from, to, at, reason });
-        if (ring.length > eventcap) {
-            ring.splice(0, ring.length - eventcap);
-        }
-    }
-    /** resolves the deadline of a phase from the budget table. */
-    function deadlinefor(state, now) {
-        const budget = budgets[state];
-        return typeof budget === 'number' && budget > 0 ? now + budget : null;
-    }
-    function statusOf(entry, now) {
-        return {
-            id: entry.id,
-            state: entry.state,
-            enteredat: entry.enteredat,
-            deadline: entry.deadline,
-            age: Math.max(0, now - entry.enteredat),
-            terminal: issandboxterminal(entry.state),
-        };
-    }
-    return {
-        add(id, now = Date.now()) {
-            if (entries.has(id)) {
-                throw new sandboxqueueerror('duplicate-sandbox', id, null, null);
-            }
-            const entry = {
-                id,
-                state: 'creating',
-                enteredat: now,
-                deadline: deadlinefor('creating', now),
-            };
-            entries.set(id, entry);
-            record(id, 'creating', 'creating', now, 'requested');
-            return entry;
-        },
-        step(id, to, now = Date.now()) {
-            const entry = entries.get(id);
-            if (entry === undefined) {
-                throw new sandboxqueueerror('unknown-sandbox', id, null, to);
-            }
-            if (!cansandboxstep(entry.state, to)) {
-                if (issandboxterminal(entry.state)) {
-                    throw new sandboxqueueerror('terminal-phase', id, entry.state, to, `sandbox ${id} is terminal (${entry.state}); ${to} is unreachable`);
-                }
-                throw new sandboxqueueerror('invalid-transition', id, entry.state, to, `sandbox ${id} cannot transition ${entry.state} -> ${to}`);
-            }
-            const from = entry.state;
-            entry.state = to;
-            entry.enteredat = now;
-            entry.deadline = deadlinefor(to, now);
-            record(id, from, to, now, 'requested');
-            return entry;
-        },
-        cancel(id, now = Date.now()) {
-            const entry = entries.get(id);
-            if (entry === undefined) {
-                throw new sandboxqueueerror('unknown-sandbox', id, null, 'cancelled');
-            }
-            const from = entry.state;
-            if (!cansandboxstep(from, 'cancelled')) {
-                if (issandboxterminal(from)) {
-                    throw new sandboxqueueerror('terminal-phase', id, from, 'cancelled', `sandbox ${id} is terminal (${from}); cancellation is unreachable`);
-                }
-                throw new sandboxqueueerror('invalid-transition', id, from, 'cancelled', `sandbox ${id} cannot be cancelled from ${from}`);
-            }
-            entry.state = 'cancelled';
-            entry.enteredat = now;
-            entry.deadline = null;
-            record(id, from, 'cancelled', now, 'cancel');
-            return entry;
-        },
-        healthcheck(now = Date.now()) {
-            const reaped = [];
-            for (const entry of entries.values()) {
-                if (entry.deadline === null || entry.deadline > now || issandboxterminal(entry.state)) {
-                    continue;
-                }
-                const from = entry.state;
-                entry.state = 'timedout';
-                entry.enteredat = now;
-                entry.deadline = null;
-                record(entry.id, from, 'timedout', now, 'timeout');
-                reaped.push(entry.id);
-            }
-            return reaped;
-        },
-        status(id, now = Date.now()) {
-            const entry = entries.get(id);
-            if (entry === undefined) {
-                throw new sandboxqueueerror('unknown-sandbox', id, null, null);
-            }
-            return statusOf(entry, now);
-        },
-        list(now = Date.now()) {
-            return [...entries.values()]
-                .map((entry) => statusOf(entry, now))
-                .sort((a, b) => (a.id < b.id ? -1 : 1));
-        },
-        events() {
-            return [...ring];
-        },
-        size() {
-            return entries.size;
-        },
-    };
-}

package/dist/sandboxquota.d.ts

@@ -1,121 +0,0 @@
-/**
- * sandboxquota.ts — the per-account resource quota ledger of saddle.
- *
- * every account holds counters of the resources its live sandboxes
- * allocate (sandbox count, vcpus, ramgb, vgpus, diskgb) against a
- * limits table. the limits are a plain parameter — the operator's plan
- * table comes from config or the database and never lives in code; an
- * absent limit means unlimited, mirroring the SADDLE_MAX_SANDBOXES
- * convention of webserver.ts (0 or unset means unlimited).
- *
- * the ledger keeps reservations and releases in balance with a simple
- * reconciliation: the host projects the authoritative usage (for
- * example from the sqlite sandboxes rows) and reconcile() overwrites
- * the in-memory counters with it, so drift from admin deletes, restarts
- * or crashes self-heals on the next create.
- *
- * the module is pure: zero imports, zero dom, zero node builtins, a
- * Map per account, typed traceable errors (quotaexceedederror carries
- * the resource, the request, the limit and the remaining headroom).
- *
- * competitor sources shaping the contract: daytonaio/daytona (tenant
- * resource quota admission with per-sandbox cpu/memory/gpu quota
- * fields and the gpu allocator acquire/release pair around create) and
- * opensandbox-group/opensandbox (namespace ResourceQuota admission —
- * the sandbox is not admitted when the quota is exhausted — and the
- * pool acquisition that fails fast when capacity stays unavailable).
- *
- * wire point: webserver.ts createsandbox reconciles the owning
- * account from store.listsandboxesbyuser rows and reserves the new
- * sandbox; destroysandbox releases it. limits come from
- * accountlimitsfromenv(process.env) and stay unlimited when unset.
- */
-/** the resource counters one account allocates through live sandboxes. */
-export type accountusage = {
-    sandboxes: number;
-    vcpus: number;
-    ramgb: number;
-    vgpus: number;
-    diskgb: number;
-};
-/** the per-account limits; an absent or non-positive field is unlimited. */
-export type accountlimits = {
-    readonly sandboxes?: number;
-    readonly vcpus?: number;
-    readonly ramgb?: number;
-    readonly vgpus?: number;
-    readonly diskgb?: number;
-};
-/** one resource wish (a partial usage delta). */
-export type resourcewish = Partial<accountusage>;
-/** failure codes carried by quotaerror. */
-export type quotaerrorcode = 'invalid-wish' | 'quota-exceeded';
-/** the typed quota failure, traceable to the account and the resource. */
-export declare class quotaerror extends Error {
-    /** machine readable failure code. */
-    readonly code: quotaerrorcode;
-    /** the account the failure belongs to. */
-    readonly accountid: string;
-    /** the resource that failed (or 'wish' for malformed deltas). */
-    readonly resource: string;
-    /** the requested amount (null when the wish itself was malformed). */
-    readonly requested: number | null;
-    /** the active limit (null when unlimited). */
-    readonly limit: number | null;
-    /** the headroom the account had before the request. */
-    readonly available: number | null;
-    constructor(code: quotaerrorcode, accountid: string, resource: string, requested: number | null, limit: number | null, available: number | null, message?: string);
-}
-/** a read-only snapshot answered by usage(). */
-export type accountquotasnapshot = {
-    readonly accountid: string;
-    readonly used: Readonly<accountusage>;
-    readonly remaining: Readonly<Record<keyof accountusage, number | null>>;
-};
-/**
- * creates the per-account ledger with one limits table for every
- * account (per-plan tables ride on the caller passing the plan row of
- * the account).
- *
- * @param limits the limits table (absent fields are unlimited).
- * @returns the ledger facade (admits, reserve, release, usage,
- *   reconcile, reset).
- */
-export declare function createaccountledger(limits: accountlimits): {
-    admits: (accountid: string, wish: resourcewish) => boolean;
-    reserve: (accountid: string, wish: resourcewish) => accountquotasnapshot;
-    release: (accountid: string, wish: resourcewish) => accountquotasnapshot;
-    usage: (accountid: string) => accountquotasnapshot;
-    reconcile: (accountid: string, observed: accountusage) => {
-        before: accountquotasnapshot;
-        after: accountquotasnapshot;
-    };
-    reset: (accountid?: string) => void;
-};
-/** the structural row shape the projection reads (SandboxRow of db.ts
- * satisfies it; kept structural so the module stays import-free). */
-export type sandboxrowlike = {
-    readonly vcpus: number | null;
-    readonly ramgb: number | null;
-    readonly state: string | null;
-};
-/**
- * projects sandbox rows onto one account usage: every row that is not
- * destroyed counts as a live allocation (the same semantics the
- * SADDLE_MAX_SANDBOXES cap check of webserver.ts uses).
- *
- * @param rows the authoritative rows of one account.
- * @returns the usage counters the rows allocate.
- */
-export declare function usagefromrows(rows: readonly sandboxrowlike[]): accountusage;
-/**
- * reads the per-account limits from the environment: SADDLE_MAX_SANDBOXES
- * (the existing count cap of webserver.ts), SADDLE_ACCOUNT_MAX_VCPUS,
- * SADDLE_ACCOUNT_MAX_RAM_GB, SADDLE_ACCOUNT_MAX_VGPUS and
- * SADDLE_ACCOUNT_MAX_DISK_GB. unset, zero and negative values mean
- * unlimited, so the default deployment enforces nothing.
- *
- * @param env the environment record (process.env shaped).
- * @returns the limits table.
- */
-export declare function accountlimitsfromenv(env: Record<string, string | undefined>): accountlimits;

package/dist/sandboxquota.js

@@ -1,236 +0,0 @@
-/**
- * sandboxquota.ts — the per-account resource quota ledger of saddle.
- *
- * every account holds counters of the resources its live sandboxes
- * allocate (sandbox count, vcpus, ramgb, vgpus, diskgb) against a
- * limits table. the limits are a plain parameter — the operator's plan
- * table comes from config or the database and never lives in code; an
- * absent limit means unlimited, mirroring the SADDLE_MAX_SANDBOXES
- * convention of webserver.ts (0 or unset means unlimited).
- *
- * the ledger keeps reservations and releases in balance with a simple
- * reconciliation: the host projects the authoritative usage (for
- * example from the sqlite sandboxes rows) and reconcile() overwrites
- * the in-memory counters with it, so drift from admin deletes, restarts
- * or crashes self-heals on the next create.
- *
- * the module is pure: zero imports, zero dom, zero node builtins, a
- * Map per account, typed traceable errors (quotaexceedederror carries
- * the resource, the request, the limit and the remaining headroom).
- *
- * competitor sources shaping the contract: daytonaio/daytona (tenant
- * resource quota admission with per-sandbox cpu/memory/gpu quota
- * fields and the gpu allocator acquire/release pair around create) and
- * opensandbox-group/opensandbox (namespace ResourceQuota admission —
- * the sandbox is not admitted when the quota is exhausted — and the
- * pool acquisition that fails fast when capacity stays unavailable).
- *
- * wire point: webserver.ts createsandbox reconciles the owning
- * account from store.listsandboxesbyuser rows and reserves the new
- * sandbox; destroysandbox releases it. limits come from
- * accountlimitsfromenv(process.env) and stay unlimited when unset.
- */
-/** the resource names tracked by the ledger. */
-const RESOURCES = [
-    'sandboxes',
-    'vcpus',
-    'ramgb',
-    'vgpus',
-    'diskgb',
-];
-/** the typed quota failure, traceable to the account and the resource. */
-export class quotaerror extends Error {
-    /** machine readable failure code. */
-    code;
-    /** the account the failure belongs to. */
-    accountid;
-    /** the resource that failed (or 'wish' for malformed deltas). */
-    resource;
-    /** the requested amount (null when the wish itself was malformed). */
-    requested;
-    /** the active limit (null when unlimited). */
-    limit;
-    /** the headroom the account had before the request. */
-    available;
-    constructor(code, accountid, resource, requested, limit, available, message) {
-        super(message ??
-            `account ${accountid} ${code} on ${resource}: requested ${requested ?? '?'} of ${limit ?? 'unlimited'} (${available ?? '?'} available)`);
-        this.name = 'quotaerror';
-        this.code = code;
-        this.accountid = accountid;
-        this.resource = resource;
-        this.requested = requested;
-        this.limit = limit;
-        this.available = available;
-    }
-}
-/* ------------------------------------------------------------------ */
-/* helpers                                                             */
-/* ------------------------------------------------------------------ */
-/** validates one resource wish: every present field is a positive number. */
-function sanitize(wish) {
-    const clean = {};
-    for (const resource of RESOURCES) {
-        const value = wish[resource];
-        if (value === undefined) {
-            continue;
-        }
-        if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
-            throw new quotaerror('invalid-wish', '', resource, typeof value === 'number' ? value : null, null, null, `resource ${resource} must be a positive finite number (received ${String(value)})`);
-        }
-        clean[resource] = value;
-    }
-    return clean;
-}
-/** headroom of one resource under its limit (null limit means Infinity). */
-function headroom(limit, used) {
-    return typeof limit === 'number' && limit > 0 ? Math.max(0, limit - used) : null;
-}
-/**
- * creates the per-account ledger with one limits table for every
- * account (per-plan tables ride on the caller passing the plan row of
- * the account).
- *
- * @param limits the limits table (absent fields are unlimited).
- * @returns the ledger facade (admits, reserve, release, usage,
- *   reconcile, reset).
- */
-export function createaccountledger(limits) {
-    const books = new Map();
-    /** zeroes the counters of an unseen account. */
-    function blank(accountid) {
-        const existing = books.get(accountid);
-        if (existing !== undefined) {
-            return existing;
-        }
-        const fresh = { sandboxes: 0, vcpus: 0, ramgb: 0, vgpus: 0, diskgb: 0 };
-        books.set(accountid, fresh);
-        return fresh;
-    }
-    function snapshotOf(accountid, used) {
-        const remaining = {};
-        for (const resource of RESOURCES) {
-            remaining[resource] = headroom(limits[resource], used[resource]);
-        }
-        return { accountid, used: { ...used }, remaining };
-    }
-    /** the shared admit-or-throw walk used by admits and reserve. */
-    function check(accountid, wish) {
-        const clean = sanitize(wish);
-        const used = blank(accountid);
-        for (const resource of RESOURCES) {
-            const request = clean[resource];
-            if (request === undefined) {
-                continue;
-            }
-            const room = headroom(limits[resource], used[resource]);
-            if (room !== null && request > room) {
-                throw new quotaerror('quota-exceeded', accountid, resource, request, limits[resource] ?? null, room);
-            }
-        }
-        return clean;
-    }
-    return {
-        admits(accountid, wish) {
-            try {
-                check(accountid, wish);
-                return true;
-            }
-            catch (error) {
-                if (error instanceof quotaerror) {
-                    return false;
-                }
-                throw error;
-            }
-        },
-        reserve(accountid, wish) {
-            const clean = check(accountid, wish);
-            const used = blank(accountid);
-            for (const resource of RESOURCES) {
-                const request = clean[resource];
-                if (request !== undefined) {
-                    used[resource] += request;
-                }
-            }
-            return snapshotOf(accountid, used);
-        },
-        release(accountid, wish) {
-            const clean = sanitize(wish);
-            const used = blank(accountid);
-            for (const resource of RESOURCES) {
-                const request = clean[resource];
-                if (request !== undefined) {
-                    used[resource] = Math.max(0, used[resource] - request);
-                }
-            }
-            return snapshotOf(accountid, used);
-        },
-        usage(accountid) {
-            return snapshotOf(accountid, blank(accountid));
-        },
-        reconcile(accountid, observed) {
-            const used = blank(accountid);
-            const before = snapshotOf(accountid, used);
-            for (const resource of RESOURCES) {
-                const value = observed[resource];
-                used[resource] =
-                    typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
-            }
-            const after = snapshotOf(accountid, used);
-            return { before, after };
-        },
-        reset(accountid) {
-            if (accountid === undefined) {
-                books.clear();
-                return;
-            }
-            books.delete(accountid);
-        },
-    };
-}
-/**
- * projects sandbox rows onto one account usage: every row that is not
- * destroyed counts as a live allocation (the same semantics the
- * SADDLE_MAX_SANDBOXES cap check of webserver.ts uses).
- *
- * @param rows the authoritative rows of one account.
- * @returns the usage counters the rows allocate.
- */
-export function usagefromrows(rows) {
-    const usage = { sandboxes: 0, vcpus: 0, ramgb: 0, vgpus: 0, diskgb: 0 };
-    for (const row of rows) {
-        if (row.state === 'destroyed') {
-            continue;
-        }
-        usage.sandboxes += 1;
-        usage.vcpus += typeof row.vcpus === 'number' ? row.vcpus : 0;
-        usage.ramgb += typeof row.ramgb === 'number' ? row.ramgb : 0;
-    }
-    return usage;
-}
-/* ------------------------------------------------------------------ */
-/* adapter: limits from the environment                                */
-/* ------------------------------------------------------------------ */
-/**
- * reads the per-account limits from the environment: SADDLE_MAX_SANDBOXES
- * (the existing count cap of webserver.ts), SADDLE_ACCOUNT_MAX_VCPUS,
- * SADDLE_ACCOUNT_MAX_RAM_GB, SADDLE_ACCOUNT_MAX_VGPUS and
- * SADDLE_ACCOUNT_MAX_DISK_GB. unset, zero and negative values mean
- * unlimited, so the default deployment enforces nothing.
- *
- * @param env the environment record (process.env shaped).
- * @returns the limits table.
- */
-export function accountlimitsfromenv(env) {
-    const positive = (name) => {
-        const parsed = Number(env[name]);
-        return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : undefined;
-    };
-    return {
-        sandboxes: positive('SADDLE_MAX_SANDBOXES'),
-        vcpus: positive('SADDLE_ACCOUNT_MAX_VCPUS'),
-        ramgb: positive('SADDLE_ACCOUNT_MAX_RAM_GB'),
-        vgpus: positive('SADDLE_ACCOUNT_MAX_VGPUS'),
-        diskgb: positive('SADDLE_ACCOUNT_MAX_DISK_GB'),
-    };
-}