@rebasepro/server-postgres 0.24.0 → 0.24.1-canary.gcb918fc

package/dist/services/realtimeService.d.ts

@@ -95,6 +95,13 @@ type StoredCollectionRequest = {
     fields?: string[];
     /** `SELECT DISTINCT` over the projection. */
     distinct?: boolean;
+    /**
+     * A subscription to the count alone (`listenCount`): no rows are read,
+     * and each frame carries `rows: []` and the `meta` with the total. A
+     * server that predates it reads the rows it was asked for (the SDK asks
+     * for one) and counts them as usual, so the same frame answers it.
+     */
+    countOnly?: boolean;
 };
 /**
  * What an in-process listener asks for: the read, and who it reads as.
@@ -111,6 +118,7 @@ export type DataDriverSubscriptionRequest = {
 } | {
     type: "single";
     id: string | number;
+    include?: IncludeSpec;
 });
 /**
  * A registered subscription, plus the two counters that order its deliveries.
@@ -142,6 +150,13 @@ type Subscription = {
     path: string;
     id?: string | number;
     collectionRequest?: StoredCollectionRequest;
+    /**
+     * The relations a single-row subscription loads into every frame — the
+     * `include` a `findById` takes. A list keeps its own in `collectionRequest`.
+     */
+    include?: IncludeSpec;
+    /** A single-row subscriber that asked for the row's `ETag` on every frame. */
+    etag?: boolean;
     authContext?: SubscriptionAuthContext;
     /**
      * An in-process listener's error callback, called when a refetch fails.
@@ -153,7 +168,28 @@ type Subscription = {
     started: number;
     /** The highest started-sequence that has already reached the subscriber. */
     delivered: number;
+    /**
+     * A socket subscriber's last data frame, as {@link frameDigest} of what
+     * follows its subscription id; unset before the first and after an error
+     * frame. A refetch that reads the same rows sends it nothing — see
+     * {@link sendDataFrame}.
+     */
+    lastFrame?: string;
 };
+/**
+ * How many group refetches may run at once: a quarter of the connection pool
+ * the service shares with every REST request, and never fewer than two.
+ *
+ * One write to a list watched by many different principals arms a refetch
+ * per principal, and they all came due in the same tick. Started together,
+ * 200 of them were 200 transactions queued on a 20-connection pool, and an
+ * unrelated request arriving meanwhile waited behind every one (measured: a
+ * `SELECT 1` took 521 ms). Capped, the refetches queue here instead, and
+ * three quarters of the pool stays free for the requests. A pool this cannot
+ * read (a test double, a client that is not a `pg` pool) is taken to be the
+ * default 20-connection one.
+ */
+export declare function refetchConcurrencyFor(db: object): number;
 /**
  * The default ceiling on subscriptions one socket may hold.
  *
@@ -172,6 +208,25 @@ export declare const DEFAULT_MAX_SUBSCRIPTIONS_PER_SOCKET = 1000;
  * meaning anything.
  */
 export declare function parseMaxSubscriptionsPerSocket(value: unknown, source: string): number;
+/**
+ * The smallest last total at which a group's count is reused under
+ * `REALTIME_RECOUNT_INTERVAL_MS`, unless `REALTIME_RECOUNT_MIN_ROWS` says
+ * otherwise. Below it a count is cheap, and stays exact.
+ */
+export declare const DEFAULT_RECOUNT_MIN_ROWS = 100000;
+/**
+ * Read one of the realtime tuning numbers (`REALTIME_REFETCH_MAX_WAIT_MS`,
+ * `REALTIME_RECOUNT_INTERVAL_MS`, `REALTIME_RECOUNT_MIN_ROWS` and their
+ * `realtime.*` options). A value someone set and mistyped stops the boot
+ * rather than quietly becoming the default.
+ */
+export declare function parseRealtimeTuning(value: unknown, source: string, unit: string): number;
+/**
+ * Read `REALTIME_MAX_SOCKETS_PER_USER` / `realtime.maxSocketsPerUser`. Like the
+ * subscription ceiling, a value someone set and mistyped stops the boot rather
+ * than quietly becoming no ceiling.
+ */
+export declare function parseMaxSocketsPerUser(value: unknown, source: string): number;
 /**
  * PostgreSQL-specific realtime service.
  * Handles WebSocket connections and subscriptions for real-time row updates.
@@ -188,8 +243,19 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     readonly supportsChannels = true;
     private clients;
+    /** What each socket opted into when it opened — see `socket-opt-ins.ts`. */
+    private clientOptIns;
     private channels;
     private presence;
+    /**
+     * The reverse of {@link channels} and {@link presence}: the channels each
+     * client is a member of, and those it has a presence entry in. Kept in
+     * step wherever either map gains or loses a client, so a disconnect visits
+     * what the client was in. It used to walk every channel on the instance:
+     * with a channel per document, 5.4 ms per disconnect at 50k channels.
+     */
+    private channelsByClient;
+    private presenceByClient;
     /**
      * Ordered, replayable history for channels that opt into it.
      *
@@ -230,9 +296,17 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     private presenceStore?;
     /** Sweeps roster rows left behind by instances that stopped heartbeating. */
     private presenceSweepInterval?;
+    /**
+     * The clients that have tracked presence through this instance — the only
+     * ones with roster rows to delete when their socket closes. Most sockets
+     * never track presence, and each of their closes was a `DELETE` too.
+     */
+    private presenceTrackers;
     /**
      * Channels whose oversized ephemeral broadcasts have already been reported,
      * so a hot channel logs the problem once rather than once per message.
+     * Forgotten with the channel, so it holds live channels only — not every
+     * name a client ever broadcast on.
      */
     private oversizedBroadcastWarned;
     /**
@@ -252,6 +326,11 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     private foreignInstanceSeen;
     /** So the multi-pod memory-bus warning is emitted once, not once per join. */
     private memoryBusWarned;
+    /** When the database was last asked whether another instance listens — see {@link warnIfMemoryBusOnMultiplePods}. */
+    private otherInstancesCheckedAt?;
+    /** The check in flight, so a burst of joins asks once. Awaited by tests. */
+    private otherInstancesCheck?;
+    private static readonly OTHER_INSTANCES_CHECK_INTERVAL_MS;
     private presenceInterval?;
     private static readonly PRESENCE_TIMEOUT_MS;
     /** How often stale roster rows from other instances are reaped. */
@@ -271,8 +350,25 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     private subscriptionCallbacks;
     /** Each client's subscriptions, by key — for its ceiling and its disconnect. */
     private subscriptionsByClient;
+    /**
+     * The in-process subscriptions — started by `startDataDriverSubscription`,
+     * `subscribeToCollection` or `subscribeToOne` — by the id their caller
+     * gave them, for {@link unsubscribe}, which has nothing else to go on. It
+     * used to walk every subscription on the server, sockets' included.
+     */
+    private inProcessKeysById;
     /** Subscriptions one refetch answers — see {@link SubscriptionGroup}. */
     private groups;
+    /**
+     * Groups whose refetch is due and waiting for a slot, in the order they
+     * came due. A group is in it at most once; changes that arrive while it
+     * waits join the read it is waiting for, which starts after them.
+     */
+    private refetchQueue;
+    /** Group refetches running now — at most {@link maxConcurrentRefetches}. */
+    private refetchesRunning;
+    /** See {@link refetchConcurrencyFor}. */
+    maxConcurrentRefetches: number;
     /**
      * The collection groups on each path, and the single-row groups at each
      * `path` + id: what a change looks up, instead of walking every
@@ -280,6 +376,21 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     private collectionGroupsByPath;
     private singleGroupsByAddress;
+    /** The single-row groups on each path, for a change that names no row ({@link ANY_ROW}). */
+    private singleGroupsByPath;
+    /**
+     * When something on each path a list group reads last changed: the
+     * debounce clock those groups share, moved once per changed row instead
+     * of once per row per group. See {@link notifyPathUpdate}.
+     */
+    private listPathChangedAt;
+    /**
+     * The list groups on each path that a change still has to schedule: new
+     * ones, and those whose last refetch has started. The rest already have a
+     * refetch for every member pending, which the next change only has to
+     * keep waiting — the clock above does that.
+     */
+    private unscheduledListGroups;
     /**
      * Every path a subscription holds, with the collection it lands on and how
      * many hold it — the candidates `aliasPaths` considers, resolved once.
@@ -290,21 +401,60 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * {@link DEFAULT_MAX_SUBSCRIPTIONS_PER_SOCKET}.
      */
     maxSubscriptionsPerSocket: number;
+    /**
+     * The longest a change waits for its refetch, in ms; set from config at
+     * boot (`REALTIME_REFETCH_MAX_WAIT_MS`). See {@link REFETCH_MAX_WAIT_MS},
+     * the default.
+     */
+    refetchMaxWaitMs: number;
+    /**
+     * How long a list's total may be reused before it is counted again, in ms
+     * (`REALTIME_RECOUNT_INTERVAL_MS`). Unset, the default, counts with every
+     * frame. Only for a group whose last total was at least
+     * {@link recountMinRows}: a count is cheap on a small set, and exact there.
+     */
+    recountIntervalMs: number | undefined;
+    /** See {@link recountIntervalMs} (`REALTIME_RECOUNT_MIN_ROWS`). */
+    recountMinRows: number;
     private driver?;
     /** Unique identifier for this process instance, used to skip own notifications. */
     private readonly instanceId;
+    /** What this instance's LISTEN connections report in `pg_stat_activity`. */
+    private readonly listenerApplicationName;
     /** The LISTEN connection on {@link PG_NOTIFY_CHANNEL}, outside the Drizzle pool. */
     private crossInstanceListener?;
     /** Whether cross-instance broadcasting is active. */
     private broadcasting;
+    /**
+     * Changes waiting to be announced on {@link PG_NOTIFY_CHANNEL}, and the
+     * send that will announce them — see {@link broadcastChange}.
+     */
+    private pendingBroadcasts;
+    private broadcastFlush?;
     /** Debounce window (ms) for coalescing rapid row updates into a single correctness refetch. */
     private static readonly REFETCH_DEBOUNCE_MS;
+    /**
+     * The longest a change waits for its refetch, quiet window or not.
+     *
+     * A pure debounce waits for 300 ms without a change, and a collection
+     * written more often than that — an orders, events or chat table at a few
+     * writes a second — never went quiet: its subscribers received nothing for
+     * as long as the writes continued. Under a steady stream a group now
+     * refetches once per this interval, which is the whole cost.
+     */
+    private static readonly REFETCH_MAX_WAIT_MS;
     /** Dedicated LISTEN client for DB-level change events (undefined unless CDC is enabled). */
     private cdcListener?;
     /** Whether database-level CDC is the active cross-instance change source. */
     private cdcActive;
     /** Junction table → the child lists its rows belong to, built when CDC starts. */
     private junctionLinkMap?;
+    /** Changes waiting for a turn of the event loop — see {@link handleCdcEvents}. */
+    private cdcBacklog;
+    /** Changes handled in the current turn. */
+    private cdcTurnRows;
+    /** How many changed rows one turn of the event loop routes: ~5–10 ms of work. */
+    private static readonly CDC_ROWS_PER_TURN;
     /** Reverse lookup: `schema.table` (and bare `table`) → collection, built when CDC starts. */
     private cdcTableMap?;
     /**
@@ -349,6 +499,18 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * redaction lives.
      */
     private debugLog;
+    /**
+     * {@link rawQueryLoggingEnabled}, read at most once a second.
+     *
+     * It reads two environment variables, and `process.env` is a getenv per
+     * read: called three or four times per changed row, it was the largest
+     * cost of a change notification here — 1.4 µs of every ~3.5 µs per row,
+     * so ~1.4 s of event loop for a 1M-row statement. A switch flipped at run
+     * time is honoured within a second.
+     */
+    private debugEnabled;
+    private debugFlag;
+    private debugCheckedAt;
     setDataDriver(driver: DataDriver): void;
     /**
      * The live subscriptions by the id their client gave them — for tests and
@@ -368,13 +530,18 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * every index that finds it.
      */
     private registerSubscription;
+    /** Remember an in-process subscription by its caller's id — see {@link inProcessKeysById}. */
+    private indexInProcess;
     /** Remove the subscription under `key` from everything that holds it. */
     private dropSubscription;
     /** Take `subscription` out of its group and path count; a group left empty goes, timer and all. */
     private leaveGroup;
+    /** See {@link unscheduledListGroups}. */
+    private markListGroupUnscheduled;
     /**
      * Ask for a refetch of `group` once changes have been quiet for the
-     * debounce window — for every member, or only for `member`.
+     * debounce window — for every member, or only for `member` — and in any
+     * case no later than {@link REFETCH_MAX_WAIT_MS} after the first of them.
      *
      * The window is measured from the last change, as a debounce is, but the
      * timer is not re-armed per change: a 10k-row statement is 10k changes,
@@ -384,6 +551,13 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     private scheduleGroupRefetch;
     private armGroupTimer;
+    /**
+     * Start queued group refetches while fewer than
+     * {@link maxConcurrentRefetches} are running. Each one that settles starts
+     * the next, so the fan-out of one write waits its turn here rather than
+     * in the pool, ahead of every REST request.
+     */
+    private drainRefetchQueue;
     /**
      * One read for the group, delivered to each member it is for.
      *
@@ -456,7 +630,12 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
     unsubscribe(subscriptionId: string): void;
     addClient(clientId: string, ws: WebSocket): void;
     handleClientMessage(clientId: string, message: WebSocketMessage, authContext?: SubscriptionAuthContext): Promise<void>;
+    /** Record what a socket opted into when it opened. See `socket-opt-ins.ts`. */
+    setClientOptIns(clientId: string, optIns: ReadonlySet<string>): void;
     removeClient(clientId: string): Promise<void>;
+    /** Record that `clientId` is in `channel`, in a reverse index — see {@link channelsByClient}. */
+    private indexClientChannel;
+    private unindexClientChannel;
     private handleMessage;
     /**
      * Refuse a new subscription past the socket's ceiling, and say so.
@@ -569,13 +748,20 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     private reportDriverFetchFailure;
     /**
-     * Fetch a collection with optional RLS auth context.
+     * Fetch a collection with optional RLS auth context, and with `meta: true`
+     * the `meta` a socket frame carries beside the rows.
+     *
      * When authContext is provided, the fetch runs inside a transaction
-     * with set_config calls so PostgreSQL RLS policies are enforced.
+     * with set_config calls so PostgreSQL RLS policies are enforced. The count
+     * behind `meta` runs in that same transaction — one pool acquisition and
+     * one `applyAuthContext` per refetch, where it used to take a second
+     * transaction of its own — see {@link collectionMeta}.
      */
     private fetchCollectionWithAuth;
     /**
-     * The `meta` a `collection_update` frame carries beside its rows.
+     * The `meta` a `collection_update` frame carries beside its rows, counted
+     * through `service` — the subscriber's own transaction, read only, with
+     * its auth context and `beforeQuery` narrowing already bound.
      *
      * Frames used to carry rows and primary keys and nothing else, so the
      * client issued a `GET /count` **per push** to fill in a total it needed to
@@ -583,20 +769,61 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * write, per subscriber, forever. The refetch already knows the query; it
      * counts once, here, under the same RLS transaction that read the rows, so
      * the total describes the same set they came from.
+     *
+     * A first page that came back short of its limit *is* the whole set — the
+     * same filter, the same narrowing, read as the same principal — so its
+     * length is the total and nothing is counted. Not for a later page, a
+     * cursor page, a search (whose page and count are not the same query) or
+     * a `distinct` read (whose count counts rows, not values): those count.
      */
-    private collectionMetaWithAuth;
+    private collectionMeta;
+    /**
+     * A `single_update` frame's row, and — when the subscriber asked — the
+     * `ETag` a `GET /:id` of the same row answers.
+     *
+     * The tag names the row, not the read: `GET` hashes the row as
+     * `restFetchService.fetchOneForRest` serves it with no `include`, and a
+     * write's `If-Match` is compared against that same rendering. A frame
+     * whose relations are loaded therefore takes its tag from a second read
+     * without them, read first — as `GET /:id?include=` does — so a write
+     * landing between the two leaves the tag older than the body (a 412 the
+     * client recovers from) and never newer, which would let an edit made
+     * against the older body pass over a change it never saw.
+     */
+    private fetchEntityFrame;
     /**
      * Fetch a single row with optional RLS auth context.
      */
     private fetchEntityWithAuth;
-    private sendCollectionUpdate;
     /**
      * Everything in a `collection_update` frame after its subscription id,
-     * serialised once for every member of a group: the same rows, keys and
-     * meta as {@link sendCollectionUpdate} sends, in the same order.
+     * serialised once for every member of a group: the rows, the collection's
+     * key columns, and the `meta` beside them (see {@link CollectionUpdateMeta}
+     * for the round trip that removes). The order is the one
+     * {@link CollectionUpdateMessage} declares.
      */
     private collectionFrameTail;
-    private sendSingleUpdate;
+    /** Everything in a `single_update` frame after its subscription id. */
+    private singleFrameTail;
+    /** A frame tail with its {@link frameDigest}, computed once for every member it goes to. */
+    private dataFrame;
+    /**
+     * What a subscriber was last sent, in 44 bytes: holding the frames
+     * themselves would keep a page of rows per subscriber in memory.
+     */
+    private frameDigest;
+    /**
+     * Send a data frame to a socket subscriber — unless it is exactly the one
+     * the subscriber was last sent.
+     *
+     * A write anywhere in a collection refetches every list of it, and the
+     * first 50 rows of a 10k-row list come back the same for 99.5% of writes.
+     * Each of those frames was sent anyway: ~30 KB per viewer per write,
+     * parsed, merged and re-rendered by every client to change nothing. The
+     * comparison is per subscriber, because the members of one group need not
+     * have been sent the same frame last — one may have joined since.
+     */
+    private sendDataFrame;
     /**
      * Send a lightweight row-level patch to a collection subscriber.
      * The client can merge this into its cached data for instant feedback.
@@ -709,6 +936,21 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * fraction of the room. The evidence is already in the process, so use it.
      */
     private warnIfMemoryBusOnMultiplePods;
+    /**
+     * Ask the database whether another process holds a realtime LISTEN
+     * connection on it, at most once per {@link OTHER_INSTANCES_CHECK_INTERVAL_MS}.
+     *
+     * The legacy entity channel proves a second instance with every foreign
+     * `sid`, but under change capture — the default — nothing crosses that
+     * channel, so the warning above could never fire on exactly the
+     * deployments it was written for. Every LISTEN connection names itself
+     * (`application_name`, which `pg_stat_activity` shows to any role), so
+     * the count is one cheap query. Only a process that listens is asked: a
+     * single process with no LISTEN connection has nothing to compare with.
+     */
+    private checkForOtherInstances;
+    /** Drop a channel its last local member left, and what was kept per channel for it. */
+    private forgetChannel;
     /** Leave a broadcast channel */
     leaveChannel(clientId: string, channel: string): void;
     /**
@@ -926,6 +1168,19 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * therefore only ever receives rows its RLS policies permit — filtering is per
      * subscriber, never per publisher.
      */
+    /**
+     * Route the rows one notification names — a statement's batch, or one row.
+     *
+     * Each is handled as a change on its own (the app-emit de-duplication and
+     * single-row addressing are per row), at most {@link CDC_ROWS_PER_TURN} in
+     * one turn of the event loop; the rest wait in order for the next turns. A
+     * socket read hands the listener up to 2 MB of notifications at once, and
+     * batched that is ~250k rows: handled in one go, the event loop stalled
+     * for ~400 ms. Sliced, a 1M-row statement is ~200 short turns that timers,
+     * sockets and requests run between.
+     */
+    private handleCdcEvents;
+    private drainCdcBacklog;
     private handleCdcEvent;
     /**
      * Deliver a change on a many-to-many junction table as a change to the child
@@ -944,7 +1199,11 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * Returns whether the table was recognised as a junction.
      */
     private handleJunctionCdcEvent;
-    /** Compute the canonical (possibly composite) id string from a captured row. */
+    /**
+     * Compute the canonical (possibly composite) id string from a captured row,
+     * or {@link ANY_ROW} when it names none — a key too large to notify, a
+     * table with no key.
+     */
     private extractIdFromCdcRow;
     /**
      * A captured row with its key under the key's *field* names.
@@ -957,8 +1216,19 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      */
     private cdcRowByKeyFields;
     private dedupKey;
-    /** Record that this instance just delivered `key` via the app path. */
+    /**
+     * Record that this instance just delivered `key` via the app path.
+     *
+     * Expired entries are purged so the map cannot grow unbounded under write
+     * load — once it holds over 1,000, and at most once per dedup window. The
+     * purge walks the whole map, and it used to run on every write past 1,000:
+     * inside one window nothing has expired yet, so a burst of writes walked
+     * all of it each time (703 ms of event loop for 20,000 marks). Once a
+     * window, the map holds at most two windows' writes.
+     */
     private markAppEmit;
+    /** When {@link markAppEmit} may next purge expired entries. */
+    private nextAppEmitPurgeAt;
     /** Consume a matching app-emit record if present and unexpired; true ⇒ suppress the CDC echo. */
     private consumeAppEmit;
     /**
@@ -979,18 +1249,48 @@ export declare class RealtimeService extends EventEmitter implements RealtimePro
      * @param connectionString Raw Postgres connection string for the LISTEN client.
      */
     startListening(connectionString: string): Promise<void>;
+    /**
+     * Announce this process's writes on {@link PG_NOTIFY_CHANNEL} without
+     * listening for anyone else's.
+     *
+     * For a process that serves no websockets (`worker`, `functions`) while
+     * change capture is not in effect. It has no subscriber of its own, so it
+     * holds no LISTEN connection — but without capture the announcement is
+     * the only way the `api` hears that a cron or a function wrote a row.
+     * Sending needs only the pool.
+     */
+    startPublishing(): void;
     /**
      * Stop listening and clean up the dedicated LISTEN connection.
      */
     stopListening(): Promise<void>;
     /**
-     * Broadcast a change notification to other instances via pg_notify.
-     * Uses the main Drizzle connection (pooled) — NOT the LISTEN client.
+     * Announce a change to the other instances on {@link PG_NOTIFY_CHANNEL},
+     * with the rest of its burst. Resolves once the notification carrying it
+     * has been sent. Uses the main Drizzle connection (pooled), not the LISTEN
+     * client.
+     *
+     * Changes queued in the same turn of the event loop go out together, as
+     * many to a notification as fit under the NOTIFY ceiling: a 1,000-row save
+     * used to be 1,000 round trips. A burst of one keeps the single-change
+     * shape `{ sid, p, eid, db }`, which an older instance in a rolling deploy
+     * still reads; a batch is `{ sid, c: [[p, eid, db], …] }`. Both carry
+     * addresses and nothing else.
      */
     private broadcastChange;
-    /** One change another instance published on {@link PG_NOTIFY_CHANNEL}. */
+    private flushBroadcasts;
+    /** One notification another instance published on {@link PG_NOTIFY_CHANNEL}: one change, or a batch. */
     private handleCrossInstanceNotification;
 }
+/**
+ * Pack `changes` into as few payloads as fit under
+ * {@link ENTITY_NOTIFY_MAX_BYTES}. One change keeps the single-change shape.
+ */
+export declare function packEntityChanges(sid: string, changes: Array<{
+    p: string;
+    eid: string;
+    db: string | null;
+}>): string[];
 /**
  * Alias for RealtimeService for consistent naming with other database implementations.
  * This allows code to use PostgresRealtimeProvider alongside future MongoRealtimeProvider, etc.

package/dist/services/row-pipeline.d.ts

@@ -29,15 +29,6 @@ export type RelationStyle = "ref" | "inline";
  * to unwrap that same level back out.
  */
 export declare function isJunctionRelation(relation: ResolvedRelation): boolean;
-/**
- * Apply {@link toRestScalar} across a row, leaving undeclared columns alone.
- *
- * Exported because the include loader attaches related rows itself, and a
- * target rendered differently from its parent is the shape bug this whole file
- * exists to prevent — a date was a string at the top level and a
- * `{ __type: "date" }` envelope one level down, in the same response.
- */
-export declare function toRestValues(row: Record<string, unknown>, collection: CollectionConfig): Record<string, unknown>;
 /** Render one target row in the requested style. */
 /**
  * Drop every column this caller may not read.
@@ -69,6 +60,22 @@ export declare function toRestValues(row: Record<string, unknown>, collection: C
  * though the array itself is theirs to see.
  */
 export declare function stripUnreadable(row: Record<string, unknown>, collection: CollectionConfig): Record<string, unknown>;
+/**
+ * May the current caller be handed the rows of this relation of `collection`?
+ *
+ * A relation property's value *is* its related rows, so a property the caller
+ * may not read withholds the relation whole: an `include` neither loads it nor
+ * counts it. {@link stripUnreadable} cannot be the only guard here, because the
+ * REST rows are stripped before the include loader runs (`toRestRow`, then
+ * `loadIncludes`) — the loader wrote the rows back onto the key the strip had
+ * just deleted, and `_count` beside them.
+ *
+ * Judged by every `type: "relation"` property that names this relation: by its
+ * own key (the include key of an inline relation), or by the `relationName` it
+ * addresses in the collection's `relations` array. A relation declared only in
+ * `relations` has no property, so no field rule, and stays readable.
+ */
+export declare function canReadRelation(collection: CollectionConfig, key: string, relation: ResolvedRelation): boolean;
 /**
  * The address a relation ref points at.
  *

package/dist/services/socket-liveness.d.ts

@@ -11,8 +11,10 @@
  * Two checks catch it. The socket must answer a ping: one that has not answered
  * by the next is terminated. And it must read what it is sent: one whose unsent
  * backlog passes {@link MAX_SOCKET_BUFFERED_BYTES} is terminated at the next
- * frame for it. A terminated socket closes like any other, so the realtime
- * service drops its subscriptions, channels and presence on its `close`.
+ * frame for it, and when all of the process's sockets together hold more than
+ * {@link MAX_PROCESS_BUFFERED_BYTES}, the ones with the largest backlogs go
+ * first. A terminated socket closes like any other, so the realtime service
+ * drops its subscriptions, channels and presence on its `close`.
  */
 import { WebSocket, type WebSocketServer } from "ws";
 /**
@@ -33,6 +35,40 @@ export declare const SOCKET_PING_INTERVAL_MS = 30000;
  * subscription instead of the backlog.
  */
 export declare const MAX_SOCKET_BUFFERED_BYTES: number;
+/**
+ * The unsent bytes all of this process's sockets may hold between them before
+ * the ones with the largest backlogs are terminated.
+ *
+ * The per-socket ceiling alone bounds nothing for the process: a hundred slow
+ * phones during a bulk-update storm could each sit just under it, 1.6 GB of
+ * frames between them, before any one was let go. A healthy socket's backlog
+ * is close to nothing — the kernel takes a frame as it is written — so a
+ * process holding this much unread is already in a storm. 256 MiB is sixteen
+ * sockets at their own ceiling, and an eighth of a 2 GiB container; under a
+ * smaller memory limit it is a quarter of that limit (see
+ * {@link processSendBudget}).
+ */
+export declare const MAX_PROCESS_BUFFERED_BYTES: number;
+/**
+ * The process-wide budget: {@link MAX_PROCESS_BUFFERED_BYTES}, or a quarter of
+ * the memory limit the process runs under when that is smaller — never less
+ * than one socket's own ceiling. `constrained` is the limit in bytes, 0 for
+ * none, as `process.constrainedMemory()` reports it.
+ */
+export declare function processSendBudget(constrained?: number): number;
+/**
+ * Count the sockets of `wss` in the process-wide send budget. Returns the
+ * function that stops counting them, for when the server closes.
+ */
+export declare function budgetSendBuffers(wss: WebSocketServer): () => void;
+/**
+ * Terminate sockets, largest backlog first, until what this process's sockets
+ * hold unread between them is back within `budget`. Returns the sockets it
+ * terminated. A terminated socket closes like any other, and its client
+ * reconnects and re-subscribes: one fresh frame per subscription, instead of
+ * the backlog.
+ */
+export declare function enforceProcessSendBudget(budget?: number): WebSocket[];
 /**
  * Ping every socket of `wss` each `intervalMs`, and terminate the ones that did
  * not answer the previous ping. Returns the function that stops it.
@@ -41,5 +77,9 @@ export declare function reapSilentSockets(wss: WebSocketServer, intervalMs?: num
 /**
  * Terminate `ws` if its unsent backlog has passed {@link MAX_SOCKET_BUFFERED_BYTES}.
  * Returns whether it did; the caller then sends nothing.
+ *
+ * Every frame in and out of a socket comes through here, so this is also where
+ * the process-wide budget is kept, summed at most every
+ * {@link PROCESS_BUDGET_CHECK_MS} — see {@link enforceProcessSendBudget}.
  */
 export declare function terminateIfBacklogged(ws: WebSocket, clientId: string): boolean;