@openlup/platform 0.0.0 → 0.16.0

package/src/scheduler/jobs.ts

@@ -0,0 +1,119 @@
+// Transport-neutral scheduled jobs.
+//
+// A job is `{ id, schedule, lease?, run(context) }`. Domains and packages contribute jobs to a
+// registry; a host runs them on its own timer or through an authenticated HTTP cron entry, and both
+// call the same `run`. The in-process path carries no HTTP secret. When a job declares a lease, the
+// runner claims it through the deployment's job-lease port first and skips the run when another
+// instance holds it; a job that fences its own work (for example the outbox) declares no lease.
+
+import type {
+  JobLeasePort,
+  PlatformJobFinishSummary,
+  PlatformJobInvocation,
+} from "@openlup/core/platform-runtime";
+
+export interface ScheduledJobContext {
+  /** Who triggered this run; evidence only, never an authorization control. */
+  readonly invocation: PlatformJobInvocation;
+  /** The lease's run id when the job declares a lease. */
+  readonly runId?: string;
+  readonly signal?: AbortSignal;
+}
+
+export interface ScheduledJob {
+  readonly id: string;
+  /** Crontab expression (UTC). */
+  readonly schedule: string;
+  /** Claim a job-run lease of this many seconds before running. */
+  readonly lease?: { readonly seconds: number };
+  run(context: ScheduledJobContext): Promise<PlatformJobFinishSummary | void> | PlatformJobFinishSummary | void;
+}
+
+export type ScheduledJobRunResult =
+  | { readonly status: "completed"; readonly summary: PlatformJobFinishSummary | null }
+  | { readonly status: "skipped"; readonly reason: string };
+
+const EMPTY_SUMMARY: PlatformJobFinishSummary = { checked: 0, updated: 0, failures: 0, skipped: false };
+
+/** Merge contributed jobs into one registry; refuses a duplicate id or an empty id or schedule. */
+export function createScheduledJobRegistry(
+  ...contributions: ReadonlyArray<readonly ScheduledJob[]>
+): readonly ScheduledJob[] {
+  const seen = new Set<string>();
+  const jobs: ScheduledJob[] = [];
+  for (const job of contributions.flat()) {
+    if (!job.id?.trim()) throw new Error("scheduled_job_id_required");
+    if (!job.schedule?.trim()) throw new Error(`scheduled_job_schedule_required:${job.id}`);
+    if (seen.has(job.id)) throw new Error(`scheduled_job_duplicate:${job.id}`);
+    seen.add(job.id);
+    jobs.push(job);
+  }
+  return Object.freeze(jobs);
+}
+
+/**
+ * The cron expression for a fixed cadence: a whole number of minutes that divides an hour, or a
+ * whole number of hours that divides a day. Any other cadence is refused rather than approximated.
+ */
+export function cronFromCadenceSeconds(cadenceSeconds: number): string {
+  if (Number.isInteger(cadenceSeconds) && cadenceSeconds > 0 && cadenceSeconds % 60 === 0) {
+    const minutes = cadenceSeconds / 60;
+    if (minutes < 60 && 60 % minutes === 0) return minutes === 1 ? "* * * * *" : `*/${minutes} * * * *`;
+    if (minutes % 60 === 0) {
+      const hours = minutes / 60;
+      if (hours === 24) return "0 0 * * *";
+      if (hours < 24 && 24 % hours === 0) return hours === 1 ? "0 * * * *" : `0 */${hours} * * *`;
+    }
+  }
+  throw new Error(`scheduled_job_cadence_unsupported:${cadenceSeconds}`);
+}
+
+/**
+ * Jobs for a package contribution's cadence schedules; each run passes the invocation through. A
+ * run that reports `{ outcome: "failed" }` instead of throwing fails the job, so neither transport
+ * reports it as completed.
+ */
+export function scheduledJobsFromContribution(
+  schedules: ReadonlyArray<{ id: string; cadenceSeconds: number; run: (invocation: PlatformJobInvocation) => unknown }>,
+): ScheduledJob[] {
+  return schedules.map((schedule) => ({
+    id: schedule.id,
+    schedule: cronFromCadenceSeconds(schedule.cadenceSeconds),
+    async run({ invocation }) {
+      const result = await schedule.run(invocation);
+      if (typeof result === "object" && result !== null && (result as { outcome?: unknown }).outcome === "failed") {
+        throw new Error(`scheduled_job_outcome_failed:${schedule.id}`);
+      }
+    },
+  }));
+}
+
+/** Run one job once, under its lease when it declares one. */
+export async function runScheduledJob(
+  job: ScheduledJob,
+  options: { invocation: PlatformJobInvocation; lease?: JobLeasePort; signal?: AbortSignal },
+): Promise<ScheduledJobRunResult> {
+  if (!job.lease) {
+    const summary = await job.run({ invocation: options.invocation, signal: options.signal });
+    return { status: "completed", summary: summary ?? null };
+  }
+  if (!options.lease) throw new Error(`scheduled_job_lease_port_required:${job.id}`);
+  const claim = await options.lease.claimJobRun(job.id, options.invocation, job.lease.seconds);
+  if (!claim.acquired) return { status: "skipped", reason: claim.reason };
+  if (!claim.runId) throw new Error(`scheduled_job_lease_without_run_id:${job.id}`);
+  let summary: PlatformJobFinishSummary | void;
+  try {
+    summary = await job.run({ invocation: options.invocation, runId: claim.runId, signal: options.signal });
+  } catch (error) {
+    try {
+      await options.lease.finishJobRun(job.id, claim.runId, options.invocation, "failed", { ...EMPTY_SUMMARY, failures: 1 });
+    } catch (finishError) {
+      throw new AggregateError([error, finishError], `scheduled_job_failed_unfinished:${job.id}`);
+    }
+    throw error;
+  }
+  const finished = await options.lease.finishJobRun(job.id, claim.runId, options.invocation, "success", summary ?? EMPTY_SUMMARY);
+  // A refused finish means the lease no longer belongs to this run; its result cannot be recorded.
+  if (!finished) throw new Error(`scheduled_job_finish_refused:${job.id}`);
+  return { status: "completed", summary: summary ?? null };
+}

package/src/scheduler/nodeScheduler.ts

@@ -0,0 +1,123 @@
+// Node (self-hosted) SchedulerPort adapter.
+//
+// Unlike a managed host with an adopter-owned declarative cron manifest, a self-hosted Node bundle owns the timers itself.
+// This adapter:
+//   1. Takes its job set from the platform-runtime configuration `crons` (the SAME single source
+//      the managed-host adapter also reads), never a hand-copied list.
+//   2. Registers each job with node-cron (injected lazily so `pg`/`node-cron` aren't required to
+//      typecheck or to run the default vercel-supabase path).
+//   3. Wraps every job body in a PER-JOB advisory lock: multi-instance Node must not
+//      double-run a cron. Only the instance that acquires `pg_try_advisory_lock(<job>)` runs; others
+//      skip. The lock is released in a finally, even if the body throws.
+
+import type { SchedulerPort } from "@openlup/core/platform-runtime";
+import type { HttpRequest } from "../http/index.js";
+import type { ScheduledJobDeclaration } from "./jobRegistry.js";
+import { verifyCronAuth } from "./vercelScheduler.js";
+import { createNoopAdvisoryLock, type AdvisoryLock } from "./advisoryLock.js";
+
+type CronEnv = Record<string, string | undefined> & { CRON_SECRET?: string };
+
+/** Minimal node-cron surface we depend on (keeps the package optional at type level). */
+export interface CronScheduler {
+  schedule(
+    expression: string,
+    handler: () => void | Promise<void>,
+    options?: { timezone?: string },
+  ): { stop: () => void };
+}
+
+interface RegisteredTimer {
+  jobId: string;
+  stop: () => void;
+}
+
+export interface NodeSchedulerAdapter extends SchedulerPort {
+  readonly jobs: readonly ScheduledJobDeclaration[];
+  /** Stop all registered node-cron timers (graceful shutdown). */
+  stopAll(): void;
+}
+
+export interface CreateNodeSchedulerOptions {
+  /** node-cron instance (inject `import("node-cron")` at the host boot site). */
+  cron: CronScheduler;
+  /** Per-job advisory lock; defaults to a no-op (single-instance) — supply pg-backed in prod. */
+  lock?: AdvisoryLock;
+  /** Environment whose CRON_SECRET verifies an invocation. */
+  env: CronEnv;
+  /** The deployment's declared jobs (see `loadJobRegistry`). */
+  jobs: readonly ScheduledJobDeclaration[];
+  /** crontab timezone; jobs are authored in UTC to match Vercel. */
+  timezone?: string;
+  /** Structured error sink for failed job bodies (defaults to console.error). */
+  onError?: (jobId: string, error: unknown) => void;
+}
+
+/**
+ * Wrap a job body with the per-job advisory lock. Returns a guarded runner that:
+ *  - tries to acquire the lock; if not acquired (another instance is running it) -> skip silently;
+ *  - runs the body; always releases the lock in finally.
+ */
+export function withAdvisoryLock(
+  jobId: string,
+  lock: AdvisoryLock,
+  body: () => Promise<void> | void,
+  onError: (jobId: string, error: unknown) => void,
+): () => Promise<void> {
+  return async () => {
+    const acquired = await lock.tryAcquire(jobId);
+    if (!acquired) {
+      // Another instance holds the lock for this minute — skip (no double-run).
+      return;
+    }
+    try {
+      await body();
+    } catch (error) {
+      onError(jobId, error);
+    } finally {
+      await lock.release(jobId);
+    }
+  };
+}
+
+/** Build the Node scheduler adapter backed by node-cron + per-job advisory locks. */
+export function createNodeScheduler(options: CreateNodeSchedulerOptions): NodeSchedulerAdapter {
+  const env = options.env;
+  const jobs = options.jobs;
+  const lock = options.lock ?? createNoopAdvisoryLock();
+  const onError =
+    options.onError ??
+    ((jobId: string, error: unknown) => {
+      console.error(`[node-scheduler] job "${jobId}" failed`, error);
+    });
+  const scheduleById = new Map(jobs.map((job) => [job.jobId, job.schedule]));
+  const timers: RegisteredTimer[] = [];
+
+  return {
+    jobs,
+    register(input) {
+      // Prefer an explicit schedule; fall back to the single-source registry when the caller
+      // omits one (empty string or undefined both fall back).
+      const explicit = input.schedule?.trim();
+      const schedule = explicit && explicit.length > 0 ? explicit : scheduleById.get(input.jobId);
+      if (!schedule) {
+        throw new Error(
+          `node-scheduler: job "${input.jobId}" is not declared in config/platform-runtime.json crons`,
+        );
+      }
+      const guarded = withAdvisoryLock(input.jobId, lock, input.handler, onError);
+      const timer = options.cron.schedule(schedule, guarded, { timezone: options.timezone });
+      timers.push({ jobId: input.jobId, stop: timer.stop });
+    },
+    verifyInvocation(req: HttpRequest) {
+      // Self-hosted invocations still present the shared CRON_SECRET; reuse the canonical check.
+      return verifyCronAuth(req, env);
+    },
+    stopAll() {
+      for (const timer of timers) {
+        timer.stop();
+      }
+      timers.length = 0;
+    },
+  };
+}

package/src/scheduler/vercelScheduler.ts

@@ -0,0 +1,71 @@
+// Vercel cron SchedulerPort adapter.
+//
+// On Vercel, scheduling is declarative: an adopter-owned `crons` manifest generated from the
+// platform-runtime configuration (the same single source as `jobs`) tells Vercel to GET
+// each `/api/cron/*` endpoint on its schedule. So `register()` is a no-op verification step here —
+// the platform owns the timer. What this adapter OWNS is invocation authenticity: every cron
+// endpoint must verify `Authorization: Bearer ${CRON_SECRET}`, fail-closed when the secret is unset.
+//
+// `verifyCronAuth(req, env)` is the reusable form of a bearer check against CRON_SECRET; cron
+// handlers and the Node host call it instead of re-implementing the comparison.
+
+import type { PlatformHttpRequest, SchedulerPort } from "@openlup/core/platform-runtime";
+import type { ScheduledJobDeclaration } from "./jobRegistry.js";
+import { bearerToken, cronSecretMatches } from "./cronSecret.js";
+
+type CronEnv = Record<string, string | undefined> & { CRON_SECRET?: string };
+
+export { bearerToken } from "./cronSecret.js";
+
+/**
+ * Verify a cron invocation is authentic. Fail-CLOSED:
+ *  - CRON_SECRET unset                         -> false (never authorize when no secret configured)
+ *  - presented Bearer token != CRON_SECRET     -> false
+ *  - presented Bearer token == CRON_SECRET     -> true
+ * This is the single canonical check that replaces the per-handler inline comparisons.
+ */
+export function verifyCronAuth(req: PlatformHttpRequest, env: CronEnv): boolean {
+  const expected = env.CRON_SECRET;
+  if (!expected) {
+    return false;
+  }
+  return cronSecretMatches(bearerToken(req), expected);
+}
+
+export interface VercelSchedulerAdapter extends SchedulerPort {
+  /** The jobs this scheduler knows about, derived from the platform-runtime single source. */
+  readonly jobs: readonly ScheduledJobDeclaration[];
+}
+
+/**
+ * Build the Vercel cron scheduler adapter.
+ *
+ * `register()` validates the job is part of the declared registry (so callers can't silently
+ * register a job Vercel will never fire) but does NOT start a timer — Vercel's cron does that.
+ */
+export function createVercelScheduler(options: {
+  env: CronEnv;
+  /** The deployment's declared jobs (see `loadJobRegistry`). */
+  jobs: readonly ScheduledJobDeclaration[];
+}): VercelSchedulerAdapter {
+  const env = options.env;
+  const jobs = options.jobs;
+  const knownIds = new Set(jobs.map((job) => job.jobId));
+
+  return {
+    jobs,
+    register(input) {
+      // Vercel owns the timer through the adopter manifest. We only guard that the job is declared,
+      // surfacing drift between code and the single-source registry at registration time.
+      if (!knownIds.has(input.jobId)) {
+        throw new Error(
+          `vercel-scheduler: job "${input.jobId}" is not declared in config/platform-runtime.json crons`,
+        );
+      }
+      // No-op timer: the handler at the cron path is invoked by Vercel directly.
+    },
+    verifyInvocation(req) {
+      return verifyCronAuth(req, env);
+    },
+  };
+}