@pawabase/client 0.0.0-stage → 0.1.0

package/dist/esm/realtime.js

@@ -0,0 +1,699 @@
+import { ConfigError, RealtimeError } from "./errors.js";
+import { backoff, encodePath, sleep } from "./util.js";
+const OPEN = 1;
+const FATAL_CLOSE = new Set([4001]);
+const SEEN_LIMIT = 1000;
+export class RealtimeClient {
+    http;
+    auth;
+    options;
+    socket = null;
+    currentStatus = "idle";
+    channels = new Map();
+    pending = new Map();
+    statusListeners = new Set();
+    refs = 0;
+    attempts = 0;
+    manual = false;
+    connecting = null;
+    heartbeat = null;
+    reconnectTimer = null;
+    lastActivity = 0;
+    triedRefresh = false;
+    authSubscription = null;
+    /** The server's id for this connection, once welcomed. */
+    connectionId = null;
+    constructor(http, auth, options = {}) {
+        this.http = http;
+        this.auth = auth;
+        this.options = options;
+    }
+    get status() {
+        return this.currentStatus;
+    }
+    onStatusChange(handler) {
+        this.statusListeners.add(handler);
+        return () => void this.statusListeners.delete(handler);
+    }
+    setStatus(status) {
+        if (this.currentStatus === status)
+            return;
+        this.currentStatus = status;
+        for (const handler of [...this.statusListeners]) {
+            try {
+                handler(status);
+            }
+            catch {
+                /* observers must not break the connection */
+            }
+        }
+    }
+    // ── channels ──────────────────────────────────────────────────────────
+    /**
+     * A channel by name. Asking twice returns the same object, so listeners are shared.
+     * Channel names are authorised by the project's realtime rules.
+     */
+    channel(name, options = {}) {
+        let channel = this.channels.get(name);
+        if (!channel) {
+            channel = new RealtimeChannel(this, name, options);
+            this.channels.set(name, channel);
+        }
+        else if (options.presence || options.replay !== undefined) {
+            channel.configure(options);
+        }
+        return channel;
+    }
+    /** Forget a channel object once it is unsubscribed. */
+    forget(name) {
+        this.channels.delete(name);
+    }
+    // ── connection ────────────────────────────────────────────────────────
+    url(token) {
+        const base = new URL(this.http.config.baseUrl);
+        base.protocol = base.protocol === "https:" ? "wss:" : "ws:";
+        base.pathname = `${base.pathname.replace(/\/+$/, "")}/realtime/v1/socket`;
+        base.search = "";
+        base.searchParams.set("apikey", this.http.config.apiKey);
+        if (token)
+            base.searchParams.set("token", token);
+        if (this.options.environment)
+            base.searchParams.set("environment", this.options.environment);
+        return base.toString();
+    }
+    /** Open the connection (channels do this for you). Resolves once the server has welcomed it. */
+    connect() {
+        if (this.currentStatus === "open")
+            return Promise.resolve();
+        if (this.connecting)
+            return this.connecting;
+        this.manual = false;
+        this.connecting = this.open().finally(() => {
+            this.connecting = null;
+        });
+        return this.connecting;
+    }
+    async open() {
+        const Impl = this.options.webSocket ?? globalThis.WebSocket;
+        if (!Impl) {
+            throw new ConfigError("No WebSocket implementation found. Pass `realtime: { webSocket }` to createClient (for example the `ws` package on Node 20).");
+        }
+        this.setStatus(this.attempts > 0 ? "reconnecting" : "connecting");
+        const token = (await this.auth?.getAccessToken().catch(() => null)) ?? null;
+        const socket = new Impl(this.url(token));
+        this.socket = socket;
+        this.lastActivity = Date.now();
+        const timeoutMs = this.options.connectTimeoutMs ?? 10_000;
+        await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new RealtimeError("connect_timeout", `The realtime connection did not open within ${timeoutMs} ms.`));
+                try {
+                    socket.close(4000, "connect timeout");
+                }
+                catch {
+                    /* already closed */
+                }
+            }, timeoutMs);
+            let welcomed = false;
+            socket.onmessage = (event) => {
+                this.lastActivity = Date.now();
+                const frame = this.parse(event.data);
+                if (!frame)
+                    return;
+                if (!welcomed && frame["type"] === "welcome") {
+                    welcomed = true;
+                    clearTimeout(timer);
+                    this.connectionId = typeof frame["connection_id"] === "string" ? frame["connection_id"] : null;
+                    socket.onmessage = (next) => this.onMessage(next.data);
+                    this.attempts = 0;
+                    this.triedRefresh = false;
+                    this.setStatus("open");
+                    this.startHeartbeat();
+                    this.watchAuth();
+                    void this.resubscribe();
+                    resolve();
+                    return;
+                }
+                this.onMessage(event.data);
+            };
+            socket.onerror = () => {
+                /* the close event follows with the code */
+            };
+            socket.onclose = (event) => {
+                clearTimeout(timer);
+                if (!welcomed) {
+                    reject(new RealtimeError(`closed_${event.code}`, event.reason || `The connection closed (${event.code}) before it opened.`));
+                }
+                this.onClose(event.code, event.reason ?? "", welcomed);
+            };
+        });
+    }
+    /** Close the connection and stop reconnecting. Channels keep their listeners and rejoin on the next `connect()`. */
+    disconnect() {
+        this.manual = true;
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+        this.stopHeartbeat();
+        this.authSubscription?.unsubscribe();
+        this.authSubscription = null;
+        const socket = this.socket;
+        this.socket = null;
+        this.failPending(new RealtimeError("closed", "The realtime connection was closed."));
+        for (const channel of this.channels.values())
+            channel.markClosed("disconnected");
+        if (socket) {
+            socket.onclose = null;
+            socket.onmessage = null;
+            try {
+                socket.close(1000, "client closed");
+            }
+            catch {
+                /* already closed */
+            }
+        }
+        this.attempts = 0;
+        this.setStatus("closed");
+    }
+    onClose(code, reason, wasOpen) {
+        this.stopHeartbeat();
+        this.socket = null;
+        this.failPending(new RealtimeError("closed", "The realtime connection closed."));
+        for (const channel of this.channels.values())
+            channel.markClosed(reason || `closed (${code})`);
+        if (this.manual)
+            return;
+        if (FATAL_CLOSE.has(code)) {
+            this.setStatus("closed");
+            return;
+        }
+        if (code === 4003 && !this.triedRefresh && this.auth) {
+            // The token was refused: refresh it once, then try again.
+            this.triedRefresh = true;
+            void this.auth
+                .refreshSession()
+                .then(() => this.scheduleReconnect(0))
+                .catch(() => this.setStatus("closed"));
+            return;
+        }
+        if (code === 4003) {
+            this.setStatus("closed");
+            return;
+        }
+        void wasOpen;
+        this.scheduleReconnect();
+    }
+    scheduleReconnect(forcedDelay) {
+        const policy = this.options.reconnect;
+        if (policy === false) {
+            this.setStatus("closed");
+            return;
+        }
+        const maxAttempts = policy?.maxAttempts ?? Infinity;
+        if (this.attempts >= maxAttempts) {
+            this.setStatus("closed");
+            return;
+        }
+        const delay = forcedDelay ?? backoff(this.attempts, { baseDelayMs: policy?.baseDelayMs ?? 500, maxDelayMs: policy?.maxDelayMs ?? 15_000 });
+        this.attempts += 1;
+        this.setStatus("reconnecting");
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connecting = this.open()
+                .catch(() => {
+                // open() rejected without a close event reaching onClose (rare); try again.
+                if (!this.manual && !this.socket)
+                    this.scheduleReconnect();
+            })
+                .finally(() => {
+                this.connecting = null;
+            });
+        }, delay);
+        this.reconnectTimer.unref?.();
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        const interval = (this.options.heartbeatSeconds ?? 25) * 1000;
+        this.heartbeat = setInterval(() => {
+            const socket = this.socket;
+            if (!socket || socket.readyState !== OPEN)
+                return;
+            if (Date.now() - this.lastActivity > interval * 2 + 1000) {
+                // Nothing, not even a pong: the link is dead without having closed.
+                try {
+                    socket.close(4000, "heartbeat timeout");
+                }
+                catch {
+                    /* already closed */
+                }
+                return;
+            }
+            try {
+                socket.send(JSON.stringify({ type: "ping" }));
+            }
+            catch {
+                /* the close handler will follow */
+            }
+        }, interval);
+        this.heartbeat.unref?.();
+    }
+    stopHeartbeat() {
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        this.heartbeat = null;
+    }
+    /** Tell the server about a refreshed (or removed) token without reconnecting. */
+    watchAuth() {
+        if (!this.auth || this.authSubscription)
+            return;
+        this.authSubscription = this.auth.onAuthStateChange((event, session) => {
+            if (event === "INITIAL_SESSION" || this.currentStatus !== "open")
+                return;
+            void this.request({ type: "auth", token: session?.access_token ?? null }).catch(() => undefined);
+        });
+    }
+    async resubscribe() {
+        for (const channel of [...this.channels.values()]) {
+            if (channel.wantsJoin)
+                await channel.rejoin().catch(() => undefined);
+        }
+    }
+    // ── messages ──────────────────────────────────────────────────────────
+    parse(raw) {
+        if (typeof raw !== "string") {
+            this.options.onProtocolError?.("a binary frame arrived; Pawabase sends JSON text");
+            return null;
+        }
+        try {
+            const value = JSON.parse(raw);
+            if (typeof value === "object" && value !== null && !Array.isArray(value))
+                return value;
+        }
+        catch {
+            /* fall through */
+        }
+        this.options.onProtocolError?.(`an invalid frame arrived: ${raw.slice(0, 120)}`);
+        return null;
+    }
+    onMessage(raw) {
+        this.lastActivity = Date.now();
+        const frame = this.parse(raw);
+        if (!frame)
+            return;
+        switch (frame["type"]) {
+            case "ack": {
+                const pending = this.take(frame["ref"]);
+                if (!pending)
+                    return;
+                if (frame["ok"] === false) {
+                    pending.reject(new RealtimeError(String(frame["error"] ?? "error"), String(frame["reason"] ?? frame["error"] ?? "The request was refused.")));
+                }
+                else if (pending.expect === "ack")
+                    pending.resolve(frame);
+                return;
+            }
+            case "history": {
+                const pending = this.take(frame["ref"]);
+                pending?.resolve(frame);
+                return;
+            }
+            case "message": {
+                this.channels.get(String(frame["channel"]))?.deliver(frame);
+                return;
+            }
+            case "presence_state": {
+                this.channels.get(String(frame["channel"]))?.setPresence(frame["members"] ?? []);
+                return;
+            }
+            case "presence_diff": {
+                this.channels
+                    .get(String(frame["channel"]))
+                    ?.applyPresence(frame["joins"] ?? [], frame["leaves"] ?? []);
+                return;
+            }
+            case "pong":
+            case "welcome":
+                return;
+            case "error":
+                this.options.onProtocolError?.(`the server reported: ${String(frame["error"])}`);
+                return;
+            default:
+                this.options.onProtocolError?.(`an unknown frame arrived: ${String(frame["type"])}`);
+        }
+    }
+    take(ref) {
+        if (typeof ref !== "string")
+            return undefined;
+        const pending = this.pending.get(ref);
+        if (!pending)
+            return undefined;
+        clearTimeout(pending.timer);
+        this.pending.delete(ref);
+        return pending;
+    }
+    failPending(error) {
+        for (const [ref, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+            this.pending.delete(ref);
+        }
+    }
+    /** Send a frame and wait for its acknowledgement (or, for `history`, its answer). */
+    request(frame, expect = "ack") {
+        const socket = this.socket;
+        if (!socket || socket.readyState !== OPEN) {
+            return Promise.reject(new RealtimeError("not_connected", "The realtime connection is not open."));
+        }
+        const ref = String(++this.refs);
+        return new Promise((resolve, reject) => {
+            const timeoutMs = this.options.ackTimeoutMs ?? 10_000;
+            const timer = setTimeout(() => {
+                this.pending.delete(ref);
+                reject(new RealtimeError("ack_timeout", `The server did not answer within ${timeoutMs} ms.`));
+            }, timeoutMs);
+            this.pending.set(ref, { resolve, reject, timer, expect });
+            try {
+                socket.send(JSON.stringify({ ...frame, ref }));
+            }
+            catch (error) {
+                clearTimeout(timer);
+                this.pending.delete(ref);
+                reject(new RealtimeError("send_failed", "Could not send on the realtime connection.", { cause: error }));
+            }
+        });
+    }
+    // ── HTTP counterparts (no socket needed) ──────────────────────────────
+    /** Publish from anywhere, without a socket. The channel's `publish` rule applies. */
+    publish(channel, event, payload) {
+        return this.http.request({ method: "POST", path: "/realtime/v1/publish", body: { channel, event, payload } });
+    }
+    /**
+     * Listen to channels over Server-Sent Events: one-way, over plain HTTP, with no socket to manage. Iterate the frames
+     * (`welcome`, `message`, `presence_diff`) until you `break` or abort the `signal`. Publish with {@link publish}. At most 20 channels
+     * per stream; the signed-in user, if any, is who is listening.
+     *
+     * ```ts
+     * for await (const frame of pawabase.realtime.stream(["chat:lobby"])) if (frame.type === "message") show(frame.payload);
+     * ```
+     */
+    async *stream(channels, options = {}) {
+        const names = Array.isArray(channels) ? channels : [channels];
+        if (names.length === 0)
+            throw new ConfigError("Pass at least one channel to listen to.");
+        const token = (await this.auth?.getAccessToken().catch(() => null)) ?? null;
+        const response = await this.http.send({
+            path: "/realtime/v1/sse",
+            query: { channels: names.join(","), ...(token ? { token } : {}) },
+            headers: { accept: "text/event-stream" },
+            retry: false,
+            timeoutMs: 0, // a stream is meant to stay open
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        if (!response.body)
+            return;
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let data = [];
+        const flush = () => {
+            const text = data.join("\n");
+            data = [];
+            if (!text)
+                return null;
+            try {
+                const frame = JSON.parse(text);
+                return frame && typeof frame === "object" && !Array.isArray(frame) ? frame : null;
+            }
+            catch {
+                return null;
+            }
+        };
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let newline = buffer.indexOf("\n");
+                while (newline >= 0) {
+                    const line = buffer.slice(0, newline).replace(/\r$/, "");
+                    buffer = buffer.slice(newline + 1);
+                    if (line === "") {
+                        const frame = flush();
+                        if (frame)
+                            yield frame;
+                    }
+                    else if (line.startsWith("data:")) {
+                        data.push(line.slice(5).replace(/^ /, ""));
+                    }
+                    newline = buffer.indexOf("\n");
+                }
+            }
+            const last = flush();
+            if (last)
+                yield last;
+        }
+        finally {
+            await reader.cancel().catch(() => undefined);
+        }
+    }
+    /** Who is on a channel right now. */
+    async presence(channel) {
+        return (await this.http.request({ path: `/realtime/v1/channels/${encodePath(channel)}/presence` })).members;
+    }
+    /** Recent messages on a channel, oldest first. */
+    async history(channel, limit = 50) {
+        return (await this.http.request({
+            path: `/realtime/v1/channels/${encodePath(channel)}/history`,
+            query: { limit },
+        })).messages;
+    }
+    /**
+     * Wait until the socket is really open, or `ms` pass: after a drop the status can lag the
+     * socket for a moment, and a reconnect takes a few. Connects first when idle or closed.
+     */
+    async whenOpen(ms = 5000) {
+        const deadline = Date.now() + ms;
+        for (;;) {
+            if (this.currentStatus === "open" && this.socket?.readyState === OPEN)
+                return;
+            if (Date.now() > deadline)
+                throw new RealtimeError("not_connected", "The realtime connection did not open in time.");
+            if (this.currentStatus === "idle" || (this.currentStatus === "closed" && !this.manual))
+                await this.connect().catch(() => undefined);
+            else
+                await sleep(20);
+        }
+    }
+}
+/** One named channel: receive messages and presence, publish, and see who is here. */
+export class RealtimeChannel {
+    client;
+    name;
+    handlers = new Map();
+    options;
+    joined = false;
+    joining = null;
+    wanted = false;
+    members = new Map();
+    seen = new Set();
+    order = [];
+    queue = [];
+    waiters = [];
+    ended = false;
+    constructor(client, name, options) {
+        this.client = client;
+        this.name = name;
+        this.options = { ...options };
+    }
+    /** @internal */
+    configure(options) {
+        this.options = { ...this.options, ...options };
+    }
+    /** True while the channel is subscribed on the open connection. */
+    get subscribed() {
+        return this.joined;
+    }
+    /** @internal Whether the channel should rejoin after a reconnect. */
+    get wantsJoin() {
+        return this.wanted;
+    }
+    /** Listen to `message`, `presence`, `subscribed`, `closed` or `error`. Returns a function that stops listening. */
+    on(event, handler) {
+        let set = this.handlers.get(event);
+        if (!set)
+            this.handlers.set(event, (set = new Set()));
+        set.add(handler);
+        return () => void set.delete(handler);
+    }
+    /** Listen to messages with one event name only. */
+    onEvent(event, handler) {
+        return this.on("message", (message) => {
+            if (message.event === event)
+                handler(message);
+        });
+    }
+    emit(event, value) {
+        for (const handler of [...(this.handlers.get(event) ?? [])]) {
+            try {
+                handler(value);
+            }
+            catch {
+                /* a listener must not break delivery */
+            }
+        }
+    }
+    /**
+     * Start receiving. Connects first if needed. Rejects with a {@link RealtimeError} when the
+     * channel's rule refuses (`code: "forbidden"`). Safe to call twice.
+     */
+    async subscribe() {
+        this.ended = false;
+        if (this.joined)
+            return this;
+        if (!this.joining) {
+            this.joining = (async () => {
+                await this.client.connect();
+                await this.join(false);
+                // Only a channel that joined is rejoined after a reconnect: the client rejoins
+                // on its own at welcome, and must not race this first join.
+                this.wanted = true;
+            })().finally(() => {
+                this.joining = null;
+            });
+        }
+        await this.joining;
+        return this;
+    }
+    /** @internal Rejoin after a reconnect. */
+    async rejoin() {
+        await this.join(true);
+    }
+    async join(rejoining) {
+        try {
+            await this.client.request({
+                type: "subscribe",
+                channel: this.name,
+                ...(this.options.presence ? { presence: this.options.presence } : {}),
+            });
+        }
+        catch (error) {
+            if (error instanceof RealtimeError)
+                this.emit("error", error);
+            throw error;
+        }
+        this.joined = true;
+        this.emit("subscribed", undefined);
+        if (rejoining && (this.options.replay ?? 0) > 0) {
+            const history = await this.history(this.options.replay).catch(() => []);
+            for (const message of history)
+                this.deliver(message);
+        }
+    }
+    /** Stop receiving. Pending iterators end. */
+    async unsubscribe() {
+        this.wanted = false;
+        if (this.joined) {
+            await this.client.request({ type: "unsubscribe", channel: this.name }).catch(() => undefined);
+        }
+        this.joined = false;
+        this.members.clear();
+        this.end("unsubscribed");
+        this.client.forget(this.name);
+    }
+    /** Publish to the channel over the socket. Resolves with the message id once the server accepted it. */
+    async send(event, payload) {
+        await this.client.whenOpen();
+        const ack = await this.client.request({ type: "publish", channel: this.name, event, payload });
+        return { id: String(ack["id"] ?? "") };
+    }
+    /** Set the presence data others see for you. Subscribe first. */
+    async track(meta) {
+        this.options = { ...this.options, presence: meta };
+        await this.client.whenOpen();
+        await this.client.request({ type: "presence", channel: this.name, meta });
+    }
+    /** Recent messages, oldest first. */
+    async history(limit = 50) {
+        await this.client.whenOpen();
+        const reply = await this.client.request({ type: "history", channel: this.name, limit }, "history");
+        return reply["messages"] ?? [];
+    }
+    /** Who is on the channel now, as last told by the server. Empty unless presence is enabled for it. */
+    presenceState() {
+        return [...this.members.values()];
+    }
+    // ── delivery (called by the client) ───────────────────────────────────
+    /** @internal */
+    deliver(message) {
+        if (message.id) {
+            if (this.seen.has(message.id))
+                return;
+            this.seen.add(message.id);
+            this.order.push(message.id);
+            if (this.order.length > SEEN_LIMIT)
+                this.seen.delete(this.order.shift());
+        }
+        const typed = message;
+        this.emit("message", typed);
+        const waiter = this.waiters.shift();
+        if (waiter)
+            waiter({ value: typed, done: false });
+        else {
+            this.queue.push(typed);
+            if (this.queue.length > 1000)
+                this.queue.shift();
+        }
+    }
+    /** @internal */
+    setPresence(list) {
+        this.members.clear();
+        for (const member of list)
+            this.members.set(member.presence_ref, member);
+        this.emit("presence", { joins: [...this.members.values()], leaves: [], members: this.presenceState() });
+    }
+    /** @internal */
+    applyPresence(joins, leaves) {
+        for (const member of leaves)
+            this.members.delete(member.presence_ref);
+        for (const member of joins)
+            this.members.set(member.presence_ref, member);
+        this.emit("presence", {
+            joins: joins,
+            leaves: leaves,
+            members: this.presenceState(),
+        });
+    }
+    /** @internal The connection dropped; the channel will rejoin by itself if it can. */
+    markClosed(reason) {
+        if (!this.joined)
+            return;
+        this.joined = false;
+        this.members.clear();
+        this.emit("closed", { reason });
+    }
+    end(reason) {
+        this.ended = true;
+        this.emit("closed", { reason });
+        for (const waiter of this.waiters.splice(0))
+            waiter({ value: undefined, done: true });
+    }
+    /** Iterate messages: `for await (const message of channel) { … }`. Ends on `unsubscribe()`. */
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const ready = this.queue.shift();
+                if (ready)
+                    return Promise.resolve({ value: ready, done: false });
+                if (this.ended)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => this.waiters.push(resolve));
+            },
+            return: async () => {
+                await this.unsubscribe();
+                return { value: undefined, done: true };
+            },
+        };
+    }
+}
+//# sourceMappingURL=realtime.js.map