@isomorph.ai/app-sdk 1.3.1 → 1.4.1

package/dist/runtime.d.ts

@@ -39,6 +39,8 @@ 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;
     }>;
@@ -56,11 +58,18 @@ export declare class Runs {
         cancelled?: boolean;
     }): Promise<void>;
 }
+/**
+ * What the process runs beside the action server:
+ *   full     the in-process cron scheduler and the queue loop (the default)
+ *   actions  the queue loop only; the platform's CronJobs run the schedules
+ *   gate     nothing: actions only, for the kit gate
+ */
+export type RuntimeMode = 'full' | 'actions' | 'gate';
 export interface RuntimeOptions {
     root: string;
     port: number;
     gatewayUrl: string;
-    mode: 'full' | 'gate';
+    mode: RuntimeMode;
     tokenFile?: string;
     log?: (line: string) => void;
 }
@@ -75,10 +84,20 @@ export declare class Runtime {
     readonly server: import("http").Server<typeof IncomingMessage, typeof ServerResponse>;
     constructor(options: RuntimeOptions);
     start(): Promise<number>;
+    /**
+     * `--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, 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>;
@@ -87,3 +106,5 @@ export declare class Runtime {
 }
 /** The runtime's settings from the environment; exported for the entry point and its test. */
 export declare function optionsFromEnvironment(env?: NodeJS.ProcessEnv): RuntimeOptions;
+/** The job named by `--run-job <name>` or `--run-job=<name>`; undefined when the runtime is a server. */
+export declare function runJobFromArguments(argv?: string[]): string | undefined;

package/dist/runtime.js

@@ -10,6 +10,12 @@
 // database or a company system directly: every read and write goes through
 // the App Gateway as the workload identity, the same door the browser uses.
 //
+// Started with `--run-job <name>` it is a CronJob pod instead of a server: it
+// runs that one `jobs/<name>.ts` once for the current minute, the way the
+// in-process scheduler would have, and exits 0 when the handler returned, 1
+// when it threw or the app has no such job. No port is opened, no scheduler
+// or queue loop starts.
+//
 // Environment:
 //   PORT                          the action server's port (default 8080)
 //   ISOMORPH_GATEWAY_URL          the gateway the SDK calls; HARBOUR_GATEWAY_URL
@@ -17,6 +23,13 @@
 //   ISOMORPH_WORKLOAD_TOKEN       the workload's bearer; HARBOUR_WORKLOAD_TOKEN_FILE
 //                                 names a projected token file re-read every minute
 //   ISOMORPH_RUNTIME_MODE=gate    serve actions only: no scheduler, no queue loop
+//   ISOMORPH_JOBS_SCHEDULER=platform
+//                                 the platform runs the cron (one CronJob pod per
+//                                 scheduled job, each `--run-job <name>`): serve
+//                                 actions and work the queue, never tick the
+//                                 in-process scheduler. Set by Provision on the
+//                                 hosted kit-runtime; `isomorph dev` leaves it
+//                                 unset and keeps cron in-process
 //   ISOMORPH_APP_ROOT             the app root (default: the working directory)
 import { createServer } from 'node:http';
 import { readFile, readdir, stat } from 'node:fs/promises';
@@ -41,6 +54,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) => {
@@ -137,6 +154,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 };
@@ -209,14 +230,52 @@ export class Runtime {
         this.log(`serving ${this.inventory.actions.length} action(s) and ${this.inventory.jobs.length} job(s) on port ${port} (${this.options.mode})`);
         if (this.options.tokenFile)
             this.every(TOKEN_REFRESH_MS, () => this.refreshToken());
-        if (this.options.mode === 'full') {
-            if (this.inventory.jobs.some((job) => job.schedule))
-                this.scheduleTick();
-            if (this.inventory.jobs.length > 0 && this.options.gatewayUrl)
-                this.every(QUEUE_POLL_MS, () => this.work());
-        }
+        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());
         return port;
     }
+    /**
+     * `--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, 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);
+        await this.refreshToken();
+        if (!this.inventory.jobs.some((job) => job.name === name)) {
+            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)
@@ -267,20 +326,23 @@ export class Runtime {
             this.scheduleTick();
         }, Math.max(0, next - now)));
     }
+    /** One scheduled run; true when the handler returned, false when it threw or the last tick's run is still going. */
     async runScheduled(name, at) {
         const key = `schedule:${name}`;
         if (this.running.has(key)) {
             this.log(`jobs/${name}.ts is still running; the ${at.toISOString()} tick is skipped`);
-            return;
+            return false;
         }
         this.running.add(key);
         try {
             const handler = await loadHandler(this.options.root, JOBS_DIR, name);
             await handler({ scheduledAt: at.toISOString(), progress: async () => undefined, cancelled: async () => false });
             this.log(`jobs/${name}.ts ran for ${at.toISOString()}`);
+            return true;
         }
         catch (error) {
             this.log(`jobs/${name}.ts failed for ${at.toISOString()}: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
         }
         finally {
             this.running.delete(key);
@@ -394,10 +456,21 @@ export function optionsFromEnvironment(env = process.env) {
         root: resolve(env.ISOMORPH_APP_ROOT || process.cwd()),
         port: Number(env.PORT || 8080),
         gatewayUrl: (env.ISOMORPH_GATEWAY_URL || env.HARBOUR_GATEWAY_URL || '').replace(/\/$/, ''),
-        mode: env.ISOMORPH_RUNTIME_MODE === 'gate' ? 'gate' : 'full',
+        mode: env.ISOMORPH_RUNTIME_MODE === 'gate' ? 'gate' : env.ISOMORPH_JOBS_SCHEDULER === 'platform' ? 'actions' : 'full',
         tokenFile: env.HARBOUR_WORKLOAD_TOKEN_FILE || undefined,
     };
 }
+/** The job named by `--run-job <name>` or `--run-job=<name>`; undefined when the runtime is a server. */
+export function runJobFromArguments(argv = process.argv.slice(2)) {
+    for (let i = 0; i < argv.length; i += 1) {
+        const argument = argv[i];
+        if (argument === '--run-job')
+            return argv[i + 1] ?? '';
+        if (argument.startsWith('--run-job='))
+            return argument.slice('--run-job='.length);
+    }
+    return undefined;
+}
 const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : '';
 if (import.meta.url === entry) {
     // Extensionless relative imports in the app's server code resolve to
@@ -412,6 +485,14 @@ if (import.meta.url === entry) {
         process.exit(2);
     }
     const runtime = new Runtime(options);
+    const job = runJobFromArguments();
+    if (job !== undefined) {
+        if (!job) {
+            console.error('isomorph runtime: --run-job needs a job name');
+            process.exit(2);
+        }
+        process.exit((await runtime.runJobOnce(job)) ? 0 : 1);
+    }
     const shutdown = () => { void runtime.stop().then(() => process.exit(0)); };
     process.on('SIGTERM', shutdown);
     process.on('SIGINT', shutdown);

package/package.json

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