@rebasepro/client 0.9.1-canary.ff338b5 → 0.10.0

package/src/realtime-channel.ts

@@ -35,6 +35,61 @@ export interface PresenceDiff {
 export interface BroadcastEvent {
     event: string;
     payload: unknown;
+    /**
+     * Per-channel sequence number, present only on retained channels.
+     *
+     * Monotonically increasing and dense, so a consumer that remembers the last
+     * one it applied can tell the server exactly where to resume from.
+     */
+    seq?: number;
+    /**
+     * True when this arrived through catch-up rather than live.
+     *
+     * Handlers do not have to care — replayed messages are delivered to the
+     * same `onBroadcast` handlers, in sequence order, so an operation stream
+     * needs no second code path. It is exposed for consumers that want to,
+     * for example, skip an animation while fast-forwarding.
+     */
+    replayed?: boolean;
+}
+
+/** One retained message, as returned by {@link RebaseRealtimeChannel.history}. */
+export interface ChannelHistoryEntry {
+    seq: number;
+    event: string;
+    payload: unknown;
+    senderId?: string;
+    at?: string;
+}
+
+/** The answer to a catch-up request. */
+export interface ChannelHistoryResult {
+    messages: ChannelHistoryEntry[];
+    /**
+     * Whether the server retains anything for this channel.
+     *
+     * False means there is no retention rule configured for it, so the empty
+     * list means "never keeps history" rather than "you missed nothing" — a
+     * client that needs to converge has to fall back to a full resync.
+     */
+    retained: boolean;
+    /** Highest sequence the server holds, even if this batch was capped. */
+    latestSeq?: number;
+}
+
+/** Options for a channel handle. */
+export interface ChannelOptions {
+    /**
+     * Ask the server to replay what this client missed, on join and on every
+     * reconnect.
+     *
+     * Only meaningful for a channel the *server* has a retention rule for —
+     * retention is configured on the backend, since a channel is created by
+     * whoever names it and a client-chosen history depth would let any visitor
+     * commit the backend to unbounded storage. On a channel with no rule the
+     * server answers `retained: false` and this is inert.
+     */
+    history?: boolean;
 }
 
 /** The socket operations a channel needs; satisfied by RebaseWebSocketClient. */
@@ -52,6 +107,15 @@ export interface ChannelTransport {
  */
 const PRESENCE_HEARTBEAT_MS = 20_000;
 
+/**
+ * How long live messages are held back waiting for a catch-up response.
+ *
+ * Short, because the cost of waiting is visible — on a collaborative document
+ * this is a stall in everyone else's edits appearing. Long enough that a slow
+ * replay of a busy channel is not abandoned needlessly.
+ */
+const CATCH_UP_TIMEOUT_MS = 10_000;
+
 export class RebaseRealtimeChannel {
     private presenceHandlers = new Set<(state: PresenceState, diff?: PresenceDiff) => void>();
     private broadcastHandlers = new Set<(event: BroadcastEvent) => void>();
@@ -64,10 +128,72 @@ export class RebaseRealtimeChannel {
     private heartbeat: ReturnType<typeof setInterval> | null = null;
     private joined = false;
 
+    /** Whether this handle asks the server to replay missed messages. */
+    private wantsHistory: boolean;
+
+    /**
+     * Highest sequence number delivered to handlers so far.
+     *
+     * This is the resume point sent as `sinceSeq`, and the watermark that makes
+     * replay idempotent: catch-up ranges overlap with what arrived live, and
+     * anything at or below this has already been seen.
+     */
+    private lastSeq = 0;
+
+    /**
+     * Live messages that arrived while a catch-up was in flight.
+     *
+     * Without this they would be delivered ahead of the older messages being
+     * fetched, and — worse — would advance {@link lastSeq} past them, so the
+     * catch-up response would then be discarded as already-seen and those
+     * messages would be lost for good. Held here and flushed, in order, once
+     * the replay lands.
+     */
+    private pendingLive: BroadcastEvent[] = [];
+    private catchUpInFlight = false;
+
+    /**
+     * Deadline for a catch-up response.
+     *
+     * Buffering live messages is only safe because the wait is bounded. A
+     * catch-up frame that never arrives — a server that dropped it, a socket
+     * that died between request and reply — would otherwise leave the channel
+     * silently holding every subsequent edit forever, which is a worse failure
+     * than the one replay was added to fix.
+     */
+    private catchUpTimeout: ReturnType<typeof setTimeout> | null = null;
+
+    /**
+     * Callers of {@link history} awaiting the next `channel_history` frame.
+     *
+     * These frames are addressed by channel rather than by request id, so they
+     * are matched in arrival order. Requests on one channel are serialized by
+     * the socket, so FIFO is the right correlation here.
+     */
+    private historyWaiters: Array<(result: ChannelHistoryResult) => void> = [];
+
     constructor(
         public readonly name: string,
-        private transport: ChannelTransport
-    ) {}
+        private transport: ChannelTransport,
+        options: ChannelOptions = {}
+    ) {
+        this.wantsHistory = options.history ?? false;
+    }
+
+    /**
+     * Turn on catch-up for a handle that was created without it.
+     *
+     * The client hands back the same channel object for a given name, so a
+     * later `channel(name, { history: true })` has no new object to configure —
+     * it upgrades this one instead. Idempotent, and never downgrades: one
+     * caller asking for history must not be switched off by another that did
+     * not ask.
+     */
+    enableHistory(): void {
+        if (this.wantsHistory) return;
+        this.wantsHistory = true;
+        if (this.joined) void this.requestHistory();
+    }
 
     /**
      * Join the channel and ask for the current roster.
@@ -113,6 +239,7 @@ export class RebaseRealtimeChannel {
         // Not optional. Joining does not push the roster — without this the
         // channel believes it is alone until somebody else happens to move.
         await this.send("presence_state");
+        if (this.wantsHistory) await this.requestHistory();
     }
 
     private async rejoin(): Promise<void> {
@@ -122,11 +249,61 @@ export class RebaseRealtimeChannel {
             if (this.trackedState) {
                 await this.send("presence_track", { state: this.trackedState });
             }
+            // The reason this class tracks a sequence number at all: whatever
+            // was broadcast while the socket was down was delivered to everyone
+            // else and never to us. Asking from `lastSeq` is the difference
+            // between resuming and resyncing the whole document.
+            if (this.wantsHistory) await this.requestHistory();
         } catch {
             // The socket is down again; the next reconnect will retry.
         }
     }
 
+    /**
+     * Ask the server for everything after {@link lastSeq}.
+     *
+     * Live messages are buffered from here until the answer arrives — see
+     * {@link pendingLive}.
+     */
+    private async requestHistory(limit?: number): Promise<void> {
+        this.catchUpInFlight = true;
+
+        if (this.catchUpTimeout) clearTimeout(this.catchUpTimeout);
+        this.catchUpTimeout = setTimeout(() => this.abandonCatchUp(), CATCH_UP_TIMEOUT_MS);
+        (this.catchUpTimeout as unknown as { unref?: () => void }).unref?.();
+
+        try {
+            await this.send("channel_history", {
+                sinceSeq: this.lastSeq,
+                ...(limit !== undefined ? { limit } : {})
+            });
+        } catch {
+            // The frame never went out, so nothing will answer it.
+            this.abandonCatchUp();
+        }
+    }
+
+    /**
+     * Give up waiting for a catch-up and release what was held back.
+     *
+     * The buffered messages are still the freshest thing this client has, so
+     * they are delivered rather than dropped. Callers of {@link history} are
+     * answered with `retained: false` — accurate in the sense that matters:
+     * this client has no history to work from and has to resync.
+     */
+    private abandonCatchUp(): void {
+        if (this.catchUpTimeout) {
+            clearTimeout(this.catchUpTimeout);
+            this.catchUpTimeout = null;
+        }
+        if (!this.catchUpInFlight) return;
+        this.catchUpInFlight = false;
+        for (const resolve of this.historyWaiters.splice(0)) {
+            resolve({ messages: [], retained: false });
+        }
+        this.flushPendingLive();
+    }
+
     /**
      * Publish this client's presence state, and keep publishing it.
      *
@@ -192,6 +369,37 @@ export class RebaseRealtimeChannel {
         return () => this.broadcastHandlers.delete(wrapped);
     }
 
+    /**
+     * The last sequence number this channel has delivered.
+     *
+     * Zero on a channel that retains nothing. Persist it if you want catch-up
+     * to survive a page reload as well as a reconnect, and pass it back via
+     * {@link history}.
+     */
+    get sequence(): number {
+        return this.lastSeq;
+    }
+
+    /**
+     * Fetch retained messages explicitly, instead of waiting for join or
+     * reconnect to do it.
+     *
+     * Defaults to resuming from {@link sequence}. Messages are delivered to
+     * `onBroadcast` handlers as usual — the returned value is for callers that
+     * want to inspect the batch, or to learn from `retained` that the channel
+     * keeps no history at all.
+     */
+    async history(options: { sinceSeq?: number; limit?: number } = {}): Promise<ChannelHistoryResult> {
+        await this.join();
+        if (options.sinceSeq !== undefined) this.lastSeq = options.sinceSeq;
+
+        const result = new Promise<ChannelHistoryResult>((resolve) => {
+            this.historyWaiters.push(resolve);
+        });
+        await this.requestHistory(options.limit);
+        return result;
+    }
+
     /** Leave the channel and release every listener and timer. */
     async leave(): Promise<void> {
         this.stopHeartbeat();
@@ -199,6 +407,18 @@ export class RebaseRealtimeChannel {
         this.presences = {};
         this.presenceHandlers.clear();
         this.broadcastHandlers.clear();
+        // A rejoin is a fresh start: replaying from a watermark left over from
+        // the previous membership would silently skip everything before it.
+        this.lastSeq = 0;
+        this.pendingLive = [];
+        this.catchUpInFlight = false;
+        if (this.catchUpTimeout) {
+            clearTimeout(this.catchUpTimeout);
+            this.catchUpTimeout = null;
+        }
+        for (const resolve of this.historyWaiters.splice(0)) {
+            resolve({ messages: [], retained: false });
+        }
 
         for (const off of this.unsubscribers) off();
         this.unsubscribers = [];
@@ -235,13 +455,83 @@ export class RebaseRealtimeChannel {
                 break;
             }
             case "broadcast": {
-                const event = { event: message.event as string, payload: message.payload };
-                for (const handler of this.broadcastHandlers) handler(event);
+                const seq = typeof message.seq === "number" ? message.seq : undefined;
+                const event: BroadcastEvent = {
+                    event: message.event as string,
+                    payload: message.payload,
+                    ...(seq !== undefined ? { seq } : {})
+                };
+
+                // Unsequenced channels keep the original behaviour exactly:
+                // straight through, no buffering, no watermark.
+                if (seq === undefined) {
+                    this.deliver(event);
+                    break;
+                }
+
+                if (this.catchUpInFlight) {
+                    this.pendingLive.push(event);
+                    break;
+                }
+                if (seq <= this.lastSeq) break; // already delivered
+                this.lastSeq = seq;
+                this.deliver(event);
+                break;
+            }
+            case "channel_history": {
+                this.catchUpInFlight = false;
+                if (this.catchUpTimeout) {
+                    clearTimeout(this.catchUpTimeout);
+                    this.catchUpTimeout = null;
+                }
+
+                const entries = (message.messages as ChannelHistoryEntry[] | undefined) ?? [];
+                const retained = message.retained === true;
+                const latestSeq = typeof message.latestSeq === "number" ? message.latestSeq : undefined;
+
+                for (const resolve of this.historyWaiters.splice(0)) {
+                    resolve({ messages: entries, retained, latestSeq });
+                }
+
+                // Server-ordered ascending; the watermark check makes the
+                // overlap with anything already seen a no-op rather than a
+                // double-apply.
+                for (const entry of entries) {
+                    if (entry.seq <= this.lastSeq) continue;
+                    this.lastSeq = entry.seq;
+                    this.deliver({
+                        event: entry.event,
+                        payload: entry.payload,
+                        seq: entry.seq,
+                        replayed: true
+                    });
+                }
+
+                this.flushPendingLive();
                 break;
             }
         }
     }
 
+    /** Deliver everything held back during a catch-up, in sequence order. */
+    private flushPendingLive(): void {
+        if (this.pendingLive.length === 0) return;
+        const buffered = this.pendingLive.sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+        this.pendingLive = [];
+        for (const event of buffered) {
+            const seq = event.seq;
+            if (seq !== undefined) {
+                if (seq <= this.lastSeq) continue;
+                this.lastSeq = seq;
+            }
+            this.deliver(event);
+        }
+    }
+
+    private deliver(event: BroadcastEvent): void {
+        for (const handler of [...this.broadcastHandlers]) handler(event);
+    }
+
     private emitPresence(diff?: PresenceDiff): void {
         const snapshot = { ...this.presences };
         for (const handler of this.presenceHandlers) handler(snapshot, diff);

package/src/transport-baseurl.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect, afterEach } from "@jest/globals";
+import { createTransport } from "./transport";
+
+/**
+ * `baseUrl` is optional because the common production shape is a Rebase backend
+ * serving its own SPA: the API is the page's origin. These pin the resolution,
+ * because getting it wrong pushes apps into baking an absolute host — which
+ * breaks the moment a custom domain points at the same app, and which CORS
+ * cannot repair (a SameSite=Lax auth cookie is not sent cross-site either).
+ */
+const setWindow = (origin?: string) => {
+    if (origin === undefined) { delete (globalThis as never as { window?: unknown }).window; return; }
+    (globalThis as never as { window: unknown }).window = { location: { origin, href: origin + "/" } };
+};
+
+afterEach(() => setWindow(undefined));
+
+describe("transport baseUrl resolution", () => {
+    it("uses the page origin when unset in a browser", () => {
+        setWindow("https://dadaki.com");
+        expect(createTransport({}).baseUrl).toBe("https://dadaki.com");
+    });
+
+    it("gives callers something they can build an absolute URL from", () => {
+        setWindow("https://dadaki.com");
+        const t = createTransport({});
+        // The empty-string version of this threw, which is what drove apps to
+        // bake a hostname into the bundle.
+        expect(() => new URL(`${t.baseUrl}/api/functions/doc-content/get`)).not.toThrow();
+    });
+
+    it("follows the page, so a second hostname on the same app just works", () => {
+        setWindow("https://dadaki.apps.rebase.pro");
+        expect(createTransport({}).baseUrl).toBe("https://dadaki.apps.rebase.pro");
+        setWindow("https://dadaki.com");
+        expect(createTransport({}).baseUrl).toBe("https://dadaki.com");
+    });
+
+    it("still honours an explicit baseUrl, which is what dev needs", () => {
+        setWindow("https://dadaki.com");
+        expect(createTransport({ baseUrl: "http://localhost:3001" }).baseUrl).toBe("http://localhost:3001");
+    });
+
+    it("strips a trailing slash so joins do not double up", () => {
+        setWindow(undefined);
+        expect(createTransport({ baseUrl: "https://api.example.com/" }).baseUrl).toBe("https://api.example.com");
+    });
+
+    it("stays relative off-browser, where there is no origin to borrow", () => {
+        setWindow(undefined);
+        expect(createTransport({}).baseUrl).toBe("");
+    });
+});

package/src/transport.ts

@@ -112,6 +112,29 @@ export interface Transport {
     resolveToken: () => Promise<string | null>;
 }
 
+/**
+ * The base every request and every caller-built URL resolves against.
+ *
+ * `baseUrl` is optional because the common production shape is a Rebase
+ * backend serving its own SPA, where the API is simply the page's origin.
+ * Leaving it unset is therefore the *correct* configuration there — and the
+ * one that keeps working when a second hostname (a custom domain) points at
+ * the same app.
+ *
+ * When unset in a browser this resolves to the page origin rather than "".
+ * Requests behave identically either way, but the empty string is a trap for
+ * anything that builds a URL from `client.baseUrl`: `new URL("" + path)`
+ * throws, so apps "fixed" it by baking an absolute host into their bundle —
+ * which is exactly what breaks the day a custom domain is added, and which no
+ * amount of CORS configuration repairs, because a SameSite=Lax auth cookie is
+ * not sent cross-site either.
+ */
+function resolveBaseUrl(configured?: string): string {
+    if (configured) return configured.replace(/\/$/, "");
+    if (typeof window !== "undefined" && window.location?.origin) return window.location.origin;
+    return "";
+}
+
 export function createTransport(config: RebaseClientConfig): Transport {
     const fetchFn = config.fetch || globalThis.fetch;
     const apiPath = config.apiPath || "/api";
@@ -128,8 +151,7 @@ export function createTransport(config: RebaseClientConfig): Transport {
     }
 
     async function request<T = unknown>(path: string, init?: RequestInit): Promise<T> {
-        const base = config.baseUrl ? config.baseUrl.replace(/\/$/, "") : "";
-        const url = base + apiPath + path;
+        const url = resolveBaseUrl(config.baseUrl) + apiPath + path;
 
         let activeToken = token;
         if (tokenGetter) {
@@ -242,7 +264,7 @@ headers: retryHeaders });
         setToken(newToken: string | null) { token = newToken || undefined; },
         setAuthTokenGetter(getter: () => Promise<string | null>) { tokenGetter = getter; },
         setOnUnauthorized(handler: () => Promise<boolean>) { onUnauthorizedHandler = handler; },
-        get baseUrl() { return config.baseUrl ? config.baseUrl.replace(/\/$/, "") : ""; },
+        get baseUrl() { return resolveBaseUrl(config.baseUrl); },
         get apiPath() { return apiPath; },
         get fetchFn() { return fetchFn; },
         getHeaders: (init?: RequestInit) => getHeaders(token, init) as Record<string, string>,

package/src/websocket.ts

@@ -64,7 +64,11 @@ const CHANNEL_MESSAGE_TYPES = new Set([
     "broadcast",
     "presence_track",
     "presence_untrack",
-    "presence_state"
+    "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"
 ]);
 
 /**
@@ -599,7 +603,7 @@ export class RebaseWebSocketClient {
         // 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 === "broadcast" || type === "presence_state" || type === "presence_diff" || type === "channel_history")) {
             const handlers = this.channelHandlers.get(message.channel);
             if (handlers) {
                 for (const handler of [...handlers]) {
@@ -1062,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"