@chidchanun/bcp 0.2.11 → 0.2.13

package/packages/server/src/realtime.ts

@@ -0,0 +1,1464 @@
+import {
+    randomUUID,
+} from "node:crypto";
+
+export interface RealtimeEnvelope<TPayload = unknown> {
+    id: string;
+    channel: string;
+    event: string;
+    payload: TPayload;
+    timestamp: number;
+    sourceId?: string;
+    excludeConnectionId?: string;
+}
+
+export interface RealtimePresenceMember<TData = unknown> {
+    connectionId: string;
+    channel: string;
+    userId?: string;
+    data?: TData;
+    joinedAt: number;
+    updatedAt: number;
+}
+
+export interface RealtimeBroker {
+    publish(message: RealtimeEnvelope): Promise<void>;
+    subscribe(
+        listener: (
+            message: RealtimeEnvelope
+        ) => void | Promise<void>
+    ): () => void;
+    close?(): Promise<void>;
+}
+
+export interface RealtimePresenceStore {
+    join(member: RealtimePresenceMember): Promise<void>;
+    leave(
+        channel: string,
+        connectionId: string
+    ): Promise<void>;
+    leaveConnection(
+        connectionId: string
+    ): Promise<void>;
+    touch(
+        connectionId: string,
+        updatedAt: number
+    ): Promise<void>;
+    list(
+        channel: string
+    ): Promise<RealtimePresenceMember[]>;
+    close?(): Promise<void>;
+}
+
+export interface MemoryRealtimeBroker
+extends RealtimeBroker {
+    clear(): void;
+}
+
+export interface MemoryRealtimePresenceStore
+extends RealtimePresenceStore {
+    clear(): void;
+}
+
+export interface RealtimeSocket {
+    send(data: string): void | Promise<void>;
+    close?(
+        code?: number,
+        reason?: string
+    ): void | Promise<void>;
+    onMessage(
+        listener: (
+            data: string
+        ) => void | Promise<void>
+    ): () => void;
+    onClose(
+        listener: () => void | Promise<void>
+    ): () => void;
+    onError?(
+        listener: (
+            error: unknown
+        ) => void | Promise<void>
+    ): () => void;
+}
+
+export interface RealtimeAuthenticationContext<TData = unknown> {
+    request?: Request;
+    data?: TData;
+}
+
+export type RealtimeAuthenticate<TUser = unknown, TData = unknown> = (
+    context: RealtimeAuthenticationContext<TData>
+) => TUser | null | undefined | Promise<TUser | null | undefined>;
+
+export interface RealtimeChannelAuthorizationContext<TUser = unknown> {
+    connection: RealtimeConnection<TUser>;
+    channel: string;
+}
+
+export type RealtimeAuthorizeChannel<TUser = unknown> = (
+    context: RealtimeChannelAuthorizationContext<TUser>
+) => boolean | Promise<boolean>;
+
+export interface RealtimeOptions<TUser = unknown> {
+    broker?: RealtimeBroker;
+    presence?: RealtimePresenceStore;
+    authenticate?: RealtimeAuthenticate<TUser>;
+    authorizeChannel?: RealtimeAuthorizeChannel<TUser>;
+    getUserId?: (
+        user: TUser
+    ) => string | number | null | undefined;
+    now?: () => number;
+    idFactory?: () => string;
+    heartbeatTimeoutMs?: number;
+    onError?: (
+        error: unknown
+    ) => void | Promise<void>;
+}
+
+export interface RealtimeConnectOptions<TUser = unknown, TData = unknown> {
+    request?: Request;
+    user?: TUser;
+    data?: TData;
+    socket?: RealtimeSocket;
+    connectionId?: string;
+}
+
+export interface RealtimeJoinOptions<TData = unknown> {
+    presence?: TData;
+}
+
+export interface RealtimeBroadcastOptions {
+    excludeConnectionId?: string;
+}
+
+export interface RealtimeConnection<TUser = unknown> {
+    readonly id: string;
+    readonly user: TUser | undefined;
+    readonly connectedAt: number;
+    readonly lastSeenAt: number;
+    readonly connected: boolean;
+    readonly channels: readonly string[];
+    join<TData = unknown>(
+        channel: string,
+        options?: RealtimeJoinOptions<TData>
+    ): Promise<void>;
+    leave(channel: string): Promise<void>;
+    emit<TPayload = unknown>(
+        channel: string,
+        event: string,
+        payload: TPayload
+    ): Promise<void>;
+    send<TPayload = unknown>(
+        event: string,
+        payload: TPayload,
+        channel?: string
+    ): Promise<void>;
+    touch(): Promise<void>;
+    disconnect(
+        code?: number,
+        reason?: string
+    ): Promise<void>;
+}
+
+export interface RealtimeEventContext<TUser = unknown, TPayload = unknown> {
+    connection: RealtimeConnection<TUser>;
+    channel: string;
+    event: string;
+    payload: TPayload;
+}
+
+export type RealtimeEventHandler<TUser = unknown, TPayload = unknown> = (
+    context: RealtimeEventContext<TUser, TPayload>
+) => void | Promise<void>;
+
+export interface RealtimeHeartbeatRunner {
+    readonly running: boolean;
+    stop(): Promise<void>;
+}
+
+export interface RealtimeHeartbeatOptions {
+    intervalMs?: number;
+}
+
+export interface RealtimeSseOptions {
+    signal?: AbortSignal;
+    event?: string;
+    retryMs?: number;
+    keepAliveMs?: number;
+    headers?: HeadersInit;
+}
+
+export interface RealtimeHub<TUser = unknown> {
+    readonly id: string;
+    readonly broker: RealtimeBroker;
+    readonly presence: RealtimePresenceStore;
+    connect<TData = unknown>(
+        options?: RealtimeConnectOptions<TUser, TData>
+    ): Promise<RealtimeConnection<TUser>>;
+    attachSocket<TData = unknown>(
+        socket: RealtimeSocket,
+        options?: Omit<RealtimeConnectOptions<TUser, TData>, "socket">
+    ): Promise<RealtimeConnection<TUser>>;
+    broadcast<TPayload = unknown>(
+        channel: string,
+        event: string,
+        payload: TPayload,
+        options?: RealtimeBroadcastOptions
+    ): Promise<void>;
+    subscribe(
+        channel: string,
+        listener: (
+            message: RealtimeEnvelope
+        ) => void | Promise<void>
+    ): () => void;
+    on<TPayload = unknown>(
+        event: string,
+        handler: RealtimeEventHandler<TUser, TPayload>
+    ): () => void;
+    members(
+        channel: string
+    ): Promise<RealtimePresenceMember[]>;
+    connection(
+        id: string
+    ): RealtimeConnection<TUser> | null;
+    connections(): RealtimeConnection<TUser>[];
+    sweepStale(): Promise<number>;
+    startHeartbeat(
+        options?: RealtimeHeartbeatOptions
+    ): RealtimeHeartbeatRunner;
+    sse(
+        channel: string,
+        options?: RealtimeSseOptions
+    ): Response;
+    close(): Promise<void>;
+}
+
+interface InternalConnection<TUser> {
+    api: RealtimeConnection<TUser>;
+    user: TUser | undefined;
+    socket?: RealtimeSocket;
+    channels: Set<string>;
+    connectedAt: number;
+    lastSeenAt: number;
+    connected: boolean;
+    cleanup: Array<() => void>;
+}
+
+interface SocketClientMessage {
+    type?: unknown;
+    channel?: unknown;
+    event?: unknown;
+    payload?: unknown;
+    presence?: unknown;
+}
+
+export function createMemoryRealtimeBroker():
+MemoryRealtimeBroker {
+    const listeners =
+        new Set<(
+            message: RealtimeEnvelope
+        ) => void | Promise<void>>();
+
+    return {
+        async publish(message) {
+            for (const listener of listeners) {
+                await listener(cloneEnvelope(message));
+            }
+        },
+
+        subscribe(listener) {
+            if (typeof listener !== "function") {
+                throw new TypeError(
+                    "BCP Realtime: broker listener must be a function."
+                );
+            }
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+
+        clear() {
+            listeners.clear();
+        },
+    };
+}
+
+export function createMemoryRealtimePresenceStore():
+MemoryRealtimePresenceStore {
+    const members =
+        new Map<string, RealtimePresenceMember>();
+
+    return {
+        async join(member) {
+            members.set(
+                presenceKey(
+                    member.channel,
+                    member.connectionId
+                ),
+                clonePresence(member)
+            );
+        },
+
+        async leave(channel, connectionId) {
+            members.delete(
+                presenceKey(
+                    normalizeChannel(channel),
+                    normalizeId(
+                        connectionId,
+                        "connection id"
+                    )
+                )
+            );
+        },
+
+        async leaveConnection(connectionId) {
+            const id =
+                normalizeId(
+                    connectionId,
+                    "connection id"
+                );
+            for (const [key, member] of members) {
+                if (member.connectionId === id) {
+                    members.delete(key);
+                }
+            }
+        },
+
+        async touch(connectionId, updatedAt) {
+            const id =
+                normalizeId(
+                    connectionId,
+                    "connection id"
+                );
+            assertFiniteNumber(
+                updatedAt,
+                "presence updatedAt"
+            );
+            for (const member of members.values()) {
+                if (member.connectionId === id) {
+                    member.updatedAt = updatedAt;
+                }
+            }
+        },
+
+        async list(channel) {
+            const normalized =
+                normalizeChannel(channel);
+            return Array.from(
+                members.values()
+            )
+                .filter(member =>
+                    member.channel === normalized
+                )
+                .sort((left, right) =>
+                    left.joinedAt - right.joinedAt ||
+                    left.connectionId.localeCompare(
+                        right.connectionId
+                    )
+                )
+                .map(clonePresence);
+        },
+
+        clear() {
+            members.clear();
+        },
+    };
+}
+
+export function createRealtime<TUser = unknown>(
+    options: RealtimeOptions<TUser> = {}
+): RealtimeHub<TUser> {
+    const broker =
+        options.broker ??
+        createMemoryRealtimeBroker();
+    const presence =
+        options.presence ??
+        createMemoryRealtimePresenceStore();
+    const now =
+        options.now ?? Date.now;
+    const idFactory =
+        options.idFactory ?? randomUUID;
+    const hubId =
+        normalizeId(
+            idFactory(),
+            "hub id"
+        );
+    const heartbeatTimeoutMs =
+        positiveInteger(
+            options.heartbeatTimeoutMs ?? 60_000,
+            "heartbeatTimeoutMs"
+        );
+    const connections =
+        new Map<string, InternalConnection<TUser>>();
+    const subscriptions =
+        new Map<
+            string,
+            Set<(
+                message: RealtimeEnvelope
+            ) => void | Promise<void>>
+        >();
+    const handlers =
+        new Map<
+            string,
+            Set<RealtimeEventHandler<TUser, any>>
+        >();
+    const heartbeatRunners =
+        new Set<RealtimeHeartbeatRunner>();
+
+    const unsubscribeBroker =
+        broker.subscribe(
+            async message => {
+                await dispatchBrokerMessage(
+                    message
+                );
+            }
+        );
+
+    const hub: RealtimeHub<TUser> = {
+        id: hubId,
+        broker,
+        presence,
+
+        async connect(connectOptions = {}) {
+            const user =
+                connectOptions.user ??
+                (
+                    options.authenticate
+                        ? await options.authenticate({
+                            request:
+                                connectOptions.request,
+                            data:
+                                connectOptions.data,
+                        }) ?? undefined
+                        : undefined
+                );
+            const connectionId =
+                normalizeId(
+                    connectOptions.connectionId ??
+                    idFactory(),
+                    "connection id"
+                );
+            if (connections.has(connectionId)) {
+                throw new Error(
+                    `BCP Realtime: connection id "${connectionId}" already exists.`
+                );
+            }
+            const connectedAt = now();
+            assertFiniteNumber(
+                connectedAt,
+                "connection timestamp"
+            );
+
+            const internal:
+                InternalConnection<TUser> = {
+                api: null as unknown as RealtimeConnection<TUser>,
+                user,
+                socket:
+                    connectOptions.socket,
+                channels:
+                    new Set<string>(),
+                connectedAt,
+                lastSeenAt:
+                    connectedAt,
+                connected: true,
+                cleanup: [],
+            };
+
+            const api:
+                RealtimeConnection<TUser> = {
+                id: connectionId,
+                user,
+                connectedAt,
+
+                get lastSeenAt() {
+                    return internal.lastSeenAt;
+                },
+
+                get connected() {
+                    return internal.connected;
+                },
+
+                get channels() {
+                    return Array.from(
+                        internal.channels
+                    ).sort();
+                },
+
+                async join(
+                    rawChannel,
+                    joinOptions = {}
+                ) {
+                    assertConnected(
+                        internal,
+                        connectionId
+                    );
+                    const channel =
+                        normalizeChannel(
+                            rawChannel
+                        );
+                    if (
+                        options.authorizeChannel &&
+                        !await options.authorizeChannel({
+                            connection: api,
+                            channel,
+                        })
+                    ) {
+                        throw new Error(
+                            `BCP Realtime: connection "${connectionId}" is not authorized for channel "${channel}".`
+                        );
+                    }
+                    if (internal.channels.has(channel)) {
+                        return;
+                    }
+                    internal.channels.add(channel);
+                    const timestamp = now();
+                    const userId =
+                        user !== undefined &&
+                        options.getUserId
+                            ? optionalId(
+                                options.getUserId(
+                                    user
+                                )
+                            )
+                            : undefined;
+                    await presence.join({
+                        connectionId,
+                        channel,
+                        userId,
+                        data:
+                            joinOptions.presence,
+                        joinedAt:
+                            timestamp,
+                        updatedAt:
+                            timestamp,
+                    });
+                    await sendPresence(
+                        channel,
+                        "presence.join",
+                        connectionId
+                    );
+                },
+
+                async leave(rawChannel) {
+                    const channel =
+                        normalizeChannel(
+                            rawChannel
+                        );
+                    if (!internal.channels.delete(channel)) {
+                        return;
+                    }
+                    await presence.leave(
+                        channel,
+                        connectionId
+                    );
+                    await sendPresence(
+                        channel,
+                        "presence.leave",
+                        connectionId
+                    );
+                },
+
+                async emit(
+                    rawChannel,
+                    rawEvent,
+                    payload
+                ) {
+                    assertConnected(
+                        internal,
+                        connectionId
+                    );
+                    const channel =
+                        normalizeChannel(
+                            rawChannel
+                        );
+                    if (!internal.channels.has(channel)) {
+                        throw new Error(
+                            `BCP Realtime: connection "${connectionId}" has not joined channel "${channel}".`
+                        );
+                    }
+                    const event =
+                        normalizeEvent(
+                            rawEvent
+                        );
+                    await api.touch();
+                    const group =
+                        handlers.get(event);
+                    if (group) {
+                        for (const handler of group) {
+                            await handler({
+                                connection: api,
+                                channel,
+                                event,
+                                payload,
+                            });
+                        }
+                    }
+                },
+
+                async send(
+                    event,
+                    payload,
+                    channel = "@system"
+                ) {
+                    await sendToConnection(
+                        internal,
+                        createEnvelope(
+                            normalizeChannel(channel),
+                            normalizeEvent(event),
+                            payload
+                        )
+                    );
+                },
+
+                async touch() {
+                    assertConnected(
+                        internal,
+                        connectionId
+                    );
+                    internal.lastSeenAt = now();
+                    await presence.touch(
+                        connectionId,
+                        internal.lastSeenAt
+                    );
+                },
+
+                async disconnect(
+                    code = 1000,
+                    reason = "connection closed"
+                ) {
+                    if (!internal.connected) {
+                        return;
+                    }
+                    internal.connected = false;
+                    connections.delete(
+                        connectionId
+                    );
+                    const channels =
+                        Array.from(
+                            internal.channels
+                        );
+                    internal.channels.clear();
+                    await presence.leaveConnection(
+                        connectionId
+                    );
+                    for (const channel of channels) {
+                        await sendPresence(
+                            channel,
+                            "presence.leave",
+                            connectionId
+                        );
+                    }
+                    for (const cleanup of internal.cleanup.splice(0)) {
+                        cleanup();
+                    }
+                    await internal.socket?.close?.(
+                        code,
+                        reason
+                    );
+                },
+            };
+
+            internal.api = api;
+            connections.set(
+                connectionId,
+                internal
+            );
+
+            if (connectOptions.socket) {
+                bindSocket(
+                    internal,
+                    api
+                );
+            }
+
+            return api;
+        },
+
+        attachSocket(socket, attachOptions = {}) {
+            return hub.connect({
+                ...attachOptions,
+                socket,
+            });
+        },
+
+        async broadcast(
+            channel,
+            event,
+            payload,
+            broadcastOptions = {}
+        ) {
+            await broker.publish(
+                createEnvelope(
+                    normalizeChannel(channel),
+                    normalizeEvent(event),
+                    payload,
+                    broadcastOptions.excludeConnectionId
+                )
+            );
+        },
+
+        subscribe(channel, listener) {
+            const normalized =
+                normalizeChannel(channel);
+            if (typeof listener !== "function") {
+                throw new TypeError(
+                    "BCP Realtime: subscriber must be a function."
+                );
+            }
+            let group =
+                subscriptions.get(normalized);
+            if (!group) {
+                group = new Set();
+                subscriptions.set(
+                    normalized,
+                    group
+                );
+            }
+            group.add(listener);
+            return () => {
+                group?.delete(listener);
+                if (group?.size === 0) {
+                    subscriptions.delete(
+                        normalized
+                    );
+                }
+            };
+        },
+
+        on(event, handler) {
+            const normalized =
+                normalizeEvent(event);
+            if (typeof handler !== "function") {
+                throw new TypeError(
+                    "BCP Realtime: event handler must be a function."
+                );
+            }
+            let group =
+                handlers.get(normalized);
+            if (!group) {
+                group = new Set();
+                handlers.set(
+                    normalized,
+                    group
+                );
+            }
+            group.add(handler);
+            return () => {
+                group?.delete(handler);
+                if (group?.size === 0) {
+                    handlers.delete(normalized);
+                }
+            };
+        },
+
+        members(channel) {
+            return presence.list(
+                normalizeChannel(channel)
+            );
+        },
+
+        connection(id) {
+            return connections.get(
+                normalizeId(id, "connection id")
+            )?.api ?? null;
+        },
+
+        connections() {
+            return Array.from(
+                connections.values(),
+                connection =>
+                    connection.api
+            );
+        },
+
+        async sweepStale() {
+            const cutoff =
+                now() -
+                heartbeatTimeoutMs;
+            const stale =
+                Array.from(
+                    connections.values()
+                ).filter(connection =>
+                    connection.lastSeenAt <= cutoff
+                );
+            for (const connection of stale) {
+                await connection.api.disconnect(
+                    4000,
+                    "heartbeat timeout"
+                );
+            }
+            return stale.length;
+        },
+
+        startHeartbeat(
+            heartbeatOptions = {}
+        ) {
+            const intervalMs =
+                positiveInteger(
+                    heartbeatOptions.intervalMs ??
+                    Math.max(
+                        1_000,
+                        Math.floor(
+                            heartbeatTimeoutMs / 2
+                        )
+                    ),
+                    "heartbeat interval"
+                );
+            let running = true;
+            let stopPromise:
+                Promise<void> | null =
+                null;
+            let timer:
+                ReturnType<typeof setTimeout> |
+                undefined;
+
+            const tick = async () => {
+                if (!running) {
+                    return;
+                }
+                try {
+                    for (const connection of connections.values()) {
+                        await connection.api.send(
+                            "realtime.ping",
+                            {
+                                timestamp: now(),
+                            }
+                        );
+                    }
+                    await hub.sweepStale();
+                } catch (error) {
+                    await reportError(error);
+                }
+                if (running) {
+                    timer =
+                        setTimeout(
+                            tick,
+                            intervalMs
+                        );
+                }
+            };
+
+            timer =
+                setTimeout(
+                    tick,
+                    intervalMs
+                );
+
+            const runner:
+                RealtimeHeartbeatRunner = {
+                get running() {
+                    return running;
+                },
+                stop() {
+                    if (!stopPromise) {
+                        running = false;
+                        if (timer) {
+                            clearTimeout(timer);
+                        }
+                        heartbeatRunners.delete(
+                            runner
+                        );
+                        stopPromise =
+                            Promise.resolve();
+                    }
+                    return stopPromise;
+                },
+            };
+            heartbeatRunners.add(runner);
+            return runner;
+        },
+
+        sse(channel, sseOptions = {}) {
+            return createRealtimeSseResponse(
+                hub,
+                channel,
+                sseOptions
+            );
+        },
+
+        async close() {
+            await Promise.all(
+                Array.from(
+                    heartbeatRunners,
+                    runner => runner.stop()
+                )
+            );
+            await Promise.all(
+                Array.from(
+                    connections.values(),
+                    connection =>
+                        connection.api.disconnect(
+                            1001,
+                            "realtime hub closing"
+                        )
+                )
+            );
+            unsubscribeBroker();
+            subscriptions.clear();
+            handlers.clear();
+            await presence.close?.();
+            await broker.close?.();
+        },
+    };
+
+    return hub;
+
+    function createEnvelope<TPayload>(
+        channel: string,
+        event: string,
+        payload: TPayload,
+        excludeConnectionId?: string
+    ): RealtimeEnvelope<TPayload> {
+        return {
+            id: normalizeId(
+                idFactory(),
+                "message id"
+            ),
+            channel,
+            event,
+            payload,
+            timestamp: now(),
+            sourceId: hubId,
+            excludeConnectionId,
+        };
+    }
+
+    async function dispatchBrokerMessage(
+        message: RealtimeEnvelope
+    ): Promise<void> {
+        const subscribers =
+            subscriptions.get(
+                message.channel
+            );
+        if (subscribers) {
+            for (const listener of subscribers) {
+                try {
+                    await listener(
+                        cloneEnvelope(message)
+                    );
+                } catch (error) {
+                    await reportError(error);
+                }
+            }
+        }
+
+        for (const connection of connections.values()) {
+            if (
+                !connection.connected ||
+                !connection.channels.has(
+                    message.channel
+                ) ||
+                connection.api.id ===
+                    message.excludeConnectionId
+            ) {
+                continue;
+            }
+            try {
+                await sendToConnection(
+                    connection,
+                    message
+                );
+            } catch (error) {
+                await reportError(error);
+            }
+        }
+    }
+
+    async function sendToConnection(
+        connection: InternalConnection<TUser>,
+        message: RealtimeEnvelope
+    ): Promise<void> {
+        if (!connection.connected) {
+            return;
+        }
+        if (!connection.socket) {
+            return;
+        }
+        await connection.socket.send(
+            JSON.stringify({
+                type: "event",
+                ...message,
+            })
+        );
+    }
+
+    async function sendPresence(
+        channel: string,
+        event: string,
+        excludeConnectionId?: string
+    ): Promise<void> {
+        const members =
+            await presence.list(channel);
+        await broker.publish(
+            createEnvelope(
+                channel,
+                event,
+                {
+                    members,
+                },
+                excludeConnectionId
+            )
+        );
+    }
+
+    function bindSocket(
+        internal: InternalConnection<TUser>,
+        connection: RealtimeConnection<TUser>
+    ): void {
+        const socket =
+            internal.socket;
+        if (!socket) {
+            return;
+        }
+
+        internal.cleanup.push(
+            socket.onMessage(
+                async raw => {
+                    try {
+                        const message =
+                            parseSocketMessage(raw);
+                        await connection.touch();
+                        if (message.type === "ping") {
+                            await connection.send(
+                                "realtime.pong",
+                                {
+                                    timestamp: now(),
+                                }
+                            );
+                            return;
+                        }
+                        if (message.type === "join") {
+                            await connection.join(
+                                normalizeChannel(
+                                    message.channel
+                                ),
+                                {
+                                    presence:
+                                        message.presence,
+                                }
+                            );
+                            return;
+                        }
+                        if (message.type === "leave") {
+                            await connection.leave(
+                                normalizeChannel(
+                                    message.channel
+                                )
+                            );
+                            return;
+                        }
+                        if (message.type === "event") {
+                            await connection.emit(
+                                normalizeChannel(
+                                    message.channel
+                                ),
+                                normalizeEvent(
+                                    message.event
+                                ),
+                                message.payload
+                            );
+                            return;
+                        }
+                        throw new Error(
+                            "BCP Realtime: unsupported socket message type."
+                        );
+                    } catch (error) {
+                        await reportError(error);
+                        try {
+                            await connection.send(
+                                "realtime.error",
+                                {
+                                    message:
+                                        formatError(error),
+                                }
+                            );
+                        } catch {
+                            // Preserve the original socket message error.
+                        }
+                    }
+                }
+            )
+        );
+        internal.cleanup.push(
+            socket.onClose(
+                async () => {
+                    await connection.disconnect(
+                        1000,
+                        "socket closed"
+                    );
+                }
+            )
+        );
+        if (socket.onError) {
+            internal.cleanup.push(
+                socket.onError(
+                    async error => {
+                        await reportError(error);
+                    }
+                )
+            );
+        }
+    }
+
+    async function reportError(
+        error: unknown
+    ): Promise<void> {
+        if (options.onError) {
+            await options.onError(error);
+        }
+    }
+}
+
+export function createRealtimeSseResponse(
+    hub: Pick<RealtimeHub, "subscribe">,
+    rawChannel: string,
+    options: RealtimeSseOptions = {}
+): Response {
+    const channel =
+        normalizeChannel(
+            rawChannel
+        );
+    const encoder =
+        new TextEncoder();
+    const eventName =
+        options.event
+            ? normalizeEvent(
+                options.event
+            )
+            : undefined;
+    const retryMs =
+        options.retryMs === undefined
+            ? undefined
+            : positiveInteger(
+                options.retryMs,
+                "SSE retryMs"
+            );
+    const keepAliveMs =
+        positiveInteger(
+            options.keepAliveMs ?? 15_000,
+            "SSE keepAliveMs"
+        );
+
+    const stream =
+        new ReadableStream<Uint8Array>({
+            start(controller) {
+                let closed = false;
+                let timer:
+                    ReturnType<typeof setTimeout> |
+                    undefined;
+                let unsubscribe:
+                    () => void =
+                    () => undefined;
+
+                const close = () => {
+                    if (closed) {
+                        return;
+                    }
+                    closed = true;
+                    if (timer) {
+                        clearTimeout(timer);
+                    }
+                    unsubscribe();
+                    try {
+                        controller.close();
+                    } catch {
+                        // Stream may already be closed by the runtime.
+                    }
+                };
+
+                const write = (
+                    value: string
+                ) => {
+                    if (!closed) {
+                        controller.enqueue(
+                            encoder.encode(value)
+                        );
+                    }
+                };
+
+                if (retryMs !== undefined) {
+                    write(
+                        `retry: ${retryMs}\n\n`
+                    );
+                }
+                write(
+                    ": connected\n\n"
+                );
+
+                unsubscribe =
+                    hub.subscribe(
+                        channel,
+                        message => {
+                            if (
+                                eventName &&
+                                message.event !== eventName
+                            ) {
+                                return;
+                            }
+                            write(
+                                serializeSseMessage(
+                                    message
+                                )
+                            );
+                        }
+                    );
+
+                const keepAlive = () => {
+                    if (closed) {
+                        return;
+                    }
+                    write(
+                        `: keep-alive ${Date.now()}\n\n`
+                    );
+                    timer =
+                        setTimeout(
+                            keepAlive,
+                            keepAliveMs
+                        );
+                };
+                timer =
+                    setTimeout(
+                        keepAlive,
+                        keepAliveMs
+                    );
+
+                if (options.signal) {
+                    if (options.signal.aborted) {
+                        close();
+                        return;
+                    }
+                    options.signal.addEventListener(
+                        "abort",
+                        close,
+                        {
+                            once: true,
+                        }
+                    );
+                }
+            },
+        });
+
+    const headers =
+        new Headers(
+            options.headers
+        );
+    headers.set(
+        "Content-Type",
+        "text/event-stream; charset=utf-8"
+    );
+    headers.set(
+        "Cache-Control",
+        "no-cache, no-transform"
+    );
+    headers.set(
+        "Connection",
+        "keep-alive"
+    );
+    headers.set(
+        "X-Accel-Buffering",
+        "no"
+    );
+
+    return new Response(
+        stream,
+        {
+            status: 200,
+            headers,
+        }
+    );
+}
+
+function serializeSseMessage(
+    message: RealtimeEnvelope
+): string {
+    const payload =
+        JSON.stringify({
+            id: message.id,
+            channel: message.channel,
+            event: message.event,
+            payload: message.payload,
+            timestamp: message.timestamp,
+        });
+    return `id: ${escapeSse(message.id)}\nevent: ${escapeSse(message.event)}\ndata: ${payload}\n\n`;
+}
+
+function parseSocketMessage(
+    raw: string
+): SocketClientMessage {
+    if (typeof raw !== "string") {
+        throw new TypeError(
+            "BCP Realtime: socket messages must be UTF-8 strings."
+        );
+    }
+    let parsed:
+        unknown;
+    try {
+        parsed =
+            JSON.parse(raw);
+    } catch {
+        throw new Error(
+            "BCP Realtime: socket message must be valid JSON."
+        );
+    }
+    if (
+        !parsed ||
+        typeof parsed !== "object" ||
+        Array.isArray(parsed)
+    ) {
+        throw new Error(
+            "BCP Realtime: socket message must be an object."
+        );
+    }
+    return parsed as SocketClientMessage;
+}
+
+function cloneEnvelope<TPayload>(
+    message: RealtimeEnvelope<TPayload>
+): RealtimeEnvelope<TPayload> {
+    return {
+        ...message,
+    };
+}
+
+function clonePresence<TData>(
+    member: RealtimePresenceMember<TData>
+): RealtimePresenceMember<TData> {
+    return {
+        ...member,
+    };
+}
+
+function presenceKey(
+    channel: string,
+    connectionId: string
+): string {
+    return `${channel}\u0000${connectionId}`;
+}
+
+function normalizeChannel(
+    value: unknown
+): string {
+    const channel =
+        String(value ?? "").trim();
+    if (!channel) {
+        throw new TypeError(
+            "BCP Realtime: channel must be a non-empty string."
+        );
+    }
+    if (channel.length > 200) {
+        throw new TypeError(
+            "BCP Realtime: channel must not exceed 200 characters."
+        );
+    }
+    return channel;
+}
+
+function normalizeEvent(
+    value: unknown
+): string {
+    const event =
+        String(value ?? "").trim();
+    if (!event) {
+        throw new TypeError(
+            "BCP Realtime: event must be a non-empty string."
+        );
+    }
+    if (event.length > 200) {
+        throw new TypeError(
+            "BCP Realtime: event must not exceed 200 characters."
+        );
+    }
+    return event;
+}
+
+function normalizeId(
+    value: unknown,
+    field: string
+): string {
+    const id =
+        String(value ?? "").trim();
+    if (!id) {
+        throw new TypeError(
+            `BCP Realtime: ${field} must be a non-empty string.`
+        );
+    }
+    return id;
+}
+
+function optionalId(
+    value: unknown
+): string | undefined {
+    if (
+        value === undefined ||
+        value === null
+    ) {
+        return undefined;
+    }
+    const id =
+        String(value).trim();
+    return id || undefined;
+}
+
+function positiveInteger(
+    value: number,
+    field: string
+): number {
+    if (
+        !Number.isInteger(value) ||
+        value <= 0
+    ) {
+        throw new TypeError(
+            `BCP Realtime: ${field} must be a positive integer.`
+        );
+    }
+    return value;
+}
+
+function assertFiniteNumber(
+    value: number,
+    field: string
+): void {
+    if (!Number.isFinite(value)) {
+        throw new TypeError(
+            `BCP Realtime: ${field} must be a finite number.`
+        );
+    }
+}
+
+function assertConnected<TUser>(
+    connection: InternalConnection<TUser>,
+    id: string
+): void {
+    if (!connection.connected) {
+        throw new Error(
+            `BCP Realtime: connection "${id}" is closed.`
+        );
+    }
+}
+
+function escapeSse(
+    value: string
+): string {
+    return value.replace(
+        /[\r\n]/g,
+        ""
+    );
+}
+
+function formatError(
+    error: unknown
+): string {
+    if (error instanceof Error) {
+        return error.message || error.name;
+    }
+    if (typeof error === "string") {
+        return error;
+    }
+    try {
+        return JSON.stringify(error) ??
+            String(error);
+    } catch {
+        return String(error);
+    }
+}