@rebasepro/server 0.13.0 → 0.13.1-canary.g06dbe5b

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

@@ -16,14 +16,89 @@ export interface WebhookDeliveryResult {
     success: boolean;
     attemptNumber: number;
 }
+export interface WebhookDispatcherOptions {
+    /**
+     * Deliver to destinations that resolve to loopback, link-local or private
+     * addresses. Off by default. Turning it on re-opens SSRF: anyone who can
+     * choose a webhook URL can then reach the pod's metadata endpoint, the
+     * cluster API server and the database — and read the first 1000 bytes of
+     * the answer back out of `responseBody`. Only for a receiver you run
+     * yourself on the same host or network.
+     */
+    allowPrivateNetworks?: boolean;
+    /**
+     * Deadline for one attempt, covering the response body as well as the
+     * headers. Defaults to 10s.
+     */
+    timeoutMs?: number;
+    /**
+     * Called with the final result of every delivery, including the ones
+     * started by {@link WebhookDispatcher.enqueueEntityChange} — which return
+     * nothing to their caller, so this is the only place their failures
+     * surface.
+     */
+    onDelivery?: (result: WebhookDeliveryResult) => void;
+    /**
+     * Hostname resolver used by the destination guard. Defaults to
+     * `dns.lookup`; injected by tests so a unit suite never asks a resolver.
+     */
+    lookup?: (hostname: string) => Promise<string[]>;
+}
 export declare class WebhookDispatcher {
     private webhooks;
     private maxRetries;
     private retryDelays;
+    private readonly options;
+    private readonly timeoutMs;
+    private queue;
+    private draining;
+    constructor(options?: WebhookDispatcherOptions);
     /** Register webhooks to watch */
     setWebhooks(webhooks: WebhookConfig[]): void;
-    /** Called when a entity changes — checks if any webhook matches */
+    /**
+     * Called when a entity changes — checks if any webhook matches, and awaits
+     * every delivery, retries included.
+     *
+     * **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.
+     */
     onEntityChange(table: string, event: "INSERT" | "UPDATE" | "DELETE", id: string, entity: Record<string, unknown> | null, previousEntity?: Record<string, unknown> | null): Promise<WebhookDeliveryResult[]>;
+    /**
+     * Queue the same deliveries and return immediately.
+     *
+     * This is the form a collection callback wants. `afterSave` is awaited
+     * *inside* the transaction that wrote the row, so anything it awaits is
+     * transaction time; queueing hands the HTTP to a drain loop that runs
+     * after the callback returns, and the transaction commits without waiting
+     * for a third party. It also means a receiver that is down can no longer
+     * fail the customer's write.
+     *
+     * The cost, stated plainly: the queue is in-process and in-memory. A crash
+     * or a deploy between the enqueue and the delivery drops the event, and a
+     * receiver may see the notification a few milliseconds before the row it
+     * describes is committed. Use {@link flush} on shutdown, and
+     * `onDelivery` to record failures.
+     */
+    enqueueEntityChange(table: string, event: "INSERT" | "UPDATE" | "DELETE", id: string, entity: Record<string, unknown> | null, previousEntity?: Record<string, unknown> | null): void;
+    /**
+     * Wait for every queued delivery to finish. For graceful shutdown, and for
+     * tests that need to observe what {@link enqueueEntityChange} sent.
+     */
+    flush(): Promise<void>;
+    private startDraining;
+    private drainQueue;
+    /** The payload each matching webhook gets for this change. */
+    private buildDeliveries;
     private deliverWithRetry;
     private deliver;
+    /**
+     * Read at most {@link MAX_RESPONSE_BYTES} of the response and cancel the
+     * rest, so a receiver cannot buffer a 10 GB body into the pod before the
+     * caller truncates it to 1000 characters.
+     */
+    private readCappedBody;
 }

package/dist/singleton.d.ts

@@ -22,14 +22,30 @@ export declare function _resetRebaseMock(): void;
  * **Admin data plane** (`rebase.dataAsAdmin`):
  * Backed by the native DataDriver — calls go directly to the database without
  * JSON serialization, HTTP dispatch, or middleware overhead. The driver is
- * scoped as `{ uid: "service", roles: ["admin"] }`, so **every read and write
- * bypasses row-level-security policies**. No `REBASE_SERVICE_KEY` is required.
+ * scoped once as `{ uid: "service", roles: ["admin"] }` (`SERVICE_IDENTITY`),
+ * which makes it **admin-scoped, not RLS-bypassing**: every read and write runs
+ * in a transaction that has done `SET LOCAL ROLE rebase_user` with
+ * `app.uid = 'service'`, and policies are evaluated against that. No
+ * `REBASE_SERVICE_KEY` is required.
  *
- * ⚠️ Because it bypasses RLS, `rebase.dataAsAdmin` is for trusted background
- * work (cron jobs, migrations, service tasks) — **not** for serving user-facing
- * data. Inside a request handler, run user-scoped queries through the
- * request-scoped driver (`c.var.driver`), which carries the caller's identity
- * so RLS applies.
+ * It clears the default policies through their `rolesOverlap(['admin'])` arm —
+ * which is why the difference rarely shows. It shows when you write your own:
+ *
+ * - `policy.serverContext()` compiles to `auth.uid() IS NULL` and is therefore
+ *   **false** for this accessor. A collection with `disableDefaultPolicies:
+ *   true` whose rule is `serverContext()` denies these writes (`42501`) and
+ *   returns zero rows — HTTP 200, empty — for these reads.
+ * - Its reach equals an `admin`-roled application user's reach. It is not a
+ *   private door.
+ *
+ * `rebase.sql()` *is* an unconditional bypass — it runs on the owner connection
+ * and never goes through `withAuth`. Of the two accessors on this object, the
+ * quieter one is the more privileged.
+ *
+ * ⚠️ `rebase.dataAsAdmin` is for trusted background work (cron jobs,
+ * migrations, service tasks) — **not** for serving user-facing data. Inside a
+ * request handler, run user-scoped queries through the request-scoped driver
+ * (`c.var.driver`), which carries the caller's identity.
  *
  * `rebase.data` is **gone from the type**: `RebaseServerClient` omits it, so the
  * admin-scoped accessor has exactly one name and the privilege is visible at the
@@ -45,7 +61,8 @@ export declare function _resetRebaseMock(): void;
  * ```typescript
  * import { rebase } from "@rebasepro/server";
  *
- * // In a cron job, hook, or trusted service file (admin scope, bypasses RLS):
+ * // In a cron job, hook, or trusted service file (admin scope, RLS evaluated
+ * // as `{ uid: "service", roles: ["admin"] }`):
  * await rebase.email.send({ to: "admin@co.com", subject: "Alert", html: "<p>Hi</p>" });
  * const jobs = await rebase.dataAsAdmin.jobs.find({ limit: 10 });
  * ```