@atcute/xrpc-server 1.0.0 → 2.0.1

package/lib/main/router.ts

@@ -1,464 +0,0 @@
-import {
-	safeParse,
-	type XRPCProcedureMetadata,
-	type XRPCQueryMetadata,
-	type XRPCSubscriptionMetadata,
-} from '@atcute/lexicons/validations';
-
-import type { Literal, Promisable } from '../types/misc.ts';
-
-import type {
-	ProcedureConfig,
-	QueryConfig,
-	SubscriptionConfig,
-	UnknownOperationContext,
-	UnknownSubscriptionContext,
-} from './types/operation.ts';
-import type { WebSocketAdapter } from './types/websocket.ts';
-import { encodeErrorFrame, encodeMessageFrame, extractMessageType, omitMessageType } from './utils/frames.ts';
-import { createAsyncMiddlewareRunner, type Middleware } from './utils/middlewares.ts';
-import { unwrapLxm, type Namespaced } from './utils/namespaced.ts';
-import { constructMimeValidator, hasRequestBody } from './utils/request-input.ts';
-import { constructParamsHandler } from './utils/request-params.ts';
-import { invalidRequest, validationError } from './utils/response.ts';
-import { XRPCError, XRPCSubscriptionError } from './xrpc-error.ts';
-
-type InternalRequestContext = {
-	url: URL;
-	request: Request;
-};
-
-type InternalRequestHandler = (context: InternalRequestContext) => Promise<Response>;
-
-type InternalRouteData = {
-	method: 'GET' | 'POST';
-	handler: InternalRequestHandler;
-};
-
-export type FetchMiddleware = Middleware<[request: Request], Promise<Response>>;
-
-export type NotFoundHandler = (request: Request) => Promisable<Response>;
-export type HealthCheckHandler = (request: Request) => Promisable<Response>;
-export type ExceptionHandler = (error: unknown, request: Request) => Promisable<Response>;
-
-/** telemetry hook invoked for unexpected HTTP handler errors; fire-and-forget. */
-export type ErrorObserver = (ctx: { error: unknown; request: Request }) => void;
-/** telemetry hook invoked for unexpected subscription errors; fire-and-forget. */
-export type SocketErrorObserver = (ctx: { error: unknown; request: Request }) => void;
-
-export const defaultExceptionHandler: ExceptionHandler = (error: unknown) => {
-	if (error instanceof XRPCError) {
-		return error.toResponse();
-	}
-
-	if (error instanceof Response) {
-		return error;
-	}
-
-	return Response.json(
-		{ error: 'InternalServerError', message: `an exception happened whilst processing this request` },
-		{ status: 500 },
-	);
-};
-
-export const defaultNotFoundHandler: NotFoundHandler = () => {
-	return new Response('Not Found', { status: 404 });
-};
-
-export interface XRPCRouterOptions {
-	middlewares?: FetchMiddleware[];
-	handleNotFound?: NotFoundHandler;
-	/**
-	 * optional handler for `/xrpc/_health`. when provided, the router answers
-	 * health-check requests by invoking this handler; when absent, the path
-	 * falls through to `handleNotFound`. `_health` is not part of the atproto
-	 * XRPC spec, so callers opt in explicitly.
-	 */
-	handleHealthCheck?: HealthCheckHandler;
-	/** translates a thrown error into an HTTP response. */
-	handleException?: ExceptionHandler;
-	/**
-	 * fire-and-forget telemetry hook for unexpected HTTP errors. not invoked for
-	 * client-induced errors (aborted requests, `XRPCError` subclasses, thrown
-	 * `Response` objects).
-	 */
-	onError?: ErrorObserver;
-	/**
-	 * fire-and-forget telemetry hook for unexpected subscription errors. not
-	 * invoked for aborted signals or `XRPCSubscriptionError` (which is
-	 * translated to an error frame).
-	 */
-	onSocketError?: SocketErrorObserver;
-	websocket?: WebSocketAdapter;
-}
-
-export class XRPCRouter {
-	#handlers: Record<string, InternalRouteData> = {};
-	#handleNotFound: NotFoundHandler;
-	#handleHealthCheck?: HealthCheckHandler;
-	#handleException: ExceptionHandler;
-	#onError?: ErrorObserver;
-	#onSocketError?: SocketErrorObserver;
-	#websocket?: WebSocketAdapter;
-
-	fetch: (request: Request) => Promise<Response>;
-
-	constructor({
-		middlewares = [],
-		handleException = defaultExceptionHandler,
-		handleNotFound = defaultNotFoundHandler,
-		handleHealthCheck,
-		onError,
-		onSocketError,
-		websocket,
-	}: XRPCRouterOptions = {}) {
-		const runner = createAsyncMiddlewareRunner([...middlewares, (request) => this.#dispatch(request)]);
-
-		this.fetch = (request) => runner(request);
-		this.#handleException = handleException;
-		this.#handleNotFound = handleNotFound;
-		this.#handleHealthCheck = handleHealthCheck;
-		this.#onError = onError;
-		this.#onSocketError = onSocketError;
-		this.#websocket = websocket;
-	}
-
-	#observeError(error: unknown, request: Request): void {
-		// client-induced errors are not bugs; skip telemetry
-		if (request.signal.aborted) {
-			return;
-		}
-		if (error instanceof XRPCError) {
-			return;
-		}
-		if (error instanceof Response) {
-			return;
-		}
-
-		try {
-			this.#onError?.({ error, request });
-		} catch {
-			// observer threw; swallow to keep response path deterministic
-		}
-	}
-
-	#observeSocketError(error: unknown, request: Request): void {
-		if (request.signal.aborted) {
-			return;
-		}
-		if (error instanceof XRPCSubscriptionError) {
-			return;
-		}
-
-		try {
-			this.#onSocketError?.({ error, request });
-		} catch {
-			// observer threw; swallow to keep socket close path deterministic
-		}
-	}
-
-	async #dispatch(request: Request): Promise<Response> {
-		const url = new URL(request.url);
-		const pathname = url.pathname;
-
-		if (!pathname.startsWith('/xrpc/')) {
-			return this.#handleNotFound(request);
-		}
-
-		const nsid = pathname.slice('/xrpc/'.length);
-
-		if (nsid === '_health' && this.#handleHealthCheck !== undefined) {
-			try {
-				return await this.#handleHealthCheck(request);
-			} catch (err) {
-				if (request.signal.aborted) {
-					return new Response(null, { status: 499 });
-				}
-
-				this.#observeError(err, request);
-				return this.#handleException(err, request);
-			}
-		}
-
-		const route = this.#handlers[nsid];
-		if (route === undefined) {
-			return this.#handleNotFound(request);
-		}
-
-		// allow HEAD alongside GET; the runtime is responsible for stripping the
-		// response body per the Fetch API.
-		const allowed = request.method === route.method || (route.method === 'GET' && request.method === 'HEAD');
-		if (!allowed) {
-			return Response.json(
-				{ error: 'InvalidRequest', message: `invalid http method (expected ${route.method})` },
-				{ status: 405, headers: { allow: route.method === 'GET' ? 'GET, HEAD' : route.method } },
-			);
-		}
-
-		try {
-			const response = await route.handler({
-				request: request,
-				url: url,
-			});
-
-			return response;
-		} catch (err) {
-			if (request.signal.aborted) {
-				return new Response(null, { status: 499 });
-			}
-
-			this.#observeError(err, request);
-			return this.#handleException(err, request);
-		}
-	}
-
-	/** @deprecated use `addQuery` and `addProcedure` instead */
-	add<TQuery extends XRPCQueryMetadata>(
-		query: TQuery | Namespaced<TQuery>,
-		config: QueryConfig<TQuery>,
-	): void;
-	add<TProcedure extends XRPCProcedureMetadata>(
-		procedure: TProcedure | Namespaced<TProcedure>,
-		config: ProcedureConfig<TProcedure>,
-	): void;
-	add(
-		operation:
-			| XRPCQueryMetadata
-			| XRPCProcedureMetadata
-			| Namespaced<XRPCQueryMetadata | XRPCProcedureMetadata>,
-		config: any,
-	): void {
-		const schema = unwrapLxm(operation);
-
-		switch (schema.type) {
-			case 'xrpc_query': {
-				return this.addQuery(schema, config);
-			}
-			case 'xrpc_procedure': {
-				return this.addProcedure(schema, config);
-			}
-		}
-	}
-
-	addQuery<TQuery extends XRPCQueryMetadata, TConfig extends QueryConfig<TQuery>>(
-		query: TQuery | Namespaced<TQuery>,
-		config: TConfig,
-	): void {
-		const querySchema = unwrapLxm(query);
-		const handleParams = querySchema.params ? constructParamsHandler(querySchema.params) : null;
-
-		const handler = config.handler;
-
-		this.#handlers[querySchema.nsid] = {
-			method: 'GET',
-			handler: async ({ request, url }) => {
-				let params: Record<string, Literal | Literal[]>;
-
-				if (handleParams !== null) {
-					const result = handleParams(url.searchParams);
-					if (!result.ok) {
-						return validationError('params', result);
-					}
-
-					params = result.value;
-				} else {
-					params = {};
-				}
-
-				const context: UnknownOperationContext = {
-					request: request,
-					signal: request.signal,
-					params: params,
-				};
-
-				const output = await handler(context as any);
-
-				if (output instanceof Response) {
-					return output;
-				}
-
-				return new Response(null);
-			},
-		};
-	}
-
-	addProcedure<TProcedure extends XRPCProcedureMetadata, TConfig extends ProcedureConfig<TProcedure>>(
-		procedure: TProcedure | Namespaced<TProcedure>,
-		config: TConfig,
-	): void {
-		const procedureSchema = unwrapLxm(procedure);
-		const handleParams = procedureSchema.params ? constructParamsHandler(procedureSchema.params) : null;
-		const validateInputType = procedureSchema.input ? constructMimeValidator(procedureSchema.input) : null;
-
-		const requiresInput = procedureSchema.input !== null;
-		const inputSchema = procedureSchema.input?.type === 'lex' ? procedureSchema.input.schema : null;
-
-		const handler = config.handler;
-
-		this.#handlers[procedureSchema.nsid] = {
-			method: 'POST',
-			handler: async ({ request, url }) => {
-				let params: Record<string, Literal | Literal[]>;
-				let input: Record<string, unknown> | undefined;
-
-				if (handleParams !== null) {
-					const result = handleParams(url.searchParams);
-					if (!result.ok) {
-						return validationError('params', result);
-					}
-
-					params = result.value;
-				} else {
-					params = {};
-				}
-
-				if (requiresInput) {
-					if (!hasRequestBody(request)) {
-						return invalidRequest(`request body is expected but none was provided`);
-					}
-
-					if (validateInputType !== null) {
-						const result = validateInputType(request);
-						if (!result.ok) {
-							return invalidRequest(result.error);
-						}
-					}
-
-					if (inputSchema !== null) {
-						let raw: any;
-						try {
-							raw = await request.json();
-						} catch {
-							return invalidRequest(`invalid request body (failed to parse json)`);
-						}
-
-						const result = safeParse(inputSchema, raw);
-						if (!result.ok) {
-							return validationError('input', result);
-						}
-
-						input = result.value;
-					}
-				} else {
-					if (hasRequestBody(request)) {
-						return invalidRequest(`request body is provided when none was expected`);
-					}
-				}
-
-				const context: UnknownOperationContext = {
-					request: request,
-					signal: request.signal,
-					params: params,
-					input: input,
-				};
-
-				const output = await handler(context as any);
-
-				if (output instanceof Response) {
-					return output;
-				}
-
-				return new Response(null);
-			},
-		};
-	}
-
-	addSubscription<
-		TSubscription extends XRPCSubscriptionMetadata,
-		TConfig extends SubscriptionConfig<TSubscription>,
-	>(subscription: TSubscription | Namespaced<TSubscription>, config: TConfig): void {
-		const websocket = this.#websocket;
-		if (websocket === undefined) {
-			throw new Error(`WebSocket adapter not configured`);
-		}
-
-		const subscriptionSchema = unwrapLxm(subscription);
-		const nsid = subscriptionSchema.nsid;
-
-		const handleParams = subscriptionSchema.params ? constructParamsHandler(subscriptionSchema.params) : null;
-		const handler = config.handler;
-
-		this.#handlers[nsid] = {
-			method: 'GET',
-			handler: async ({ request, url }) => {
-				{
-					const con = request.headers.get('connection');
-					const req = request.headers.get('upgrade');
-					if (
-						con === null ||
-						req === null ||
-						con.toLowerCase() !== 'upgrade' ||
-						req.toLowerCase() !== 'websocket'
-					) {
-						return invalidRequest(`invalid WebSocket upgrade`);
-					}
-				}
-
-				let params: Record<string, Literal | Literal[]>;
-
-				if (handleParams !== null) {
-					const result = handleParams(url.searchParams);
-					if (!result.ok) {
-						return validationError('params', result);
-					}
-
-					params = result.value;
-				} else {
-					params = {};
-				}
-
-				const upgrade = await websocket.upgrade(request, async (ws) => {
-					const signal = ws.signal;
-
-					const context: UnknownSubscriptionContext = {
-						request: request,
-						params: params,
-						signal: signal,
-					};
-
-					try {
-						for await (const message of handler(context)) {
-							if (signal.aborted) {
-								break;
-							}
-
-							const type = extractMessageType(message, nsid);
-							const body = omitMessageType(message);
-
-							const frame = encodeMessageFrame(body, type);
-							await ws.send(frame);
-							const drained = ws.drain();
-							if (drained) {
-								await drained;
-							}
-						}
-
-						ws.close(1000);
-					} catch (err) {
-						if (err instanceof XRPCSubscriptionError) {
-							const frame = encodeErrorFrame(err.error, err.message || undefined);
-
-							try {
-								await ws.send(frame);
-							} catch {
-								// best-effort, socket may already be closed
-							}
-
-							ws.close(err.closeCode, err.error);
-							return;
-						}
-
-						ws.close(1011, `internal server error`);
-						this.#observeSocketError(err, request);
-					}
-				});
-
-				if (upgrade !== undefined) {
-					return upgrade;
-				}
-
-				return invalidRequest(`WebSocket upgrade failed`);
-			},
-		};
-	}
-}

package/lib/main/types/operation.ts

@@ -1,130 +0,0 @@
-import type {
-	InferOutput,
-	ObjectSchema,
-	VariantSchema,
-	XRPCBlobBodyParam,
-	XRPCLexBodyParam,
-	XRPCProcedureMetadata,
-	XRPCQueryMetadata,
-	XRPCSubscriptionMetadata,
-} from '@atcute/lexicons/validations';
-
-import type { Literal, Promisable } from '../../types/misc.ts';
-import type { JSONResponse } from '../response.ts';
-
-/**
- * untyped variant of {@link QueryContext} / {@link ProcedureContext}.
- *
- * `input` is set only when the lexicon declares a `lex` input body and the
- * request JSON parsed successfully. for blob inputs (and for procedures that
- * declare no input at all) it is `undefined`; handlers that expect a blob
- * should stream from `request.body` directly.
- */
-export type UnknownOperationContext = {
-	request: Request;
-	signal: AbortSignal;
-	params: Record<string, Literal | Literal[]>;
-	input?: Record<string, unknown>;
-};
-
-// #region Query
-
-export type QueryContext<TQuery extends XRPCQueryMetadata> = {
-	request: Request;
-	signal: AbortSignal;
-} & (TQuery['params'] extends ObjectSchema
-	? {
-			params: InferOutput<TQuery['params']>;
-		}
-	: {
-			// params
-		});
-
-export type QueryHandler<TQuery extends XRPCQueryMetadata> = (
-	context: QueryContext<TQuery>,
-) => Promisable<
-	TQuery['output'] extends null
-		? Response | void
-		: TQuery['output'] extends XRPCLexBodyParam
-			? Response | JSONResponse<InferOutput<TQuery['output']['schema']>>
-			: Response
->;
-
-export type QueryConfig<TQuery extends XRPCQueryMetadata = XRPCQueryMetadata> = {
-	handler: QueryHandler<TQuery>;
-};
-
-// #region Procedure
-
-export type ProcedureContext<TProcedure extends XRPCProcedureMetadata> = {
-	signal: AbortSignal;
-} & (TProcedure['input'] extends XRPCBlobBodyParam
-	? {
-			request: Request & { readonly body: ReadableStream<Uint8Array> };
-		}
-	: TProcedure['input'] extends XRPCLexBodyParam
-		? {
-				request: Request & { readonly body: null };
-			}
-		: {
-				request: Request;
-			}) &
-	(TProcedure['params'] extends ObjectSchema
-		? {
-				params: InferOutput<TProcedure['params']>;
-			}
-		: {
-				// params
-			}) &
-	(TProcedure['input'] extends XRPCLexBodyParam
-		? {
-				input: InferOutput<TProcedure['input']['schema']>;
-			}
-		: {
-				// input
-			});
-
-export type ProcedureHandler<TProcedure extends XRPCProcedureMetadata> = (
-	context: ProcedureContext<TProcedure>,
-) => Promisable<
-	TProcedure['output'] extends null
-		? Response | void
-		: TProcedure['output'] extends XRPCLexBodyParam
-			? Response | JSONResponse<InferOutput<TProcedure['output']['schema']>>
-			: Response
->;
-
-export type ProcedureConfig<TProcedure extends XRPCProcedureMetadata = XRPCProcedureMetadata> = {
-	handler: ProcedureHandler<TProcedure>;
-};
-
-// #region Subscription
-
-export interface UnknownSubscriptionContext {
-	request: Request;
-	signal: AbortSignal;
-	params: Record<string, Literal | Literal[]>;
-}
-
-export type SubscriptionContext<TSubscription extends XRPCSubscriptionMetadata> = {
-	request: Request;
-	signal: AbortSignal;
-} & (TSubscription['params'] extends ObjectSchema
-	? {
-			params: InferOutput<TSubscription['params']>;
-		}
-	: {
-			// params
-		});
-
-export type SubscriptionHandler<TSubscription extends XRPCSubscriptionMetadata> = (
-	context: SubscriptionContext<TSubscription>,
-) => AsyncIterable<
-	TSubscription['message'] extends ObjectSchema | VariantSchema<any>
-		? InferOutput<TSubscription['message']>
-		: never
->;
-
-export type SubscriptionConfig<TSubscription extends XRPCSubscriptionMetadata = XRPCSubscriptionMetadata> = {
-	handler: SubscriptionHandler<TSubscription>;
-};

package/lib/main/types/websocket.ts

@@ -1,22 +0,0 @@
-import type { Promisable } from '../../types/misc.ts';
-
-export interface WebSocketConnection {
-	signal: AbortSignal;
-	send(data: Uint8Array): void | Promise<void>;
-	/**
-	 * backpressure hook invoked by the router after every frame it sends.
-	 * adapters that can observe the outgoing send buffer (Node `ws`, Bun, Deno)
-	 * should resolve only once the buffer has drained below a healthy threshold.
-	 * adapters without that visibility (e.g. Cloudflare Workers) should return
-	 * synchronously.
-	 */
-	drain(): void | Promise<void>;
-	close(code?: number, reason?: string): void;
-}
-
-export interface WebSocketAdapter {
-	upgrade(
-		request: Request,
-		handler: (ws: WebSocketConnection) => Promisable<void>,
-	): Promisable<Response | undefined>;
-}

package/lib/main/utils/frames.ts

@@ -1,71 +0,0 @@
-import { encode } from '@atcute/cbor';
-import { concat } from '@atcute/uint8array';
-
-interface MessageFrameHeader {
-	op: 1;
-	t?: string; // Type discriminator for union messages (relative to NSID)
-}
-
-interface ErrorFrameHeader {
-	op: -1;
-}
-
-interface ErrorFrameBody {
-	error: string;
-	message?: string;
-}
-
-export const encodeMessageFrame = (body: unknown, type?: string): Uint8Array => {
-	const header: MessageFrameHeader = {
-		op: 1,
-		t: type,
-	};
-
-	return concat([encode(header), encode(body)]);
-};
-
-export const encodeErrorFrame = (error: string, message?: string): Uint8Array => {
-	const header: ErrorFrameHeader = {
-		op: -1,
-	};
-
-	const body: ErrorFrameBody = {
-		error: error,
-		message: message,
-	};
-
-	return concat([encode(header), encode(body)]);
-};
-
-export const extractMessageType = (message: unknown, nsid: string): string | undefined => {
-	if (typeof message !== 'object' || message === null) {
-		return undefined;
-	}
-
-	const obj = message as Record<string, unknown>;
-	const type = obj.$type;
-
-	if (typeof type !== 'string') {
-		return undefined;
-	}
-
-	// If type starts with the subscription NSID, make it relative
-	// e.g., "com.atproto.sync.subscribeRepos#commit" → "#commit"
-	if (type.startsWith(nsid + '#')) {
-		return type.slice(nsid.length);
-	}
-
-	// Otherwise return the full type
-	return type;
-};
-
-export const omitMessageType = (message: unknown): unknown => {
-	if (typeof message !== 'object' || message === null) {
-		return message;
-	}
-
-	const obj = message as Record<string, unknown>;
-	const { $type: _type, ...rest } = obj;
-
-	return rest;
-};

package/lib/main/utils/middlewares.ts

@@ -1,13 +0,0 @@
-export type Middleware<TParams extends any[], TReturn> = (
-	...params: [...TParams, next: (...params: TParams) => TReturn]
-) => TReturn;
-
-export const createAsyncMiddlewareRunner = <TParams extends any[], TReturn>(
-	middlewares: [...Middleware<TParams, Promise<TReturn>>[], Middleware<TParams, Promise<TReturn>>],
-) => {
-	// prettier-ignore
-	return middlewares.reduceRight<(...params: TParams) => Promise<TReturn>>(
-		(next, run) => (...args) => run(...args, next),
-		() => Promise.reject(new Error(`middleware chain exhausted`)),
-	);
-};

package/lib/main/utils/namespaced.ts

@@ -1,5 +0,0 @@
-export type Namespaced<T> = { mainSchema: T };
-
-export const unwrapLxm = <T extends object>(schema: T | Namespaced<T>): T => {
-	return 'mainSchema' in schema ? (schema as Namespaced<T>).mainSchema : schema;
-};