@elaraai/e3-rack 0.0.0-bootstrap.0 → 1.0.94

package/dist/src/server/rack-routes.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Machine-authenticated /api/rack routes (epic #67 design §9).
+ *
+ * #72 ships the identity half: the enrollment exchange (`POST /rack/enroll`,
+ * authenticated by the single-use enrollment token itself) and the
+ * **machine-auth middleware** every other /rack/* route sits behind.
+ * #73 adds the dispatch protocol behind that middleware:
+ * - `POST /rack/lease` — long-poll claim of the next matching task
+ * - `POST /rack/heartbeat` — liveness + stop signals for dead leases
+ * - `POST /rack/lease/extend` — visibility refresh while running
+ * - `POST /rack/complete` — terminal result (accepted-and-discarded)
+ * #74 adds the data plane:
+ * - `POST /rack/storage` — inline bytes / presigned URLs for a claimed
+ *   lease's objects (scope-validated, review F5) + the output PUT targets
+ * - `POST /rack/logs` — batched stdout/stderr → LogStore
+ *
+ * #214 moves the guest onto e3-core's own execution:
+ * - a lease is refused to an agent older than `LEASE_MIN_AGENT`;
+ * - the claim of a task or unit lease mints its attempt and records it
+ *   `running`, stamped with the rack launch; the completion records its
+ *   outcome, discards what it wrote and never committed, and wakes a run
+ *   parked on it (#208);
+ * - `/rack/storage` admits exactly the lease's closure, and takes the objects
+ *   its guest wrote in by checksum-bound PUTs and their commits.
+ *
+ * A rack token authenticates ONLY these routes — it is invisible to the
+ * human `jwtAuthorizer`, so it can never reach the human/admin API.
+ */
+import { Hono } from 'hono';
+import type { Context, Next } from 'hono';
+import { type LogStore } from '@elaraai/e3-core';
+import { type RackRegistration } from '../protocol/index.js';
+import { type RackRegistry } from '../registry/rack-registry.js';
+import type { RunnerRun } from '../runner-event.js';
+import { type RackLeaseStore, type RackLeaseRecord } from '../lease/lease-store.js';
+import type { RackStorageBridge } from './storage-bridge.js';
+import { type EnvIndexStore } from './env-publication.js';
+import { type RackLeaseResult } from '../protocol/task-envelope.js';
+import { type LeaseCoordinator } from '../lease/coordinator.js';
+import { type MachineIdentityStore } from '../identity/machine-identity.js';
+/**
+ * Hono env for rack routes: the middleware resolves the caller's identity
+ * and stashes what the routes need — the registration (quarantine checks)
+ * and the presented token's pre-activation state (rotation decisions).
+ */
+export type RackEnv = {
+    Variables: {
+        rackId: string;
+        registration: RackRegistration;
+        tokenIssuedAt: Date;
+        /** The presented token's status BEFORE any activation this request. */
+        tokenStatus: 'current' | 'pending' | 'grace';
+    };
+};
+/** Dispatch tuning — injectable so route tests run in milliseconds. */
+export interface RackRouteOptions {
+    /** Shares the dispatcher's fence for record, transfer and lease transitions. */
+    coordinator?: LeaseCoordinator;
+    /** Clock for identity, health and visibility (not the long-poll deadline). */
+    now?: () => number;
+    /** Stops outstanding lease polls when their host shuts down. */
+    signal?: AbortSignal;
+    /** Optional per-candidate compatibility gate, checked at claim time too. */
+    canClaim?: (rack: RackRegistration, lease: RackLeaseRecord) => boolean | Promise<boolean>;
+    /** Notifies session waiters after a transition and its record writes. */
+    onLeaseSignal?: (signal: RackLeaseSignal) => void | Promise<void>;
+    /**
+     * Long-poll window for /rack/lease. Must sit comfortably inside API
+     * Gateway's hard 29 s response cap (design picks ≤ ~25 s; each idle agent
+     * holds ~1 API-Lambda invocation continuously — the documented standing
+     * cost of the pull model).
+     */
+    leaseWindowMs?: number;
+    /** Claim re-check interval while long-polling. */
+    pollIntervalMs?: number;
+    /** Maximum idle claim interval; defaults to pollIntervalMs (no backoff). */
+    pollMaxMs?: number;
+    /** Idle policy refresh interval; defaults to every check. Claims always read it afresh. */
+    policyRecheckMs?: number;
+    /** Read-only cancellation watch window (default 20 s, capped at 20 s). */
+    watchWindowMs?: number;
+    /** Re-check cancellation while a watch is held (default 250 ms). */
+    watchPollIntervalMs?: number;
+    /** Visibility window granted on claim and per extension. */
+    visibilityMs?: number;
+    /** #94 Slice B: published-env index — absent means env resolution is
+     *  unavailable (requests for it error; racks fall back to cloud). */
+    envIndex?: EnvIndexStore;
+    /** The deployment's e3 version (selects which published env build). */
+    e3Version?: string;
+    /**
+     * Wakes a dataflow's parked run once a rack attempt's outcome is recorded
+     * (#208): `wakeRun` over the run's pointer, which asks the deployment's
+     * waker. Absent, only the park's backstop wakes it.
+     */
+    wake?: (repo: string, run: RunnerRun) => Promise<boolean>;
+}
+/** A committed route transition that waiters may observe. */
+export type RackLeaseSignal = {
+    kind: 'claimed';
+    repo: string;
+    leaseId: string;
+    rackId: string;
+} | {
+    kind: 'extended';
+    repo: string;
+    leaseId: string;
+} | {
+    kind: 'completed';
+    repo: string;
+    leaseId: string;
+    disposition: 'recorded' | 'idempotent' | 'discarded';
+};
+/**
+ * Where the rack routes keep a lease's attempt (#214): its records, its log
+ * lines, and the store its output is checked whole in.
+ */
+export interface RackAttemptStore {
+    /** Computes/reads the admitted closure in the repository-owning session. */
+    closure(lease: RackLeaseRecord): Promise<readonly string[]>;
+    /** Records an owner, then the newly claimed attempt as running. */
+    running(lease: RackLeaseRecord, bootId: string): Promise<void>;
+    /** Ends a prior attempt when reclaimed, superseded or cancelled. */
+    stopped(lease: RackLeaseRecord, how: 'interrupted' | 'cancelled', cause: string): Promise<void>;
+    /** Records the outcome after flushing the attempt's logs. */
+    outcome(lease: RackLeaseRecord, result: RackLeaseResult): Promise<void>;
+    /** Verifies and re-references the complete output graph before success. */
+    verifyOutput(lease: RackLeaseRecord, outputHash: string): Promise<boolean>;
+    /** Repository-session log sink. A flush is per attempt. */
+    readonly logs: Pick<LogStore, 'append'> & Partial<Pick<LogStore, 'flush'>>;
+}
+/** The most objects one `/rack/storage` request declares or commits. */
+export declare const MAX_STORAGE_OBJECTS = 256;
+/** The largest object a write target is issued for: one checksum-bound PUT. */
+export declare const MAX_RACK_OBJECT_BYTES: number;
+/**
+ * Machine-auth middleware for /rack/* routes: validates the bearer rack
+ * token (by at-rest hash) and re-resolves the rack's registration so a
+ * deregistered rack is rejected immediately — revocation needs no token
+ * bookkeeping.
+ *
+ * Rotation activation (D12, #90) lives here: the FIRST authenticated use
+ * of a `pending` successor promotes it to `current` and puts the token it
+ * replaces on the ROTATION_GRACE fuse — on any rack route, so activation
+ * is observed wherever the agent switches.
+ *
+ * @param identityStore - Machine-credential persistence
+ * @param settingsStore - Rack registry (registration existence = not revoked)
+ * @param now - Clock for token rotation and grace expiry
+ * @returns Machine authentication middleware
+ * @example
+ * app.use('/api/rack/*', createRackAuth(identities, registry));
+ */
+export declare function createRackAuth(identityStore: MachineIdentityStore, settingsStore: RackRegistry, now?: () => number): (c: Context<RackEnv>, next: Next) => Promise<Response | void>;
+/**
+ * Create the /api/rack routes: the enrollment exchange (#72), the dispatch
+ * protocol (#73), the data plane (#74), and a lease's attempt (#214).
+ *
+ * @param identityStore - Machine-credential persistence
+ * @param settingsStore - Rack registry
+ * @param leaseStore - Lease persistence (the pull queue)
+ * @param bridge - Object data-plane (presign/inline/commit)
+ * @param attempts - Where a lease's attempt is kept: its records, its log
+ *   lines, and the store its output is checked whole in
+ * @param options - Long-poll/visibility tuning, and the waker
+ * @returns The rack machine API
+ * @example
+ * const app = createRackRoutes(identities, registry, leases, bridge, attempts);
+ */
+export declare function createRackRoutes(identityStore: MachineIdentityStore, settingsStore: RackRegistry, leaseStore: RackLeaseStore, bridge: RackStorageBridge, attempts: RackAttemptStore, options?: RackRouteOptions): Hono<RackEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=rack-routes.d.ts.map

package/dist/src/server/rack-routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rack-routes.d.ts","sourceRoot":"","sources":["../../../src/server/rack-routes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI1C,OAAO,EAAwB,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACvE,OAAO,EAuBL,KAAK,gBAAgB,EAItB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAqB,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,yBAAyB,CAAC;AACvG,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAmB,KAAK,aAAa,EAAyB,MAAM,sBAAsB,CAAC;AAClG,OAAO,EAA6C,KAAK,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAE/G,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AACzF,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,iCAAiC,CAAC;AAEzC;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,SAAS,EAAE;QACT,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,EAAE,gBAAgB,CAAC;QAC/B,aAAa,EAAE,IAAI,CAAC;QACpB,uEAAuE;QACvE,WAAW,EAAE,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;KAC9C,CAAC;CACH,CAAC;AAEF,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC/B,gFAAgF;IAChF,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,8EAA8E;IAC9E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gEAAgE;IAChE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,eAAe,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1F,yEAAyE;IACzE,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2FAA2F;IAC3F,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,0EAA0E;IAC1E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;yEACqE;IACrE,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3D;AAED,6DAA6D;AAC7D,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnD;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,UAAU,GAAG,YAAY,GAAG,WAAW,CAAA;CAAE,CAAC;AAE/G;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,OAAO,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IAC5D,mEAAmE;IACnE,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,oEAAoE;IACpE,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,EAAE,aAAa,GAAG,WAAW,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChG,6DAA6D;IAC7D,OAAO,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxE,2EAA2E;IAC3E,YAAY,CAAC,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3E,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;CAC5E;AAED,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,QAAgB,CAAC;AAyBnD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAC5B,aAAa,EAAE,oBAAoB,EACnC,aAAa,EAAE,YAAY,EAC3B,GAAG,GAAE,MAAM,MAAiB,IAEd,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,IAAI,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CA+BzE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,oBAAoB,EACnC,aAAa,EAAE,YAAY,EAC3B,UAAU,EAAE,cAAc,EAC1B,MAAM,EAAE,iBAAiB,EACzB,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,CAAC,EAAE,gBAAgB,wDAunB3B"}