alepha 0.20.4 → 0.20.6

package/src/api/jobs/index.ts

@@ -4,6 +4,8 @@ import { AlephaLock } from "alepha/lock";
 import { AlephaQueue } from "alepha/queue";
 import { AlephaScheduler } from "alepha/scheduler";
 import { AdminJobController } from "./controllers/AdminJobController.ts";
+import { $job } from "./primitives/$job.ts";
+import { DirectJobDispatcher } from "./providers/DirectJobDispatcher.ts";
 import { JobProvider } from "./providers/JobProvider.ts";
 import { JobQueueProvider } from "./providers/JobQueueProvider.ts";
 import { JobService } from "./services/JobService.ts";
@@ -13,6 +15,8 @@ import { JobService } from "./services/JobService.ts";
 export * from "./controllers/AdminJobController.ts";
 export * from "./entities/jobExecutionEntity.ts";
 export * from "./primitives/$job.ts";
+export * from "./providers/DirectJobDispatcher.ts";
+export * from "./providers/JobDispatcher.ts";
 export * from "./providers/JobProvider.ts";
 export * from "./providers/JobQueueProvider.ts";
 export * from "./schemas/jobConfigAtom.ts";
@@ -39,28 +43,61 @@ declare module "alepha" {
 /**
  * Job execution framework — cron and durable queue work with a single primitive.
  *
- * A `$job` is either **cron-only** (declares `cron`) or **queue-only** (declares `schema`).
- * Cron jobs run inline on their schedule and only record errors by default.
- * Queue jobs use the outbox pattern: push commits to DB first, then notifies via queue.
+ * A `$job` is either **cron-only** (declares `cron`) or **payload-only** (declares `schema`).
  *
- * **This module provides cron support only.** To enable queue-mode jobs, also
- * import {@link AlephaApiJobsQueue} — it brings in the queue layer and infrastructure
- * binding (e.g. Cloudflare Queues). Cron-only deployments (Vercel, CF-without-Queues)
- * do not need `AlephaApiJobsQueue`.
+ * **Three runtime modes:**
+ *
+ * - **cron** — fires on a schedule. Cron-mode jobs are protected by a
+ *   distributed lock by default (`lock: true`), so multi-replica Docker
+ *   deployments only run the handler once per tick. Override with
+ *   `lock: false` if you genuinely want every replica to fire.
+ * - **queue** — push-driven, dispatched through the queue infrastructure
+ *   (`AlephaQueue`, e.g. Cloudflare Queues, Redis). Real-time delivery,
+ *   ideal for high-volume systems. Requires `AlephaApiJobsQueue`.
+ * - **direct** — push-driven, processed in-process right after the caller
+ *   awaits the push. The DB outbox row is the durability guarantee — if
+ *   the process dies, the reconciliation sweep re-dispatches. Default
+ *   when `AlephaApiJobsQueue` is *not* loaded. Best for cheap deployments
+ *   (Cloudflare Workers, single-instance Node) where standing up a queue
+ *   is overkill.
+ *
+ * **Retries** are sweep-driven across all modes (no exponential backoff).
+ * Granularity is bounded by `sweepCron` (default 5 min). The first retry
+ * may land anywhere from a few seconds to ~5 min later depending on when
+ * the next sweep tick fires. Cron jobs that declare `retry` go through
+ * the same sweep path — a transient failure no longer means waiting for
+ * the next cron tick (useful for once-daily jobs).
+ *
+ * **Runtime support for cron triggers**
+ *
+ * - **Long-running Node / Docker** — `CronProvider` runs an in-process
+ *   timer loop. Multi-replica deployments serialize ticks via the cron
+ *   lock (see `$job.lock`).
+ * - **Cloudflare Workers** — the build emits cron expressions into
+ *   `wrangler.jsonc`; Cloudflare invokes the worker on schedule and the
+ *   `cloudflare:scheduled` hook routes the event to the matching jobs.
+ * - **Vercel** — the build emits cron entries into
+ *   `.vercel/output/config.json` mapped to `/_alepha/cron/:name`; the
+ *   serverless handler emits `serverless:cron` and `CronProvider` runs
+ *   the matching job. Set `CRON_SECRET` to require authenticated calls.
  *
  * @module alepha.api.jobs
  */
 export const AlephaApiJobs = $module({
   name: "alepha.api.jobs",
+  primitives: [$job],
   imports: [AlephaScheduler, AlephaLock],
-  services: [JobProvider, JobService, AdminJobController],
+  services: [JobProvider, JobService, AdminJobController, DirectJobDispatcher],
 });
 
 /**
  * Queue support for `$job`. Import alongside {@link AlephaApiJobs} when your
- * app declares queue-mode jobs (any `$job` with a `schema`).
+ * app declares queue-mode jobs (any `$job` with a `schema`) and you want a
+ * real queue (e.g. Cloudflare Queues, Redis) instead of in-process direct
+ * execution.
  *
- * Adds `JobQueueProvider` which plumbs the outbox dispatch through `AlephaQueue`.
+ * Adds `JobQueueProvider` to the container. `JobProvider` detects its
+ * presence at start-up and routes dispatches through it.
  *
  * @module alepha.api.jobs.queue
  */

package/src/api/jobs/primitives/$job.ts

@@ -40,16 +40,8 @@ export interface JobHandlerArgs<T extends TSchema = TSchema> {
   executionId: string;
 }
 
-export interface JobRetryBackoff {
-  initial: DurationLike;
-  factor?: number;
-  max?: DurationLike;
-  jitter?: boolean;
-}
-
 export interface JobRetryOptions {
   retries: number;
-  backoff?: DurationLike | JobRetryBackoff;
   when?: (error: Error) => boolean;
 }
 
@@ -81,11 +73,32 @@ export interface JobPrimitiveOptions<T extends TSchema = TSchema>
   cron?: string;
 
   /**
-   * Retry policy for queue-mode jobs.
+   * Retry policy for queue-mode and direct-mode jobs.
    * Cron-mode jobs do not retry — the next tick re-runs.
+   *
+   * Retries are picked up by the reconciliation sweep, so retry granularity
+   * is bounded by `sweepCron` (default 5 minutes). The first retry may run
+   * earlier than 5 minutes if the sweep tick happens sooner.
    */
   retry?: JobRetryOptions;
 
+  /**
+   * **Cron-mode only.** Whether to acquire a distributed lock around the
+   * cron tick so that only one instance of a multi-replica deployment runs
+   * the handler per tick.
+   *
+   * Has **no effect** on queue-mode and direct-mode jobs — those rely on
+   * the outbox `claim()` UPDATE-guard to serialize work instead, which is
+   * always on.
+   *
+   * To get cross-instance coordination on Docker / Node deployments,
+   * register a real `LockProvider` (e.g. `alepha/lock/redis`). The default
+   * `MemoryLockProvider` is per-process only.
+   *
+   * @default true
+   */
+  lock?: boolean;
+
   /**
    * Max execution time per attempt. Handler receives an `AbortSignal`.
    */

package/src/api/jobs/providers/DirectJobDispatcher.ts

@@ -0,0 +1,71 @@
+import { $inject, Alepha } from "alepha";
+import { $logger } from "alepha/logger";
+import { JobDispatcher } from "./JobDispatcher.ts";
+import { JobProvider } from "./JobProvider.ts";
+
+/**
+ * Default `JobDispatcher` for environments without `AlephaApiJobsQueue`.
+ *
+ * Runs `JobProvider.processExecution` in the background — the caller's
+ * `push()` returns immediately while the handler continues to completion
+ * in the same process. The DB outbox row is the durability guarantee:
+ * if the process dies before the handler finishes, the next sweep tick
+ * picks the row up and re-dispatches.
+ *
+ * **Cloudflare Workers** — when an `executionCtx.waitUntil` is available
+ * in the alepha store at `cloudflare.waitUntil`, the dispatch wraps the
+ * background promise with `waitUntil` so the runtime keeps the isolate
+ * alive past the HTTP response. Without this, the handler would be
+ * terminated when the response is returned and only the next sweep
+ * (every 5 min by default) would re-dispatch.
+ *
+ * **Vercel / single-Node** — on long-running runtimes the event loop
+ * keeps the promise alive naturally; no special wiring is required.
+ */
+export class DirectJobDispatcher extends JobDispatcher {
+  public readonly kind = "direct" as const;
+
+  protected readonly alepha = $inject(Alepha);
+  protected readonly log = $logger();
+
+  // Lazy: resolved on first dispatch to break the JobProvider ↔ Dispatcher
+  // injection cycle (JobProvider injects JobDispatcher to dispatch; we need
+  // JobProvider to actually run executions).
+  protected jobProviderRef?: JobProvider;
+  protected getJobProvider(): JobProvider {
+    if (!this.jobProviderRef) {
+      this.jobProviderRef = this.alepha.inject(JobProvider);
+    }
+    return this.jobProviderRef;
+  }
+
+  public async dispatch(jobName: string, executionId: string): Promise<void> {
+    const promise = this.getJobProvider()
+      .processExecution(jobName, executionId)
+      .catch((err) => {
+        this.log.warn(
+          `Direct execution failed for '${jobName}' (sweep will retry)`,
+          err,
+        );
+      });
+
+    // Cloudflare Workers: keep the isolate alive past the HTTP response so
+    // the handler actually finishes. Outside CF this read returns undefined
+    // and we fall through to plain fire-and-track.
+    const waitUntil = this.alepha.store.get("cloudflare.waitUntil") as
+      | ((p: Promise<unknown>) => void)
+      | undefined;
+    if (typeof waitUntil === "function") {
+      try {
+        waitUntil(promise);
+      } catch (e) {
+        // The runtime may reject waitUntil if called outside a request scope.
+        // Promise still runs; just log.
+        this.log.debug(
+          "waitUntil rejected — falling back to fire-and-track",
+          e,
+        );
+      }
+    }
+  }
+}

package/src/api/jobs/providers/JobDispatcher.ts

@@ -0,0 +1,49 @@
+/**
+ * Abstract dispatcher for queued/direct job executions.
+ *
+ * The default implementation, {@link DirectJobDispatcher}, runs the handler
+ * in-process after the caller's `push()` returns — fast and dependency-free.
+ *
+ * `AlephaApiJobsQueue` substitutes this with `JobQueueProvider`, which
+ * publishes the executionId to `AlephaQueue` so a worker pool can consume
+ * the work asynchronously.
+ *
+ * Substitute via DI:
+ * ```ts
+ * Alepha.create()
+ *   .with({ provide: JobDispatcher, use: MyCustomDispatcher })
+ *   .with(AlephaApiJobs);
+ * ```
+ *
+ * The `kind` getter is read by the `JobProvider.effectiveMode` accessor
+ * and by the admin UI so users can see which dispatcher is currently active.
+ */
+export abstract class JobDispatcher {
+  /**
+   * Identifier for this dispatcher's effective mode. Reported to the admin
+   * UI so operators can see whether `$job` is running in `queue` or
+   * `direct` mode.
+   */
+  public abstract readonly kind: "queue" | "direct";
+
+  /**
+   * Hand off a single execution. The caller's `push()` awaits this so the
+   * caller can be sure the dispatch has at least been initiated. Long-running
+   * work must NOT be awaited here (use background scheduling instead) — this
+   * call should return as quickly as possible.
+   */
+  public abstract dispatch(jobName: string, executionId: string): Promise<void>;
+
+  /**
+   * Optional batch dispatch. The default implementation loops, but
+   * dispatchers backed by a real queue should override this to use the
+   * provider's batch send (e.g. Cloudflare Queues `sendBatch`).
+   */
+  public async dispatchMany(
+    items: Array<{ jobName: string; executionId: string }>,
+  ): Promise<void> {
+    for (const item of items) {
+      await this.dispatch(item.jobName, item.executionId);
+    }
+  }
+}