orpc-fn 0.1.0 → 0.2.0

package/dist/live/pub-sub.js

@@ -1,6 +1,7 @@
 import { ORPCError } from '@orpc/server';
 import { errorMessageOf } from '../otel.js';
-import { decodePayload, encodePayload } from './codec.js';
+import { decodeMessage, encodePayload } from './codec.js';
+import { LIVE_GAP, positiveInteger, safely, waitFor } from './lifecycle.js';
 // ═══════════════════════════════════════════════════════════════════════════
 // Bounded queue
 // ═══════════════════════════════════════════════════════════════════════════
@@ -22,6 +23,7 @@ import { decodePayload, encodePayload } from './codec.js';
  * drop-oldest with the new event enqueued.
  */
 export function createBoundedEventQueue(opts) {
+    positiveInteger(opts.maxSize, 'maxSize');
     const items = [];
     // The queued marker while an overflow episode is open. Created once per
     // episode, so identity is the exact "is this the pending marker?" test.
@@ -31,35 +33,41 @@ export function createBoundedEventQueue(opts) {
             return items.length;
         },
         enqueue(data) {
-            if (items.length >= opts.maxSize) {
-                if (pendingOverflowMarker !== null) {
-                    // Episode already signalled: drop the oldest non-marker message
-                    // and enqueue WITHOUT a second marker.
-                    const dropIndex = items[0] === pendingOverflowMarker ? 1 : 0;
-                    if (dropIndex >= items.length) {
-                        // Degenerate maxSize: the queue is just the pending marker, so
-                        // the new event is the drop - the marker's resync covers it.
-                        opts.onDrop?.();
+            try {
+                if (items.length >= opts.maxSize) {
+                    if (pendingOverflowMarker !== null) {
+                        // Episode already signalled: drop the oldest non-marker message
+                        // and enqueue WITHOUT a second marker.
+                        const dropIndex = items[0] === pendingOverflowMarker ? 1 : 0;
+                        if (dropIndex >= items.length) {
+                            // Degenerate maxSize: the queue is just the pending marker, so
+                            // the new event is the drop - the marker's resync covers it.
+                            safely(opts.onDrop);
+                            return;
+                        }
+                        items.splice(dropIndex, 1);
+                        safely(opts.onDrop);
+                        items.push(data);
+                        return;
+                    }
+                    items.shift();
+                    safely(opts.onDrop);
+                    const marker = opts.createOverflowMarker?.() ?? null;
+                    if (marker !== null) {
+                        pendingOverflowMarker = marker;
+                        items.push(marker);
                         return;
                     }
-                    items.splice(dropIndex, 1);
-                    opts.onDrop?.();
-                    items.push(data);
-                    return;
-                }
-                items.shift();
-                opts.onDrop?.();
-                const marker = opts.createOverflowMarker?.() ?? null;
-                if (marker !== null) {
-                    pendingOverflowMarker = marker;
-                    items.push(marker);
-                    return;
                 }
+                items.push(data);
+            }
+            finally {
+                safely(() => opts.onDepth?.(items.length));
             }
-            items.push(data);
         },
         dequeue() {
             const next = items.shift();
+            safely(() => opts.onDepth?.(items.length));
             if (next !== undefined && next === pendingOverflowMarker) {
                 pendingOverflowMarker = null;
             }
@@ -81,9 +89,11 @@ export function createSubscriberDelivery(options) {
             const marker = options.overflowMarker?.() ?? null;
             return marker === null ? null : { data: marker, marker: true };
         },
-        onDrop: options.onDrop
+        onDrop: options.onDrop,
+        ...(options.onDepth ? { onDepth: options.onDepth } : {})
     });
     let closed = false;
+    let failure;
     let wake = null;
     const notify = () => {
         wake?.();
@@ -104,7 +114,7 @@ export function createSubscriberDelivery(options) {
                         continue;
                 }
                 catch (error) {
-                    options.onFilterError(error);
+                    safely(() => options.onFilterError(error));
                     continue;
                 }
                 if (closed)
@@ -112,18 +122,24 @@ export function createSubscriberDelivery(options) {
             }
             yield item.data;
         }
+        if (failure !== undefined)
+            throw failure;
     }
     return {
-        push(data) {
+        push(data, marker = false) {
             if (closed)
                 return;
-            queue.enqueue({ data, marker: false });
+            queue.enqueue({ data, marker });
             notify();
         },
         events: events(),
         /** Stop delivering; a parked read ends at once. */
-        close() {
+        close(error) {
+            if (closed)
+                return;
+            failure = error;
             closed = true;
+            safely(() => options.onDepth?.(0));
             notify();
         }
     };
@@ -140,11 +156,48 @@ function getResubscribeDelayMs(attempt) {
     const base = Math.min(RESUBSCRIBE_BASE_DELAY_MS * 2 ** attempt, RESUBSCRIBE_MAX_DELAY_MS);
     return base + Math.floor(Math.random() * RESUBSCRIBE_MAX_JITTER_MS);
 }
-const resolveChannel = (channel, params, context) => (typeof channel === 'string' ? channel : channel(params, context));
+const resolveChannel = (channel, params, context, publishing = false) => {
+    if (typeof channel === 'string')
+        return channel;
+    if (typeof channel === 'function')
+        return channel(params, context);
+    return publishing
+        ? channel.publish(params)
+        : channel.subscribe({ input: params, context });
+};
 /** @internal */
 export function createLiveRuntime(options) {
     const { tracing, createLogger } = options;
     const logger = createLogger('pubsub', undefined);
+    let terminated = false;
+    let shutdownPromise;
+    const releases = new Set();
+    const pendingInitialization = new Set();
+    const pendingOpens = new Set();
+    const defaultMaxQueue = positiveInteger(options.pubsub?.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE, 'maxQueueSize');
+    const defaultMaxIngress = positiveInteger(options.pubsub?.maxIngressSize ?? defaultMaxQueue, 'maxIngressSize');
+    const defaultMaxReplay = positiveInteger(options.pubsub?.maxReplaySize ?? defaultMaxQueue, 'maxReplaySize');
+    const initializationTimeout = positiveInteger(options.pubsub?.initializationTimeoutMs ?? 10000, 'initializationTimeoutMs');
+    const metric = (event) => safely(() => options.pubsub?.onMetric?.(event));
+    const namespace = options.pubsub?.namespace;
+    const qualify = (name) => (namespace ? `${namespace}:${name}` : name);
+    const assertOpen = () => {
+        if (terminated)
+            throw new ORPCError('SERVICE_UNAVAILABLE', {
+                message: 'Live runtime has shut down'
+            });
+    };
+    const releaseTransport = (release) => {
+        if (!release)
+            return;
+        const task = Promise.resolve(release()).catch((error) => {
+            logger.warn('Failed to release subscription', {
+                error: errorMessageOf(error)
+            });
+        });
+        releases.add(task);
+        void task.finally(() => releases.delete(task));
+    };
     // Deploy drain: every open subscription registers its close here. On
     // SIGTERM the app ends them deliberately instead of letting the socket die
     // with the process: the generator returns, oRPC closes the SSE response and
@@ -162,7 +215,14 @@ export function createLiveRuntime(options) {
      * backlog when enabled) inside a producer span.
      */
     function createChannelPublisher(config) {
-        const { name, eventSchema, getChannelName, mirrorChannel } = config;
+        const { name, eventSchema, getChannelName } = config;
+        const mirrorChannel = config.mirrorChannel
+            ? qualify(config.mirrorChannel)
+            : undefined;
+        if (config.backlogSize !== undefined)
+            positiveInteger(config.backlogSize, 'backlogSize');
+        if (config.backlogTtl !== undefined)
+            positiveInteger(config.backlogTtl, 'backlogTtl');
         const backlog = config.useBacklog
             ? { size: config.backlogSize ?? 50, ttlSeconds: config.backlogTtl ?? 30 }
             : undefined;
@@ -180,6 +240,7 @@ export function createLiveRuntime(options) {
             return messages;
         };
         const send = (operation, items) => tracing.inSpan(`${name}:${operation}`, 'PRODUCER', async (span) => {
+            assertOpen();
             const startTime = performance.now();
             try {
                 span?.setAttribute('pubsub.operation', operation);
@@ -222,38 +283,88 @@ export function createLiveRuntime(options) {
             let attempt = 0;
             let timer = null;
             let markReady = () => { };
-            const ready = new Promise((resolve) => {
-                markReady = resolve;
-            });
-            // Parse in arrival order even when the schema is async.
-            // ponytail: unbounded while an async schema lags behind the broker;
-            // bound it if a channel can outpace its schema.
-            let parsing = Promise.resolve();
-            const deliver = async (raw) => {
-                let parsed;
-                try {
-                    parsed = await eventSchema.parseAsync(decodePayload(raw));
-                }
-                catch (error) {
-                    // Malformed payloads are dropped once for the whole channel.
-                    logger.warn(`Dropped malformed message on ${channel}`, {
-                        error: errorMessageOf(error)
+            let connectedOnce = false;
+            let connected = false;
+            let ready;
+            const markPending = () => {
+                ready = new Promise((resolve) => {
+                    markReady = resolve;
+                });
+            };
+            markPending();
+            let parsing = false;
+            const ingress = createBoundedEventQueue({
+                maxSize: config.maxIngress,
+                onDepth: (depth) => metric({
+                    type: 'queue',
+                    stage: 'ingress',
+                    depth,
+                    limit: config.maxIngress,
+                    name: config.name,
+                    channel
+                }),
+                onDrop: () => {
+                    metric({
+                        type: 'drop',
+                        stage: 'ingress',
+                        count: 1,
+                        name: config.name,
+                        channel
                     });
+                    safely(() => options.pubsub?.onDrop?.(1, { name: config.name, channel }));
+                    for (const sub of [...subscribers]) {
+                        try {
+                            sub.gap();
+                        }
+                        catch (error) {
+                            safely(() => sub.fail(error));
+                        }
+                    }
+                }
+            });
+            const parsePending = async () => {
+                if (parsing)
                     return;
+                parsing = true;
+                try {
+                    while (!closed) {
+                        const raw = ingress.dequeue();
+                        if (raw === undefined)
+                            break;
+                        try {
+                            const message = decodeMessage(raw);
+                            const parsed = await eventSchema.parseAsync(message.value);
+                            if (closed)
+                                break;
+                            for (const sub of [...subscribers])
+                                if (sub.isActive()) {
+                                    try {
+                                        sub.push(parsed, message.id);
+                                    }
+                                    catch (error) {
+                                        safely(() => sub.fail(error));
+                                    }
+                                }
+                        }
+                        catch (error) {
+                            metric({
+                                type: 'parseError',
+                                stage: 'ingress',
+                                error,
+                                name: config.name,
+                                channel
+                            });
+                            logger.warn(`Dropped malformed message on ${channel}`, {
+                                error: errorMessageOf(error)
+                            });
+                        }
+                    }
                 }
-                // Parsed once; each subscriber filters in its own delivery.
-                for (const sub of [...subscribers]) {
-                    if (sub.isActive())
-                        sub.push(parsed);
+                finally {
+                    parsing = false;
                 }
             };
-            const release = (stale) => {
-                stale?.().catch((error) => {
-                    logger.warn(`Failed to unsubscribe from ${channel}`, {
-                        error: errorMessageOf(error)
-                    });
-                });
-            };
+            const release = releaseTransport;
             const scheduleResubscribe = (reason) => {
                 if (closed || timer)
                     return;
@@ -276,16 +387,51 @@ export function createLiveRuntime(options) {
             const connect = async () => {
                 try {
                     const next = await requireTransport().subscribe(channel, (raw) => {
-                        parsing = parsing.then(() => deliver(raw));
+                        if (closed)
+                            return;
+                        ingress.enqueue(raw);
+                        void parsePending();
                     }, (error) => {
+                        if (connected) {
+                            connected = false;
+                            markPending();
+                        }
                         logger.error(`Subscription to ${channel} lost`, {
                             error: error.message
                         });
                         scheduleResubscribe('lost');
+                    }, {
+                        onReconnect: () => {
+                            if (closed)
+                                return;
+                            metric({ type: 'reconnect', name: config.name, channel });
+                            for (const sub of [...subscribers]) {
+                                try {
+                                    sub.gap();
+                                }
+                                catch (error) {
+                                    safely(() => sub.fail(error));
+                                }
+                            }
+                        }
                     });
                     if (closed)
                         return release(next);
                     unsubscribe = next;
+                    connected = true;
+                    if (connectedOnce) {
+                        metric({ type: 'reconnect', name: config.name, channel });
+                        for (const sub of [...subscribers]) {
+                            try {
+                                sub.gap();
+                            }
+                            catch (error) {
+                                safely(() => sub.fail(error));
+                            }
+                        }
+                    }
+                    connectedOnce = true;
+                    markReady();
                     attempt = 0;
                     logger.info(`Subscribed to ${channel}`);
                 }
@@ -295,18 +441,23 @@ export function createLiveRuntime(options) {
                     });
                     scheduleResubscribe('subscribe-failed');
                 }
-                finally {
-                    // A failed first attempt must not hold subscribers forever; the
-                    // backoff keeps retrying in the background.
-                    markReady();
-                }
             };
             void connect();
             return {
                 subscribers,
-                ready,
+                get ready() {
+                    return ready;
+                },
                 close: () => {
                     closed = true;
+                    metric({
+                        type: 'queue',
+                        stage: 'ingress',
+                        depth: 0,
+                        limit: config.maxIngress,
+                        name: config.name,
+                        channel
+                    });
                     if (timer)
                         clearTimeout(timer);
                     timer = null;
@@ -339,9 +490,20 @@ export function createLiveRuntime(options) {
     /** Publish and open subscriptions on one channel definition. */
     function createChannel(channelOptions) {
         const { name, channel, eventSchema, filterFn, authFn, overflowMarker, useBacklog = false } = channelOptions;
-        const getChannelName = (params, context) => resolveChannel(channel, params, context);
-        const addLocalSubscriber = createChannelHubs({ eventSchema });
-        const open = async ({ input, context, signal }) => {
+        const getChannelName = (params, context) => qualify(resolveChannel(channel, params, context));
+        const getPublishChannel = (params) => qualify(resolveChannel(channel, params, undefined, true));
+        const maxQueue = positiveInteger(channelOptions.maxQueueSize ?? defaultMaxQueue, 'maxQueueSize');
+        const maxIngress = positiveInteger(channelOptions.maxIngressSize ?? defaultMaxIngress, 'maxIngressSize');
+        const maxReplay = positiveInteger(channelOptions.maxReplaySize ?? defaultMaxReplay, 'maxReplaySize');
+        const addLocalSubscriber = createChannelHubs({
+            eventSchema,
+            name,
+            maxIngress
+        });
+        const openInternal = async ({ input, context, signal, recoverGaps = false }) => {
+            assertOpen();
+            signal?.throwIfAborted();
+            const initializing = new AbortController();
             const transport = requireTransport();
             const channelName = getChannelName(input, context);
             const startTime = performance.now();
@@ -351,16 +513,24 @@ export function createLiveRuntime(options) {
                 'pubsub.name': name
             });
             const subscriberLogger = createLogger('pubsub', span);
+            const cancelInitialization = () => initializing.abort(signal?.reason ?? new Error('Subscription initialization stopped'));
+            pendingInitialization.add(cancelInitialization);
+            signal?.addEventListener('abort', cancelInitialization, { once: true });
+            const finishInitialization = () => {
+                pendingInitialization.delete(cancelInitialization);
+                signal?.removeEventListener('abort', cancelInitialization);
+            };
             try {
                 if (authFn !== undefined &&
                     authFn !== true &&
-                    !(await authFn({ input, ctx: context }))) {
+                    !(await waitFor(Promise.resolve(authFn({ input, ctx: context })), initializationTimeout, initializing.signal))) {
                     throw new ORPCError('FORBIDDEN', {
                         message: 'You do not have access to this subscription'
                     });
                 }
             }
             catch (error) {
+                finishInitialization();
                 tracing.end(span, error);
                 throw error;
             }
@@ -368,27 +538,98 @@ export function createLiveRuntime(options) {
             let messageCount = 0;
             let droppedCount = 0;
             const delivery = createSubscriberDelivery({
-                maxSize: options.pubsub?.maxQueueSize ?? DEFAULT_MAX_QUEUE_SIZE,
-                accept: filterFn && ((data) => filterFn({ input, data })),
-                overflowMarker: overflowMarker && (() => overflowMarker(input)),
+                maxSize: maxQueue,
+                onDepth: (depth) => metric({
+                    type: 'queue',
+                    stage: 'delivery',
+                    depth,
+                    limit: maxQueue,
+                    name,
+                    channel: channelName
+                }),
+                accept: filterFn &&
+                    ((data) => (data === LIVE_GAP ? true : filterFn({ input, data }))),
+                overflowMarker: recoverGaps
+                    ? () => LIVE_GAP
+                    : overflowMarker && (() => overflowMarker(input)),
                 onFilterError: (error) => subscriberLogger.error('Error processing message', {
                     error: errorMessageOf(error)
                 }),
                 onDrop: () => {
                     droppedCount++;
-                    options.pubsub?.onDrop?.(1, { name, channel: channelName });
+                    metric({
+                        type: 'drop',
+                        stage: 'delivery',
+                        count: 1,
+                        name,
+                        channel: channelName
+                    });
+                    safely(() => options.pubsub?.onDrop?.(1, { name, channel: channelName }));
+                    if (!recoverGaps && !overflowMarker)
+                        queueMicrotask(() => close(new ORPCError('SERVICE_UNAVAILABLE', {
+                            message: 'Subscription queue overflow; reconnect and resync'
+                        })));
                 }
             });
-            // Live events wait here while the backlog replays, so replay comes first.
-            // ponytail: unbounded for the length of one backlog read.
             let replaying = useBacklog ? [] : null;
-            const push = (data) => {
+            let replayGap = false;
+            const seen = new Set();
+            const dedupe = (id) => {
+                if (!id)
+                    return false;
+                if (seen.has(id))
+                    return true;
+                seen.add(id);
+                if (seen.size >
+                    Math.max(maxReplay, maxQueue, channelOptions.backlogSize ?? 50) * 2)
+                    seen.delete(seen.values().next().value);
+                return false;
+            };
+            const push = (data, id) => {
                 messageCount++;
-                if (replaying)
-                    replaying.push(data);
-                else
+                if (replaying) {
+                    if (replaying.length >= maxReplay) {
+                        replaying.shift();
+                        replayGap = true;
+                        metric({
+                            type: 'drop',
+                            stage: 'replay',
+                            count: 1,
+                            name,
+                            channel: channelName
+                        });
+                        safely(() => options.pubsub?.onDrop?.(1, { name, channel: channelName }));
+                    }
+                    replaying.push({ data, id });
+                    metric({
+                        type: 'queue',
+                        stage: 'replay',
+                        depth: replaying.length,
+                        limit: maxReplay,
+                        name,
+                        channel: channelName
+                    });
+                }
+                else if (!dedupe(id))
                     delivery.push(data);
             };
+            const gap = () => {
+                if (replaying) {
+                    replayGap = true;
+                    return;
+                }
+                if (recoverGaps)
+                    delivery.push(LIVE_GAP);
+                else if (overflowMarker) {
+                    const marker = overflowMarker(input);
+                    if (marker !== null)
+                        delivery.push(marker, true);
+                }
+                else
+                    close(new ORPCError('SERVICE_UNAVAILABLE', {
+                        message: 'Subscription lost events; reconnect and resync'
+                    }));
+            };
             // The one way a subscription ends, whatever ends it: abort, drain, the
             // stream finishing, or `close()`. Releases everything at once, even
             // while the stream is parked or not yet read.
@@ -397,7 +638,8 @@ export function createLiveRuntime(options) {
                 if (closed)
                     return;
                 closed = true;
-                delivery.close();
+                initializing.abort(error[0] ?? new Error('Subscription closed'));
+                delivery.close(error[0]);
                 activeSubscriberCleanups.delete(stop);
                 signal?.removeEventListener('abort', stop);
                 local.remove();
@@ -415,45 +657,76 @@ export function createLiveRuntime(options) {
             const stop = () => close();
             const local = addLocalSubscriber(channelName, {
                 isActive: () => !closed,
-                push
+                push,
+                gap,
+                fail: (error) => close(error)
             });
             activeSubscriberCleanups.add(stop);
             signal?.addEventListener('abort', stop);
             if (signal?.aborted)
                 close();
-            // Subscribed before returning, so nothing published after `open`
-            // resolves is missed.
-            // ponytail: a failed first attempt also settles `ready` (the hub keeps
-            // retrying); events published before a retry succeeds are lost.
-            await local.ready;
-            if (replaying && !closed) {
-                try {
-                    const items = await transport.readBacklog(channelName);
-                    span?.setAttribute('pubsub.backlog_count', items.length);
-                    for (const raw of items) {
-                        if (closed)
-                            break;
-                        try {
-                            messageCount++;
-                            delivery.push(await eventSchema.parseAsync(decodePayload(raw)));
-                        }
-                        catch {
-                            // Ignore malformed backlog entries
+            try {
+                await waitFor(local.ready, initializationTimeout, initializing.signal);
+                if (replaying && !closed) {
+                    try {
+                        const items = await waitFor(transport.readBacklog(channelName), initializationTimeout, initializing.signal);
+                        span?.setAttribute('pubsub.backlog_count', items.length);
+                        for (const raw of items.slice(-maxReplay)) {
+                            if (closed)
+                                break;
+                            try {
+                                const message = decodeMessage(raw);
+                                if (!dedupe(message.id)) {
+                                    messageCount++;
+                                    delivery.push(await waitFor(eventSchema.parseAsync(message.value), initializationTimeout, initializing.signal));
+                                }
+                            }
+                            catch (error) {
+                                metric({
+                                    type: 'parseError',
+                                    stage: 'replay',
+                                    error,
+                                    name,
+                                    channel: channelName
+                                });
+                                /* Malformed backlog entries are skipped. */
+                            }
                         }
+                        if (items.length > maxReplay)
+                            replayGap = true;
+                    }
+                    catch (error) {
+                        replayGap = true;
+                        subscriberLogger.warn(`Failed to replay backlog for ${channelName}`, { error: errorMessageOf(error) });
                     }
                 }
-                catch (error) {
-                    // Live events still flow; only the backlog replay is lost.
-                    subscriberLogger.warn(`Failed to replay backlog for ${channelName}`, {
-                        error: errorMessageOf(error)
+                for (const { data, id } of replaying ?? [])
+                    if (!dedupe(id))
+                        delivery.push(data);
+                replaying = null;
+                metric({
+                    type: 'queue',
+                    stage: 'replay',
+                    depth: 0,
+                    limit: maxReplay,
+                    name,
+                    channel: channelName
+                });
+                if (replayGap && !closed)
+                    gap();
+            }
+            catch (error) {
+                if (!closed) {
+                    close(error);
+                    throw new ORPCError('SERVICE_UNAVAILABLE', {
+                        message: 'Unable to establish subscription',
+                        cause: error
                     });
                 }
             }
-            // ponytail: an event both in the backlog and arriving live is delivered
-            // twice; events carry no id to dedupe on.
-            for (const data of replaying ?? [])
-                delivery.push(data);
-            replaying = null;
+            finally {
+                finishInitialization();
+            }
             async function* events() {
                 try {
                     yield* delivery.events;
@@ -462,39 +735,54 @@ export function createLiveRuntime(options) {
                     close();
                 }
             }
-            return { events: events(), close: () => close() };
+            return { events: events(), close: () => close(), isClosed: () => closed };
         };
         const { publish, publishMany } = createChannelPublisher({
             ...channelOptions,
-            getChannelName
+            getChannelName: getPublishChannel
         });
-        return { open, publish, publishMany, getChannelName };
+        const open = (params) => {
+            const task = openInternal(params);
+            pendingOpens.add(task);
+            void task.then(() => pendingOpens.delete(task), () => pendingOpens.delete(task));
+            return task;
+        };
+        return {
+            open,
+            publish,
+            publishMany,
+            getChannelName,
+            getSubscriptionChannelName: ({ input, context }) => getChannelName(input, context),
+            getPublishChannelName: getPublishChannel
+        };
     }
     function createPubSub(pubsubOptions) {
         const { name } = pubsubOptions;
         const channel = createChannel(pubsubOptions);
-        const subscribe = options.buildProcedure({
+        const { channel: _channel, eventSchema: _eventSchema, inputSchema, filterFn: _filterFn, authFn: _authFn, overflowMarker: _overflowMarker, useBacklog: _useBacklog, backlogSize: _backlogSize, backlogTtl: _backlogTtl, mirrorChannel: _mirrorChannel, maxQueueSize: _maxQueueSize, maxIngressSize: _maxIngressSize, maxReplaySize: _maxReplaySize, ...routeOptions } = pubsubOptions;
+        const subscribe = options.fn({
+            ...routeOptions,
             name,
-            procedure: pubsubOptions.procedure,
-            meta: {},
-            route: {
-                method: 'GET',
-                tags: pubsubOptions.tags,
-                summary: pubsubOptions.summary ?? `Subscribe to ${name}`,
-                description: pubsubOptions.description
-            },
-            input: pubsubOptions.inputSchema,
+            stream: true,
+            method: 'GET',
+            input: inputSchema,
+            summary: pubsubOptions.summary ?? `Subscribe to ${name}`,
             handler: async function* ({ input, context, signal }) {
-                // The generator from `events()` releases everything when it ends.
-                yield* (await channel.open({ input: input, context, signal }))
-                    .events;
+                yield* (await channel.open({ input, context, signal })).events;
             }
         });
         const { publish, publishMany, getChannelName } = channel;
-        return { subscribe, publish, publishMany, getChannelName };
+        return {
+            subscribe,
+            publish,
+            publishMany,
+            getChannelName,
+            getSubscriptionChannelName: channel.getSubscriptionChannelName,
+            getPublishChannelName: channel.getPublishChannelName
+        };
     }
     function createPublisher(publisherOptions) {
-        const getChannelName = (params) => resolveChannel(publisherOptions.channel, params);
+        const getChannelName = (params) => qualify(resolveChannel(publisherOptions.channel, params, undefined, true));
         const { publish, publishMany } = createChannelPublisher({
             ...publisherOptions,
             getChannelName
@@ -503,6 +791,22 @@ export function createLiveRuntime(options) {
     }
     return {
         createChannel,
+        shutdown: () => {
+            if (shutdownPromise)
+                return shutdownPromise;
+            terminated = true;
+            for (const cancel of [...pendingInitialization])
+                safely(cancel);
+            for (const cleanup of [...activeSubscriberCleanups])
+                safely(cleanup);
+            shutdownPromise = (async () => {
+                await Promise.allSettled([...pendingOpens]);
+                await Promise.all([...releases]);
+                if (options.pubsub?.ownsTransport)
+                    await options.pubsub.transport.close?.();
+            })();
+            return shutdownPromise;
+        },
         createPubSub,
         createPublisher,
         /** Open subscriptions of this instance (drain progress, gauges). */