@rebasepro/server 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/services/outbound-post.d.ts

@@ -0,0 +1,50 @@
+import { type AddressJudge, type OutboundUrlGuardOptions } from "./outbound-url-guard.js";
+/**
+ * How the webhook dispatcher sends a POST to a destination that came from data.
+ *
+ * On Node, through an http(s) Agent whose `lookup` is the destination guard's
+ * ({@link guardedLookup}): the name is resolved once per new connection, every
+ * address it answers with is judged, and the socket connects to an address
+ * that was. It used to be validate-then-fetch — a `dns.lookup` per delivery
+ * attempt on the libuv threadpool, and then a second resolution inside `fetch`
+ * that the guard never saw, so a TTL-0 name that flipped between the two
+ * could still land on a blocked address. Keep-alive connections are reused, so
+ * a steady stream of deliveries to one receiver resolves its name about once.
+ *
+ * With `allowPrivateNetworks` there is nothing to judge, and on a runtime
+ * without `node:http` there is no Agent to hand a resolver to: both send with
+ * `fetch`, after {@link assertAllowedOutboundUrl}, as before.
+ *
+ * Internal to the server.
+ */
+/** What the dispatcher reads of a response, from either transport. */
+export interface OutboundResponse {
+    status: number;
+    header(name: string): string | null;
+    /** The body as a stream, so a reader can stop at a cap and cancel the rest. */
+    body: ReadableStream<Uint8Array> | null;
+    text(): Promise<string>;
+}
+export interface OutboundPostInit {
+    headers: Record<string, string>;
+    body: string;
+    /** Aborts the request — and the response body, while it is being read. */
+    signal: AbortSignal;
+}
+/**
+ * POST `body` to `rawUrl`, never following a redirect: a redirect would send
+ * the POST — signature and all — somewhere the guard never judged.
+ *
+ * @throws BlockedUrlError when the guard refuses the destination.
+ */
+export type OutboundPost = (rawUrl: string, init: OutboundPostInit) => Promise<OutboundResponse>;
+export declare function createOutboundPost(options?: OutboundUrlGuardOptions): OutboundPost;
+/** Validate-then-fetch: the path for `allowPrivateNetworks`, and for a runtime without `node:http`. */
+export declare function createFetchPost(options?: OutboundUrlGuardOptions): OutboundPost;
+/**
+ * The guarded Node transport, or `undefined` on a runtime without
+ * `node:http`. Loaded on use, like the guard's own resolver, so that this
+ * module imports on a runtime that has neither. `judge` is for tests that
+ * need a receiver on loopback.
+ */
+export declare function createNodePost(options?: OutboundUrlGuardOptions, judge?: AddressJudge): Promise<OutboundPost | undefined>;

package/dist/services/outbound-url-guard.d.ts

@@ -1,3 +1,4 @@
+import type { LookupFunction } from "node:net";
 /**
  * Refusal to send a request to a destination the guard does not allow.
  *
@@ -29,6 +30,8 @@ export interface OutboundUrlGuardOptions {
  * outbound call whose destination comes from data.
  */
 export declare function blockedAddressReason(address: string): string | null;
+/** Why an address may not be connected to, or `null`: {@link blockedAddressReason}. */
+export type AddressJudge = (address: string) => string | null;
 /**
  * Resolve and validate a destination before anything connects to it.
  *
@@ -40,14 +43,40 @@ export declare function blockedAddressReason(address: string): string | null;
  * Known limit: this is validate-then-fetch. Between the lookup here and the
  * connection the runtime makes there is a second resolution this code does not
  * see, so a TTL-0 name that flips between answers can still land on a blocked
- * address. Closing that needs the socket pinned to the address checked here,
- * which Node's global `fetch` does not expose without an undici dispatcher.
- * The redirect policy in {@link WebhookDispatcher} closes the much wider
- * version of the same hole — a receiver that simply *points* at the internal
- * address.
+ * address. On Node the webhook dispatcher does not use this: it checks the
+ * address it connects to, through {@link guardedLookup}. This is the check for
+ * a runtime whose `fetch` cannot be handed a resolver.
  *
  * @throws BlockedUrlError when the destination is not allowed. DNS failures
  * are rethrown as they are, so callers can tell "never send this" from
  * "could not send this right now".
  */
 export declare function assertAllowedOutboundUrl(rawUrl: string, options?: OutboundUrlGuardOptions): Promise<URL>;
+/**
+ * Every check of {@link assertAllowedOutboundUrl} but the lookup, for a
+ * connection that resolves the name through {@link guardedLookup}. The scheme,
+ * the internal names and an address written into the URL are judged here —
+ * a connection to a literal address asks no resolver, so nothing else would.
+ *
+ * Internal to the server: not exported from the package.
+ */
+export declare function assertAllowedBeforeConnecting(rawUrl: string, options?: OutboundUrlGuardOptions): URL;
+/**
+ * A `dns.lookup` for an http(s) Agent that refuses to connect anywhere the
+ * guard would not send: it resolves the name, judges *every* address it got,
+ * and hands the connection only addresses it judged — so the address checked
+ * is the address connected to. Validate-then-fetch resolves twice, and a
+ * name whose TTL-0 record flips between the two lookups lands on whatever the
+ * second one says.
+ *
+ * Called once per new connection, not per request: a keep-alive connection
+ * is to an address already judged. Nothing is cached — an "allowed" verdict
+ * that outlived its lookup would be the rebinding window again.
+ *
+ * Fails with {@link BlockedUrlError}, which the connection reports as its
+ * error; a resolver failure is reported as itself.
+ *
+ * Internal to the server: not exported from the package. `judge` is for the
+ * tests that need a receiver on loopback; nothing else passes one.
+ */
+export declare function guardedLookup(options?: OutboundUrlGuardOptions, judge?: AddressJudge): LookupFunction;

package/dist/services/routed-realtime-service.d.ts

@@ -26,6 +26,11 @@ export interface WsRealtimeService extends RealtimeProvider {
      * interface and the socket's calls so it cannot happen twice.
      */
     rescopeClient(clientId: string, authContext: unknown): Promise<void>;
+    /**
+     * What the client opted into when it opened the socket (`?rebase_caps=`).
+     * Optional: a provider that sends nothing depending on one ignores them.
+     */
+    setClientOptIns?(clientId: string, optIns: ReadonlySet<string>): void;
     /**
      * Whether this provider actually implements channels, presence and
      * broadcast. Declared by the provider rather than inferred, because the

package/dist/services/webhook-service.d.ts

@@ -23,6 +23,11 @@ export interface WebhookDeliveryResult {
     statusCode: number;
     responseBody: string;
     success: boolean;
+    /**
+     * The attempt this result is from, counting from 1. `0` for a delivery
+     * refused before any attempt: an in-process queue that was full, with
+     * `statusCode: 0` and `responseBody: "queue full"`.
+     */
     attemptNumber: number;
 }
 export interface WebhookDispatcherOptions {
@@ -48,7 +53,8 @@ export interface WebhookDispatcherOptions {
      */
     onDelivery?: (result: WebhookDeliveryResult) => void;
     /**
-     * Hostname resolver used by the destination guard. Defaults to
+     * Hostname resolver used by the destination guard — once per new
+     * connection, and its answer is where the connection goes. Defaults to
      * `dns.lookup`; injected by tests so a unit suite never asks a resolver.
      */
     lookup?: (hostname: string) => Promise<string[]>;
@@ -61,27 +67,48 @@ export interface WebhookDispatcherOptions {
      */
     jobQueue?: JobQueueClient;
 }
+/**
+ * What a delivery queued as a job carries: the webhook's id — never its
+ * secret — and the delivery id every attempt sends, so a receiver can
+ * deduplicate the queue's at-least-once retries. Rows queued before the id was
+ * stored have none; the job's own id stands in for it.
+ */
+export interface QueuedWebhookDelivery {
+    webhookId: string;
+    event: string;
+    payload: Record<string, unknown>;
+    deliveryId?: string;
+}
 export declare class WebhookDispatcher {
     private webhooks;
+    /** Attempts per in-process delivery, the first included. */
     private maxRetries;
+    /**
+     * The wait before each attempt after the first: 1 s before the second, 5 s
+     * before the third. One per retry — a third entry here was never reached.
+     */
     private retryDelays;
     private readonly options;
     private readonly timeoutMs;
-    private queue;
-    private draining;
+    /** In-process deliveries, one lane per webhook id. A lane is removed when it empties. */
+    private lanes;
+    /** Sends one attempt, through the destination guard — see `outbound-post.ts`. */
+    private readonly post;
     constructor(options?: WebhookDispatcherOptions);
     /** Register webhooks to watch */
     setWebhooks(webhooks: WebhookConfig[]): void;
     /**
      * Called when a entity changes — checks if any webhook matches, and awaits
-     * every delivery, retries included.
+     * every delivery, retries included. The matching webhooks are delivered to
+     * at the same time, so the wait is the slowest receiver's, not the sum of
+     * all of them; the results come back in webhook order either way.
      *
      * **Do not await this inside a collection callback.** `afterSave` and
      * `afterDelete` run inside the write's Postgres transaction, so awaiting a
      * delivery here holds a pooled connection and the row's locks for as long
-     * as the receiver takes to answer — up to ~36s across three attempts, per
-     * matching webhook. Use {@link enqueueEntityChange} there; this method is
-     * for a custom function or a job that wants the results.
+     * as the slowest receiver takes to answer — up to ~36s across three
+     * attempts. Use {@link enqueueEntityChange} there; this method is for a
+     * custom function or a job that wants the results.
      */
     onEntityChange(table: string, event: "INSERT" | "UPDATE" | "DELETE", id: string, entity: Record<string, unknown> | null, previousEntity?: Record<string, unknown> | null): Promise<WebhookDeliveryResult[]>;
     /**
@@ -108,6 +135,20 @@ export declare class WebhookDispatcher {
      */
     enqueueEntityChange(table: string, event: "INSERT" | "UPDATE" | "DELETE", id: string, entity: Record<string, unknown> | null, previousEntity?: Record<string, unknown> | null): void;
     private dispatchDeliveries;
+    /**
+     * Append each delivery to its webhook's lane, starting the lane if it is
+     * idle. Deliveries to one webhook keep their order; deliveries to
+     * different webhooks no longer wait for each other — one serial queue for
+     * every webhook meant a receiver that refused connections held every
+     * other receiver six seconds per queued event.
+     */
+    private enqueueInProcess;
+    /**
+     * Turn a delivery away from a full lane, and say so: through `onDelivery`
+     * for each one — the hook a caller of {@link enqueueEntityChange} already
+     * watches for failures — and in the server log once per burst.
+     */
+    private refuse;
     /**
      * Deliver one queued job, as the worker runs it.
      *
@@ -116,22 +157,33 @@ export declare class WebhookDispatcher {
      * of three job attempts is nine deliveries and about two minutes of holding
      * a worker slot — and only the queue's retries survive a restart, which is
      * the whole reason for moving.
+     *
+     * Pass the job context as the second argument —
+     * `ctx => dispatcher.deliverQueuedJob(ctx.payload, ctx)` — so each attempt
+     * sends its real `X-Webhook-Attempt`, and a row queued without a delivery
+     * id still sends the same `X-Webhook-Delivery` on every retry (the job's
+     * id). Without it, every attempt says it is the first.
      */
-    deliverQueuedJob(job: {
-        webhookId: string;
-        event: string;
-        payload: Record<string, unknown>;
+    deliverQueuedJob(job: QueuedWebhookDelivery, context?: {
+        id?: string;
+        attempt?: number;
     }): Promise<void>;
     /**
      * Wait for every queued delivery to finish. For graceful shutdown, and for
      * tests that need to observe what {@link enqueueEntityChange} sent.
      *
+     * `timeoutMs` bounds the wait: a receiver that is down costs each of its
+     * queued deliveries up to ~36 seconds of retries, which a shutdown cannot
+     * always afford. Resolves `true` when everything finished, `false` when
+     * the budget ran out first — those deliveries carry on in the background
+     * for as long as the process does. Without it, waits however long the
+     * deliveries take.
+     *
      * In-process deliveries only — with a `jobQueue` configured there is
      * nothing here to wait for, because the deliveries are rows.
      */
-    flush(): Promise<void>;
-    private startDraining;
-    private drainQueue;
+    flush(timeoutMs?: number): Promise<boolean>;
+    private drainLane;
     /** The payload each matching webhook gets for this change. */
     private buildDeliveries;
     private deliverWithRetry;

package/dist/singleton.d.ts

@@ -7,8 +7,9 @@ import type { RebaseServerClient } from "@rebasepro/types";
  */
 export declare function _setRebaseResolver(resolve: (() => RebaseServerClient | null) | null): (() => RebaseServerClient | null) | null;
 /**
- * @internal Called once during server initialization to set the backing instance.
- * This is invoked by `initializeRebaseBackend()` — never call it manually.
+ * @internal Set the process default's client — what `rebase` is outside any
+ * backend's scope. Invoked by `setDefaultBackend()` (and so by
+ * `initializeRebaseBackend()`) — never call it manually.
  */
 export declare function _initRebase(client: RebaseServerClient): void;
 /**
@@ -21,10 +22,13 @@ export declare function _setRebaseMock(mockInstance: Partial<RebaseServerClient>
  */
 export declare function _resetRebaseMock(): void;
 /**
- * The server-side Rebase singleton.
+ * The server-side Rebase client, as a module-level handle.
  *
- * Initialized automatically during server startup. Provides access to all
- * app-scoped services: **data**, **auth**, **storage**, and **email**.
+ * Inside a request, cron run or job a backend serves, it is that backend's
+ * client (`backend.rebase`) — so with two backends in one process, each one's
+ * functions see their own. Anywhere else it is the process default's, which
+ * `initializeRebaseBackend` (or `setDefaultBackend`) installs. Provides access
+ * to all app-scoped services: **data**, **auth**, **storage**, and **email**.
  *
  * **Admin data plane** (`rebase.dataAsAdmin`):
  * Backed by the native DataDriver — calls go directly to the database without