@isomorph.ai/app-sdk 1.4.0 → 1.4.2

package/dist/runtime.d.ts

@@ -39,22 +39,25 @@ export declare class Runs {
     private readonly client;
     constructor(client: IsomorphClient);
     private table;
+    /** The cheapest read the runs table answers; rejects while the gateway's data path is down. */
+    ready(): Promise<void>;
     enqueue(job: string, input: unknown, owner: string): Promise<{
         id: string;
     }>;
     get(id: string, owner: string): Promise<JobRun | null>;
     cancel(id: string, owner: string): Promise<JobRun | null>;
-    /** Rows whose lease ran out go back to the queue while attempts remain, else fail. */
-    reclaim(now: Date): Promise<void>;
+    /** Rows whose lease ran out go back to the queue while attempts remain, else fail; how many there were. */
+    reclaim(now: Date): Promise<number>;
     /** Claims the oldest queued run by a conditional update; null when the queue is empty or another worker won. */
     claim(now: Date): Promise<JobRun | null>;
     progress(id: string, percent: number, note?: string): Promise<void>;
     cancelRequested(id: string): Promise<boolean>;
+    /** Records the outcome; the status written, `queued` when the failure left a retry for the next pass. */
     finish(run: JobRun, outcome: {
         result?: unknown;
         error?: string;
         cancelled?: boolean;
-    }): Promise<void>;
+    }): Promise<JobRun['status']>;
 }
 /**
  * What the process runs beside the action server:
@@ -70,6 +73,8 @@ export interface RuntimeOptions {
     mode: RuntimeMode;
     tokenFile?: string;
     log?: (line: string) => void;
+    /** The pause between queue passes while work is found; the tests shorten it. */
+    queuePollMs?: number;
 }
 export declare class Runtime {
     private readonly options;
@@ -77,27 +82,45 @@ export declare class Runtime {
     private readonly running;
     private readonly timers;
     private stopped;
+    private queueLive;
+    private queueWake;
     private readonly runs;
     private readonly log;
     readonly server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
     constructor(options: RuntimeOptions);
     start(): Promise<number>;
+    /** Whether this process works the queue at all: not the gate, an app with jobs, a gateway to reach. */
+    private worksQueue;
+    /**
+     * Starts the queue loop unless it is already live. The first pass runs at
+     * once; each further pass follows QUEUE_POLL_MS after one that found work
+     * (or threw: a gateway that is waking answers 5xx, and the row that woke
+     * the loop is still there). A pass that finds nothing ends the loop with no
+     * timer armed, so an idle runtime makes no data calls at all.
+     */
+    wakeQueue(): void;
     /**
      * `--run-job <name>`: one scheduled run of one job, as a CronJob pod runs it.
      * The run is the scheduler's own (`runScheduled`, the current minute as its
      * tick), so it is loaded, run and recorded exactly as an in-process tick
-     * would have been. False when the app has no such job or the handler threw;
-     * the log names which.
+     * would have been. False when the app has no such job, the gateway's data
+     * path never answered, or the handler threw; the log names which.
      */
     runJobOnce(name: string, now?: Date): Promise<boolean>;
+    private awaitDataPath;
     stop(): Promise<void>;
     private every;
     private refreshToken;
     private scheduleTick;
     /** One scheduled run; true when the handler returned, false when it threw or the last tick's run is still going. */
     private runScheduled;
-    /** One pass of the queue loop: reclaim expired leases, claim one run, run it. */
-    work(): Promise<void>;
+    /**
+     * One pass of the queue loop: reclaim expired leases, claim one run, run it.
+     * True when the pass found work — a lease reclaimed, a run claimed, or the
+     * run it finished left a retry queued — so the loop should look again; false
+     * when the queue is empty (or another pass is already going).
+     */
+    work(): Promise<boolean>;
     private serve;
     private reserved;
 }

package/dist/runtime.js

@@ -16,6 +16,20 @@
 // when it threw or the app has no such job. No port is opened, no scheduler
 // or queue loop starts.
 //
+// The queue is worked on demand, not on a clock. An idle kit app makes no
+// database calls: the runtime is the process that serves the enqueue action
+// and the one that finishes every run, so it knows when work exists. It runs
+// one pass at start (reclaiming whatever a crashed predecessor left running
+// and draining any backlog), then loops every QUEUE_POLL_MS only while a pass
+// found something — a claimed run, a reclaimed lease, a run that finished with
+// retries queued — and stops with no timer armed once the queue is empty. An
+// enqueue starts the loop again. This holds because kit-runtime is pinned to
+// one replica; a multi-replica runtime would need a slow periodic poll as well,
+// since a row inserted through another replica is invisible to this one until
+// it looks (out of scope here). The V2 idle controller reads pg_stat_database
+// counters to decide a database is quiet, so a poll that issued a transaction
+// every 2 s kept the shared Postgres awake for every app that had a job.
+//
 // Environment:
 //   PORT                          the action server's port (default 8080)
 //   ISOMORPH_GATEWAY_URL          the gateway the SDK calls; HARBOUR_GATEWAY_URL
@@ -54,6 +68,10 @@ const LEASE_MS = 5 * 60_000;
 const QUEUE_POLL_MS = 2_000;
 const TOKEN_REFRESH_MS = 60_000;
 const DEFAULT_MAX_ATTEMPTS = 3;
+// A CronJob pod may start while the app's database is still waking: --run-job
+// waits this long for the gateway's data path, probing every retry interval.
+const DATA_PATH_WAIT_MS = 90_000;
+const DATA_PATH_RETRY_MS = 3_000;
 /** Every `actions/<name>.ts` and `jobs/<name>.ts` the app carries, by logical name. */
 export async function discover(root) {
     const list = async (dir) => {
@@ -150,6 +168,10 @@ export class Runs {
         this.client = client;
     }
     table() { return this.client.data.from(RUNS_TABLE); }
+    /** The cheapest read the runs table answers; rejects while the gateway's data path is down. */
+    async ready() {
+        await this.table().select('id').limit(1);
+    }
     async enqueue(job, input, owner) {
         const { data } = await this.table().insert({ job, input: input ?? null, status: 'queued', attempt: 0, max_attempts: DEFAULT_MAX_ATTEMPTS, progress: 0, owner_subject: owner, cancel_requested: false }).select('id').single();
         return { id: data.id };
@@ -166,13 +188,14 @@ export class Runs {
         }
         return data;
     }
-    /** Rows whose lease ran out go back to the queue while attempts remain, else fail. */
+    /** Rows whose lease ran out go back to the queue while attempts remain, else fail; how many there were. */
     async reclaim(now) {
         const { data: expired } = await this.table().select('*').eq('status', 'running').lt('lease_until', now.toISOString()).limit(20);
         for (const run of expired) {
             const exhausted = run.attempt >= run.max_attempts;
             await this.table().update({ status: exhausted ? 'failed' : 'queued', error: exhausted ? 'the worker was interrupted and no attempts remain' : run.error, lease_until: null, updated_at: now.toISOString() }).eq('id', run.id).eq('status', 'running');
         }
+        return expired.length;
     }
     /** Claims the oldest queued run by a conditional update; null when the queue is empty or another worker won. */
     async claim(now) {
@@ -190,10 +213,12 @@ export class Runs {
         const { data } = await this.table().select('cancel_requested').eq('id', id).maybeSingle();
         return Boolean(data?.cancel_requested);
     }
+    /** Records the outcome; the status written, `queued` when the failure left a retry for the next pass. */
     async finish(run, outcome) {
         const retry = outcome.error !== undefined && !outcome.cancelled && run.attempt < run.max_attempts;
         const status = outcome.cancelled ? 'cancelled' : outcome.error === undefined ? 'succeeded' : retry ? 'queued' : 'failed';
         await this.table().update({ status, result: outcome.result ?? null, error: outcome.error ?? null, progress: status === 'succeeded' ? 100 : run.progress, lease_until: null, updated_at: new Date().toISOString() }).eq('id', run.id).eq('status', 'running');
+        return status;
     }
 }
 export class Runtime {
@@ -202,6 +227,10 @@ export class Runtime {
     running = new Set();
     timers = [];
     stopped = false;
+    // The queue loop is live while a pass runs or its next pass is timed; a
+    // wake that arrives mid-pass is remembered so the pass after it looks again.
+    queueLive = false;
+    queueWake = false;
     runs;
     log;
     server = createServer((request, response) => { void this.serve(request, response); });
@@ -224,16 +253,58 @@ export class Runtime {
             this.every(TOKEN_REFRESH_MS, () => this.refreshToken());
         if (this.options.mode === 'full' && this.inventory.jobs.some((job) => job.schedule))
             this.scheduleTick();
-        if (this.options.mode !== 'gate' && this.inventory.jobs.length > 0 && this.options.gatewayUrl)
-            this.every(QUEUE_POLL_MS, () => this.work());
+        this.wakeQueue();
         return port;
     }
+    /** Whether this process works the queue at all: not the gate, an app with jobs, a gateway to reach. */
+    worksQueue() {
+        return this.options.mode !== 'gate' && this.inventory.jobs.length > 0 && Boolean(this.options.gatewayUrl);
+    }
+    /**
+     * Starts the queue loop unless it is already live. The first pass runs at
+     * once; each further pass follows QUEUE_POLL_MS after one that found work
+     * (or threw: a gateway that is waking answers 5xx, and the row that woke
+     * the loop is still there). A pass that finds nothing ends the loop with no
+     * timer armed, so an idle runtime makes no data calls at all.
+     */
+    wakeQueue() {
+        if (this.stopped || !this.worksQueue())
+            return;
+        if (this.queueLive) {
+            this.queueWake = true;
+            return;
+        }
+        this.queueLive = true;
+        const pass = async () => {
+            if (this.stopped) {
+                this.queueLive = false;
+                return;
+            }
+            this.queueWake = false;
+            let again = true;
+            try {
+                again = await this.work();
+            }
+            catch (error) {
+                this.log(`queue pass failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (this.stopped) {
+                this.queueLive = false;
+                return;
+            }
+            if (again || this.queueWake)
+                this.timers.push(setTimeout(() => void pass(), this.options.queuePollMs ?? QUEUE_POLL_MS));
+            else
+                this.queueLive = false;
+        };
+        void pass();
+    }
     /**
      * `--run-job <name>`: one scheduled run of one job, as a CronJob pod runs it.
      * The run is the scheduler's own (`runScheduled`, the current minute as its
      * tick), so it is loaded, run and recorded exactly as an in-process tick
-     * would have been. False when the app has no such job or the handler threw;
-     * the log names which.
+     * would have been. False when the app has no such job, the gateway's data
+     * path never answered, or the handler threw; the log names which.
      */
     async runJobOnce(name, now = new Date()) {
         this.inventory = await discover(this.options.root);
@@ -242,8 +313,32 @@ export class Runtime {
             this.log(`this app has no ${JOBS_DIR}/${name}.ts`);
             return false;
         }
+        if (this.options.gatewayUrl && !(await this.awaitDataPath()))
+            return false;
         return this.runScheduled(name, new Date(Math.floor(now.getTime() / 60_000) * 60_000));
     }
+    // The pod is scheduled by the cluster clock, not by the app's readiness: its
+    // database may be paused or waking (plan §5.3) and the gateway answers 5xx
+    // until it is up. The handler runs once the cheapest read answers; when it
+    // never does within the wait, the run fails with one line naming the last error.
+    async awaitDataPath() {
+        const deadline = Date.now() + DATA_PATH_WAIT_MS;
+        for (;;) {
+            try {
+                await this.runs.ready();
+                return true;
+            }
+            catch (error) {
+                const reason = error instanceof Error ? error.message : String(error);
+                if (Date.now() + DATA_PATH_RETRY_MS > deadline) {
+                    this.log(`the data path did not answer within ${DATA_PATH_WAIT_MS / 1000} s: ${reason}`);
+                    return false;
+                }
+                this.log(`waiting for the data path: ${reason}`);
+                await new Promise((wake) => setTimeout(wake, DATA_PATH_RETRY_MS));
+            }
+        }
+    }
     async stop() {
         this.stopped = true;
         for (const timer of this.timers)
@@ -316,20 +411,25 @@ export class Runtime {
             this.running.delete(key);
         }
     }
-    /** One pass of the queue loop: reclaim expired leases, claim one run, run it. */
+    /**
+     * One pass of the queue loop: reclaim expired leases, claim one run, run it.
+     * True when the pass found work — a lease reclaimed, a run claimed, or the
+     * run it finished left a retry queued — so the loop should look again; false
+     * when the queue is empty (or another pass is already going).
+     */
     async work() {
         if (this.running.has('queue'))
-            return;
+            return false;
         this.running.add('queue');
         try {
             const now = new Date();
-            await this.runs.reclaim(now);
+            const reclaimed = await this.runs.reclaim(now);
             const run = await this.runs.claim(now);
             if (!run)
-                return;
+                return reclaimed > 0;
             if (!this.inventory.jobs.some((job) => job.name === run.job)) {
                 await this.runs.finish({ ...run, attempt: run.max_attempts }, { error: `no jobs/${run.job}.ts in this app` });
-                return;
+                return true;
             }
             try {
                 const handler = await loadHandler(this.options.root, JOBS_DIR, run.job);
@@ -344,6 +444,7 @@ export class Runtime {
             catch (error) {
                 await this.runs.finish(run, { error: error instanceof Error ? error.message : String(error) });
             }
+            return true;
         }
         finally {
             this.running.delete('queue');
@@ -399,7 +500,9 @@ export class Runtime {
                     throw new IsomorphError('VALIDATION_FAILED', `this app has no ${JOBS_DIR}/${job || '<name>'}.ts`, undefined, undefined, 400);
                 if (!owner)
                     throw new IsomorphError('AUTH_REQUIRED', 'a run is started by a signed-in person', undefined, undefined, 401);
-                return this.runs.enqueue(job, body.input, owner);
+                const queued = await this.runs.enqueue(job, body.input, owner);
+                this.wakeQueue();
+                return queued;
             }
             case GET_RUN_ACTION: {
                 const run = typeof body.id === 'string' ? await this.runs.get(body.id, owner) : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "type": "module",
   "repository": {
     "type": "git",