orpc-fn 0.3.0 → 0.5.0

package/src/live/pub-sub.ts

@@ -2,7 +2,12 @@ import type { Schema } from '@orpc/contract'
 import { ORPCError } from '@orpc/server'
 import type { ZodObject, ZodRawShape, ZodType, z } from 'zod'
 import type { FnLogger } from '../logger.js'
-import { errorMessageOf, type SpanLike, type Tracing } from '../otel.js'
+import {
+	errorAttributes,
+	errorMessageOf,
+	type SpanLike,
+	type Tracing
+} from '../otel.js'
 import type {
 	GuardOptions,
 	FnContext,
@@ -79,6 +84,11 @@ export type PublisherConfig = {
 	 * channel means no duplicate work.
 	 */
 	mirrorChannel?: string
+	/**
+	 * Log publish failures (validation or broker) instead of throwing them, so
+	 * a publish after a committed write cannot fail the request. No retry.
+	 */
+	safePublish?: boolean
 }
 
 /** Per-definition overrides of the factory queue bounds. */
@@ -607,10 +617,25 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 				}
 			})
 
+		const guarded = async (
+			operation: 'publish' | 'publishMany',
+			items: readonly unknown[]
+		) => {
+			if (!config.safePublish) return send(operation, items)
+			try {
+				await send(operation, items)
+			} catch (error) {
+				logger.error('pubsub.publish_failed', {
+					name,
+					...errorAttributes(error)
+				})
+			}
+		}
+
 		return {
-			publish: (data: unknown) => send('publish', [data]),
+			publish: (data: unknown) => guarded('publish', [data]),
 			publishMany: async (items: readonly unknown[]) => {
-				if (items.length > 0) await send('publishMany', items)
+				if (items.length > 0) await guarded('publishMany', items)
 			}
 		}
 	}
@@ -706,8 +731,9 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 								name: config.name,
 								channel
 							})
-							logger.warn(`Dropped malformed message on ${channel}`, {
-								error: errorMessageOf(error)
+							logger.warn('pubsub.message_dropped', {
+								channel,
+								...errorAttributes(error)
 							})
 						}
 					}
@@ -721,7 +747,8 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 				if (closed || timer) return
 				const delayMs = getResubscribeDelayMs(attempt)
 				attempt++
-				logger.warn(`Scheduling resubscribe for ${channel}`, {
+				logger.warn('pubsub.resubscribe_scheduled', {
+					channel,
 					reason,
 					attempt,
 					delayMs
@@ -749,8 +776,9 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 								connected = false
 								markPending()
 							}
-							logger.error(`Subscription to ${channel} lost`, {
-								error: error.message
+							logger.error('pubsub.subscription_lost', {
+								channel,
+								...errorAttributes(error)
 							})
 							scheduleResubscribe('lost')
 						},
@@ -784,10 +812,11 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 					connectedOnce = true
 					markReady()
 					attempt = 0
-					logger.info(`Subscribed to ${channel}`)
+					logger.debug('pubsub.subscribed', { channel })
 				} catch (error) {
-					logger.error(`Failed to subscribe to ${channel}`, {
-						error: errorMessageOf(error)
+					logger.error('pubsub.subscribe_failed', {
+						channel,
+						...errorAttributes(error)
 					})
 					scheduleResubscribe('subscribe-failed')
 				}
@@ -926,7 +955,7 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 				throw error
 			}
 
-			subscriberLogger.info(`Subscribing to ${channelName}`)
+			subscriberLogger.debug('pubsub.subscribing', { channel: channelName })
 
 			let messageCount = 0
 			let droppedCount = 0
@@ -1051,7 +1080,8 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 				span?.setAttribute('pubsub.message_count', messageCount)
 				span?.setAttribute('pubsub.dropped_count', droppedCount)
 				tracing.end(span, ...error)
-				subscriberLogger.info(`Unsubscribed from ${channelName}`, {
+				subscriberLogger.debug('pubsub.unsubscribed', {
+					channel: channelName,
 					messageCount,
 					droppedCount,
 					durationMs: Math.round(durationMs)
@@ -1106,10 +1136,10 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 						if (items.length > maxReplay) replayGap = true
 					} catch (error) {
 						replayGap = true
-						subscriberLogger.warn(
-							`Failed to replay backlog for ${channelName}`,
-							{ error: errorMessageOf(error) }
-						)
+						subscriberLogger.warn('pubsub.replay_failed', {
+							channel: channelName,
+							...errorAttributes(error)
+						})
 					}
 				}
 				for (const { data, id } of replaying ?? [])
@@ -1195,6 +1225,7 @@ export function createLiveRuntime(options: LiveRuntimeOptions) {
 			backlogSize: _backlogSize,
 			backlogTtl: _backlogTtl,
 			mirrorChannel: _mirrorChannel,
+			safePublish: _safePublish,
 			maxQueueSize: _maxQueueSize,
 			maxIngressSize: _maxIngressSize,
 			maxReplaySize: _maxReplaySize,

package/src/live/redis-bun.ts

@@ -9,6 +9,8 @@ export interface BunRedisClientLike {
 	unsubscribe(channel: string, listener?: Listener): Promise<unknown>
 	duplicate(): Promise<BunRedisClientLike>
 	close(): void
+	/** Bun's `RedisClient.connected`; read by `stats()` when present. */
+	readonly connected?: boolean
 	onconnect: ((this: never) => void) | null
 	onclose: ((this: never, error: Error) => void) | null
 }
@@ -58,6 +60,7 @@ export function bunRedisTransport(
 					ours.delete(channel)
 					return subscriber.unsubscribe(channel, dispatch)
 				},
+				connected: () => subscriber.connected !== false,
 				close() {
 					// No-ops, not null: Bun calls `onclose` without checking it.
 					subscriber.onconnect = () => {}

package/src/live/redis.ts

@@ -1,5 +1,9 @@
 import { errorMessageOf } from '../otel.js'
-import { backlogKey, type PubSubTransport } from './transport.js'
+import {
+	backlogKey,
+	type PubSubTransport,
+	type PubSubTransportStats
+} from './transport.js'
 
 export type RedisSend = (command: string, args: string[]) => Promise<unknown>
 
@@ -77,6 +81,8 @@ export type SubscriberConnection = {
 	resubscribe?(channel: string): Promise<unknown>
 	/** Stop delivering and release the connection (if the driver created it). */
 	close(): void | Promise<void>
+	/** The driver reports the connection open; omitted means open until lost. */
+	connected?(): boolean
 }
 
 /** Callbacks for one connection; they do nothing once it is replaced. */
@@ -115,7 +121,10 @@ export function createRedisTransport(driver: {
 	connectSubscriber: (
 		handlers: SubscriberHandlers
 	) => Promise<SubscriberConnection>
-}): PubSubTransport & { close(): Promise<void> } {
+}): PubSubTransport & {
+	close(): Promise<void>
+	stats(): PubSubTransportStats
+} {
 	const publishScript = createLuaScript(driver.send, PUBLISH_LUA)
 	const channels = new Map<string, ChannelState>()
 	// An UNSUBSCRIBE still in flight would cancel a SUBSCRIBE sent after it.
@@ -124,6 +133,8 @@ export function createRedisTransport(driver: {
 		connection: Promise<SubscriberConnection>
 		retire: () => Promise<void>
 	} | null = null
+	// The open connection of the current generation, once it resolves.
+	let open: SubscriberConnection | null = null
 
 	const connect = () => {
 		let retired = false
@@ -131,7 +142,10 @@ export function createRedisTransport(driver: {
 		const retire = (error?: Error) => {
 			if (retired) return closing ?? Promise.resolve()
 			retired = true
-			if (current?.connection === connection) current = null
+			if (current?.connection === connection) {
+				current = null
+				open = null
+			}
 			closing = connection.then((open) => open.close()).catch(() => {})
 			if (!error) return closing
 			const lost = [...channels.values()].flatMap((state) => [...state.entries])
@@ -182,9 +196,14 @@ export function createRedisTransport(driver: {
 			onLost: (error) => retire(error)
 		}
 		const connection = driver.connectSubscriber(handlers)
-		connection.catch(() => {
-			if (current?.connection === connection) current = null
-		})
+		connection.then(
+			(resolved) => {
+				if (!retired) open = resolved
+			},
+			() => {
+				if (current?.connection === connection) current = null
+			}
+		)
 		current = { connection, retire: () => retire() }
 		return connection
 	}
@@ -268,6 +287,14 @@ export function createRedisTransport(driver: {
 				await done
 			}
 		},
+		stats: () => ({
+			channels: channels.size,
+			listeners: [...channels.values()].reduce(
+				(sum, state) => sum + state.entries.size,
+				0
+			),
+			subscriberConnected: open ? (open.connected?.() ?? true) : false
+		}),
 		async close() {
 			const closing = current?.retire()
 			channels.clear()

package/src/live/scoped-change-bus.ts

@@ -0,0 +1,98 @@
+import type { ZodType, z } from 'zod'
+import type {
+	AnyFnContext,
+	FnDefinition,
+	FnRouteOptions,
+	GuardOptions,
+	ProcedureKey,
+	ProcedureOption
+} from '../types.js'
+import type {
+	CreatePubSub,
+	ObjectSchema,
+	PubSub,
+	PubSubOptions
+} from './pub-sub.js'
+
+/** Where a change bus partitions its channels, e.g. one per organization. */
+export type ChangeBusScope<TContext, TEvent> = {
+	/** The subscriber's scope key, from its context. Throw to refuse the subscription. */
+	subscribe: (context: TContext) => string
+	/** The event's scope key, carried in the event itself. */
+	publish: (event: TEvent) => string
+}
+
+/** A bus's channel definition; pass it to `fnLive` to share the bus's events. */
+export type ChangeBusChannel<TContext, TEvent> = {
+	subscribe: (params: { context: TContext }) => string
+	publish: (event: TEvent) => string
+}
+
+export type ScopedChangeBus<
+	TDef extends FnDefinition,
+	TInputSchema extends ObjectSchema,
+	TEventSchema extends ZodType,
+	TKey extends ProcedureKey<TDef>,
+	TScopeEvent
+> = PubSub<TDef, TInputSchema, TEventSchema, TKey> & {
+	channel: ChangeBusChannel<AnyFnContext<TDef>, TScopeEvent>
+}
+
+/**
+ * Binds the app's `createPubSub` to one scope rule, for buses that tell every
+ * subscriber in a scope "something changed". Each bus then names only its
+ * channel prefix: events go to `${prefix}:${scope}`. Publishing is safe by
+ * default (`safePublish: true`), because buses publish after committed writes.
+ *
+ * ```ts
+ * const defineChangeBus = defineScopedChangeBus(createPubSub, {
+ *   subscribe: (context) => activeOrganizationId(context),
+ *   publish: (event: { organizationId: string }) => event.organizationId
+ * })
+ * export const dealChanges = defineChangeBus({
+ *   name: 'deal.subscribe',
+ *   prefix: 'deal:change',
+ *   inputSchema: z.object({}),
+ *   eventSchema: z.object({ organizationId: z.string(), dealId: z.string() })
+ * })
+ * // fnLive({ live: { channel: dealChanges.channel, ... } }) shares the channel.
+ * ```
+ */
+export function defineScopedChangeBus<TDef extends FnDefinition, TScopeEvent>(
+	createPubSub: CreatePubSub<TDef>,
+	scope: ChangeBusScope<AnyFnContext<TDef>, TScopeEvent>
+) {
+	return <
+		TInputSchema extends ObjectSchema,
+		TEventSchema extends ZodType<TScopeEvent>,
+		TKey extends ProcedureKey<TDef> = TDef['default']
+	>(
+		options: Omit<
+			PubSubOptions<TDef, TInputSchema, TEventSchema, NoInfer<TKey>>,
+			'channel'
+		> &
+			GuardOptions<TDef['guards']> &
+			Pick<
+				FnRouteOptions<TDef, TKey, z.output<TInputSchema>>,
+				'meta' | 'guardResolvers'
+			> &
+			ProcedureOption<TDef, TKey> & {
+				/** Channel prefix; the scope key is appended as `${prefix}:${scope}`. */
+				prefix: string
+			}
+	): ScopedChangeBus<TDef, TInputSchema, TEventSchema, TKey, TScopeEvent> => {
+		const { prefix, ...pubsubOptions } = options
+		const channel: ChangeBusChannel<AnyFnContext<TDef>, TScopeEvent> = {
+			subscribe: ({ context }) => `${prefix}:${scope.subscribe(context)}`,
+			publish: (event) => `${prefix}:${scope.publish(event)}`
+		}
+		// The bus's context is one member of AnyFnContext, which the generic
+		// signature of createPubSub cannot see.
+		const bus = (createPubSub as (options: object) => object)({
+			safePublish: true,
+			...pubsubOptions,
+			channel
+		}) as PubSub<TDef, TInputSchema, TEventSchema, TKey>
+		return { ...bus, channel }
+	}
+}

package/src/live/transport.ts

@@ -1,6 +1,16 @@
 /** One payload for one channel. */
 export type PubSubMessage = { channel: string; payload: string }
 
+/** What a transport holds open on this instance, for gauges and health checks. */
+export type PubSubTransportStats = {
+	/** Broker channels subscribed (one per channel, however many listeners). */
+	channels: number
+	/** Local listeners across those channels. */
+	listeners: number
+	/** The subscriber connection is open; false before the first subscribe. */
+	subscriberConnected: boolean
+}
+
 export type BacklogOptions = {
 	/** Items kept per channel (oldest dropped). */
 	size: number
@@ -39,6 +49,8 @@ export interface PubSubTransport {
 		onLost?: (error: Error) => void,
 		options?: { onReconnect?: () => void }
 	): Promise<() => Promise<void>>
+	/** Current subscription counts and connection state. */
+	stats?(): PubSubTransportStats
 }
 
 export const backlogKey = (channel: string) => `${channel}:backlog`

package/src/otel.ts

@@ -195,6 +195,14 @@ export function errorMessageOf(error: unknown): string {
 	return error instanceof Error ? error.message : String(error)
 }
 
+/** Error fields for a log line, named like the `fn.completed` ones. */
+export function errorAttributes(error: unknown) {
+	return {
+		error_type: error instanceof Error ? error.name : typeof error,
+		error_message: errorMessageOf(error)
+	}
+}
+
 function protectSpan<T extends SpanLike>(span: T): T {
 	return new Proxy(span, {
 		get(target, key) {

package/src/procedure-cli.ts

@@ -0,0 +1,99 @@
+import { type AnyProcedure, call, isProcedure, ORPCError } from '@orpc/server'
+import {
+	CliError,
+	type Command,
+	type CommandGroup,
+	defineCommand
+} from 'hanzio/cli'
+import { z } from 'zod'
+import { type FnMeta, readFnMeta } from './meta.js'
+
+export type ProcedureCommandsOptions<C> = {
+	/**
+	 * Which procedures become commands. Default: those declared with
+	 * `meta: { cli: true }` (add `cli?: boolean` to the app's meta type).
+	 */
+	filter?: (meta: FnMeta) => boolean
+	/**
+	 * The oRPC context a command calls its procedure with, from the CLI's
+	 * context (`defineCli({ context })`). Default: that context as-is. It gets
+	 * the procedure's meta, so it can refuse early with a `CliError`, e.g. a
+	 * protected procedure run without a user.
+	 */
+	context?: (cliContext: C, meta: FnMeta) => unknown
+}
+
+const optedIn = (meta: FnMeta) => (meta.meta as { cli?: unknown }).cli === true
+
+const kebab = (key: string) =>
+	key.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)
+
+/**
+ * The opted-in `fn()` procedures of a router as hanzio/cli commands, nested
+ * like the router: `supportLearning.syncRun` is `support-learning sync-run`.
+ * Flags come from the procedure's input schema, help from its summary. A
+ * command calls the procedure through oRPC, so middleware, guards, tracing
+ * and errors run as they do over HTTP.
+ */
+export function procedureCommands<C = unknown>(
+	router: object,
+	options: ProcedureCommandsOptions<C> = {}
+): CommandGroup<C> {
+	const filter = options.filter ?? optedIn
+	const commands: Record<string, Command<C> | CommandGroup<C>> = {}
+
+	for (const [key, value] of Object.entries(router)) {
+		if (isProcedure(value)) {
+			const meta = readFnMeta(value)
+			if (filter(meta)) commands[kebab(key)] = toCommand(value, meta, options)
+		} else if (value && typeof value === 'object') {
+			const group = procedureCommands(value, options)
+			if (Object.keys(group).length > 0) commands[kebab(key)] = group
+		}
+	}
+
+	return commands
+}
+
+function toCommand<C>(
+	procedure: AnyProcedure,
+	meta: FnMeta,
+	options: ProcedureCommandsOptions<C>
+): Command<C> {
+	const name = meta.name ?? 'procedure'
+	if (meta.stream) {
+		throw new TypeError(`orpc-fn: ${name} streams and cannot be a CLI command`)
+	}
+	const input = meta.inputSchema
+	if (input !== undefined && !(input instanceof z.ZodObject)) {
+		throw new TypeError(
+			`orpc-fn: ${name} must take a z.object() input to be a CLI command`
+		)
+	}
+
+	return defineCommand<z.ZodObject, unknown, C>({
+		description: meta.description,
+		input: input ?? z.object({}),
+		run: async (parsed, ctx) => {
+			const context = options.context
+				? await options.context(ctx.context, meta)
+				: ctx.context
+			try {
+				// The flags were validated against this schema; the procedure parses
+				// them again, like any nested call with a parsed value.
+				return await call(procedure, input ? parsed : undefined, {
+					context: context as Record<never, never>
+				})
+			} catch (error) {
+				// A refusal the caller drives (auth, permission, not found) reads as
+				// a message, not a crash with a stack trace.
+				if (error instanceof ORPCError && error.status < 500) {
+					throw new CliError(`${error.code}: ${error.message}`, {
+						cause: error
+					})
+				}
+				throw error
+			}
+		}
+	})
+}