@rebasepro/server 0.14.0 → 0.14.1

package/dist/init/shutdown.d.ts

@@ -5,6 +5,10 @@ interface ShutdownConfig {
     cronScheduler?: {
         stop(): void;
     };
+    /** Structural, for the same no-circular-imports reason as the backend below. */
+    jobQueue?: {
+        stop(): Promise<void>;
+    };
     realtimeServices: Record<string, RealtimeProvider>;
 }
 /**

package/dist/init/surfaces.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Which HTTP surfaces a runtime process mounts.
+ *
+ * One process serving everything is the only shape this server had, and it is
+ * still the default. This exists so a deployment can boot the *same* image and
+ * the *same* bundle several times over and have each process serve a different
+ * part of the project — a custom function that pins the event loop then does so
+ * in a process that is not also answering `/api/data`.
+ *
+ * A surface is a mount point, not a feature. Switching `data` off does not stop
+ * the collection registry from being built (functions read through it); it stops
+ * `${basePath}/data` from answering. What a process *owns* — the cron scheduler,
+ * the job workers, schema DDL — is a separate axis, because "which URLs answer"
+ * and "which timers fire" are genuinely independent questions. See
+ * {@link RuntimeOwnership}.
+ */
+/**
+ * A mountable HTTP surface.
+ *
+ * These are coarse on purpose: the set of processes anyone wants to run is
+ * small, and a per-route toggle is a combinatorial space nobody tests.
+ *
+ * - `auth` — `${basePath}/auth`, plus `/.well-known/jwks.json`, which is only
+ *   meaningful for a process that mints tokens.
+ * - `data` — `${basePath}/data`, the collection REST API.
+ * - `storage` — `${basePath}/storage`, including the stub mounted when storage
+ *   is unconfigured.
+ * - `admin` — every admin-gated surface: `${basePath}/admin` and its children
+ *   (users, roles, api-keys, backups), `${basePath}/logs`, and the schema
+ *   editor. One name because they share one gate and one audience.
+ * - `functions` — `${basePath}/functions`, the custom function router.
+ * - `cron` — `${basePath}/cron`, the cron *admin* surface. Whether jobs actually
+ *   fire is {@link RuntimeOwnership.cronScheduler}, not this.
+ * - `meta` — `${basePath}/meta`, the contract endpoint a generated SDK reads.
+ */
+export type RuntimeSurface = "auth" | "data" | "storage" | "admin" | "functions" | "cron" | "meta";
+/** Every surface, in a stable order. */
+export declare const ALL_RUNTIME_SURFACES: readonly RuntimeSurface[];
+/** A fully-resolved answer for every surface. */
+export type ResolvedSurfaces = Record<RuntimeSurface, boolean>;
+/**
+ * What a process owns, as opposed to what it serves.
+ *
+ * Both of these are already safe to run in more than one process — the cron
+ * scheduler claims each `(job, slot)` pair in `rebase.cron_claims`, and the job
+ * store claims rows `FOR UPDATE SKIP LOCKED`. So this is not a correctness
+ * control; it is about not giving scheduled work to a process whose replica
+ * count is a scaling decision.
+ */
+export interface RuntimeOwnership {
+    /** Start the cron scheduler's timers. The `cron` surface is separate. */
+    cronScheduler: boolean;
+    /** Start the durable job queue's workers. Only relevant when `jobs.enabled`. */
+    jobWorkers: boolean;
+}
+/** A fully-resolved answer for every owned singleton. */
+export type ResolvedOwnership = RuntimeOwnership;
+/**
+ * Surfaces as a caller may express them: name only what differs.
+ *
+ * `undefined` means "every surface", which is what every existing caller passes
+ * by passing nothing.
+ */
+export type RuntimeSurfaceOptions = Partial<ResolvedSurfaces>;
+/** Ownership as a caller may express it: name only what differs. */
+export type RuntimeOwnershipOptions = Partial<ResolvedOwnership>;
+/**
+ * Resolve a partial surface set against the default, which is everything on.
+ *
+ * Defaulting to on rather than off is the whole compatibility story: a caller
+ * that says nothing gets the process this server has always booted, and a
+ * surface added later is mounted by every existing deployment without anyone
+ * editing a list.
+ */
+export declare function resolveSurfaces(options?: RuntimeSurfaceOptions): ResolvedSurfaces;
+/** Resolve partial ownership against the default, which is owning everything. */
+export declare function resolveOwnership(options?: RuntimeOwnershipOptions): ResolvedOwnership;
+/** The surfaces a process is not serving, for a boot log line. */
+export declare function disabledSurfaces(resolved: ResolvedSurfaces): RuntimeSurface[];

package/dist/init.d.ts

@@ -1,9 +1,12 @@
-import { AuthAdapter, BackendBootstrapper, BootstrappedAuth, DatabaseAdapter, DataDriver, DataSourceDefinition, CollectionCallbacks, AnyCollectionConfig, HealthCheckResult, HistoryConfig, RealtimeProvider } from "@rebasepro/types";
+import { AuthAdapter, BackendBootstrapper, BootstrappedAuth, DatabaseAdapter, DataDriver, DataSourceDefinition, CollectionCallbacks, AnyCollectionConfig, HealthCheckResult, HistoryConfig, InitializedDriver, RealtimeProvider } from "@rebasepro/types";
 import { BackendCollectionRegistry } from "./collections/BackendCollectionRegistry";
 import { DriverRegistry } from "./services/driver-registry";
 import { Server } from "http";
 import { Hono } from "hono";
 import { HonoEnv } from "./api/types";
+import { type RuntimeOwnershipOptions, type RuntimeSurfaceOptions } from "./init/surfaces";
+import type { JwtSigningKeyConfig } from "./auth/jwt-keys";
+import type { JobQueueOptions } from "./jobs/types";
 import { BackendStorageConfig, StorageController, StorageRegistry } from "./storage";
 import { type DataRateLimitConfig } from "./auth/rate-limiter";
 import { EmailConfig } from "./email";
@@ -32,6 +35,22 @@ export interface RebaseAuthConfig {
      */
     collection?: AnyCollectionConfig;
     jwtSecret?: string;
+    /**
+     * Asymmetric keys for signing access tokens, newest first. Additive —
+     * without them tokens stay HS256, exactly as before. With them, anyone can
+     * verify a session from `/.well-known/jwks.json` without holding the key
+     * that mints one, and a key can be rotated without signing users out.
+     *
+     * ```ts
+     * auth: {
+     *   jwtSecret: process.env.JWT_SECRET,
+     *   signingKeys: [{ kid: "2026-08", privateKey: process.env.JWT_PRIVATE_KEY! }]
+     * }
+     * ```
+     */
+    signingKeys?: JwtSigningKeyConfig[];
+    /** Which of {@link signingKeys} mints new tokens. Defaults to the first. */
+    activeKid?: string;
     accessExpiresIn?: string;
     refreshExpiresIn?: string;
     requireAuth?: boolean;
@@ -261,6 +280,21 @@ export interface RebaseBackendConfig {
     schemaEditor?: boolean;
     /** Options that only apply when collections are derived from the database. */
     baas?: BaasOptions;
+    /**
+     * The pre-init handle to hand the boot-time schema hooks, when the caller
+     * has one.
+     *
+     * Those hooks run before any driver is initialized, so there is no driver
+     * result to pass — the bundle boot path can still supply a stand-in built
+     * from the connection its coordinator opened, and does, because a driver
+     * written before this was optional dereferences `driverResult.internals`
+     * unconditionally. An application that constructed its own adapter has no
+     * such handle to give (it gave the connection to the adapter instead), so it
+     * leaves this unset and the adapter falls back to its own connection.
+     *
+     * Not part of the ordinary configuration surface: set by `bootFromBundle`.
+     */
+    provisioningDriverResult?: InitializedDriver;
     /**
      * Declared data sources, shared with the frontend `<Rebase dataSources>`.
      *
@@ -370,6 +404,43 @@ export interface RebaseBackendConfig {
      */
     history?: HistoryConfig;
     enableSwagger?: boolean;
+    /**
+     * Which HTTP surfaces this process mounts. Every one, unless named.
+     *
+     * The point of naming a subset is to run the same bundle as several
+     * cooperating processes — one answering `/api/data`, another `/api/functions`
+     * — so a custom function that pins the event loop does not do it in the
+     * process serving the data API. `bootFromBundle` derives this from
+     * `REBASE_ROLE`; passing it directly is for tests and for embedders.
+     *
+     * Omitting it, or naming only some surfaces, leaves the rest mounted. That
+     * default is deliberate: a surface added in a later version is served by
+     * every existing deployment without anyone editing a list.
+     */
+    /**
+     * Whether this process provisions the collection schema and its RLS
+     * policies at boot. Default `true` — what every deployment does today.
+     *
+     * `false` on every process but one in a split deployment: `CREATE … IF NOT
+     * EXISTS` reads the catalog and then writes to it, so N processes racing to
+     * provision the same schema is a state nobody designed. `bootFromBundle`
+     * derives it from `REBASE_ROLE`.
+     */
+    provisionSchema?: boolean;
+    surfaces?: RuntimeSurfaceOptions;
+    /**
+     * Which background singletons this process runs. All of them, unless named.
+     *
+     * Separate from {@link surfaces} because "which URLs answer" and "which
+     * timers fire" are independent: a process can serve the cron *admin* surface
+     * without being the one that fires the jobs, and vice versa.
+     *
+     * Neither is a correctness control — the cron scheduler claims each
+     * `(job, slot)` pair and the job store claims rows `FOR UPDATE SKIP LOCKED`,
+     * so running several of each is already safe. It is about not handing
+     * scheduled work to a process whose replica count is a scaling decision.
+     */
+    ownership?: RuntimeOwnershipOptions;
     functionsDir?: string;
     /**
      * Per-request ceiling for `/api/functions/*`, in milliseconds.
@@ -382,6 +453,24 @@ export interface RebaseBackendConfig {
      * cancelled, so give outbound calls an `AbortSignal`.
      */
     functionsTimeoutMs?: number;
+    /**
+     * Serve only some of the bundle's functions.
+     *
+     * How one expensive function gets its own replica count and its own blast
+     * radius without its code moving anywhere. `bootFromBundle` fills this from
+     * `REBASE_FUNCTIONS_ONLY` / `REBASE_FUNCTIONS_EXCLUDE`.
+     *
+     * A name that is not in the bundle fails the boot — see `selectFunctions`.
+     */
+    functionsSelection?: import("./functions/selection").FunctionSelection;
+    /**
+     * Forward `/api/functions/*` to another process instead of serving it here.
+     *
+     * Only consulted when the `functions` surface is off — a process that serves
+     * them has nothing to forward. `bootFromBundle` fills this from
+     * `REBASE_FUNCTIONS_UPSTREAM` on the `api` role.
+     */
+    functionsUpstream?: string;
     cronsDir?: string;
     /**
      * Enable/disable database persistence for cron job execution logs.
@@ -389,6 +478,24 @@ export interface RebaseBackendConfig {
      * Default: true.
      */
     cronPersistence?: boolean;
+    /**
+     * The durable job queue: background work that survives a restart.
+     *
+     * Off unless `enabled` is set, because a worker polls the database forever
+     * and that is not a default anyone chose. Requires a driver that can run
+     * SQL; on one that cannot, the queue is unavailable and callers are told
+     * so at boot rather than at the first enqueue.
+     *
+     * ```ts
+     * jobs: {
+     *   enabled: true,
+     *   tasks: {
+     *     "send-welcome": async ({ payload }) => { await sendEmail(payload.email); }
+     *   }
+     * }
+     * ```
+     */
+    jobs?: JobQueueOptions;
     /**
      * Maximum request body size in bytes for API routes (default: 10MB).
      * Set to 0 to disable the global limit entirely.
@@ -484,6 +591,19 @@ export interface RebaseBackendInstance {
     storageController?: StorageController;
     collectionRegistry: BackendCollectionRegistry;
     cronScheduler?: import("./cron").CronScheduler;
+    /**
+     * The durable job queue, when `jobs.enabled` is set and the driver can run
+     * SQL. Present on the instance because the *producers* live in application
+     * code — a `WebhookDispatcher` is constructed by the app, so this is what
+     * it gets handed:
+     *
+     * ```ts
+     * const { jobQueue } = await initializeRebaseBackend({ jobs: { enabled: true } });
+     * const dispatcher = new WebhookDispatcher({ jobQueue });
+     * jobQueue?.register(WEBHOOK_DELIVERY_TASK, ctx => dispatcher.deliverQueuedJob(ctx.payload));
+     * ```
+     */
+    jobQueue?: import("./jobs").JobQueue;
     /**
      * Attach collection callbacks AFTER initialization.
      *

package/dist/jobs/index.d.ts

@@ -0,0 +1,5 @@
+export { createJobStore } from "./job-store";
+export type { JobStore } from "./job-store";
+export { createJobQueue, defaultBackoff } from "./job-queue";
+export type { JobQueue } from "./job-queue";
+export type { EnqueueOptions, JobContext, JobHandler, JobQueueClient, JobQueueOptions, JobRecord, JobStatus } from "./types";

package/dist/jobs/job-queue.d.ts

@@ -0,0 +1,14 @@
+import type { JobStore } from "./job-store.js";
+import type { JobHandler, JobQueueClient, JobQueueOptions } from "./types.js";
+/** 1s, 5s, 25s, 125s … capped at an hour. */
+export declare function defaultBackoff(attempt: number): number;
+export interface JobQueue extends JobQueueClient {
+    start(): void;
+    stop(): Promise<void>;
+    /** Run one poll's worth of work and return how many jobs ran. For tests and for `/jobs/drain`. */
+    runOnce(): Promise<number>;
+    /** Registered after construction — how `tasks` from config and internal producers meet. */
+    register<P = unknown>(task: string, handler: JobHandler<P>): void;
+    isRunning(): boolean;
+}
+export declare function createJobQueue(store: JobStore, options?: JobQueueOptions): JobQueue;

package/dist/jobs/job-store.d.ts

@@ -0,0 +1,22 @@
+import type { DataDriver } from "@rebasepro/types";
+import type { JobRecord } from "./types.js";
+export interface JobStore {
+    ensureTable(): Promise<void>;
+    /** Returns the new job's id, or `null` if an idempotency key matched unfinished work. */
+    insert(job: {
+        task: string;
+        payload: unknown;
+        runAt: Date;
+        maxAttempts: number;
+        idempotencyKey?: string;
+    }): Promise<string | null>;
+    /** Atomically take up to `limit` runnable jobs for this worker. */
+    claim(limit: number, workerId: string): Promise<JobRecord[]>;
+    complete(id: string): Promise<void>;
+    /** Back to `pending` with a later `runAt`, or `failed` when out of attempts. */
+    fail(id: string, error: string, retryAt: Date | null): Promise<void>;
+    /** Return jobs stranded by a worker that died holding them. Resolves with how many. */
+    reapExpired(visibilityTimeoutMs: number): Promise<number>;
+    fetch(id: string): Promise<JobRecord | null>;
+}
+export declare function createJobStore(driver: DataDriver): JobStore | undefined;

package/dist/jobs/types.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Background work that survives a restart.
+ *
+ * Rebase already had two ways to run something later, and neither is this one.
+ * Cron runs work on a *schedule*, coordinated across instances by a claims
+ * table. The webhook dispatcher runs work *soon*, from an array in memory — and
+ * says so in its own docblock: "the queue is in-process and in-memory. A
+ * crash…". Everything queued that way is gone on deploy, on a crash, and on the
+ * pod being rescheduled, with no record that it existed.
+ *
+ * A job is a row. It is claimed by exactly one worker, retried on failure with
+ * a widening delay, and left in the table when it finally gives up so somebody
+ * can look at it. The table is the queue: there is nothing to install, nothing
+ * to run alongside Postgres, and a job enqueued in a transaction that rolls
+ * back was never enqueued.
+ */
+/** Where a job is in its life. */
+export type JobStatus = 
+/** Waiting for `runAt` to arrive and a worker to claim it. */
+"pending"
+/** Claimed. `lockedAt` is when, which is what makes a dead worker recoverable. */
+ | "running"
+/** Handler returned. Kept briefly so a caller can observe the outcome. */
+ | "succeeded"
+/**
+ * Out of attempts. Deliberately *kept* rather than deleted: a queue that
+ * silently drops what it could not deliver is indistinguishable from one
+ * with nothing to do.
+ */
+ | "failed";
+/** A job as stored. */
+export interface JobRecord<P = unknown> {
+    id: string;
+    /** Which handler runs it. */
+    task: string;
+    payload: P;
+    status: JobStatus;
+    /** Not before this instant. Bumped on each retry to implement backoff. */
+    runAt: string;
+    attempts: number;
+    maxAttempts: number;
+    lastError: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** What a handler is given. */
+export interface JobContext<P = unknown> {
+    id: string;
+    task: string;
+    payload: P;
+    /**
+     * Which attempt this is, counting from 1.
+     *
+     * Worth branching on: the first attempt of a webhook delivery and its
+     * fourth are the same call, but the fourth is the one where it is worth
+     * logging loudly, or falling back to a different route.
+     */
+    attempt: number;
+    maxAttempts: number;
+}
+/**
+ * A handler. Throwing is how a job fails — there is no `return false`, because
+ * a boolean would be silently ignored by every handler that forgot to return
+ * one, and the failure path has to be the one you get by default.
+ */
+export type JobHandler<P = unknown> = (ctx: JobContext<P>) => Promise<void> | void;
+/** Options for a single enqueue. */
+export interface EnqueueOptions {
+    /** Run no earlier than this many milliseconds from now. */
+    delayMs?: number;
+    /** Overrides the queue default (3). */
+    maxAttempts?: number;
+    /**
+     * At most one *unfinished* job may hold a given key.
+     *
+     * The narrow scope is the point. Keying on the whole lifetime would mean a
+     * key could never be reused — "send the nightly digest to user 7" would
+     * work once, ever. Keying on unfinished work collapses a double-click, a
+     * retried request, and two instances reacting to one event into a single
+     * job, and still lets tomorrow's digest through.
+     */
+    idempotencyKey?: string;
+}
+/** How the worker behaves. */
+export interface JobQueueOptions {
+    /**
+     * Off unless asked for. A worker polls the database forever, and turning
+     * that on for every backend that happens to run on Postgres is not a
+     * default anyone chose.
+     */
+    enabled?: boolean;
+    /** Named handlers. A job whose `task` is not here is left alone, not failed — see the worker. */
+    tasks?: Record<string, JobHandler<never>>;
+    /** How many jobs one instance runs at once. Default 5. */
+    concurrency?: number;
+    /** How often to look for work when the last look found none. Default 2000ms. */
+    pollIntervalMs?: number;
+    /**
+     * How long a claimed job may stay claimed before another worker may take
+     * it. Default 5 minutes.
+     *
+     * This is the only thing that recovers work from a worker that died holding
+     * it — a `SIGKILL`ed pod cannot release its own claim. It is therefore also
+     * the interval after which a job that legitimately runs longer than this
+     * gets a *second* worker running it concurrently, so it must exceed the
+     * slowest handler.
+     */
+    visibilityTimeoutMs?: number;
+    /** Attempts before a job is left `failed`. Default 3. */
+    maxAttempts?: number;
+    /**
+     * Delay before attempt N+1, in milliseconds. Default: 1s, 5s, 25s, …
+     * capped at an hour.
+     */
+    backoff?: (attempt: number) => number;
+}
+/** The enqueue side, as application code sees it. */
+export interface JobQueueClient {
+    /**
+     * Add a job. Resolves with its id, or with `null` when an
+     * `idempotencyKey` matched an unfinished job — the caller usually does not
+     * care which, and the ones that do can tell.
+     */
+    enqueue<P = unknown>(task: string, payload?: P, options?: EnqueueOptions): Promise<string | null>;
+}