@rebasepro/client 0.9.0 → 0.9.1-canary.09aaf62

package/src/realtime-channel.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect, beforeEach, afterEach, jest } from "@jest/globals";
+/**
+ * The channel surface, and specifically the two protocol details it exists to
+ * hide: the roster is not pushed on join, and presence expires after 30s.
+ */
+import {
+    RebaseRealtimeChannel,
+    type ChannelTransport,
+    type PresenceState
+} from "./realtime-channel";
+
+/** Stand-in socket that records what was sent and can push frames back. */
+function fakeTransport() {
+    const sent: Record<string, unknown>[] = [];
+    let channelHandler: ((m: Record<string, unknown>) => void) | undefined;
+    let reconnectHandler: (() => void) | undefined;
+
+    const transport: ChannelTransport = {
+        sendMessage: async (message) => { sent.push(message); return undefined; },
+        onChannelMessage: (_channel, handler) => {
+            channelHandler = handler;
+            return () => { channelHandler = undefined; };
+        },
+        onReconnect: (handler) => {
+            reconnectHandler = handler;
+            return () => { reconnectHandler = undefined; };
+        }
+    };
+
+    return {
+        transport,
+        sent,
+        types: () => sent.map((m) => m.type),
+        push: (message: Record<string, unknown>) => channelHandler?.(message),
+        reconnect: () => reconnectHandler?.(),
+        hasChannelHandler: () => channelHandler !== undefined
+    };
+}
+
+describe("RebaseRealtimeChannel", () => {
+    let fake: ReturnType<typeof fakeTransport>;
+    let channel: RebaseRealtimeChannel;
+
+    beforeEach(() => {
+        jest.useFakeTimers();
+        fake = fakeTransport();
+        channel = new RebaseRealtimeChannel("doc:42", fake.transport);
+    });
+
+    afterEach(() => {
+        jest.useRealTimers();
+    });
+
+    describe("joining", () => {
+        it("asks for the roster, because joining does not push it", async () => {
+            // A joining client's presence_diff contains only itself, so
+            // without this request the channel believes it is alone until
+            // somebody else happens to move.
+            await channel.join();
+
+            expect(fake.types()).toEqual(["join_channel", "presence_state"]);
+        });
+
+        it("joins only once across repeated calls", async () => {
+            await channel.join();
+            await channel.join();
+            await channel.broadcast("ping", {});
+
+            expect(fake.types().filter((t) => t === "join_channel")).toHaveLength(1);
+        });
+    });
+
+    describe("presence", () => {
+        it("reports the roster from a presence_state frame", async () => {
+            const seen: PresenceState[] = [];
+            channel.onPresence((state) => seen.push(state));
+            await channel.join();
+
+            fake.push({ type: "presence_state", channel: "doc:42", presences: { a: { name: "Ana" } } });
+
+            expect(seen.at(-1)).toEqual({ a: { name: "Ana" } });
+        });
+
+        it("maintains the roster across diffs so callers never reassemble it", async () => {
+            const seen: PresenceState[] = [];
+            channel.onPresence((state) => seen.push(state));
+            await channel.join();
+
+            fake.push({ type: "presence_state", channel: "doc:42", presences: { a: { name: "Ana" } } });
+            fake.push({ type: "presence_diff", channel: "doc:42", joins: { b: { name: "Bo" } }, leaves: {} });
+
+            expect(seen.at(-1)).toEqual({ a: { name: "Ana" }, b: { name: "Bo" } });
+
+            fake.push({ type: "presence_diff", channel: "doc:42", joins: {}, leaves: { a: { name: "Ana" } } });
+
+            expect(seen.at(-1)).toEqual({ b: { name: "Bo" } });
+        });
+
+        it("passes the diff alongside the full state", async () => {
+            let lastDiff: unknown;
+            channel.onPresence((_state, diff) => { lastDiff = diff; });
+            await channel.join();
+
+            fake.push({ type: "presence_diff", channel: "doc:42", joins: { b: { x: 1 } }, leaves: {} });
+
+            expect(lastDiff).toEqual({ joins: { b: { x: 1 } }, leaves: {} });
+        });
+
+        it("re-sends presence on a timer, because it expires after 30s", async () => {
+            // Server-side PRESENCE_TIMEOUT_MS is 30s. A client that tracks once
+            // and goes quiet vanishes from everyone else's roster while still
+            // sitting in the document.
+            await channel.track({ cursor: 1 });
+            expect(fake.types().filter((t) => t === "presence_track")).toHaveLength(1);
+
+            await jest.advanceTimersByTimeAsync(21_000);
+            expect(fake.types().filter((t) => t === "presence_track")).toHaveLength(2);
+
+            await jest.advanceTimersByTimeAsync(21_000);
+            expect(fake.types().filter((t) => t === "presence_track")).toHaveLength(3);
+        });
+
+        it("heartbeats within the expiry window", async () => {
+            await channel.track({ cursor: 1 });
+            const before = fake.types().filter((t) => t === "presence_track").length;
+
+            // One beat must land comfortably before 30s, and with enough margin
+            // that a single dropped frame is not a disappearance.
+            await jest.advanceTimersByTimeAsync(25_000);
+
+            expect(fake.types().filter((t) => t === "presence_track").length).toBeGreaterThan(before);
+        });
+
+        it("heartbeats the latest state after a re-track", async () => {
+            await channel.track({ cursor: 1 });
+            await channel.track({ cursor: 99 });
+
+            await jest.advanceTimersByTimeAsync(21_000);
+
+            const beats = fake.sent.filter((m) => m.type === "presence_track");
+            expect(beats.at(-1)).toMatchObject({ state: { cursor: 99 } });
+        });
+
+        it("stops the heartbeat on untrack", async () => {
+            await channel.track({ cursor: 1 });
+            await channel.untrack();
+            const after = fake.types().filter((t) => t === "presence_track").length;
+
+            await jest.advanceTimersByTimeAsync(60_000);
+
+            expect(fake.types().filter((t) => t === "presence_track")).toHaveLength(after);
+        });
+    });
+
+    describe("broadcast", () => {
+        it("delivers events to a handler", async () => {
+            const received: unknown[] = [];
+            channel.onBroadcast((e) => received.push(e));
+            await channel.join();
+
+            fake.push({ type: "broadcast", channel: "doc:42", event: "edit", payload: { at: 3 } });
+
+            expect(received).toEqual([{ event: "edit", payload: { at: 3 } }]);
+        });
+
+        it("filters by event name when one is given", async () => {
+            const received: unknown[] = [];
+            channel.onBroadcast("edit", (payload) => received.push(payload));
+            await channel.join();
+
+            fake.push({ type: "broadcast", channel: "doc:42", event: "other", payload: { no: true } });
+            fake.push({ type: "broadcast", channel: "doc:42", event: "edit", payload: { yes: true } });
+
+            expect(received).toEqual([{ yes: true }]);
+        });
+
+        it("stops delivering after the returned unsubscribe", async () => {
+            const received: unknown[] = [];
+            const off = channel.onBroadcast((e) => received.push(e));
+            await channel.join();
+            off();
+
+            fake.push({ type: "broadcast", channel: "doc:42", event: "edit", payload: {} });
+
+            expect(received).toEqual([]);
+        });
+    });
+
+    describe("reconnect", () => {
+        it("re-joins, re-requests the roster and re-tracks", async () => {
+            // A reconnect drops server-side membership and presence. Nothing
+            // else notices: the socket returns and the client just stops
+            // receiving.
+            await channel.track({ cursor: 7 });
+            fake.sent.length = 0;
+
+            fake.reconnect();
+            await jest.advanceTimersByTimeAsync(0);
+
+            expect(fake.types()).toEqual(["join_channel", "presence_state", "presence_track"]);
+            expect(fake.sent.at(-1)).toMatchObject({ state: { cursor: 7 } });
+        });
+
+        it("does not re-track when the client never tracked", async () => {
+            await channel.join();
+            fake.sent.length = 0;
+
+            fake.reconnect();
+            await jest.advanceTimersByTimeAsync(0);
+
+            expect(fake.types()).toEqual(["join_channel", "presence_state"]);
+        });
+    });
+
+    describe("leave", () => {
+        it("releases the socket handler, the timer and the listeners", async () => {
+            const received: unknown[] = [];
+            channel.onBroadcast((e) => received.push(e));
+            await channel.track({ cursor: 1 });
+
+            await channel.leave();
+
+            expect(fake.types().at(-1)).toBe("leave_channel");
+            expect(fake.hasChannelHandler()).toBe(false);
+
+            const beats = fake.types().filter((t) => t === "presence_track").length;
+            await jest.advanceTimersByTimeAsync(60_000);
+            expect(fake.types().filter((t) => t === "presence_track")).toHaveLength(beats);
+        });
+
+        it("can rejoin after leaving", async () => {
+            await channel.join();
+            await channel.leave();
+            fake.sent.length = 0;
+
+            await channel.join();
+
+            expect(fake.types()).toEqual(["join_channel", "presence_state"]);
+        });
+    });
+});

package/src/realtime-channel.ts

@@ -0,0 +1,238 @@
+/**
+ * Broadcast channels and presence, as an SDK surface.
+ *
+ * The realtime engine has supported `join_channel`, `broadcast`,
+ * `presence_track`, `presence_untrack` and `presence_state` for a while, but
+ * the client only recognised those types well enough to send them
+ * fire-and-forget: there were no methods to call and no way to receive channel
+ * or broadcast events, since `on()` handles only connect / disconnect /
+ * reconnect / error. Anything wanting presence therefore opened a *second*
+ * socket and reimplemented the AUTHENTICATE → AUTH_SUCCESS handshake, the
+ * reconnect backoff, and the presence heartbeat — a couple of hundred lines
+ * per app, all of it duplicating this package.
+ *
+ * Two protocol details this hides, because both are easy to get wrong and
+ * neither is discoverable from the message list:
+ *
+ *  - **A joining client is told only about its own join.** The `presence_diff`
+ *    it receives after `presence_track` contains just itself. The existing
+ *    roster arrives only in response to an explicit `presence_state` request,
+ *    so `join()` sends one.
+ *  - **Presence expires after 30s** (`PRESENCE_TIMEOUT_MS` server-side). A
+ *    client that tracks once and goes quiet silently vanishes from everyone
+ *    else's roster while still sitting in the document, so `track()` starts a
+ *    heartbeat and `leave()` stops it.
+ */
+
+/** Presence state keyed by the server's client id. */
+export type PresenceState = Record<string, Record<string, unknown>>;
+
+export interface PresenceDiff {
+    joins: PresenceState;
+    leaves: PresenceState;
+}
+
+export interface BroadcastEvent {
+    event: string;
+    payload: unknown;
+}
+
+/** The socket operations a channel needs; satisfied by RebaseWebSocketClient. */
+export interface ChannelTransport {
+    sendMessage(message: Record<string, unknown>): Promise<unknown>;
+    onChannelMessage(channel: string, handler: (message: Record<string, unknown>) => void): () => void;
+    onReconnect(handler: () => void): () => void;
+}
+
+/**
+ * Re-send presence comfortably inside the server's 30s expiry.
+ *
+ * Two-thirds of the window: one lost heartbeat still leaves time for the next
+ * before the entry is reaped, so a single dropped frame is not a disappearance.
+ */
+const PRESENCE_HEARTBEAT_MS = 20_000;
+
+export class RebaseRealtimeChannel {
+    private presenceHandlers = new Set<(state: PresenceState, diff?: PresenceDiff) => void>();
+    private broadcastHandlers = new Set<(event: BroadcastEvent) => void>();
+    private unsubscribers: (() => void)[] = [];
+
+    /** Last known roster, kept so handlers always get a full picture. */
+    private presences: PresenceState = {};
+    /** What this client last tracked, replayed on reconnect and heartbeat. */
+    private trackedState: Record<string, unknown> | null = null;
+    private heartbeat: ReturnType<typeof setInterval> | null = null;
+    private joined = false;
+
+    constructor(
+        public readonly name: string,
+        private transport: ChannelTransport
+    ) {}
+
+    /**
+     * Join the channel and ask for the current roster.
+     *
+     * Called automatically by `track`, `broadcast`, `onPresence` and
+     * `onBroadcast`; calling it directly is only needed to start receiving
+     * before there is anything to send.
+     */
+    async join(): Promise<void> {
+        if (this.joined) return;
+        this.joined = true;
+
+        this.unsubscribers.push(
+            this.transport.onChannelMessage(this.name, (message) => this.handle(message))
+        );
+
+        // A reconnect drops server-side channel membership and presence, so
+        // both have to be re-established. Nothing else notices this: the
+        // socket comes back, and the client just stops receiving.
+        this.unsubscribers.push(
+            this.transport.onReconnect(() => {
+                void this.rejoin();
+            })
+        );
+
+        await this.transport.sendMessage({ type: "join_channel", channel: this.name });
+        // Not optional. Joining does not push the roster — without this the
+        // channel believes it is alone until somebody else happens to move.
+        await this.transport.sendMessage({ type: "presence_state", channel: this.name });
+    }
+
+    private async rejoin(): Promise<void> {
+        try {
+            await this.transport.sendMessage({ type: "join_channel", channel: this.name });
+            await this.transport.sendMessage({ type: "presence_state", channel: this.name });
+            if (this.trackedState) {
+                await this.transport.sendMessage({
+                    type: "presence_track",
+                    channel: this.name,
+                    state: this.trackedState
+                });
+            }
+        } catch {
+            // The socket is down again; the next reconnect will retry.
+        }
+    }
+
+    /**
+     * Publish this client's presence state, and keep publishing it.
+     *
+     * Calling `track` again replaces the state (and restarts the heartbeat),
+     * which is how you update e.g. a cursor position.
+     */
+    async track(state: Record<string, unknown>): Promise<void> {
+        await this.join();
+        this.trackedState = state;
+
+        await this.transport.sendMessage({ type: "presence_track", channel: this.name, state });
+
+        if (!this.heartbeat) {
+            this.heartbeat = setInterval(() => {
+                if (!this.trackedState) return;
+                void this.transport
+                    .sendMessage({ type: "presence_track", channel: this.name, state: this.trackedState })
+                    .catch(() => { /* a dropped beat is recoverable; the next one carries the same state */ });
+            }, PRESENCE_HEARTBEAT_MS);
+            // Do not hold a Node process open just to say "still here".
+            (this.heartbeat as unknown as { unref?: () => void }).unref?.();
+        }
+    }
+
+    /** Stop publishing presence, without leaving the channel. */
+    async untrack(): Promise<void> {
+        this.stopHeartbeat();
+        this.trackedState = null;
+        if (this.joined) {
+            await this.transport.sendMessage({ type: "presence_untrack", channel: this.name });
+        }
+    }
+
+    /**
+     * Observe the roster. The handler fires immediately with what is already
+     * known, then on every change.
+     */
+    onPresence(handler: (state: PresenceState, diff?: PresenceDiff) => void): () => void {
+        this.presenceHandlers.add(handler);
+        void this.join();
+        if (Object.keys(this.presences).length > 0) handler({ ...this.presences });
+        return () => this.presenceHandlers.delete(handler);
+    }
+
+    /** Send a broadcast. The sender does not receive its own message. */
+    async broadcast(event: string, payload: unknown): Promise<void> {
+        await this.join();
+        await this.transport.sendMessage({ type: "broadcast", channel: this.name, event, payload });
+    }
+
+    /** Observe broadcasts. Pass an event name to filter. */
+    onBroadcast(handler: (event: BroadcastEvent) => void): () => void;
+    onBroadcast(event: string, handler: (payload: unknown) => void): () => void;
+    onBroadcast(
+        eventOrHandler: string | ((event: BroadcastEvent) => void),
+        maybeHandler?: (payload: unknown) => void
+    ): () => void {
+        const wrapped: (event: BroadcastEvent) => void = typeof eventOrHandler === "string"
+            ? (e) => { if (e.event === eventOrHandler) maybeHandler!(e.payload); }
+            : eventOrHandler;
+
+        this.broadcastHandlers.add(wrapped);
+        void this.join();
+        return () => this.broadcastHandlers.delete(wrapped);
+    }
+
+    /** Leave the channel and release every listener and timer. */
+    async leave(): Promise<void> {
+        this.stopHeartbeat();
+        this.trackedState = null;
+        this.presences = {};
+        this.presenceHandlers.clear();
+        this.broadcastHandlers.clear();
+
+        for (const off of this.unsubscribers) off();
+        this.unsubscribers = [];
+
+        if (this.joined) {
+            this.joined = false;
+            await this.transport.sendMessage({ type: "leave_channel", channel: this.name });
+        }
+    }
+
+    private stopHeartbeat(): void {
+        if (this.heartbeat) {
+            clearInterval(this.heartbeat);
+            this.heartbeat = null;
+        }
+    }
+
+    /** Fold an incoming frame into the roster and fan it out. */
+    private handle(message: Record<string, unknown>): void {
+        switch (message.type) {
+            case "presence_state": {
+                this.presences = (message.presences as PresenceState) ?? {};
+                this.emitPresence();
+                break;
+            }
+            case "presence_diff": {
+                const joins = (message.joins as PresenceState) ?? {};
+                const leaves = (message.leaves as PresenceState) ?? {};
+                // A diff carries only what moved, so the roster is maintained
+                // here rather than handed to callers to reassemble.
+                for (const [id, state] of Object.entries(joins)) this.presences[id] = state;
+                for (const id of Object.keys(leaves)) delete this.presences[id];
+                this.emitPresence({ joins, leaves });
+                break;
+            }
+            case "broadcast": {
+                const event = { event: message.event as string, payload: message.payload };
+                for (const handler of this.broadcastHandlers) handler(event);
+                break;
+            }
+        }
+    }
+
+    private emitPresence(diff?: PresenceDiff): void {
+        const snapshot = { ...this.presences };
+        for (const handler of this.presenceHandlers) handler(snapshot, diff);
+    }
+}

package/src/realtime-optout.test.ts

@@ -0,0 +1,119 @@
+import { jest } from "@jest/globals";
+import { createRebaseClient } from "./index";
+
+/**
+ * A WebSocket stand-in that records construction. The real socket keeps the Node
+ * event loop alive, which is what makes a one-shot script hang; here we only
+ * need to know whether one would have been opened at all.
+ */
+function trackingWebSocket() {
+    const opened: string[] = [];
+    const closed: 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() {
+            closed.push(this.url);
+        }
+
+        send() { /* no-op */ }
+    }
+
+    return { FakeWebSocket: FakeWebSocket as unknown as typeof WebSocket, opened, closed };
+}
+
+describe("realtime opt-out", () => {
+    const original = globalThis.WebSocket;
+
+    afterEach(() => {
+        globalThis.WebSocket = original;
+        jest.restoreAllMocks();
+    });
+
+    it("opens the socket by default", () => {
+        const { FakeWebSocket, opened } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+
+        expect(opened).toHaveLength(1);
+    });
+
+    it("opens no socket when realtime is disabled", () => {
+        const { FakeWebSocket, opened } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        const client = createRebaseClient({
+            baseUrl: "http://localhost:3000/api",
+            realtime: false
+        });
+
+        // The socket is what keeps a CLI / cron / ETL process alive past its work.
+        expect(opened).toHaveLength(0);
+        expect(client.ws).toBeUndefined();
+    });
+
+    it("opens no socket when realtime is disabled even if a websocketUrl is given", () => {
+        const { FakeWebSocket, opened } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        createRebaseClient({
+            baseUrl: "http://localhost:3000/api",
+            websocketUrl: "ws://localhost:3000",
+            realtime: false
+        });
+
+        expect(opened).toHaveLength(0);
+    });
+
+    it("close() releases the socket", () => {
+        const { FakeWebSocket, opened, closed } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        const client = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        expect(opened).toHaveLength(1);
+
+        client.close();
+
+        expect(closed).toHaveLength(1);
+    });
+
+    it("close() is safe when realtime was never started, and when called twice", () => {
+        const { FakeWebSocket } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        const offline = createRebaseClient({ baseUrl: "http://localhost:3000/api", realtime: false });
+        expect(() => offline.close()).not.toThrow();
+
+        const live = createRebaseClient({ baseUrl: "http://localhost:3000/api" });
+        live.close();
+        expect(() => live.close()).not.toThrow();
+    });
+
+    it("leaves listen() absent so callers can feature-detect, and says why via the query builder", () => {
+        const { FakeWebSocket } = trackingWebSocket();
+        globalThis.WebSocket = FakeWebSocket;
+
+        const client = createRebaseClient({
+            baseUrl: "http://localhost:3000/api",
+            realtime: false
+        });
+
+        // `listen` stays undefined rather than becoming a throwing stub: the
+        // optional type is what makes `if (client.listen)` work and what makes
+        // TypeScript reject a bare call.
+        expect(client.collection("posts").listen).toBeUndefined();
+        expect(() => client.data.posts.include("author").listen(() => { /* noop */ }))
+            .toThrow(/realtime: false/);
+    });
+});