@isomorph.ai/app-sdk 1.3.1 → 1.4.0

package/dist/runtime.d.ts

@@ -56,11 +56,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 +82,19 @@ 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 or the handler threw;
+     * the log names which.
+     */
+    runJobOnce(name: string, now?: Date): Promise<boolean>;
     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 +103,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';
@@ -209,14 +222,28 @@ 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 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;
+        }
+        return this.runScheduled(name, new Date(Math.floor(now.getTime() / 60_000) * 60_000));
+    }
     async stop() {
         this.stopped = true;
         for (const timer of this.timers)
@@ -267,20 +294,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 +424,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 +453,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.0",
   "type": "module",
   "repository": {
     "type": "git",