orpc-fn 0.1.0

package/src/live/redis-bun.ts

@@ -0,0 +1,76 @@
+import { createRedisTransport } from './redis.js'
+
+type Listener = (message: string, channel: string) => void
+
+/** The part of Bun's `RedisClient` this transport uses. */
+export interface BunRedisClientLike {
+	send(command: string, args: string[]): Promise<unknown>
+	subscribe(channel: string, listener: Listener): Promise<unknown>
+	unsubscribe(channel: string, listener?: Listener): Promise<unknown>
+	duplicate(): Promise<BunRedisClientLike>
+	close(): void
+	onconnect: ((this: never) => void) | null
+	onclose: ((this: never, error: Error) => void) | null
+}
+
+/**
+ * `PubSubTransport` for Bun's built-in `RedisClient`. Subscriptions use a
+ * dedicated connection (`client.duplicate()` unless `subscriber` is given)
+ * that re-subscribes its channels after every reconnect; configure retries on
+ * the client (`maxRetries`) since the duplicate copies its options.
+ *
+ * Call `close()` on shutdown to close the subscriber connection it created.
+ */
+export function bunRedisTransport(
+	client: BunRedisClientLike,
+	options: { subscriber?: BunRedisClientLike } = {}
+) {
+	return createRedisTransport({
+		send: (command, args) => client.send(command, args),
+		async connectSubscriber(handlers) {
+			const owned = !options.subscriber
+			const subscriber = options.subscriber ?? (await client.duplicate())
+			const dispatch: Listener = (message, channel) =>
+				handlers.onMessage(channel, message)
+			const ours = new Set<string>()
+			// Bun reconnects on its own but drops every subscription. Also fires on
+			// the first connect, when there is nothing to restore yet.
+			subscriber.onconnect = () => handlers.onReconnect()
+			// Fires only when Bun gives up reconnecting (and on close(), which
+			// detaches it first).
+			subscriber.onclose = (error) =>
+				handlers.onLost(error ?? new Error('Redis subscriber closed'))
+			return {
+				subscribe: (channel) => {
+					ours.add(channel)
+					return subscriber.subscribe(channel, dispatch)
+				},
+				// Bun keeps listeners across a reconnect and does not dedupe them, so
+				// clear the channel before adding its listener again. unsubscribe
+				// throws synchronously outside subscriber mode.
+				resubscribe: async (channel) => {
+					await Promise.resolve()
+						.then(() => subscriber.unsubscribe(channel))
+						.catch(() => {})
+					return subscriber.subscribe(channel, dispatch)
+				},
+				unsubscribe: (channel) => {
+					ours.delete(channel)
+					return subscriber.unsubscribe(channel, dispatch)
+				},
+				close() {
+					// No-ops, not null: Bun calls `onclose` without checking it.
+					subscriber.onconnect = () => {}
+					subscriber.onclose = () => {}
+					if (owned) return subscriber.close()
+					// A given subscriber stays open: remove only this transport's listeners.
+					for (const channel of ours) {
+						void Promise.resolve()
+							.then(() => subscriber.unsubscribe(channel, dispatch))
+							.catch(() => {})
+					}
+				}
+			}
+		}
+	})
+}

package/src/live/redis.ts

@@ -0,0 +1,255 @@
+import { errorMessageOf } from '../otel.js'
+import { backlogKey, type PubSubTransport } from './transport.js'
+
+export type RedisSend = (command: string, args: string[]) => Promise<unknown>
+
+function isNoScriptError(error: unknown) {
+	return errorMessageOf(error).includes('NOSCRIPT')
+}
+
+/**
+ * Ship a Lua script by SHA instead of resending its source on every call.
+ * Redis forgets its script cache on restart and on `SCRIPT FLUSH`, so a
+ * `NOSCRIPT` reply falls back to an inline `EVAL` (which repopulates the
+ * cache) and drops the stale digest.
+ */
+export function createLuaScript(send: RedisSend, source: string) {
+	let sha: string | null = null
+	let loading: Promise<string> | null = null
+
+	function load() {
+		loading ??= send('SCRIPT', ['LOAD', source])
+			.then(String)
+			.finally(() => {
+				loading = null
+			})
+		return loading
+	}
+
+	return async function evalScript(keys: string[], args: string[]) {
+		const tail = [String(keys.length), ...keys, ...args]
+		sha ??= await load()
+		try {
+			return await send('EVALSHA', [sha, ...tail])
+		} catch (error) {
+			if (!isNoScriptError(error)) throw error
+			sha = null
+			return await send('EVAL', [source, ...tail])
+		}
+	}
+}
+
+/**
+ * Publish payloads and maintain each channel's capped, TTL'd backlog in one
+ * atomic round-trip. Separate PUBLISH/RPUSH/LTRIM/EXPIRE calls can tear (a
+ * message published but missing from the backlog, or a backlog without TTL).
+ *
+ * KEYS = channel1, backlog1, channel2, backlog2, ...
+ * ARGV[1] = max backlog size (0 = no backlog), ARGV[2] = TTL seconds,
+ * ARGV[3..] = pairs of (channel slot, payload)
+ */
+const PUBLISH_LUA = `
+local maxSize = tonumber(ARGV[1])
+local ttl = tonumber(ARGV[2])
+for i = 3, #ARGV, 2 do
+  local slot = tonumber(ARGV[i]) * 2
+  redis.call('PUBLISH', KEYS[slot - 1], ARGV[i + 1])
+  if maxSize > 0 then
+    redis.call('RPUSH', KEYS[slot], ARGV[i + 1])
+  end
+end
+if maxSize > 0 then
+  for slot = 2, #KEYS, 2 do
+    redis.call('LTRIM', KEYS[slot], -maxSize, -1)
+    redis.call('EXPIRE', KEYS[slot], ttl)
+  end
+end
+return (#ARGV - 2) / 2
+`
+
+export type SubscriberConnection = {
+	subscribe(channel: string): Promise<unknown>
+	unsubscribe(channel: string): Promise<unknown>
+	/**
+	 * Restore one channel after the driver reconnected on its own and lost its
+	 * subscriptions. Omit when the client re-subscribes itself (ioredis).
+	 */
+	resubscribe?(channel: string): Promise<unknown>
+	/** Stop delivering and release the connection (if the driver created it). */
+	close(): void
+}
+
+/** Callbacks for one connection; they do nothing once it is replaced. */
+export type SubscriberHandlers = {
+	onMessage(channel: string, message: string): void
+	/** The driver reconnected; its subscriptions must be restored. */
+	onReconnect(): void
+	/** The connection is gone for good; a fresh one replaces it. */
+	onLost(error: Error): void
+}
+
+type Entry = {
+	listener: (payload: string) => void
+	onLost: ((error: Error) => void) | undefined
+}
+
+type ChannelState = {
+	entries: Set<Entry>
+	ready: Promise<unknown>
+	settled: boolean
+}
+
+/**
+ * Shared core of the Redis transports: one SUBSCRIBE per channel no matter
+ * how many listeners, and one dedicated subscriber connection at a time.
+ *
+ * Each connection is a generation. Losing it (or failing to restore its
+ * channels after a reconnect) retires it: the core closes it, ignores
+ * anything it still emits, and tells every listener, whose resubscribe then
+ * opens the next generation. Nothing from an old connection can reach the
+ * channels of a new one.
+ */
+export function createRedisTransport(driver: {
+	send: RedisSend
+	connectSubscriber: (
+		handlers: SubscriberHandlers
+	) => Promise<SubscriberConnection>
+}): PubSubTransport & { close(): void } {
+	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.
+	const unsubscribing = new Map<string, Promise<unknown>>()
+	let current: {
+		connection: Promise<SubscriberConnection>
+		retire: () => void
+	} | null = null
+
+	const connect = () => {
+		let retired = false
+		const retire = (error?: Error) => {
+			if (retired) return
+			retired = true
+			if (current?.connection === connection) current = null
+			void connection.then((open) => open.close()).catch(() => {})
+			if (!error) return
+			const lost = [...channels.values()].flatMap((state) => [...state.entries])
+			channels.clear()
+			for (const entry of lost) entry.onLost?.(error)
+		}
+		const handlers: SubscriberHandlers = {
+			onMessage(channel, message) {
+				if (retired) return
+				for (const entry of [...(channels.get(channel)?.entries ?? [])]) {
+					try {
+						entry.listener(message)
+					} catch {
+						// One listener must not starve the others.
+					}
+				}
+			},
+			onReconnect() {
+				if (retired) return
+				// In-flight SUBSCRIBEs are excluded: they still land on their own.
+				const settled = [...channels]
+					.filter(([, state]) => state.settled)
+					.map(([channel]) => channel)
+				void connection
+					.then((open) =>
+						Promise.all(settled.map((channel) => open.resubscribe?.(channel)))
+					)
+					.catch((error) => retire(asError(error)))
+			},
+			onLost: (error) => retire(error)
+		}
+		const connection = driver.connectSubscriber(handlers)
+		connection.catch(() => {
+			if (current?.connection === connection) current = null
+		})
+		current = { connection, retire: () => retire() }
+		return connection
+	}
+
+	return {
+		async publish(messages, backlog) {
+			const [first] = messages
+			if (!first) return
+			if (!backlog && messages.length === 1) {
+				await driver.send('PUBLISH', [first.channel, first.payload])
+				return
+			}
+			const keys: string[] = []
+			const slots = new Map<string, number>()
+			const args = [
+				String(backlog?.size ?? 0),
+				String(backlog?.ttlSeconds ?? 0)
+			]
+			for (const { channel, payload } of messages) {
+				let slot = slots.get(channel)
+				if (slot === undefined) {
+					keys.push(channel, backlogKey(channel))
+					slot = keys.length / 2
+					slots.set(channel, slot)
+				}
+				args.push(String(slot), payload)
+			}
+			await publishScript(keys, args)
+		},
+		async readBacklog(channel) {
+			const items = await driver.send('LRANGE', [
+				backlogKey(channel),
+				'0',
+				'-1'
+			])
+			return Array.isArray(items) ? items.map(String) : []
+		},
+		async subscribe(channel, listener, onLost) {
+			const connection = await (current?.connection ?? connect())
+			const entry: Entry = { listener, onLost }
+			await unsubscribing.get(channel)
+			let state = channels.get(channel)
+			if (!state) {
+				const created: ChannelState = {
+					entries: new Set(),
+					ready: connection.subscribe(channel),
+					settled: false
+				}
+				created.ready.then(
+					() => {
+						created.settled = true
+					},
+					() => {
+						if (channels.get(channel) === created) channels.delete(channel)
+					}
+				)
+				channels.set(channel, created)
+				state = created
+			}
+			state.entries.add(entry)
+			try {
+				await state.ready
+			} catch (error) {
+				state.entries.delete(entry)
+				throw error
+			}
+			const subscribed = state
+			return async () => {
+				if (!subscribed.entries.delete(entry)) return
+				if (subscribed.entries.size > 0 || channels.get(channel) !== subscribed)
+					return
+				channels.delete(channel)
+				const done = connection.unsubscribe(channel).finally(() => {
+					if (unsubscribing.get(channel) === done) unsubscribing.delete(channel)
+				})
+				unsubscribing.set(channel, done)
+				await done
+			}
+		},
+		close() {
+			current?.retire()
+			channels.clear()
+		}
+	}
+}
+
+const asError = (error: unknown) =>
+	error instanceof Error ? error : new Error(errorMessageOf(error))

package/src/live/transport.ts

@@ -0,0 +1,41 @@
+/** One payload for one channel. */
+export type PubSubMessage = { channel: string; payload: string }
+
+export type BacklogOptions = {
+	/** Items kept per channel (oldest dropped). */
+	size: number
+	/** Seconds the backlog lives after its last write. */
+	ttlSeconds: number
+}
+
+/**
+ * The broker behind `createPubSub` / `fnLive`. Implementations:
+ * `orpc-fn/live/redis-bun`, `orpc-fn/live/ioredis` and `orpc-fn/live/memory`.
+ *
+ * The backlog of a channel lives at `${channel}:backlog` (see {@link backlogKey}).
+ */
+export interface PubSubTransport {
+	/**
+	 * Publish every message, in order. With `backlog`, also append each payload
+	 * to its channel's backlog, trim and refresh its TTL - atomically, so a
+	 * message is never published without its backlog entry or vice versa.
+	 */
+	publish(
+		messages: readonly PubSubMessage[],
+		backlog?: BacklogOptions
+	): Promise<void>
+	/** The channel's backlog, oldest first. */
+	readBacklog(channel: string): Promise<string[]>
+	/**
+	 * Deliver every payload published to `channel` until the returned function
+	 * is called. `onLost` fires when the subscription can no longer deliver
+	 * (connection closed for good); the caller resubscribes.
+	 */
+	subscribe(
+		channel: string,
+		listener: (payload: string) => void,
+		onLost?: (error: Error) => void
+	): Promise<() => Promise<void>>
+}
+
+export const backlogKey = (channel: string) => `${channel}:backlog`

package/src/logger.ts

@@ -0,0 +1,28 @@
+export type LogAttributes = Record<string, unknown>
+
+/** The logger handlers receive. Any app logger with these four methods fits. */
+export interface FnLogger {
+	debug(message: string, attributes?: LogAttributes): void
+	info(message: string, attributes?: LogAttributes): void
+	warn(message: string, attributes?: LogAttributes): void
+	error(message: string, attributes?: LogAttributes): void
+}
+
+const format = (scope: string, message: string, attributes?: LogAttributes) =>
+	`[${scope}] ${message}${attributes ? ` ${JSON.stringify(attributes)}` : ''}`
+
+/**
+ * Default logger: silent for `debug`/`info`, console for `warn`/`error`, so a
+ * library default never floods stdout with one line per call. Inject your own
+ * with `createFn({ logger })`.
+ */
+export function createDefaultLogger(scope: string): FnLogger {
+	return {
+		debug() {},
+		info() {},
+		warn: (message, attributes) =>
+			console.warn(format(scope, message, attributes)),
+		error: (message, attributes) =>
+			console.error(format(scope, message, attributes))
+	}
+}

package/src/mastra.ts

@@ -0,0 +1,140 @@
+import type { RequestContext } from '@mastra/core/request-context'
+import { createTool, type Tool } from '@mastra/core/tools'
+import { type AnyProcedure, call } from '@orpc/server'
+import {
+	passThroughOutputSchema,
+	rawInputSchema,
+	type ToolSchema
+} from './json-schema.js'
+import { readFnMeta, toToolName } from './meta.js'
+import type { ProcedureInput, ProcedureOutput } from './types.js'
+
+export { toToolName }
+
+export type CreateMastraToolOptions = {
+	/** Override the tool id (defaults to the sanitized `fn` name). */
+	id?: string
+	/** Override the tool description (defaults to the route summary). */
+	description?: string
+	/** Gate execution behind the AI SDK tool-approval flow. */
+	requireApproval?: boolean
+	/**
+	 * Accept a procedure without an input schema (the tool then takes an empty
+	 * object). For no-input queries like `teams.list`.
+	 */
+	allowMissingInputSchema?: boolean
+	onExecuteFinish?: (event: {
+		toolId: string
+		durationMs: number
+		outcome: 'success' | 'error'
+	}) => void
+	/** Key holding the oRPC context in Mastra's `RequestContext`. Default 'orpcContext'. */
+	contextKey?: string
+}
+
+/** What the tool takes: the procedure's raw input, or `{}` without a schema. */
+export type MastraToolInput<TProc> =
+	unknown extends ProcedureInput<TProc>
+		? Record<string, never>
+		: ProcedureInput<TProc>
+
+/** A Mastra tool typed by the procedure's raw input and parsed output. */
+export type MastraTool<TProc extends AnyProcedure> = Tool<
+	MastraToolInput<TProc>,
+	ProcedureOutput<TProc>
+>
+
+/** LLM tool parameters must be an object; other inputs are a type error. */
+type ObjectInputCheck<TProc> =
+	MastraToolInput<TProc> extends Record<string, unknown>
+		? unknown
+		: { 'orpc-fn: an agent tool needs an object input': ProcedureInput<TProc> }
+
+/**
+ * Creates a Mastra tool from a procedure made with `fn()`. Execution calls
+ * the procedure with the oRPC context stored in the Mastra request context
+ * (`requestContext.set('orpcContext', context)`), so auth and guards apply.
+ *
+ * Mastra checks the input against the procedure's schema (with dates coerced
+ * from strings) but passes the raw input on for the procedure to parse;
+ * the output is the procedure's parsed result, passed through unchanged.
+ */
+export function createMastraTool<TProc extends AnyProcedure>(
+	procedure: TProc & ObjectInputCheck<TProc>,
+	options: CreateMastraToolOptions = {}
+): MastraTool<TProc> {
+	const meta = readFnMeta(procedure)
+	const name = options.id ?? meta.name
+	if (!name) {
+		throw new Error(
+			'Procedure must be created with fn() to use createMastraTool'
+		)
+	}
+	let inputSchema: ToolSchema | undefined
+	if (meta.inputSchema) {
+		inputSchema = rawInputSchema(meta.inputSchema)
+		if (inputSchema['~standard'].jsonSchema.input().type !== 'object') {
+			throw new Error(`${name} must take an object input to be an agent tool`)
+		}
+	} else if (!options.allowMissingInputSchema) {
+		throw new Error(
+			`${name} must declare an input schema to be exposed as an agent tool`
+		)
+	}
+
+	const id = options.id ?? toToolName(name)
+	const contextKey = options.contextKey ?? 'orpcContext'
+
+	const tool = createTool({
+		id,
+		description: options.description ?? meta.description,
+		requireApproval: options.requireApproval === true,
+		inputSchema:
+			inputSchema ??
+			({
+				'~standard': {
+					version: 1,
+					vendor: 'orpc-fn',
+					validate: () => ({ value: {} }),
+					jsonSchema: {
+						input: () => ({ type: 'object', properties: {} }),
+						output: () => ({ type: 'object', properties: {} })
+					}
+				}
+			} satisfies ToolSchema),
+		...(meta.outputSchema
+			? { outputSchema: passThroughOutputSchema(meta.outputSchema) }
+			: {}),
+		execute: async (input, ctx) => {
+			const requestContext = ctx?.requestContext as RequestContext | undefined
+			const context = requestContext?.get(contextKey)
+			if (!context) {
+				throw new Error(
+					`createMastraTool execution requires ${contextKey} in the Mastra request context`
+				)
+			}
+			const startedAt = performance.now()
+			const finish = (outcome: 'success' | 'error') =>
+				options.onExecuteFinish?.({
+					toolId: id,
+					durationMs: performance.now() - startedAt,
+					outcome
+				})
+			try {
+				const result = await call(
+					procedure,
+					meta.inputSchema ? input : undefined,
+					ctx?.abortSignal ? { context, signal: ctx.abortSignal } : { context }
+				)
+				finish('success')
+				return result
+			} catch (error) {
+				finish('error')
+				throw error
+			}
+		}
+	})
+
+	// The runtime schemas are untyped `ToolSchema`s; `MastraTool` is the typed surface.
+	return tool as unknown as MastraTool<TProc>
+}

package/src/mcp.ts

@@ -0,0 +1,73 @@
+import {
+	type AnyProcedure,
+	type AnyRouter,
+	type TraverseContractProcedureCallbackOptions,
+	traverseContractProcedures
+} from '@orpc/server'
+import { rawInputSchema, type ToolSchema } from './json-schema.js'
+import { readFnMeta, toToolName } from './meta.js'
+
+export { toToolName }
+export { rawInputSchema as toolInputSchema }
+export type { ToolSchema }
+
+/** Picks procedures; also fits oRPC's `OpenAPIHandler({ filter })`. */
+export type ProcedureFilter = (
+	options: TraverseContractProcedureCallbackOptions
+) => boolean
+
+export type McpTool = {
+	/** Tool name: the sanitized `fn` name (`user.me` becomes `user-me`). */
+	name: string
+	procedure: AnyProcedure
+	config: {
+		description?: string
+		/**
+		 * Validates and coerces (date strings to `Date`) but returns the raw
+		 * input: pass it to `call(procedure, args)`, which parses it.
+		 */
+		inputSchema?: ToolSchema
+		annotations: { readOnlyHint: boolean }
+	}
+}
+
+/** Procedures whose route has `tag`: `listTools(router, { filter: hasTag('external') })`. */
+export const hasTag =
+	(tag: string): ProcedureFilter =>
+	({ contract }) =>
+		contract['~orpc'].route.tags?.includes(tag) ?? false
+
+const isGet: ProcedureFilter = ({ contract }) =>
+	contract['~orpc'].route.method === 'GET'
+
+/**
+ * MCP tool definitions for the procedures in `router` matching `filter`
+ * (default: all). Register them with any MCP server:
+ * `server.registerTool(tool.name, tool.config, run)`.
+ *
+ * `readOnly` sets `readOnlyHint`; it defaults to GET routes, since an MCP
+ * client treats anything else as a mutation and may ask for approval.
+ */
+export function listTools(
+	router: AnyRouter,
+	options: { filter?: ProcedureFilter; readOnly?: ProcedureFilter } = {}
+): McpTool[] {
+	const { filter, readOnly = isGet } = options
+	const tools: McpTool[] = []
+	traverseContractProcedures({ router, path: [] }, (traversed) => {
+		if (filter && !filter(traversed)) return
+		const procedure = traversed.contract as AnyProcedure
+		const { inputSchema, route } = procedure['~orpc']
+		const description = route.description ?? route.summary
+		tools.push({
+			name: toToolName(readFnMeta(procedure).name ?? traversed.path.join('.')),
+			procedure,
+			config: {
+				...(description === undefined ? {} : { description }),
+				...(inputSchema ? { inputSchema: rawInputSchema(inputSchema) } : {}),
+				annotations: { readOnlyHint: readOnly(traversed) }
+			}
+		})
+	})
+	return tools
+}

package/src/meta.ts

@@ -0,0 +1,72 @@
+import type { AnySchema } from '@orpc/contract'
+import type { AnyProcedure } from '@orpc/server'
+
+/**
+ * Key under which `fn()` stores its metadata in oRPC's procedure meta
+ * (`.meta()`). Living in oRPC's own meta means it survives everything that
+ * rebuilds a procedure (`os.router()`, `.use()` on a router, lazy routers),
+ * unlike a symbol property on the procedure object.
+ */
+export const FN_META_KEY = 'orpc-fn'
+
+export type StoredFnMeta = {
+	name: string
+	procedure: string
+	meta: Record<string, unknown>
+}
+
+export type FnMeta<TMeta extends object = Record<string, unknown>> = {
+	/** `fn({ name })`, also the OpenAPI operationId; undefined if not made by `fn()`. */
+	name: string | undefined
+	/** The `procedures` key the route was built from. */
+	procedure: string | undefined
+	/** The app's typed meta (`createFn({ meta })`) declared on this route. */
+	meta: Partial<TMeta>
+	/** Route summary, falling back to description, falling back to ''. */
+	description: string
+	summary: string | undefined
+	method: string | undefined
+	path: string | undefined
+	tags: readonly string[]
+	inputSchema: AnySchema | undefined
+	outputSchema: AnySchema | undefined
+}
+
+type ProcedureDefinition = {
+	meta?: Record<string, unknown>
+	route?: {
+		summary?: string
+		description?: string
+		method?: string
+		path?: string
+		tags?: readonly string[]
+	}
+	inputSchema?: AnySchema
+	outputSchema?: AnySchema
+}
+
+/** Read what `fn()` (and oRPC) recorded on a procedure. */
+export function readFnMeta<TMeta extends object = Record<string, unknown>>(
+	procedure: AnyProcedure
+): FnMeta<TMeta> {
+	const def = (procedure as { '~orpc'?: ProcedureDefinition })['~orpc'] ?? {}
+	const stored = def.meta?.[FN_META_KEY] as StoredFnMeta | undefined
+	const route = def.route ?? {}
+	return {
+		name: stored?.name,
+		procedure: stored?.procedure,
+		meta: (stored?.meta ?? {}) as Partial<TMeta>,
+		description: route.summary ?? route.description ?? '',
+		summary: route.summary,
+		method: route.method,
+		path: route.path,
+		tags: route.tags ?? [],
+		inputSchema: def.inputSchema,
+		outputSchema: def.outputSchema
+	}
+}
+
+/** Tool-safe name (`a-z0-9-_`): `Users.Get` becomes `users-get`. */
+export function toToolName(name: string): string {
+	return name.toLowerCase().replace(/[^a-z0-9-_]/g, '-')
+}