@wenathlan/saddle 2.0.151 → 2.0.152

package/dist/sandboxqueue.js

@@ -0,0 +1,201 @@
+/**
+ * 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

@@ -0,0 +1,121 @@
+/**
+ * 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

@@ -0,0 +1,236 @@
+/**
+ * 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'),
+    };
+}