@rebasepro/server 0.22.0 → 0.24.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/health.d.ts

@@ -1,4 +1,4 @@
-import { AuthSchemaHealth, DataDriver, HealthCheckResult } from "@rebasepro/types";
+import { AuthSchemaHealth, DataDriver, HealthCheckResult, RealtimeProvider } from "@rebasepro/types";
 /**
  * @param defaultDriver     — probed for basic database reachability.
  * @param authSchemaCheck   — optional; asserts the auth schema is one this
@@ -8,4 +8,19 @@ import { AuthSchemaHealth, DataDriver, HealthCheckResult } from "@rebasepro/type
  *   check. Reporting that as healthy is what lets an orchestrator keep routing
  *   traffic to a server that cannot authenticate anyone.
  */
-export declare function createHealthCheck(defaultDriver: DataDriver, authSchemaCheck?: () => Promise<AuthSchemaHealth>): () => Promise<HealthCheckResult>;
+/**
+ * How long a realtime LISTEN connection may be down before `/health` says so.
+ *
+ * A dropped connection is replaced within seconds, and a pod that reports
+ * itself degraded over that would shed traffic for nothing. One still down
+ * after this is not reconnecting: every external and cross-instance change is
+ * being lost while writes through this pod still look live, which is the
+ * failure an orchestrator should route around.
+ */
+export declare const REALTIME_LISTENER_GRACE_MS = 60000;
+/**
+ * @param realtimeProviders — optional; each reports the LISTEN connections it
+ *   depends on. One down past {@link REALTIME_LISTENER_GRACE_MS} makes the
+ *   check unhealthy; one down for less is reported but not failed on.
+ */
+export declare function createHealthCheck(defaultDriver: DataDriver, authSchemaCheck?: () => Promise<AuthSchemaHealth>, realtimeProviders?: RealtimeProvider[]): () => Promise<HealthCheckResult>;

package/dist/init/shutdown.d.ts

@@ -2,18 +2,31 @@ 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 expired-token sweep's timer. */
+    authTokenSweep?: {
+        stop(): void;
+    };
+    /** The stop `MetricsHistory.start()` returned: its interval writes to the pool. */
+    stopMetricsSampler?: () => void;
     realtimeServices: Record<string, RealtimeProvider>;
+    /**
+     * End the responses that stay open until their client leaves — the Logs
+     * Explorer's SSE tail. `server.close()` waits for every open connection, so
+     * one of these left open held the shutdown to its force timeout.
+     */
+    closeLongLivedResponses?: () => void;
 }
 /**
  * Minimal structural view of the backend instance needed by
@@ -32,7 +45,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/init.d.ts

@@ -285,6 +285,49 @@ export interface RebaseAuthConfig {
      * auth endpoints, and CORS must allow credentials (no `origin: "*"`).
      */
     cookieAuth?: import("./auth/index.js").CookieAuthConfig;
+    /**
+     * Refuse password sign-in until the account's email address is verified,
+     * and make registration confirm-first. Off by default.
+     *
+     * Off, `POST /auth/register` signs the new account in and mails it a
+     * verification link; an address that already has an account is answered
+     * `409 EMAIL_EXISTS`. On, register signs nobody in and answers the same
+     * "check your inbox" whether or not the address has an account (an
+     * unconfirmed one is mailed its link again), and `POST /auth/login`
+     * answers `403 EMAIL_NOT_CONFIRMED` for an unverified account —
+     * only once the password is right. Following the link with the password completes
+     * the sign-up (`POST /auth/verify-email`).
+     *
+     * Needs email: the boot refuses it without, since nobody could ever
+     * confirm. Set by `AUTH_REQUIRE_EMAIL_VERIFICATION=true`.
+     */
+    requireEmailVerification?: boolean;
+    /**
+     * How long a refresh token that was rotated away still mints a sibling of
+     * the same session, in seconds. Default 10 (GoTrue's
+     * `refresh_token_reuse_interval`): a client that lost a refresh answer —
+     * a deploy, a suspended laptop, two tabs at once — is not signed out.
+     */
+    refreshTokenReuseIntervalSeconds?: number;
+    /**
+     * What a refresh token presented *after* that window does. Default
+     * `"reject"`: the request is refused and logged, and the session stands,
+     * because its live token is still good — which also means a thief who
+     * refreshed first keeps it. `"revoke-session"` ends the whole sign-in on
+     * such a replay, thief and owner alike, as GoTrue does: the owner signs
+     * in again. Set by `AUTH_REFRESH_TOKEN_REUSE`; anything else fails the boot.
+     */
+    refreshTokenReuse?: "reject" | "revoke-session";
+    /**
+     * Let a magic-link or email-code request for an address with no account
+     * create one — passwordless sign-up — while registration is open
+     * (`allowRegistration`, not `disableSelfRegistration`). The account has no
+     * password and is unverified until the link or code is used, which proves
+     * the address and signs it in. Off by default, so those requests answer an
+     * unknown address the same as a known one and create nothing. Set by
+     * `AUTH_MAGIC_LINK_CREATES_USERS`.
+     */
+    magicLinkCreatesUsers?: boolean;
 }
 /** @see RebaseBackendConfig.baas */
 export interface BaasOptions {
@@ -502,6 +545,17 @@ export interface RebaseBackendConfig {
      * behind. Set a lifecycle rule on `_rebase/renditions/` to collect them.
      */
     storageRenditionCache?: import("./storage/rendition-cache.js").RenditionCacheConfig;
+    /**
+     * How long a private file's download URL works, in seconds — the lifetime
+     * of the token `GET /storage/metadata/*` mints. Default 300; at most a week.
+     * `STORAGE_DOWNLOAD_TOKEN_TTL` on a bundle deployment.
+     *
+     * Five minutes renders a page; a private `<video>` that plays longer asks
+     * for its next range with an expired token. The token travels in the URL,
+     * which is the reason for the ceiling: an object that must be linked
+     * indefinitely belongs under the public prefix instead.
+     */
+    storageDownloadTokenTtl?: number;
     /**
      * Run something when an object lands, or when one goes.
      *

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. */