@rebasepro/server-postgres 0.9.1-canary.16c42e9 → 0.9.1-canary.26fe4b2

package/src/services/channel-history.ts

@@ -0,0 +1,343 @@
+/**
+ * Ordered, replayable per-channel message history.
+ *
+ * Broadcast on its own is fire-and-forget to whoever is connected at the
+ * instant it is sent: fine for presence and for "someone saved" notifications,
+ * not enough for op-based collaborative editing, where a client that blinks
+ * out for two seconds has to resync a whole document rather than catch up on
+ * the four operations it missed. This adds the missing half — every retained
+ * broadcast gets a per-channel sequence number, and a client can ask for
+ * everything after the last one it saw.
+ *
+ * Three decisions worth stating, because each rules out a simpler-looking one:
+ *
+ *  - **Retention is server-side and opt-in.** A channel is created by whoever
+ *    names it, so a client-supplied history depth would let any visitor commit
+ *    the backend to unbounded storage. And presence channels — the common case
+ *    — must not pay for this: with no rules configured nothing is written, no
+ *    table is created, and `broadcast` runs exactly the code it ran before.
+ *
+ *  - **Sequence numbers come from the database, not from a counter in this
+ *    process.** They have to survive a restart and be shared across instances;
+ *    an in-memory counter would restart at 1 after a deploy and hand a
+ *    reconnecting client a replay from the wrong era, silently.
+ *
+ *  - **The cursor row outlives the messages it numbered.** Pruning is what
+ *    makes retention affordable, but pruning the cursor along with the messages
+ *    would restart the sequence and make `sinceSeq` mean something different
+ *    before and after — the worst kind of bug, because replay would still
+ *    return rows and they would look plausible. Cursors are tiny and are kept
+ *    forever; see {@link prune}, which touches only `channel_messages`.
+ */
+
+import { sql } from "drizzle-orm";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { ChannelHistoryEntry, ChannelRetentionRule } from "@rebasepro/types";
+import { logger } from "@rebasepro/server";
+
+/** How many messages a replay returns when the caller does not say. */
+const DEFAULT_REPLAY_LIMIT = 200;
+
+/**
+ * Hard ceiling on one replay, whatever the caller asks for.
+ *
+ * A reconnecting client names its own `limit`, so this is the only thing
+ * standing between a stale `sinceSeq` and a single frame carrying a channel's
+ * entire retained history. A client that is further behind than this is told so
+ * via `latestSeq` and can decide to resync wholesale instead of paging.
+ */
+const MAX_REPLAY_LIMIT = 1000;
+
+/** Minimum gap between two prunes of the same channel. */
+const PRUNE_THROTTLE_MS = 30_000;
+
+/**
+ * Parse a retention TTL into milliseconds.
+ *
+ * Accepts a raw millisecond count or a short duration string (`"30s"`, `"15m"`,
+ * `"24h"`, `"7d"`). Returns undefined for anything unparseable, which the
+ * caller treats as "no TTL" — a misspelt duration must not silently become an
+ * aggressive one.
+ */
+export function parseTtlMs(ttl: number | string | undefined): number | undefined {
+    if (ttl === undefined || ttl === null) return undefined;
+    if (typeof ttl === "number") return Number.isFinite(ttl) && ttl > 0 ? ttl : undefined;
+
+    const match = /^\s*(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)\s*$/i.exec(ttl);
+    if (!match) {
+        logger.warn(`⚠️ [ChannelHistory] Ignoring unparseable retention ttl "${ttl}" — expected e.g. "30s", "15m", "24h", "7d".`);
+        return undefined;
+    }
+    const value = parseFloat(match[1]);
+    const unit = match[2].toLowerCase();
+    const multiplier = unit === "ms" ? 1
+        : unit === "s" ? 1_000
+            : unit === "m" ? 60_000
+                : unit === "h" ? 3_600_000
+                    : 86_400_000;
+    const ms = value * multiplier;
+    return ms > 0 ? ms : undefined;
+}
+
+/**
+ * Whether `channel` is covered by `rule`.
+ *
+ * Exact match, or a trailing `*` acting as a prefix. Not a general glob: this
+ * decides what reaches disk, and a pattern language whose reach is not obvious
+ * at a glance is the wrong tool for that job.
+ */
+export function channelMatchesRule(channel: string, rule: ChannelRetentionRule): boolean {
+    const pattern = rule.match;
+    if (pattern === "*") return true;
+    if (pattern.endsWith("*")) return channel.startsWith(pattern.slice(0, -1));
+    return channel === pattern;
+}
+
+/** A rule with its TTL already resolved to milliseconds. */
+export interface ResolvedRetention {
+    limit?: number;
+    ttlMs?: number;
+}
+
+/**
+ * Persistence and replay for retained channels.
+ *
+ * Inert unless constructed with at least one rule: {@link enabled} is false,
+ * {@link ensureTables} does nothing, and {@link retentionFor} answers undefined
+ * for every channel, so the realtime service never reaches the SQL below.
+ */
+export class ChannelHistoryStore {
+    private rules: ChannelRetentionRule[];
+    /** Resolved rule per channel name, so the match runs once per channel. */
+    private resolved = new Map<string, ResolvedRetention | null>();
+    /** Channel → timestamp of its last prune, for {@link PRUNE_THROTTLE_MS}. */
+    private lastPruned = new Map<string, number>();
+    private tablesReady = false;
+
+    constructor(private db: NodePgDatabase<Record<string, unknown>>, rules: ChannelRetentionRule[] = []) {
+        this.rules = rules.filter(rule => {
+            if (!rule?.match) {
+                logger.warn("⚠️ [ChannelHistory] Ignoring a retention rule with no `match`.");
+                return false;
+            }
+            const hasBound = rule.limit !== undefined || rule.ttl !== undefined;
+            if (!hasBound) {
+                // Unbounded retention is almost never intended and cannot be
+                // walked back once the table has grown, so it is refused rather
+                // than honoured.
+                logger.warn(`⚠️ [ChannelHistory] Retention rule "${rule.match}" sets neither \`limit\` nor \`ttl\` — ignoring it, as it would retain forever.`);
+                return false;
+            }
+            return true;
+        });
+    }
+
+    /** Whether any channel retains anything at all. */
+    get enabled(): boolean {
+        return this.rules.length > 0;
+    }
+
+    /**
+     * The retention that applies to `channel`, or undefined when none does.
+     *
+     * First matching rule wins, so callers order them most-specific first.
+     */
+    retentionFor(channel: string): ResolvedRetention | undefined {
+        if (!this.enabled || !channel) return undefined;
+
+        const cached = this.resolved.get(channel);
+        if (cached !== undefined) return cached ?? undefined;
+
+        const rule = this.rules.find(r => channelMatchesRule(channel, r));
+        const resolved: ResolvedRetention | null = rule
+            ? { limit: rule.limit, ttlMs: parseTtlMs(rule.ttl) }
+            : null;
+
+        // Bounded by the number of distinct channel names seen, which is the
+        // same thing the in-memory channel and presence maps are bounded by.
+        this.resolved.set(channel, resolved);
+        return resolved ?? undefined;
+    }
+
+    /**
+     * Create the history tables. Idempotent, and a no-op when no rule is set —
+     * a deployment that never retains anything gets no schema for it.
+     */
+    async ensureTables(): Promise<void> {
+        if (!this.enabled || this.tablesReady) return;
+
+        await this.db.execute(sql`CREATE SCHEMA IF NOT EXISTS rebase`);
+
+        // The primary key is exactly the replay query's access path
+        // (`channel = $1 AND seq > $2 ORDER BY seq`), so it needs no further
+        // index of its own.
+        await this.db.execute(sql`
+            CREATE TABLE IF NOT EXISTS rebase.channel_messages (
+                channel TEXT NOT NULL,
+                seq BIGINT NOT NULL,
+                event TEXT NOT NULL,
+                payload JSONB,
+                sender_id TEXT,
+                created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+                PRIMARY KEY (channel, seq)
+            )
+        `);
+
+        // Only for the TTL arm of pruning; the limit arm rides the primary key.
+        await this.db.execute(sql`
+            CREATE INDEX IF NOT EXISTS idx_channel_messages_created
+            ON rebase.channel_messages (created_at)
+        `);
+
+        // Never pruned — see the note at the top of this file. One row per
+        // channel that has ever retained a message.
+        await this.db.execute(sql`
+            CREATE TABLE IF NOT EXISTS rebase.channel_cursors (
+                channel TEXT PRIMARY KEY,
+                last_seq BIGINT NOT NULL
+            )
+        `);
+
+        this.tablesReady = true;
+        logger.info(`✅ [ChannelHistory] Retained channels ready (${this.rules.length} rule(s)).`);
+    }
+
+    /**
+     * Append a broadcast and return the sequence number it was given.
+     *
+     * The sequence is allocated by the same statement that stores the message,
+     * so a crash between the two is not a possibility. `ON CONFLICT DO UPDATE`
+     * takes a row lock on the channel's cursor, which is what makes concurrent
+     * broadcasts to one channel line up in a single order — and what keeps
+     * different channels from contending with each other at all.
+     */
+    async append(
+        channel: string,
+        event: string,
+        payload: unknown,
+        senderId?: string
+    ): Promise<{ seq: number; at: string }> {
+        const result = await this.db.execute(sql`
+            WITH next AS (
+                INSERT INTO rebase.channel_cursors (channel, last_seq)
+                VALUES (${channel}, 1)
+                ON CONFLICT (channel)
+                DO UPDATE SET last_seq = rebase.channel_cursors.last_seq + 1
+                RETURNING last_seq
+            )
+            INSERT INTO rebase.channel_messages (channel, seq, event, payload, sender_id)
+            SELECT ${channel}, next.last_seq, ${event}, ${JSON.stringify(payload ?? null)}::jsonb, ${senderId ?? null}
+            FROM next
+            RETURNING seq, created_at
+        `);
+
+        const row = result.rows[0] as { seq: string | number; created_at: Date | string } | undefined;
+        if (!row) throw new Error(`Failed to append to channel history for "${channel}"`);
+
+        return {
+            // BIGINT comes back as a string from node-postgres; the wire type is
+            // a number, and a channel would need 2^53 messages to notice.
+            seq: Number(row.seq),
+            at: row.created_at instanceof Date ? row.created_at.toISOString() : String(row.created_at)
+        };
+    }
+
+    /**
+     * Everything retained for `channel` after `sinceSeq`, oldest first.
+     *
+     * `latestSeq` is reported whether or not the messages were capped, so a
+     * client that is further behind than one page can tell.
+     */
+    async replay(
+        channel: string,
+        sinceSeq = 0,
+        limit = DEFAULT_REPLAY_LIMIT
+    ): Promise<{ messages: ChannelHistoryEntry[]; latestSeq: number }> {
+        const capped = Math.max(1, Math.min(Math.floor(limit) || DEFAULT_REPLAY_LIMIT, MAX_REPLAY_LIMIT));
+        const after = Number.isFinite(sinceSeq) && sinceSeq > 0 ? Math.floor(sinceSeq) : 0;
+
+        const result = await this.db.execute(sql`
+            SELECT seq, event, payload, sender_id, created_at
+            FROM rebase.channel_messages
+            WHERE channel = ${channel} AND seq > ${after}
+            ORDER BY seq ASC
+            LIMIT ${capped}
+        `);
+
+        const messages = (result.rows as Array<{
+            seq: string | number;
+            event: string;
+            payload: unknown;
+            sender_id: string | null;
+            created_at: Date | string;
+        }>).map(row => ({
+            seq: Number(row.seq),
+            event: row.event,
+            payload: row.payload,
+            senderId: row.sender_id ?? undefined,
+            at: row.created_at instanceof Date ? row.created_at.toISOString() : String(row.created_at)
+        }));
+
+        // Read from the cursor rather than from the messages: the cursor is the
+        // authority on how far the channel has got, and still says so after
+        // pruning has removed the messages it counted.
+        const cursor = await this.db.execute(sql`
+            SELECT last_seq FROM rebase.channel_cursors WHERE channel = ${channel}
+        `);
+        const cursorRow = cursor.rows[0] as { last_seq: string | number } | undefined;
+        const latestSeq = cursorRow ? Number(cursorRow.last_seq) : 0;
+
+        return { messages, latestSeq };
+    }
+
+    /**
+     * Enforce a channel's retention bounds.
+     *
+     * Throttled per channel, so a burst of operations prunes once rather than
+     * once per message — the cost then tracks elapsed time instead of write
+     * volume, which is what makes retention affordable on a hot channel.
+     */
+    async prune(channel: string, retention: ResolvedRetention): Promise<number> {
+        const now = Date.now();
+        const last = this.lastPruned.get(channel) ?? 0;
+        if (now - last < PRUNE_THROTTLE_MS) return 0;
+        this.lastPruned.set(channel, now);
+
+        let deleted = 0;
+
+        if (retention.ttlMs !== undefined) {
+            const result = await this.db.execute(sql`
+                DELETE FROM rebase.channel_messages
+                WHERE channel = ${channel}
+                  AND created_at < NOW() - MAKE_INTERVAL(secs => ${retention.ttlMs / 1000})
+            `);
+            deleted += result.rowCount ?? 0;
+        }
+
+        if (retention.limit !== undefined && retention.limit > 0) {
+            // OFFSET past the newest `limit` rows to find the highest seq that
+            // is no longer wanted, then delete everything at or below it. Fewer
+            // rows than the limit leaves the subquery empty, and the comparison
+            // with NULL deletes nothing.
+            const result = await this.db.execute(sql`
+                DELETE FROM rebase.channel_messages
+                WHERE channel = ${channel}
+                  AND seq <= (
+                      SELECT seq FROM rebase.channel_messages
+                      WHERE channel = ${channel}
+                      ORDER BY seq DESC
+                      OFFSET ${Math.floor(retention.limit)} LIMIT 1
+                  )
+            `);
+            deleted += result.rowCount ?? 0;
+        }
+
+        return deleted;
+    }
+
+    /** Forget throttle and match caches. Called on shutdown. */
+    clear(): void {
+        this.resolved.clear();
+        this.lastPruned.clear();
+    }
+}

package/src/services/realtimeService.ts

@@ -15,6 +15,8 @@ import { logger } from "@rebasepro/server";
 import { sanitizeErrorForClient } from "../utils/pg-error-utils";
 import { CdcListener, type CdcChangeEvent } from "./cdc/CdcListener";
 import { deriveRowAddress, getPrimaryKeys, type PrimaryKeyInfo } from "./collection-helpers";
+import { ChannelHistoryStore, type ResolvedRetention } from "./channel-history";
+import type { ChannelHistoryEntry, ChannelRetentionRule } from "@rebasepro/types";
 
 /** Channel name used for Postgres LISTEN/NOTIFY cross-instance realtime. */
 const PG_NOTIFY_CHANNEL = "rebase_entity_changes";
@@ -24,7 +26,7 @@ const PG_NOTIFY_CHANNEL = "rebase_entity_changes";
  * Mirrors the session variables set by PostgresBackendDriver.withAuth().
  */
 export interface SubscriptionAuthContext {
-    userId: string;
+    uid: string;
     roles: string[];
 }
 
@@ -52,6 +54,28 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
 
     // Presence: channel → Map<clientId, { state, lastSeen }>
     private presence = new Map<string, Map<string, { state: Record<string, unknown>; lastSeen: number }>>();
+
+    /**
+     * Ordered, replayable history for channels that opt into it.
+     *
+     * Undefined until {@link configureChannelHistory} is called, and inert even
+     * then unless retention rules were supplied — so presence and ephemeral
+     * notification channels never touch it. See `channel-history.ts`.
+     */
+    private channelHistory?: ChannelHistoryStore;
+
+    /**
+     * One promise chain per retained channel, so that assigning a sequence
+     * number and fanning the message out happen in the same order for every
+     * message on that channel.
+     *
+     * Without it, two concurrent broadcasts can be numbered 4 and 5 by the
+     * database and still reach subscribers as 5 then 4 — live order and replay
+     * order would disagree, which is exactly the divergence sequence numbers
+     * are supposed to rule out. Keyed by channel, so unrelated channels never
+     * wait on each other.
+     */
+    private channelSendQueues = new Map<string, Promise<void>>();
     private presenceInterval?: ReturnType<typeof setInterval>;
     private static readonly PRESENCE_TIMEOUT_MS = 30000; // 30s
     private dataService: DataService;
@@ -73,7 +97,7 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             searchString?: string;
         };
         // Auth context for RLS — when set, refetches run in a transaction
-        // with set_config('app.user_id', ...) / set_config('app.user_roles', ...)
+        // with set_config('app.uid', ...) / set_config('app.user_roles', ...)
         authContext?: SubscriptionAuthContext;
     }>();
 
@@ -322,6 +346,14 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
                     payload?.payload
                 );
                 break;
+            case "channel_history":
+                await this.handleChannelHistoryRequest(
+                    clientId,
+                    payload?.channel as string,
+                    payload?.sinceSeq as number | undefined,
+                    payload?.limit as number | undefined
+                );
+                break;
 
             // ── Presence ──
             case "presence_track":
@@ -669,10 +701,10 @@ export class RealtimeService extends EventEmitter implements RealtimeProvider {
             // Always wrap in a transaction with session vars, defaulting to anonymous context if missing.
             // Refetches are reads: apply the same GUCs + reader-role downgrade as the
             // driver's read path, so realtime cannot leak rows the initial fetch hid.
-            const activeAuth = authContext || { userId: "anon",
+            const activeAuth = authContext || { uid: "anon",
 roles: ["anon"] };
             return await this.db.transaction(async (tx) => {
-                await applyAuthContext(tx, { userId: activeAuth.userId, roles: activeAuth.roles }, this.rlsUserRole);
+                await applyAuthContext(tx, { uid: activeAuth.uid, roles: activeAuth.roles }, this.rlsUserRole);
                 const txEntityService = new DataService(tx, this.registry);
                 let fetchedEntities;
                 if (collectionRequest.searchString) {
@@ -711,7 +743,7 @@ roles: ["anon"] };
 
                 if (globalCallbacks?.afterRead || callbacks?.afterRead || propertyCallbacks?.afterRead) {
                     const contextForCallback = {
-                        user: { uid: activeAuth.userId,
+                        user: { uid: activeAuth.uid,
 roles: activeAuth.roles },
                         driver: this.driver,
                         data: (this.driver && "data" in this.driver) ? (this.driver as DataDriverWithData).data : undefined
@@ -849,10 +881,10 @@ roles: activeAuth.roles },
 
             // Always wrap in a transaction with session vars, defaulting to anonymous context if missing.
             // Same read isolation as collection refetches: GUCs + reader-role downgrade.
-            const activeAuth = authContext || { userId: "anon",
+            const activeAuth = authContext || { uid: "anon",
 roles: ["anon"] };
             return await this.db.transaction(async (tx) => {
-                await applyAuthContext(tx, { userId: activeAuth.userId, roles: activeAuth.roles }, this.rlsUserRole);
+                await applyAuthContext(tx, { uid: activeAuth.uid, roles: activeAuth.roles }, this.rlsUserRole);
                 const txEntityService = new DataService(tx, this.registry);
                 let processedEntity = await txEntityService.fetchOne(notifyPath, id, collection?.databaseId);
 
@@ -867,7 +899,7 @@ roles: ["anon"] };
 
                     if (globalCallbacks?.afterRead || callbacks?.afterRead || propertyCallbacks?.afterRead) {
                         const contextForCallback = {
-                            user: { uid: activeAuth.userId,
+                            user: { uid: activeAuth.uid,
 roles: activeAuth.roles },
                             driver: this.driver,
                             data: (this.driver && "data" in this.driver) ? (this.driver as DataDriverWithData).data : undefined
@@ -1039,8 +1071,85 @@ roles: activeAuth.roles },
         this.removePresence(clientId, channel);
     }
 
-    /** Broadcast a message to all clients in a channel except sender */
+    /**
+     * Broadcast a message to all clients in a channel except the sender.
+     *
+     * On a channel with no retention rule this is what it always was: a
+     * synchronous fan-out to whoever is connected, with no sequence number, no
+     * SQL and no await — the body below runs to completion before returning.
+     *
+     * On a retained channel the message is durably numbered first and only then
+     * delivered, through a per-channel queue so that delivery order matches
+     * sequence order. That ordering is the whole point: a client that catches up
+     * with `sinceSeq` has to arrive at the same state as one that never
+     * disconnected.
+     */
     broadcastToChannel(clientId: string, channel: string, event: string, payload: unknown): void {
+        const retention = this.channelHistory?.retentionFor(channel);
+        if (!retention) {
+            this.fanOutBroadcast(clientId, channel, event, payload);
+            return;
+        }
+
+        const previous = this.channelSendQueues.get(channel) ?? Promise.resolve();
+        const next = previous
+            // A failed predecessor must not poison the chain — the next message
+            // on this channel is independent and still deserves to be sent.
+            .catch(() => { /* already reported below */ })
+            .then(() => this.persistAndFanOut(clientId, channel, event, payload, retention));
+
+        this.channelSendQueues.set(channel, next);
+        void next.finally(() => {
+            // Only clear if nothing has queued behind us in the meantime.
+            if (this.channelSendQueues.get(channel) === next) this.channelSendQueues.delete(channel);
+        });
+    }
+
+    /**
+     * Number a broadcast, store it, then deliver it.
+     *
+     * A message that cannot be stored is **not** delivered. Delivering it would
+     * put it in front of live subscribers while leaving it absent from every
+     * future replay — the two views of the channel would disagree permanently,
+     * and no later message could repair the gap. Failing loudly to the sender
+     * instead lets it retry, which for an operation stream is the only outcome
+     * that keeps clients convergent.
+     */
+    private async persistAndFanOut(
+        clientId: string,
+        channel: string,
+        event: string,
+        payload: unknown,
+        retention: ResolvedRetention
+    ): Promise<void> {
+        let seq: number;
+        try {
+            ({ seq } = await this.channelHistory!.append(channel, event, payload, clientId));
+        } catch (error) {
+            logger.error(`❌ [ChannelHistory] Could not persist broadcast on "${channel}" — message dropped`, { error });
+            this.sendError(
+                clientId,
+                `Could not persist broadcast on retained channel "${channel}"`,
+                undefined,
+                "CHANNEL_HISTORY_WRITE_FAILED"
+            );
+            return;
+        }
+
+        this.fanOutBroadcast(clientId, channel, event, payload, seq);
+
+        try {
+            await this.channelHistory!.prune(channel, retention);
+        } catch (error) {
+            // Retention is a housekeeping concern; the message is already
+            // delivered and durable, so a failed prune must not surface as a
+            // broadcast failure. It will be retried on the next message.
+            logger.warn(`⚠️ [ChannelHistory] Prune failed for "${channel}"`, { error });
+        }
+    }
+
+    /** Deliver a broadcast frame to every member of a channel but the sender. */
+    private fanOutBroadcast(clientId: string, channel: string, event: string, payload: unknown, seq?: number): void {
         const members = this.channels.get(channel);
         if (!members) return;
 
@@ -1048,7 +1157,8 @@ roles: activeAuth.roles },
             type: "broadcast",
             channel,
             event,
-            payload
+            payload,
+            ...(seq !== undefined ? { seq } : {})
         });
 
         for (const memberId of members) {
@@ -1060,6 +1170,79 @@ roles: activeAuth.roles },
         }
     }
 
+    // =============================================================================
+    // Channel History
+    // =============================================================================
+
+    /**
+     * Install retention rules and create the tables they need.
+     *
+     * Safe to call with no rules (and safe not to call at all): the store stays
+     * inert, no schema is created, and broadcast keeps its original
+     * fire-and-forget path.
+     */
+    async configureChannelHistory(rules: ChannelRetentionRule[] | undefined): Promise<void> {
+        this.channelHistory = new ChannelHistoryStore(this.db, rules ?? []);
+        if (!this.channelHistory.enabled) return;
+        await this.channelHistory.ensureTables();
+    }
+
+    /** Whether any channel is configured to retain messages. */
+    public isChannelHistoryEnabled(): boolean {
+        return this.channelHistory?.enabled ?? false;
+    }
+
+    /**
+     * Answer a client's catch-up request.
+     *
+     * A channel with no retention rule is answered with `retained: false`
+     * rather than an empty list, so the client can tell "you missed nothing"
+     * apart from "this channel never keeps anything" — the second means its
+     * reconnect strategy has to be a full resync, and silence would leave it
+     * guessing.
+     */
+    private async handleChannelHistoryRequest(
+        clientId: string,
+        channel: string,
+        sinceSeq?: number,
+        limit?: number
+    ): Promise<void> {
+        if (!channel) return;
+
+        const retention = this.channelHistory?.retentionFor(channel);
+        if (!retention) {
+            this.sendChannelHistory(clientId, channel, [], false);
+            return;
+        }
+
+        try {
+            const { messages, latestSeq } = await this.channelHistory!.replay(channel, sinceSeq, limit);
+            this.sendChannelHistory(clientId, channel, messages, true, latestSeq);
+        } catch (error) {
+            logger.error(`❌ [ChannelHistory] Replay failed for "${channel}"`, { error });
+            this.sendError(clientId, `Could not replay history for channel "${channel}"`, undefined, "CHANNEL_HISTORY_READ_FAILED");
+        }
+    }
+
+    private sendChannelHistory(
+        clientId: string,
+        channel: string,
+        messages: ChannelHistoryEntry[],
+        retained: boolean,
+        latestSeq?: number
+    ): void {
+        const ws = this.clients.get(clientId);
+        if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(JSON.stringify({
+                type: "channel_history",
+                channel,
+                messages,
+                retained,
+                ...(latestSeq !== undefined ? { latestSeq } : {})
+            }));
+        }
+    }
+
     // =============================================================================
     // Presence
     // =============================================================================
@@ -1191,6 +1374,11 @@ lastSeen: Date.now() });
         // 3. Clear broadcast channels and presence
         this.channels.clear();
         this.presence.clear();
+        // Pending history writes hold the pool open; let them settle before the
+        // caller closes it, but never let a rejected one break shutdown.
+        await Promise.allSettled([...this.channelSendQueues.values()]);
+        this.channelSendQueues.clear();
+        this.channelHistory?.clear();
         if (this.presenceInterval) {
             clearInterval(this.presenceInterval);
             this.presenceInterval = undefined;