@rebasepro/client 0.9.1-canary.fd3754b → 0.10.0

package/src/websocket.ts

@@ -12,6 +12,7 @@ import {
     BranchInfo,
     RebaseApiError
 } from "@rebasepro/types";
+import { buildCompositeId, COMPOSITE_ID_SEPARATOR, type PrimaryKeyInfo } from "@rebasepro/common";
 import { rebaseReviver } from "./reviver";
 
 
@@ -29,7 +30,14 @@ function extractMessageError(message: WebSocketMessage): { errorMessage: string;
     const errorCode = typeof errPayload === "object"
         ? errPayload.code
         : payload?.code;
-    return { errorMessage,
+    // Callers treat this as a string (`.toLowerCase()` in isAuthError). A frame
+    // carrying a non-string here would throw inside the message handler, where
+    // the surrounding try/catch would swallow it — and a subscription error that
+    // never reaches its listener is a view stuck loading forever.
+    const safeMessage = typeof errorMessage === "string"
+        ? errorMessage
+        : (errorMessage == null ? "Unknown error" : JSON.stringify(errorMessage));
+    return { errorMessage: safeMessage,
 errorCode };
 }
 
@@ -44,6 +52,25 @@ export interface RebaseWebSocketConfig {
 }
 
 
+/**
+ * Broadcast and presence frames.
+ *
+ * Fire-and-forget (the server sends no response envelope), and exempt from the
+ * client-side auth gate — a public channel is usable without an account.
+ */
+const CHANNEL_MESSAGE_TYPES = new Set([
+    "join_channel",
+    "leave_channel",
+    "broadcast",
+    "presence_track",
+    "presence_untrack",
+    "presence_state",
+    // The catch-up request. Like `presence_state`, its answer comes back as a
+    // channel-addressed frame rather than a response envelope, so it must not
+    // be given a pending request to wait on.
+    "channel_history"
+]);
+
 /**
  * Low-level realtime WebSocket client.
  *
@@ -64,6 +91,42 @@ export class RebaseWebSocketClient {
 
     private listeners = new Map<string, Set<(...args: unknown[]) => void>>();
 
+    /** Channel-name → handlers, for broadcast and presence frames. */
+    private channelHandlers = new Map<string, Set<(message: Record<string, unknown>) => void>>();
+
+    /** Set by `close()`. Blocks any later operation from silently redialling. */
+    private closedByCaller = false;
+
+    /**
+     * Whether a socket exists at all (open or still opening).
+     *
+     * Lets callers distinguish "authenticate the live socket" from "there is
+     * nothing to authenticate yet", without that question forcing a dial.
+     */
+    public get hasSocket(): boolean {
+        return this.ws !== null;
+    }
+
+    /** So the "no WebSocket in this environment" warning is said once, not per call. */
+    private warnedNoWebSocket = false;
+
+    /** Subscribe to broadcast/presence frames for one channel. */
+    public onChannelMessage(channel: string, handler: (message: Record<string, unknown>) => void): () => void {
+        if (!this.channelHandlers.has(channel)) this.channelHandlers.set(channel, new Set());
+        this.channelHandlers.get(channel)!.add(handler);
+        return () => {
+            const handlers = this.channelHandlers.get(channel);
+            if (!handlers) return;
+            handlers.delete(handler);
+            if (handlers.size === 0) this.channelHandlers.delete(channel);
+        };
+    }
+
+    /** Notified after the socket comes back, so channels can re-join. */
+    public onReconnect(handler: () => void): () => void {
+        return this.on("reconnect", handler);
+    }
+
     public on(event: "connect" | "disconnect" | "reconnect" | "error", cb: (...args: unknown[]) => void) {
         if (!this.listeners.has(event)) {
             this.listeners.set(event, new Set());
@@ -89,6 +152,25 @@ export class RebaseWebSocketClient {
         latestData?: Record<string, unknown>[]; // Cache the latest flat rows
         lastUpdated?: number; // Timestamp for cache invalidation
         isInitialDataReceived?: boolean; // Track if we got initial data
+        /**
+         * A `subscribe_collection` frame is on the wire and its initial payload
+         * has not arrived yet. Without this, a subscription whose subscribe
+         * failed is indistinguishable from one still loading, and every later
+         * listener attaches to it and waits forever.
+         */
+        subscribeInFlight?: boolean;
+        /**
+         * Watchdog for the above. `subscribe_collection` expects no response
+         * envelope, so it is not covered by `pendingRequests`' timeout — a lost
+         * initial payload would otherwise hang the subscription indefinitely.
+         */
+        subscribeTimeout?: ReturnType<typeof setTimeout>;
+        /**
+         * The key columns of this collection, as told by the server on a patch.
+         * Rows are columns only, and the SDK holds no collection config, so
+         * without this there is nothing to derive an address from.
+         */
+        pks?: PrimaryKeyInfo[];
     }>();
 
     private singleSubscriptions = new Map<string, {
@@ -101,6 +183,9 @@ export class RebaseWebSocketClient {
         latestData?: Record<string, unknown> | null; // Cache the latest flat row
         lastUpdated?: number; // Timestamp for cache invalidation
         isInitialDataReceived?: boolean; // Track if we got initial data
+        /** See the collection subscription counterparts. */
+        subscribeInFlight?: boolean;
+        subscribeTimeout?: ReturnType<typeof setTimeout>;
     }>();
 
     // Maps to quickly find subscription by backend subscription ID
@@ -118,6 +203,7 @@ export class RebaseWebSocketClient {
     private isConnected = false;
     private messageQueue: Record<string, unknown>[] = [];
     private requestTimeoutMs = 30000;
+    private subscriptionTimeoutMs = 30000;
     private reconnectTimeout: ReturnType<typeof setTimeout> | null = null;
 
     private isAuthenticated = false;
@@ -132,11 +218,39 @@ export class RebaseWebSocketClient {
         this.onUnauthorized = config.onUnauthorized;
         this.WebSocketConstructor = config.WebSocket || (typeof WebSocket !== "undefined" ? WebSocket : undefined);
 
+        // Deliberately does NOT dial here. Constructing the client is not a
+        // statement that the app wants a socket — `createRebaseClient` builds
+        // one whenever realtime is not explicitly disabled, so connecting here
+        // opened a socket on every page load of every app that merely *might*
+        // subscribe later. Anonymous-first apps paid that on every visit, to
+        // authenticate with nothing, which left them choosing between "socket
+        // on every page load" and "no channels at all".
+        //
+        // The environment warning is also deferred: an app that never
+        // subscribes should say nothing at all. See `ensureConnected`.
+    }
+
+    /**
+     * Open the socket if it is not open (or opening) already.
+     *
+     * Idempotent, synchronous, and safe to call on every operation that needs a
+     * live socket — `initWebSocket` already no-ops on an open socket and is
+     * re-entrant, since the reconnect path has always called it.
+     */
+    public ensureConnected(): void {
+        // An explicit `close()` is final. Without this, one queued frame could
+        // redial a socket the caller just released and keep a Node process
+        // alive forever.
+        if (this.closedByCaller) return;
         if (!this.WebSocketConstructor) {
-            console.warn("WebSocket is not defined in this environment. Realtime subscriptions will not work unless you provide a WebSocket implementation in the config.");
-        } else {
-            this.initWebSocket();
+            if (!this.warnedNoWebSocket) {
+                this.warnedNoWebSocket = true;
+                console.warn("WebSocket is not defined in this environment. Realtime subscriptions will not work unless you provide a WebSocket implementation in the config.");
+            }
+            return;
         }
+        if (this.ws || this.reconnectTimeout) return;
+        this.initWebSocket();
     }
 
     /**
@@ -201,7 +315,16 @@ export class RebaseWebSocketClient {
         }
     }
 
-    public disconnect(): void {
+    /**
+     * Drop the socket.
+     *
+     * `permanent` distinguishes the two callers. Signing out drops the socket
+     * but the client stays usable — a later subscribe should reconnect
+     * anonymously. `client.close()` is the caller saying they are done, and
+     * must not be undone by a stray queued frame.
+     */
+    public disconnect(permanent = false): void {
+        if (permanent) this.closedByCaller = true;
         this.isAuthenticated = false;
         this.authPromise = null;
         if (this.reconnectTimeout) {
@@ -263,6 +386,10 @@ export class RebaseWebSocketClient {
                 if (wasReconnect) {
                     this.resubscribeAll();
                 }
+
+                // Subscribes requested while offline have just gone out; they
+                // could not be watchdogged at request time.
+                this.armPendingSubscribeWatchdogs();
             };
 
             this.ws!.onmessage = (event) => {
@@ -279,6 +406,9 @@ export class RebaseWebSocketClient {
                 this.isConnected = false;
                 this.isAuthenticated = false;
                 this.authPromise = null;
+                // The reconnect path re-subscribes everything; a watchdog firing
+                // in the meantime would tear down healthy subscriptions.
+                this.suspendSubscribeWatchdogs();
                 this.emit("disconnect");
 
                 // Re-queue pending requests so the UI doesn't hang indefinitely or crash
@@ -319,6 +449,11 @@ export class RebaseWebSocketClient {
     private attemptReconnect() {
         if (this.reconnectAttempts >= this.maxReconnectAttempts) {
             console.error("Max reconnection attempts reached");
+            // Nothing will re-subscribe now, so stop every subscription that
+            // never loaded from spinning forever.
+            this.failAllPendingSubscriptions(
+                new RebaseApiError("Connection lost", { code: "CONNECTION_LOST" })
+            );
             return;
         }
 
@@ -399,29 +534,32 @@ export class RebaseWebSocketClient {
                 backendKeyMap.delete(oldBackendId);
                 backendKeyMap.set(newBackendId, subscriptionKey);
 
-                this.sendMessage({
-                    type: messageType,
-                    payload: {
-                        ...subscription.props,
-                        subscriptionId: newBackendId
-                    }
-                }).catch(error => {
-                    console.error(`[WS] Failed to re-subscribe ${idPrefix} after auth refresh:`, subscriptionKey, error);
-                    subscription.callbacks.forEach(callback => {
-                        if (callback.onError) callback.onError(error);
-                    });
-                });
+                // Route through the helpers so the retry is watchdogged too.
+                if (messageType === "subscribe_collection") {
+                    this.sendCollectionSubscribe(subscriptionKey);
+                } else {
+                    this.sendEntitySubscribe(subscriptionKey);
+                }
+                return;
+            }
+
+            // The refresh did not produce usable credentials. Report the original
+            // error and drop the registration, so a later mount can try again
+            // rather than attaching to a subscription that will never load.
+            const { errorMessage, errorCode } = extractMessageError(message);
+            const error = new RebaseApiError(errorMessage, { code: errorCode });
+            if (messageType === "subscribe_collection") {
+                this.failCollectionSubscription(subscriptionKey, error);
             } else {
-                const { errorMessage, errorCode } = extractMessageError(message);
-                const error = new RebaseApiError(errorMessage, { code: errorCode });
-                subscription.callbacks.forEach(callback => {
-                    if (callback.onError) callback.onError(error);
-                });
+                this.failEntitySubscription(subscriptionKey, error);
             }
         }).catch(err => {
-            subscription.callbacks.forEach(callback => {
-                if (callback.onError) callback.onError(err);
-            });
+            const error = err instanceof Error ? err : new Error(String(err));
+            if (messageType === "subscribe_collection") {
+                this.failCollectionSubscription(subscriptionKey, error);
+            } else {
+                this.failEntitySubscription(subscriptionKey, error);
+            }
         });
     }
 
@@ -460,6 +598,25 @@ export class RebaseWebSocketClient {
             return;
         }
 
+        // Channel traffic (broadcast / presence) is addressed by channel name
+        // rather than by requestId or subscriptionId, so it is dispatched
+        // before the subscription paths — none of which would match it, and
+        // the message would otherwise fall through and be dropped silently.
+        if (typeof message.channel === "string" &&
+            (type === "broadcast" || type === "presence_state" || type === "presence_diff" || type === "channel_history")) {
+            const handlers = this.channelHandlers.get(message.channel);
+            if (handlers) {
+                for (const handler of [...handlers]) {
+                    try {
+                        handler(message as unknown as Record<string, unknown>);
+                    } catch (error) {
+                        console.error("Error in channel handler:", error);
+                    }
+                }
+            }
+            return;
+        }
+
         // Handle subscription updates for collection subscriptions
         if (subscriptionId && type === "collection_update") {
             const subscriptionKey = this.backendToCollectionKey.get(subscriptionId);
@@ -469,16 +626,27 @@ export class RebaseWebSocketClient {
                     const wireEntities = (message.rows || []) as unknown as Record<string, unknown>[];
                     const incomingRows = wireEntities;
 
+                    // The keys arrive with the rows, so they are known before the
+                    // first merge — a CDC-driven change never sends a patch, and
+                    // learning them from patches alone would leave every
+                    // externally-written collection unable to match a thing.
+                    const updatePks = (message as unknown as { pks?: PrimaryKeyInfo[] }).pks;
+                    if (updatePks) collectionSub.pks = updatePks;
+
                     // Structural merge: preserve cached row references for rows
                     // whose values haven't changed. This prevents downstream React components
                     // from re-rendering (VirtualTableCell uses deepEqual on rowData —
                     // same reference = instant true, avoiding expensive deep comparison).
-                    const rows = this.mergeRows(collectionSub.latestData, incomingRows);
+                    const rows = this.mergeRows(collectionSub.latestData, incomingRows, collectionSub.pks);
 
                     // Cache the latest data with optimizations
                     collectionSub.latestData = rows;
                     collectionSub.lastUpdated = Date.now();
                     collectionSub.isInitialDataReceived = true;
+                    // The subscribe landed — stand the watchdog down.
+                    if (collectionSub.subscribeTimeout) clearTimeout(collectionSub.subscribeTimeout);
+                    collectionSub.subscribeTimeout = undefined;
+                    collectionSub.subscribeInFlight = false;
 
                     // Notify all callbacks for this subscription
                     collectionSub.callbacks.forEach(callback => {
@@ -504,16 +672,28 @@ export class RebaseWebSocketClient {
                 const collectionSub = this.collectionSubscriptions.get(subscriptionKey);
                 if (collectionSub && collectionSub.isInitialDataReceived && collectionSub.latestData) {
                     const patchWireEntity = message.row ?? null;
-                    const patchEntityId = (message as unknown as { id: string }).id;
+                    const patchMessage = message as unknown as { id: string; pks?: PrimaryKeyInfo[] };
+                    const patchEntityId = patchMessage.id;
+                    // The server knows the key columns; remember them, because the
+                    // refetch reconciliation needs them too and carries no id.
+                    if (patchMessage.pks) collectionSub.pks = patchMessage.pks;
                     const patchRow = patchWireEntity ? (patchWireEntity as unknown as Record<string, unknown>) : null;
                     let updated: Record<string, unknown>[];
 
                     if (patchRow === null) {
                         // Row was deleted — remove it from the cached list
-                        updated = collectionSub.latestData.filter(e => String(e.id) !== String(patchEntityId));
+                        updated = collectionSub.latestData.filter(
+                            e => this.rowAddress(e, collectionSub.pks) !== String(patchEntityId)
+                        );
                     } else {
-                        // Row was created or updated — merge into the cached list
-                        const idx = collectionSub.latestData.findIndex(e => String(e.id) === String(patchRow.id));
+                        // Row was created or updated — merge into the cached list.
+                        // Matched against the patch's own address rather than
+                        // anything read off the row: `patchRow.id` is undefined
+                        // for a table not keyed on `id`, so every update looked
+                        // like a new row and was prepended as a duplicate.
+                        const idx = collectionSub.latestData.findIndex(
+                            e => this.rowAddress(e, collectionSub.pks) === String(patchEntityId)
+                        );
                         if (idx >= 0) {
                             // Update in place (preserve array position)
                             updated = [...collectionSub.latestData];
@@ -555,6 +735,9 @@ export class RebaseWebSocketClient {
                     entitySub.latestData = row;
                     entitySub.lastUpdated = Date.now();
                     entitySub.isInitialDataReceived = true;
+                    if (entitySub.subscribeTimeout) clearTimeout(entitySub.subscribeTimeout);
+                    entitySub.subscribeTimeout = undefined;
+                    entitySub.subscribeInFlight = false;
 
                     // Notify all callbacks for this subscription
                     entitySub.callbacks.forEach(callback => {
@@ -590,6 +773,14 @@ export class RebaseWebSocketClient {
                         return;
                     }
 
+                    // The server answered, so nothing is in flight any more. Leave
+                    // the registration in place (its listeners are still mounted
+                    // and have been told), but marked idle so the next listener
+                    // re-subscribes instead of attaching to a dead entry.
+                    if (collectionSub.subscribeTimeout) clearTimeout(collectionSub.subscribeTimeout);
+                    collectionSub.subscribeTimeout = undefined;
+                    collectionSub.subscribeInFlight = false;
+
                     const { errorMessage, errorCode } = extractMessageError(message);
                     const error = new RebaseApiError(errorMessage, { code: errorCode });
                     collectionSub.callbacks.forEach(callback => {
@@ -617,6 +808,10 @@ export class RebaseWebSocketClient {
                         return;
                     }
 
+                    if (entitySub.subscribeTimeout) clearTimeout(entitySub.subscribeTimeout);
+                    entitySub.subscribeTimeout = undefined;
+                    entitySub.subscribeInFlight = false;
+
                     const { errorMessage, errorCode } = extractMessageError(message);
                     const error = new RebaseApiError(errorMessage, { code: errorCode });
                     entitySub.callbacks.forEach(callback => {
@@ -717,7 +912,11 @@ export class RebaseWebSocketClient {
         }
     }
 
-    private sendMessage(message: Record<string, unknown>): Promise<unknown> {
+    /**
+     * Public because `RebaseRealtimeChannel` sends channel frames through it.
+     * Not part of the stable surface — prefer `client.realtime.channel(name)`.
+     */
+    public sendMessage(message: Record<string, unknown>): Promise<unknown> {
         // If already has a requestId (re-sending from queue), use the stored promise handlers
         const queuedMsg = message as Record<string, unknown> & { _queuedResolve?: (p: unknown) => void; _queuedReject?: (p: Error) => void };
         if (queuedMsg._queuedResolve && queuedMsg._queuedReject) {
@@ -725,6 +924,10 @@ export class RebaseWebSocketClient {
         }
 
         if (!this.isConnected || !this.ws) {
+            // The queue is only ever drained by a socket opening, so something
+            // has to open one. Before lazy connect this was guaranteed by the
+            // constructor; now the first frame is what asks for it.
+            this.ensureConnected();
             // Queue the message and return a promise that will be resolved when actually sent
             return new Promise<unknown>((resolve, reject) => {
                 const queueable = message as Record<string, unknown> & { _queuedResolve?: (p: unknown) => void; _queuedReject?: (p: Error) => void };
@@ -740,8 +943,19 @@ export class RebaseWebSocketClient {
     }
 
     private async doSendMessage(message: Record<string, unknown>, resolve: (value: unknown) => void, reject: (error: Error) => void): Promise<void> {
-        // Ensure authenticated before sending non-auth messages
-        if (message.type !== "AUTHENTICATE" && this.getAuthToken && !this.isAuthenticated) {
+        // Ensure authenticated before sending non-auth messages.
+        //
+        // Channel traffic is exempt. `ensureAuthenticated` throws "user not
+        // logged in" when there is no token, which rejects the frame before it
+        // is ever sent — so on an anonymous-first app (the kind this API was
+        // added for) *every* channel operation failed client-side, and the
+        // server never got to decide. Presence in a public room does not
+        // require an account. A signed-in caller still authenticates: the
+        // socket does it from `getAuthToken` on open, and the server authorizes
+        // these frames either way.
+        if (message.type !== "AUTHENTICATE"
+            && !CHANNEL_MESSAGE_TYPES.has(message.type as string)
+            && this.getAuthToken && !this.isAuthenticated) {
             try {
                 await this.ensureAuthenticated();
             } catch (error: unknown) {
@@ -754,17 +968,12 @@ export class RebaseWebSocketClient {
         const requestId = (message.requestId as string) || `req_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
         message.requestId = requestId;
 
-        const expectsResponse = ![
-            "subscribe_collection",
-            "subscribe_one",
-            "unsubscribe",
-            "join_channel",
-            "leave_channel",
-            "broadcast",
-            "presence_track",
-            "presence_untrack",
-            "presence_state"
-        ].includes(message.type as string);
+        const expectsResponse = !(
+            message.type === "subscribe_collection"
+            || message.type === "subscribe_one"
+            || message.type === "unsubscribe"
+            || CHANNEL_MESSAGE_TYPES.has(message.type as string)
+        );
 
         if (expectsResponse && !this.pendingRequests.has(requestId)) {
             const timeoutHandle = setTimeout(() => {
@@ -857,6 +1066,13 @@ options }
         return response.roles || [];
     }
 
+    async fetchApplicationRoles(): Promise<string[]> {
+        const response = await this.sendMessage({
+            type: "FETCH_APPLICATION_ROLES"
+        }) as { roles?: string[] };
+        return response.roles || [];
+    }
+
     async fetchCurrentDatabase(): Promise<string | undefined> {
         const response = await this.sendMessage({
             type: "FETCH_CURRENT_DATABASE"
@@ -1016,23 +1232,48 @@ options }
         return val;
     }
 
+    /**
+     * The address of a row, for matching it against another copy of itself.
+     *
+     * A row is exactly its columns and carries no address, so it is derived
+     * from the key columns the server named — including the ordinary case where
+     * that key is `id`, which the server reports like any other.
+     *
+     * Undefined when there are no keys, which means the server could not
+     * resolve any: such rows genuinely cannot be recognised, and guessing at a
+     * column called `id` would be inventing an identity for a table that has
+     * none.
+     */
+    private rowAddress(row: Record<string, unknown>, pks: PrimaryKeyInfo[] | undefined): string | undefined {
+        if (!pks || pks.length === 0) return undefined;
+        const address = buildCompositeId(row, pks);
+        if (!address || address.split(COMPOSITE_ID_SEPARATOR).every(part => part === "")) return undefined;
+        return address;
+    }
+
     /**
      * Merge incoming rows with cached data, preserving cached references
      * for rows whose values haven't changed. This avoids unnecessary
      * React re-renders when the server refetches all rows but most
      * haven't actually changed.
      */
-    private mergeRows(cached: Record<string, unknown>[] | undefined, incoming: Record<string, unknown>[]): Record<string, unknown>[] {
+    private mergeRows(
+        cached: Record<string, unknown>[] | undefined,
+        incoming: Record<string, unknown>[],
+        pks?: PrimaryKeyInfo[]
+    ): Record<string, unknown>[] {
         if (!cached || cached.length === 0) return incoming;
 
-        // Build a lookup from cached rows by ID for O(1) access
-        const cachedById = new Map<string | number, Record<string, unknown>>();
+        // Build a lookup from cached rows by address for O(1) access
+        const cachedById = new Map<string, Record<string, unknown>>();
         for (const row of cached) {
-            cachedById.set(row.id as string | number, row);
+            const address = this.rowAddress(row, pks);
+            if (address !== undefined) cachedById.set(address, row);
         }
 
         return incoming.map(incomingRow => {
-            const cachedRow = cachedById.get(incomingRow.id as string | number);
+            const address = this.rowAddress(incomingRow, pks);
+            const cachedRow = address === undefined ? undefined : cachedById.get(address);
             if (!cachedRow) return incomingRow;
 
             // Compare flat rows directly (no more path/values nesting)
@@ -1051,7 +1292,7 @@ options }
 incoming: normIncoming[key] };
                     }
                 }
-                console.debug(`[RebaseWS] Row ${incomingRow.id} refetch mismatch:\n`, JSON.stringify(mismatches, null, 2));
+                console.debug(`[RebaseWS] Row ${address} refetch mismatch:\n`, JSON.stringify(mismatches, null, 2));
             }
             return incomingRow;
         });
@@ -1063,6 +1304,11 @@ incoming: normIncoming[key] };
         onUpdate: (rows: Record<string, unknown>[]) => void,
         onError?: (error: Error) => void
     ): () => void {
+        // A subscription is the app asking for live data, so this is where the
+        // socket is wanted. Called before the dedup check below: joining an
+        // existing subscription must still work if the socket has since gone.
+        this.ensureConnected();
+
         const subscriptionKey = this.createCollectionSubscriptionKey(props);
         const callbackId = `callback_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 
@@ -1088,13 +1334,21 @@ onError });
                         onError(error instanceof Error ? error : new Error(String(error)));
                     }
                 }
+            } else if (!existingSubscription.subscribeInFlight) {
+                // Registered but idle: its subscribe never landed (the send failed,
+                // or the server answered with an error). Nothing is coming, so
+                // re-issue it — otherwise this listener waits forever.
+                this.sendCollectionSubscribe(subscriptionKey);
             }
 
             // Return unsubscribe function
             return () => {
                 callbackMap.delete(callbackId);
                 if (callbackMap.size === 0) {
-                    // No more callbacks, unsubscribe from backend
+                    // Only tear down if this is still the same registration — a
+                    // failed subscribe may have replaced it in the meantime.
+                    if (this.collectionSubscriptions.get(subscriptionKey) !== existingSubscription) return;
+                    if (existingSubscription.subscribeTimeout) clearTimeout(existingSubscription.subscribeTimeout);
                     this.collectionSubscriptions.delete(subscriptionKey);
                     this.backendToCollectionKey.delete(existingSubscription.backendSubscriptionId);
                     if (this.isConnected && this.ws) {
@@ -1125,16 +1379,9 @@ onError });
         // Add reverse lookup
         this.backendToCollectionKey.set(backendSubscriptionId, subscriptionKey);
 
-        // Send subscription request to backend
-        this.sendMessage({
-            type: "subscribe_collection",
-            payload: {
-                ...props,
-                subscriptionId: backendSubscriptionId
-            }
-        }).catch(error => {
-            if (onError) onError(error);
-        });
+        // Send subscription request to backend. A failure here drops the
+        // registration and notifies every listener, so the next mount retries.
+        this.sendCollectionSubscribe(subscriptionKey);
 
         // Return unsubscribe function
         return () => {
@@ -1143,6 +1390,7 @@ onError });
                 const callbacks = subscription.callbacks;
                 callbacks.delete(callbackId);
                 if (callbacks.size === 0) {
+                    if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
                     this.collectionSubscriptions.delete(subscriptionKey);
                     this.backendToCollectionKey.delete(subscription.backendSubscriptionId);
                     if (this.isConnected && this.ws) {
@@ -1161,6 +1409,8 @@ onError });
         onUpdate: (row: Record<string, unknown> | null) => void,
         onError?: (error: Error) => void
     ): () => void {
+        this.ensureConnected();
+
         const subscriptionKey = this.createSingleSubscriptionKey(props);
         const callbackId = `callback_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
 
@@ -1186,12 +1436,18 @@ onError });
                         onError(error instanceof Error ? error : new Error(String(error)));
                     }
                 }
+            } else if (!existingSubscription.subscribeInFlight) {
+                // See listenCollection: a registration with nothing in flight is
+                // dead, and attaching to it silently would hang this listener.
+                this.sendEntitySubscribe(subscriptionKey);
             }
 
             // Return unsubscribe function
             return () => {
                 callbackMap.delete(callbackId);
                 if (callbackMap.size === 0) {
+                    if (this.singleSubscriptions.get(subscriptionKey) !== existingSubscription) return;
+                    if (existingSubscription.subscribeTimeout) clearTimeout(existingSubscription.subscribeTimeout);
                     // No more callbacks, unsubscribe from backend
                     this.singleSubscriptions.delete(subscriptionKey);
                     this.backendToEntityKey.delete(existingSubscription.backendSubscriptionId);
@@ -1224,15 +1480,7 @@ onError });
         this.backendToEntityKey.set(backendSubscriptionId, subscriptionKey);
 
         // Send subscription request to backend
-        this.sendMessage({
-            type: "subscribe_one",
-            payload: {
-                ...props,
-                subscriptionId: backendSubscriptionId
-            }
-        }).catch(error => {
-            if (onError) onError(error);
-        });
+        this.sendEntitySubscribe(subscriptionKey);
 
         // Return unsubscribe function
         return () => {
@@ -1254,6 +1502,201 @@ onError });
         };
     }
 
+    /**
+     * Send a `subscribe_collection` for an already-registered subscription and
+     * arm its watchdog.
+     *
+     * Every path that registers a collection subscription goes through here, so
+     * that a subscribe which never lands — a rejected send, or a server that
+     * never answers — always ends up in `failCollectionSubscription` rather than
+     * leaving the entry parked with `isInitialDataReceived === false` forever.
+     */
+    private sendCollectionSubscribe(subscriptionKey: string): void {
+        const subscription = this.collectionSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+
+        const backendSubscriptionId = subscription.backendSubscriptionId;
+        subscription.subscribeInFlight = true;
+
+        if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+        subscription.subscribeTimeout = undefined;
+        // Only time out a frame that is actually on the wire. While offline the
+        // message just sits in the queue, and reconnect backoff can exceed the
+        // timeout — `armPendingSubscribeWatchdogs` picks these up on connect.
+        if (this.isConnected) this.sendCollectionSubscribeWatchdog(subscriptionKey);
+
+        this.sendMessage({
+            type: "subscribe_collection",
+            payload: {
+                ...subscription.props,
+                subscriptionId: backendSubscriptionId
+            }
+        }).catch(error => {
+            const current = this.collectionSubscriptions.get(subscriptionKey);
+            if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+            this.failCollectionSubscription(
+                subscriptionKey,
+                error instanceof Error ? error : new Error(String(error))
+            );
+        });
+    }
+
+    /** The `listenOne` counterpart of {@link sendCollectionSubscribe}. */
+    private sendEntitySubscribe(subscriptionKey: string): void {
+        const subscription = this.singleSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+
+        const backendSubscriptionId = subscription.backendSubscriptionId;
+        subscription.subscribeInFlight = true;
+
+        if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+        subscription.subscribeTimeout = undefined;
+        if (this.isConnected) this.sendEntitySubscribeWatchdog(subscriptionKey);
+
+        this.sendMessage({
+            type: "subscribe_one",
+            payload: {
+                ...subscription.props,
+                subscriptionId: backendSubscriptionId
+            }
+        }).catch(error => {
+            const current = this.singleSubscriptions.get(subscriptionKey);
+            if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+            this.failEntitySubscription(
+                subscriptionKey,
+                error instanceof Error ? error : new Error(String(error))
+            );
+        });
+    }
+
+    /**
+     * Report a subscribe failure to every listener and drop the registration.
+     *
+     * Dropping it is the point: the callbacks stay live (their components are
+     * still mounted and have been told), but the next `listenCollection` for
+     * these params finds no entry and issues a fresh subscribe instead of
+     * silently attaching to a dead one.
+     */
+    private failCollectionSubscription(subscriptionKey: string, error: Error): void {
+        const subscription = this.collectionSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+
+        if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+        subscription.subscribeInFlight = false;
+
+        this.collectionSubscriptions.delete(subscriptionKey);
+        this.backendToCollectionKey.delete(subscription.backendSubscriptionId);
+
+        subscription.callbacks.forEach(callback => {
+            if (callback.onError) {
+                try {
+                    callback.onError(error);
+                } catch (callbackError) {
+                    console.error("Error in collection subscription error callback:", callbackError);
+                }
+            }
+        });
+    }
+
+    /** The `listenOne` counterpart of {@link failCollectionSubscription}. */
+    private failEntitySubscription(subscriptionKey: string, error: Error): void {
+        const subscription = this.singleSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+
+        if (subscription.subscribeTimeout) clearTimeout(subscription.subscribeTimeout);
+        subscription.subscribeInFlight = false;
+
+        this.singleSubscriptions.delete(subscriptionKey);
+        this.backendToEntityKey.delete(subscription.backendSubscriptionId);
+
+        subscription.callbacks.forEach(callback => {
+            if (callback.onError) {
+                try {
+                    callback.onError(error);
+                } catch (callbackError) {
+                    console.error("Error in row subscription error callback:", callbackError);
+                }
+            }
+        });
+    }
+
+    /**
+     * Stop the watchdogs without failing anything — used when the socket drops,
+     * since the reconnect path re-subscribes everything anyway and a watchdog
+     * firing mid-reconnect would tear down healthy subscriptions.
+     */
+    private suspendSubscribeWatchdogs(): void {
+        for (const sub of this.collectionSubscriptions.values()) {
+            if (sub.subscribeTimeout) clearTimeout(sub.subscribeTimeout);
+            sub.subscribeTimeout = undefined;
+            sub.subscribeInFlight = false;
+        }
+        for (const sub of this.singleSubscriptions.values()) {
+            if (sub.subscribeTimeout) clearTimeout(sub.subscribeTimeout);
+            sub.subscribeTimeout = undefined;
+            sub.subscribeInFlight = false;
+        }
+    }
+
+    /**
+     * Arm watchdogs for subscribes that were requested while offline and have
+     * just been flushed to the socket. Their timers were deliberately not set at
+     * request time, so without this they would have no timeout at all.
+     */
+    private armPendingSubscribeWatchdogs(): void {
+        for (const [key, sub] of this.collectionSubscriptions.entries()) {
+            if (sub.subscribeInFlight && !sub.subscribeTimeout) this.sendCollectionSubscribeWatchdog(key);
+        }
+        for (const [key, sub] of this.singleSubscriptions.entries()) {
+            if (sub.subscribeInFlight && !sub.subscribeTimeout) this.sendEntitySubscribeWatchdog(key);
+        }
+    }
+
+    private sendCollectionSubscribeWatchdog(subscriptionKey: string): void {
+        const subscription = this.collectionSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+        const backendSubscriptionId = subscription.backendSubscriptionId;
+        subscription.subscribeTimeout = setTimeout(() => {
+            const current = this.collectionSubscriptions.get(subscriptionKey);
+            if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+            if (!current.subscribeInFlight) return;
+            this.failCollectionSubscription(
+                subscriptionKey,
+                new RebaseApiError("Subscription timed out", { code: "SUBSCRIPTION_TIMEOUT" })
+            );
+        }, this.subscriptionTimeoutMs);
+    }
+
+    private sendEntitySubscribeWatchdog(subscriptionKey: string): void {
+        const subscription = this.singleSubscriptions.get(subscriptionKey);
+        if (!subscription) return;
+        const backendSubscriptionId = subscription.backendSubscriptionId;
+        subscription.subscribeTimeout = setTimeout(() => {
+            const current = this.singleSubscriptions.get(subscriptionKey);
+            if (!current || current.backendSubscriptionId !== backendSubscriptionId) return;
+            if (!current.subscribeInFlight) return;
+            this.failEntitySubscription(
+                subscriptionKey,
+                new RebaseApiError("Subscription timed out", { code: "SUBSCRIPTION_TIMEOUT" })
+            );
+        }, this.subscriptionTimeoutMs);
+    }
+
+    /**
+     * Fail every subscription that never received data. Called when reconnection
+     * is given up on, so views surface an error instead of spinning forever.
+     */
+    private failAllPendingSubscriptions(error: Error): void {
+        for (const key of [...this.collectionSubscriptions.keys()]) {
+            const sub = this.collectionSubscriptions.get(key);
+            if (sub && !sub.isInitialDataReceived) this.failCollectionSubscription(key, error);
+        }
+        for (const key of [...this.singleSubscriptions.keys()]) {
+            const sub = this.singleSubscriptions.get(key);
+            if (sub && !sub.isInitialDataReceived) this.failEntitySubscription(key, error);
+        }
+    }
+
     /**
      * Re-send all active subscriptions to the backend after a reconnect.
      * The server wipes subscription state when a client disconnects, so
@@ -1273,15 +1716,7 @@ onError });
             this.backendToCollectionKey.delete(oldBackendId);
             this.backendToCollectionKey.set(newBackendId, key);
 
-            this.sendMessage({
-                type: "subscribe_collection",
-                payload: {
-                    ...sub.props,
-                    subscriptionId: newBackendId
-                }
-            }).catch(error => {
-                console.error("[WS] Failed to re-subscribe collection:", key, error);
-            });
+            this.sendCollectionSubscribe(key);
         }
 
         // Re-subscribe row subscriptions
@@ -1293,15 +1728,7 @@ onError });
             this.backendToEntityKey.delete(oldBackendId);
             this.backendToEntityKey.set(newBackendId, key);
 
-            this.sendMessage({
-                type: "subscribe_one",
-                payload: {
-                    ...sub.props,
-                    subscriptionId: newBackendId
-                }
-            }).catch(error => {
-                console.error("[WS] Failed to re-subscribe row:", key, error);
-            });
+            this.sendEntitySubscribe(key);
         }
     }