@rebasepro/client 0.13.0 → 0.13.1-canary.g3660bd5

package/src/index.ts

@@ -238,35 +238,48 @@ export type CreateRebaseClientResult<DB = Record<string, unknown>> = Omit<Rebase
 /**
  * Derive a WebSocket URL from an HTTP base URL.
  * `http://` → `ws://`, `https://` → `wss://`.
+ *
+ * A backend mounted under a path is the reason `baseUrl` accepts one, so the
+ * path is kept. It used to be kept for an absolute `baseUrl` and dropped for a
+ * relative one — resolved through `.origin` — so one deployment dialled two
+ * different sockets depending on whether its config said `"/backend"` or
+ * `"https://app.example.com/backend"`.
+ *
+ * Returns `""` when there is nothing to resolve against: a relative `baseUrl`
+ * outside a browser has no origin, and inventing one would dial somewhere
+ * arbitrary. The caller warns rather than leaving that silent.
  */
 function deriveWebSocketUrl(baseUrl?: string): string {
+    const toWsProtocol = (url: string): string => {
+        const secure = /^(https|wss):/i.test(url);
+        return url
+            .replace(/^https?:\/\//i, secure ? "wss://" : "ws://")
+            .replace(/^wss?:\/\//i, secure ? "wss://" : "ws://")
+            .replace(/\/$/, "");
+    };
+
     if (typeof window !== "undefined") {
-        let absoluteUrl = "";
+        let absoluteUrl: string;
         if (!baseUrl) {
             absoluteUrl = window.location.origin;
         } else if (/^https?:\/\//i.test(baseUrl) || /^wss?:\/\//i.test(baseUrl)) {
             absoluteUrl = baseUrl;
         } else {
             try {
-                absoluteUrl = new URL(baseUrl, window.location.href).origin;
+                const resolved = new URL(baseUrl, window.location.href);
+                absoluteUrl = resolved.origin + resolved.pathname;
             } catch {
                 absoluteUrl = window.location.origin;
             }
         }
-        const protocol = absoluteUrl.startsWith("https:") || absoluteUrl.startsWith("wss:") ? "wss:" : "ws:";
-        return absoluteUrl
-            .replace(/^https?:\/\//i, `${protocol}//`)
-            .replace(/^wss?:\/\//i, `${protocol}//`)
-            .replace(/\/$/, "");
+        return toWsProtocol(absoluteUrl);
     }
 
     if (!baseUrl) return "";
     if (!/^https?:\/\//i.test(baseUrl) && !/^wss?:\/\//i.test(baseUrl)) {
         return "";
     }
-    return baseUrl
-        .replace(/^https?:\/\//i, (match) => match.toLowerCase() === "https://" ? "wss://" : "ws://")
-        .replace(/\/$/, "");
+    return toWsProtocol(baseUrl);
 }
 
 export function createRebaseClient<DB = Record<string, unknown>>(options: CreateRebaseClientOptions): CreateRebaseClientResult<DB> {
@@ -332,6 +345,24 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
         ? (options.websocketUrl ?? deriveWebSocketUrl(options.baseUrl))
         : undefined;
 
+    // Realtime is on unless it was switched off, so "on, but no URL could be
+    // derived" is a misconfiguration and not a choice. It used to be silent:
+    // the client simply had no socket, `observe()` quietly degraded to a
+    // one-shot fetch, and `realtime.channel()` blamed `realtime: false` — an
+    // option the caller had not passed.
+    const realtimeUnreachable = realtimeEnabled && !resolvedWsUrl;
+    const unreachableReason =
+        "no WebSocket URL could be derived from baseUrl " +
+        `${JSON.stringify(options.baseUrl ?? null)} — outside a browser there is no page origin ` +
+        "to resolve a relative URL against. Pass an absolute `baseUrl`, set `websocketUrl` " +
+        "explicitly, or pass `realtime: false` to say this was intended.";
+    if (realtimeUnreachable) {
+        console.warn(
+            `[Rebase] Realtime is enabled but ${unreachableReason} ` +
+            "Live queries will fall back to a single fetch and channels will throw."
+        );
+    }
+
     let ws: RebaseWebSocketClient | undefined;
     /** One channel object per name — see `realtime.channel`. */
     const realtimeChannels = new Map<string, RebaseRealtimeChannel>();
@@ -529,13 +560,15 @@ export function createRebaseClient<DB = Record<string, unknown>>(options: Create
              * cut off the others.
              */
             channel: (name: string, options?: ChannelOptions): RebaseRealtimeChannel => {
-                // Only `realtime: false` gets here — a hard opt-out, so this
-                // stays an error. Being merely *unconnected* does not: the
-                // socket opens on the first channel operation, which is the
-                // whole point of asking for a channel before you use one.
+                // Being merely *unconnected* is not an error: the socket opens
+                // on the first channel operation, which is the whole point of
+                // asking for a channel before you use one. Having no socket at
+                // all is, and there are two reasons for it — say which.
                 if (!ws) {
                     throw new RebaseClientError(
-                        "Realtime is disabled on this client (realtime: false), so channels are unavailable."
+                        realtimeUnreachable
+                            ? `Realtime is enabled but ${unreachableReason}`
+                            : "Realtime is disabled on this client (realtime: false), so channels are unavailable."
                     );
                 }
                 let existing = realtimeChannels.get(name);

package/src/offline-query.test.ts

@@ -10,7 +10,8 @@ import {
     runLocalQuery,
     sortRows
 } from "./offline-query";
-import { EntityRelation } from "@rebasepro/types";
+import { DEFAULT_LIST_LIMIT, EntityRelation } from "@rebasepro/types";
+import { resolveFindWindow } from "@rebasepro/common";
 import type { FindParams } from "./transport";
 
 type Row = Record<string, unknown>;
@@ -172,12 +173,37 @@ describe("local query engine", () => {
 
     describe("pagination", () => {
         it("resolves page over offset the way the server does", () => {
-            expect(resolvePagination()).toEqual({ limit: 20, offset: 0 });
             expect(resolvePagination({ limit: 10, offset: 30 })).toEqual({ limit: 10, offset: 30 });
             expect(resolvePagination({ limit: 10, page: 3 })).toEqual({ limit: 10, offset: 20 });
             // `page` wins over `offset`, and the first page is not negative.
             expect(resolvePagination({ limit: 10, page: 1, offset: 99 })).toEqual({ limit: 10, offset: 0 });
         });
+
+        it("defaults to the same page size the server would apply", () => {
+            // Asserted against the constant, not against a number written here.
+            // This test used to say `{ limit: 20 }` — restating a default this
+            // module had invented, while `/api/data` paged by 50. The local
+            // answer and the network answer to one `observe()` were therefore
+            // different lengths, and the test agreed with the wrong one.
+            expect(resolvePagination()).toEqual({ limit: DEFAULT_LIST_LIMIT, offset: 0 });
+        });
+
+        it("agrees with the shared resolver on every shape of window", () => {
+            // The one that matters: the local evaluator and every other
+            // transport must resolve identical windows, or a cached list and a
+            // fetched list disagree about which rows page two holds.
+            for (const params of [
+                undefined,
+                { limit: 10 },
+                { offset: 30 },
+                { page: 4 },
+                { limit: 25, page: 2 },
+                { limit: 10, page: 1, offset: 99 }
+            ]) {
+                const { limit, offset } = resolveFindWindow(params);
+                expect(resolvePagination(params)).toEqual({ limit, offset });
+            }
+        });
     });
 
     describe("runLocalQuery", () => {

package/src/offline-query.ts

@@ -9,6 +9,7 @@ import {
     toCanonicalOp
 } from "@rebasepro/types";
 import { FindParams } from "./transport";
+import { resolveFindWindow } from "@rebasepro/common";
 
 /**
  * A local evaluator for `FindParams`, so cached rows can answer a query the
@@ -38,8 +39,15 @@ const collator = typeof Intl !== "undefined" && typeof Intl.Collator === "functi
     ? new Intl.Collator(undefined, { numeric: false, sensitivity: "variant" })
     : undefined;
 
-/** The server's page size when the caller does not ask for one. */
-export const DEFAULT_PAGE_SIZE = 20;
+/**
+ * The server's page size when the caller does not ask for one.
+ *
+ * Re-exported rather than redeclared. This was its own `= 20` — a third
+ * constant of this name in the workspace, next to `@rebasepro/common`'s 200 and
+ * the 50 the REST layer actually applies — and a local copy of a number that
+ * belongs to another process is a number that goes stale silently.
+ */
+export { DEFAULT_LIST_LIMIT as DEFAULT_PAGE_SIZE } from "@rebasepro/types";
 
 function isNullish(value: unknown): boolean {
     return value === null || value === undefined;
@@ -311,12 +319,17 @@ function tiebreak(a: Record<string, unknown>, b: Record<string, unknown>): numbe
     return cmp ?? 0;
 }
 
-/** Resolve `page`/`offset`/`limit` the way the server does. */
+/**
+ * Resolve `page`/`offset`/`limit` the way the server does.
+ *
+ * It did not: this defaulted an absent limit to 20 while `/api/data` pages by
+ * 50, so the same `observe()` answered with 20 rows from the local database and
+ * 50 from the network — a list that changed length depending on which side
+ * answered, with `page` striding differently on each. Delegated now, so the
+ * sentence above is true by construction rather than by agreement.
+ */
 export function resolvePagination(params?: FindParams): { limit: number; offset: number } {
-    const limit = params?.limit ?? DEFAULT_PAGE_SIZE;
-    const offset = params?.page != null
-        ? Math.max(0, (params.page - 1) * limit)
-        : (params?.offset ?? 0);
+    const { limit, offset } = resolveFindWindow(params);
     return { limit, offset };
 }
 

package/src/offline.ts

@@ -15,6 +15,7 @@ import {
 import {
     isExactlyEvaluable,
     matchesParams,
+    resolvePagination,
     runLocalQuery,
     sortRows
 } from "./offline-query";
@@ -942,7 +943,7 @@ export class OfflineManager {
         if (!state) {
             return {
                 data: [],
-                meta: { total: 0, limit: params?.limit ?? 20, offset: params?.offset ?? 0, hasMore: false },
+                meta: { ...resolvePagination(params), total: 0, hasMore: false },
                 fromCache: true,
                 hasPendingWrites: false,
                 partial: true
@@ -1150,12 +1151,13 @@ export class OfflineManager {
     }
 
     private recordSnapshot(slug: string, params: FindParams | undefined, result: FindResult<AnyRow>): QuerySnapshot {
-        const meta = result.meta ?? { total: result.data?.length ?? 0, limit: 20, offset: 0, hasMore: false };
+        const window = resolvePagination(params);
+        const meta = result.meta ?? { total: result.data?.length ?? 0, ...window, hasMore: false };
         const snapshot: QuerySnapshot = {
             ids: (result.data ?? []).map((row) => row.id as string | number).filter((id) => id !== undefined),
             total: meta.total ?? result.data?.length ?? 0,
-            limit: meta.limit ?? params?.limit ?? 20,
-            offset: meta.offset ?? params?.offset ?? 0,
+            limit: meta.limit ?? window.limit,
+            offset: meta.offset ?? window.offset,
             hasMore: meta.hasMore ?? false
         };
         const state = this.collectionState(slug);

package/src/realtime-optout.test.ts

@@ -50,7 +50,7 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket, opened } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        createRebaseClient({ baseUrl: "http://localhost:3000" });
 
         expect(opened).toHaveLength(0);
     });
@@ -59,7 +59,7 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket, opened } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
 
         // Asking for the channel is not using it.
         const channel = client.realtime.channel("doc:1");
@@ -73,7 +73,7 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket, opened } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
         expect(opened).toHaveLength(0);
 
         client.collection("posts").listen!(undefined, () => { /* noop */ });
@@ -85,7 +85,7 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket, opened } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
 
         client.collection("posts").listen!(undefined, () => { /* noop */ });
         client.collection("authors").listen!(undefined, () => { /* noop */ });
@@ -102,7 +102,7 @@ describe("realtime opt-out", () => {
         const warn = jest.spyOn(console, "warn").mockImplementation(() => { /* capture */ });
         const debug = jest.spyOn(console, "debug").mockImplementation(() => { /* capture */ });
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
         void client.realtime.channel("doc:1"); // obtained, never used
 
         expect(opened).toHaveLength(0);
@@ -118,7 +118,7 @@ describe("realtime opt-out", () => {
         delete globalThis.WebSocket;
         const warn = jest.spyOn(console, "warn").mockImplementation(() => { /* capture */ });
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
         expect(warn).not.toHaveBeenCalled();
 
         void client.realtime.channel("doc:1").join();
@@ -134,7 +134,7 @@ describe("realtime opt-out", () => {
         globalThis.WebSocket = FakeWebSocket;
 
         const client = createRebaseClient({
-            baseUrl: "http://localhost:3000/api",
+            baseUrl: "http://localhost:3000",
             realtime: false
         });
 
@@ -148,7 +148,7 @@ describe("realtime opt-out", () => {
         globalThis.WebSocket = FakeWebSocket;
 
         createRebaseClient({
-            baseUrl: "http://localhost:3000/api",
+            baseUrl: "http://localhost:3000",
             websocketUrl: "ws://localhost:3000",
             realtime: false
         });
@@ -160,7 +160,7 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket, opened, closed } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
         client.collection("posts").listen!(undefined, () => { /* noop */ });
         expect(opened).toHaveLength(1);
 
@@ -176,7 +176,7 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket, opened } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000" });
         client.collection("posts").listen!(undefined, () => { /* noop */ });
         expect(opened).toHaveLength(1);
 
@@ -190,10 +190,10 @@ describe("realtime opt-out", () => {
         const { FakeWebSocket } = trackingWebSocket();
         globalThis.WebSocket = FakeWebSocket;
 
-        const offline = createRebaseClient({ baseUrl: "http://localhost:3000/api", realtime: false });
+        const offline = createRebaseClient({ baseUrl: "http://localhost:3000", realtime: false });
         expect(() => offline.close()).not.toThrow();
 
-        const live = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        const live = createRebaseClient({ baseUrl: "http://localhost:3000" });
         live.close();
         expect(() => live.close()).not.toThrow();
     });
@@ -205,7 +205,7 @@ describe("realtime opt-out", () => {
         globalThis.WebSocket = FakeWebSocket;
 
         const client = createRebaseClient({
-            baseUrl: "http://localhost:3000/api",
+            baseUrl: "http://localhost:3000",
             realtime: false
         });
 
@@ -244,7 +244,7 @@ isAnonymous: false }
         })) as unknown as typeof globalThis.fetch;
 
         const client = createRebaseClient({
-            baseUrl: "http://localhost:3000/api",
+            baseUrl: "http://localhost:3000",
             fetch: fetchMock
         });
 
@@ -265,7 +265,7 @@ isAnonymous: false }
         globalThis.WebSocket = FakeWebSocket;
 
         const client = createRebaseClient({
-            baseUrl: "http://localhost:3000/api",
+            baseUrl: "http://localhost:3000",
             realtime: false
         });
 

package/src/realtime-subscription-key.test.ts

@@ -0,0 +1,92 @@
+import { jest } from "@jest/globals";
+import { RebaseWebSocketClient } from "./websocket";
+import { or, cond } from "@rebasepro/common";
+
+/**
+ * Two subscriptions are the same subscription only when they ask for the same
+ * rows. The key that decides this was built from a hand-listed subset of the
+ * props, so any field left off it made two different queries collide — and the
+ * second listener was handed the first one's rows, which is worse than not
+ * subscribing at all.
+ */
+
+function fakeSocket() {
+    const sent: Record<string, unknown>[] = [];
+
+    class FakeWS {
+        static readonly OPEN = 1;
+        readyState = 1;
+        onopen: (() => void) | null = null;
+        onclose: (() => void) | null = null;
+        onerror: (() => void) | null = null;
+        onmessage: ((event: { data: string }) => void) | null = null;
+
+        constructor(public url: string) {
+            setTimeout(() => this.onopen?.(), 0);
+        }
+
+        send(raw: string) {
+            const message = JSON.parse(raw) as Record<string, unknown>;
+            sent.push(message);
+            if (message.type === "AUTHENTICATE") {
+                setTimeout(() => this.onmessage?.({
+                    data: JSON.stringify({ type: "AUTH_SUCCESS", requestId: message.requestId })
+                }), 0);
+            }
+        }
+
+        close() { /* noop */ }
+    }
+
+    return { FakeWS: FakeWS as unknown as typeof WebSocket, sent };
+}
+
+function subscribeFrames(sent: Record<string, unknown>[]) {
+    return sent.filter((m) => m.type === "subscribe_collection");
+}
+
+describe("collection subscription identity", () => {
+    beforeEach(() => jest.useFakeTimers());
+    afterEach(() => jest.useRealTimers());
+
+    async function twoSubscriptions(
+        a: Record<string, unknown>,
+        b: Record<string, unknown>
+    ) {
+        const { FakeWS, sent } = fakeSocket();
+        const client = new RebaseWebSocketClient({
+            websocketUrl: "ws://localhost:1234",
+            WebSocket: FakeWS,
+            getAuthToken: async () => "token"
+        });
+        client.listenCollection({ path: "posts", ...a } as never, () => {});
+        client.listenCollection({ path: "posts", ...b } as never, () => {});
+        await jest.advanceTimersByTimeAsync(50);
+        return subscribeFrames(sent);
+    }
+
+    it("treats different offsets as different subscriptions", async () => {
+        // Page one and page two of the same live list. Sharing a subscription
+        // here shows page one's rows on page two.
+        const frames = await twoSubscriptions({ limit: 10, offset: 0 }, { limit: 10, offset: 10 });
+        expect(frames).toHaveLength(2);
+    });
+
+    it("treats different logical groups as different subscriptions", async () => {
+        const frames = await twoSubscriptions(
+            { logical: or(cond("status", "==", "draft")) },
+            { logical: or(cond("status", "==", "published")) }
+        );
+        expect(frames).toHaveLength(2);
+    });
+
+    it("still shares one subscription for genuinely identical queries", async () => {
+        // The de-duplication itself is the point of the key: two components
+        // watching the same list must not open two server subscriptions.
+        const frames = await twoSubscriptions(
+            { limit: 10, offset: 10, logical: or(cond("status", "==", "draft")) },
+            { limit: 10, offset: 10, logical: or(cond("status", "==", "draft")) }
+        );
+        expect(frames).toHaveLength(1);
+    });
+});

package/src/transport-baseurl.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, afterEach } from "@jest/globals";
+import { describe, it, expect, afterEach, jest } from "@jest/globals";
 import { createTransport } from "./transport";
 
 /**
@@ -51,3 +51,51 @@ describe("transport baseUrl resolution", () => {
         expect(createTransport({}).baseUrl).toBe("");
     });
 });
+
+describe("baseUrl that already contains the apiPath", () => {
+    /**
+     * The docblock on `baseUrl` says this "silently builds `/api/api/…` and
+     * every request 404s" — a failure mode understood well enough to be written
+     * down, and still left to be discovered at runtime. This package's own
+     * tests configured it that way a dozen times over, which is about as clear
+     * a signal as a trap gets.
+     */
+    it("warns rather than silently building /api/api", () => {
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+        createTransport({ baseUrl: "http://localhost:3000/api" });
+
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("/api/api"));
+        warn.mockRestore();
+    });
+
+    it("warns for a custom apiPath too, and tolerates a trailing slash", () => {
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+        createTransport({ baseUrl: "https://api.example.com/v2/", apiPath: "/v2" });
+
+        expect(warn).toHaveBeenCalledTimes(1);
+        warn.mockRestore();
+    });
+
+    it("says nothing about a baseUrl that merely ends in a similar word", () => {
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+        createTransport({ baseUrl: "https://rapid.example.com" });
+        createTransport({ baseUrl: "https://example.com/myapi" });
+        createTransport({ baseUrl: "https://example.com" });
+
+        expect(warn).not.toHaveBeenCalled();
+        warn.mockRestore();
+    });
+});
+
+describe("storageUrlOrigin that already contains the apiPath", () => {
+    it("warns, because storage composes it the same way baseUrl is composed", () => {
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+        createTransport({
+            baseUrl: "https://example.com",
+            storageUrlOrigin: "https://files.example.com/api"
+        });
+
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("storageUrlOrigin"));
+        warn.mockRestore();
+    });
+});

package/src/transport.ts

@@ -259,6 +259,28 @@ function resolveBaseUrl(configured?: string): string {
 export function createTransport(config: RebaseClientConfig, environment?: TransportEnvironment): Transport {
     const fetchFn = config.fetch || globalThis.fetch;
     const apiPath = config.apiPath || "/api";
+
+    // `apiPath` is appended to `baseUrl`, so a `baseUrl` that already ends in it
+    // builds `/api/api/…` and every request 404s. That was documented on
+    // `baseUrl` and left to be discovered at runtime — including by this
+    // package's own tests, which configured it that way a dozen times. A 404 on
+    // every call looks like a server that is down, not like a doubled path.
+    // `storageUrlOrigin` is checked alongside it because `storage.ts` composes
+    // it the same way — `${storageUrlOrigin ?? baseUrl}${apiPath}` — and its own
+    // docblock carries the same "no path" caveat.
+    for (const field of ["baseUrl", "storageUrlOrigin"] as const) {
+        const value = config[field];
+        if (!value || !apiPath) continue;
+        const trimmed = value.replace(/\/+$/, "");
+        if (!trimmed.endsWith(apiPath)) continue;
+        console.warn(
+            `[Rebase] ${field} ${JSON.stringify(value)} already ends with the API path ` +
+            `${JSON.stringify(apiPath)}, which is appended to it — requests will go to ` +
+            `${trimmed}${apiPath}/… and 404. Pass the origin only ` +
+            `(${JSON.stringify(trimmed.slice(0, trimmed.length - apiPath.length) || "/")}), or set ` +
+            "`apiPath` if the server really does mount the API one level deeper."
+        );
+    }
     let token = config.token;
     let tokenGetter: (() => Promise<string | null>) | undefined;
     let onUnauthorizedHandler = config.onUnauthorized;

package/src/websocket-url.test.ts

@@ -0,0 +1,97 @@
+import { jest } from "@jest/globals";
+import { createRebaseClient } from "./index";
+
+/**
+ * Where the realtime socket dials, given a `baseUrl`.
+ *
+ * The socket URL is derived rather than configured, so every disagreement
+ * between how it is derived and where the API actually lives shows up only as
+ * realtime not working — never as an error naming a cause.
+ */
+
+function setWindow(origin: string | undefined) {
+    if (origin === undefined) {
+        delete (globalThis as never as { window?: unknown }).window;
+        return;
+    }
+    (globalThis as never as { window: unknown }).window = {
+        location: { origin, href: origin + "/" }
+    };
+}
+
+function trackingWebSocket() {
+    const opened: string[] = [];
+    class FakeWebSocket {
+        static readonly OPEN = 1;
+        readyState = 0;
+        onopen: (() => void) | null = null;
+        onclose: (() => void) | null = null;
+        onerror: (() => void) | null = null;
+        onmessage: (() => void) | null = null;
+        constructor(public url: string) { opened.push(url); }
+        close() { /* no-op */ }
+        send() { /* no-op */ }
+    }
+    return { FakeWebSocket: FakeWebSocket as unknown as typeof WebSocket, opened };
+}
+
+describe("realtime socket URL", () => {
+    const originalWebSocket = globalThis.WebSocket;
+
+    afterEach(() => {
+        globalThis.WebSocket = originalWebSocket;
+        setWindow(undefined);
+        jest.restoreAllMocks();
+    });
+
+    it("keeps the path of a relative baseUrl, as it does for an absolute one", () => {
+        // A backend mounted under a path is the reason `baseUrl` accepts one.
+        // Resolving the relative form to `.origin` dropped it, so the same
+        // deployment dialled two different URLs depending on whether its
+        // baseUrl was written as "/backend" or "https://app.example.com/backend".
+        const { FakeWebSocket, opened } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+        setWindow("https://app.example.com");
+
+        const relative = createRebaseClient({ baseUrl: "/backend" });
+        relative.collection("posts").listen!(undefined, () => {});
+
+        const absolute = createRebaseClient({ baseUrl: "https://app.example.com/backend" });
+        absolute.collection("posts").listen!(undefined, () => {});
+
+        expect(opened[0]).toBe("wss://app.example.com/backend");
+        expect(opened[0]).toBe(opened[1]);
+    });
+
+    it("dials the page origin when no baseUrl is set in a browser", () => {
+        const { FakeWebSocket, opened } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+        setWindow("https://app.example.com");
+
+        const client = createRebaseClient({});
+        client.collection("posts").listen!(undefined, () => {});
+
+        expect(opened[0]).toBe("wss://app.example.com");
+    });
+
+    it("says why realtime is unavailable when no URL could be derived", () => {
+        // Node, with a relative baseUrl there is nothing to resolve against.
+        // The client silently had no socket, and `realtime.channel()` then
+        // blamed `realtime: false` — an option the caller never passed.
+        setWindow(undefined);
+        const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+        const client = createRebaseClient({ baseUrl: "/backend" });
+
+        expect(client.ws).toBeUndefined();
+        expect(warn).toHaveBeenCalledWith(expect.stringContaining("websocketUrl"));
+        expect(() => client.realtime.channel("room")).toThrow(/no WebSocket URL could be derived/i);
+        // It may still *suggest* `realtime: false` as the way to make this
+        // deliberate; what it must not do is claim that is what happened.
+        expect(() => client.realtime.channel("room")).not.toThrow(/disabled on this client/);
+    });
+
+    it("still blames the opt-out when realtime really was switched off", () => {
+        const client = createRebaseClient({ baseUrl: "https://api.example.com", realtime: false });
+        expect(() => client.realtime.channel("room")).toThrow(/realtime: false/);
+    });
+});