@rebasepro/server 0.22.0 → 0.23.0

package/dist/init/docs.d.ts

@@ -1,4 +1,4 @@
-import { Hono } from "hono";
+import { Hono, type MiddlewareHandler } from "hono";
 import { CollectionConfig } from "@rebasepro/types";
 import { HonoEnv } from "../api/types.js";
 /**
@@ -9,5 +9,8 @@ import { HonoEnv } from "../api/types.js";
  * active collection. A direct-transport collection is served by the client
  * against its own backend; documenting it here publishes a full set of CRUD
  * paths that 404, with a Try-It button next to each.
+ *
+ * `adminGate` is the runtime's admin gate — the middlewares every admin surface
+ * sits behind — for the spec when it is not public.
  */
-export declare function mountOpenApiDocs(app: Hono<HonoEnv>, basePath: string, enableSwagger: boolean | undefined, serverCollections: CollectionConfig[], requireAuth: boolean): Promise<void>;
+export declare function mountOpenApiDocs(app: Hono<HonoEnv>, basePath: string, enableSwagger: boolean | undefined, serverCollections: CollectionConfig[], requireAuth: boolean, adminGate: MiddlewareHandler<HonoEnv>[]): Promise<void>;

package/dist/init/shutdown.d.ts

@@ -2,17 +2,20 @@ import { Server } from "http";
 import { RealtimeProvider } from "@rebasepro/types";
 interface ShutdownConfig {
     server: Server;
+    /** Structural, for the same no-circular-imports reason as the backend below. */
     cronScheduler?: {
-        stop(): void;
+        stop(timeoutMs?: number): Promise<void> | void;
     };
     /** Structural, for the same no-circular-imports reason as the backend below. */
     jobQueue?: {
-        stop(): Promise<void>;
+        stop(timeoutMs?: number): Promise<void>;
     };
     /** Structural, same reason. */
     rlsAudit?: {
         stop(): void;
     };
+    /** The stop `MetricsHistory.start()` returned: its interval writes to the pool. */
+    stopMetricsSampler?: () => void;
     realtimeServices: Record<string, RealtimeProvider>;
 }
 /**
@@ -32,7 +35,9 @@ export interface ShutdownHandlerOptions {
     /**
      * Hard force-exit timeout in milliseconds. If the shutdown sequence
      * (drain + cleanup) has not completed by then, the process exits with
-     * code 1. Also passed to `backend.shutdown()` as its drain timeout.
+     * code 1. `backend.shutdown()` is given this budget less a reserve for
+     * `onCleanup` (the smaller of 2s and a fifth of it), so a drain the
+     * backend has to force still ends in the pool close.
      *
      * @default 15000
      */

package/dist/jobs/index.d.ts

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

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

@@ -2,10 +2,31 @@ 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;
+/**
+ * Thrown by a handler for a failure no retry can change — a destination that
+ * is refused, a receiver that redirects. The job is dead-lettered on this
+ * attempt, with the message as its `last_error`, instead of spending its
+ * remaining attempts proving the same thing. Returning normally is not the
+ * alternative: that records the job as succeeded.
+ */
+export declare class PermanentJobError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
 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`. */
+    /**
+     * Stop claiming, and wait for the jobs in flight — for at most `timeoutMs`
+     * when given. A job still running when the budget runs out keeps its claim
+     * and is recovered by the visibility timeout; waiting on it without a bound
+     * would let one handler that never settles hold the whole shutdown.
+     */
+    stop(timeoutMs?: number): Promise<void>;
+    /**
+     * Claim what fits in the free slots, run it, and resolve with how many jobs
+     * ran. For tests and for `/jobs/drain`; not meant to run beside `start()`.
+     */
     runOnce(): Promise<number>;
     /** Registered after construction — how `tasks` from config and internal producers meet. */
     register<P = unknown>(task: string, handler: JobHandler<P>): void;

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

@@ -1,5 +1,21 @@
 import type { DataDriver } from "@rebasepro/types";
 import type { JobRecord } from "./types.js";
+/**
+ * Which claim an outcome belongs to: the worker holding the job, and the
+ * attempt that claim spent.
+ *
+ * The visibility timeout hands a job to a second worker when the first stops
+ * renewing its claim, and the first may still be running — slow, not dead. Its
+ * outcome is then about an attempt the table has moved past, and writing it
+ * would mark a running job `succeeded`, or send a finished one back to
+ * `pending` for another run. Both writes therefore apply only while the claim
+ * they name still holds the row. The attempt is part of the identity because a
+ * worker's own reaper can hand a job back to the same worker in another slot.
+ */
+export interface JobClaim {
+    workerId: string;
+    attempt: number;
+}
 export interface JobStore {
     ensureTable(): Promise<void>;
     /** Returns the new job's id, or `null` if an idempotency key matched unfinished work. */
@@ -10,11 +26,27 @@ export interface JobStore {
         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>;
+    /**
+     * Atomically take up to `limit` runnable jobs for this worker — only jobs
+     * whose task is in `tasks`, when it is given. A worker never claims work it
+     * cannot run: a claim spends an attempt, so an instance running older code
+     * during a rollout would otherwise dead-letter the newer code's jobs.
+     */
+    claim(limit: number, workerId: string, tasks?: readonly string[]): Promise<JobRecord[]>;
+    /** Mark the job `succeeded` — a no-op once `claim` no longer holds it. */
+    complete(id: string, claim: JobClaim): Promise<void>;
+    /**
+     * Back to `pending` with a later `runAt`, or `failed` when out of attempts —
+     * a no-op once `claim` no longer holds it.
+     */
+    fail(id: string, error: string, retryAt: Date | null, claim: JobClaim): Promise<void>;
+    /**
+     * Renew `claim` on a job whose handler is still running, so the visibility
+     * timeout only ever reclaims a job from a worker that stopped renewing.
+     * Resolves with whether the claim still held. A store without it leaves a
+     * handler that outlives the timeout to be run a second time beside itself.
+     */
+    heartbeat?(id: string, claim: JobClaim): Promise<boolean>;
     /** 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>;

package/dist/jobs/types.d.ts

@@ -101,14 +101,16 @@ export interface JobQueueOptions {
     /** 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.
+     * How long a claim may go unrenewed before another worker may take the job.
+     * 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.
+     * it — a `SIGKILL`ed pod cannot release its own claim. A live worker renews
+     * the claim every third of this while the handler runs, so a handler may
+     * run longer than it; what it bounds is how long a dead worker's job waits.
+     * A worker whose event loop is blocked for longer than this cannot renew,
+     * and its job is run again beside it — though only the claim that holds
+     * the job when a run finishes gets to record its outcome.
      */
     visibilityTimeoutMs?: number;
     /** Attempts before a job is left `failed`. Default 3. */