@atcute/xrpc-server 0.1.12 → 1.0.0

package/lib/main/router.ts

@@ -38,8 +38,13 @@ type InternalRouteData = {
 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>;
-export type SubscriptionExceptionHandler = (error: unknown, request: Request) => void;
+
+/** 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) {
@@ -60,23 +65,40 @@ export const defaultNotFoundHandler: NotFoundHandler = () => {
 	return new Response('Not Found', { status: 404 });
 };
 
-export const defaultSubscriptionExceptionHandler: SubscriptionExceptionHandler = (error: unknown) => {
-	throw error;
-};
-
 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;
-	handleSubscriptionException?: SubscriptionExceptionHandler;
+	/**
+	 * 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;
-	#handleSubscriptionException: SubscriptionExceptionHandler;
+	#onError?: ErrorObserver;
+	#onSocketError?: SocketErrorObserver;
 	#websocket?: WebSocketAdapter;
 
 	fetch: (request: Request) => Promise<Response>;
@@ -85,7 +107,9 @@ export class XRPCRouter {
 		middlewares = [],
 		handleException = defaultExceptionHandler,
 		handleNotFound = defaultNotFoundHandler,
-		handleSubscriptionException = defaultSubscriptionExceptionHandler,
+		handleHealthCheck,
+		onError,
+		onSocketError,
 		websocket,
 	}: XRPCRouterOptions = {}) {
 		const runner = createAsyncMiddlewareRunner([...middlewares, (request) => this.#dispatch(request)]);
@@ -93,10 +117,46 @@ export class XRPCRouter {
 		this.fetch = (request) => runner(request);
 		this.#handleException = handleException;
 		this.#handleNotFound = handleNotFound;
-		this.#handleSubscriptionException = handleSubscriptionException;
+		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;
@@ -107,15 +167,31 @@ export class XRPCRouter {
 
 		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);
 		}
 
-		if (request.method !== route.method) {
+		// 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: 'InvalidHttpMethod', message: `invalid http method (expected ${route.method})` },
-				{ status: 405, headers: { allow: `${route.method}` } },
+				{ error: 'InvalidRequest', message: `invalid http method (expected ${route.method})` },
+				{ status: 405, headers: { allow: route.method === 'GET' ? 'GET, HEAD' : route.method } },
 			);
 		}
 
@@ -131,6 +207,7 @@ export class XRPCRouter {
 				return new Response(null, { status: 499 });
 			}
 
+			this.#observeError(err, request);
 			return this.#handleException(err, request);
 		}
 	}
@@ -350,12 +427,16 @@ export class XRPCRouter {
 
 							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.description);
+							const frame = encodeErrorFrame(err.error, err.message || undefined);
 
 							try {
 								await ws.send(frame);
@@ -368,7 +449,7 @@ export class XRPCRouter {
 						}
 
 						ws.close(1011, `internal server error`);
-						this.#handleSubscriptionException(err, request);
+						this.#observeSocketError(err, request);
 					}
 				});
 

package/lib/main/types/operation.ts

@@ -12,6 +12,14 @@ import type {
 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;

package/lib/main/types/websocket.ts

@@ -3,6 +3,14 @@ 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;
 }
 

package/lib/main/utils/websocket-mock.ts

@@ -79,6 +79,9 @@ export class MockWebSocketAdapter implements WebSocketAdapter {
 					send(data) {
 						onMessage.emit(data);
 					},
+					drain() {
+						// tests have no outgoing buffer to observe
+					},
 					close(code = 1000, reason = '') {
 						if (!signal.aborted) {
 							onClose.emit({ code, reason, wasClean: true });

package/lib/main/xrpc-error.ts

@@ -1,7 +1,71 @@
+/**
+ * a single WWW-Authenticate challenge. exactly one of `params` or `token68` may
+ * be provided. a bare scheme (no params, no token) is valid and renders as just
+ * the scheme name.
+ *
+ * @see {@link https://datatracker.ietf.org/doc/html/rfc7235#section-4.1 | RFC 7235 §4.1}
+ */
+export interface WWWAuthenticateChallenge {
+	/** authentication scheme, e.g. `Bearer`, `DPoP`, `Basic`. */
+	scheme: string;
+	/** auth-param pairs. entries whose value is `undefined` are omitted. */
+	params?: Record<string, string | undefined>;
+	/**
+	 * token68 value for schemes that carry one instead of auth-params (e.g.
+	 * `Basic`). mutually exclusive with `params`.
+	 */
+	token68?: string;
+}
+
+/**
+ * formats one or more WWW-Authenticate challenges into a single header value.
+ *
+ * each challenge is emitted as `<scheme>` followed by its params or token68.
+ * multiple challenges are joined with `, `. auth-param values are quoted using
+ * `JSON.stringify` (RFC 7230 quoted-string semantics for ASCII content).
+ *
+ * @param challenges one challenge, or an ordered array of challenges
+ * @returns the formatted header value
+ *
+ * @example
+ * ```ts
+ * formatWWWAuthenticate({ scheme: 'Bearer', params: { error: 'BadJwtSignature' } })
+ * // => `Bearer error="BadJwtSignature"`
+ * ```
+ */
+export const formatWWWAuthenticate = (
+	challenges: WWWAuthenticateChallenge | WWWAuthenticateChallenge[],
+): string => {
+	const list = Array.isArray(challenges) ? challenges : [challenges];
+	return list.map(formatChallenge).join(', ');
+};
+
+const formatChallenge = (challenge: WWWAuthenticateChallenge): string => {
+	if (challenge.token68 !== undefined) {
+		return `${challenge.scheme} ${challenge.token68}`;
+	}
+
+	if (challenge.params !== undefined) {
+		const parts: string[] = [];
+		for (const name in challenge.params) {
+			const value = challenge.params[name];
+			if (value !== undefined) {
+				parts.push(`${name}=${JSON.stringify(value)}`);
+			}
+		}
+
+		if (parts.length > 0) {
+			return `${challenge.scheme} ${parts.join(', ')}`;
+		}
+	}
+
+	return challenge.scheme;
+};
+
 export interface XRPCErrorOptions {
 	status: number;
 	error: string;
-	description?: string;
+	message?: string;
 	headers?: HeadersInit;
 }
 
@@ -11,54 +75,65 @@ export class XRPCError extends Error {
 
 	/** error name */
 	readonly error: string;
-	/** error message */
-	readonly description?: string;
 	/** response headers */
 	readonly headers?: HeadersInit;
 
-	constructor({ status, error, description, headers }: XRPCErrorOptions) {
-		super(`${error} > ${description ?? '(unspecified description)'}`);
+	constructor({ status, error, message, headers }: XRPCErrorOptions) {
+		super(message);
 
 		this.status = status;
 
 		this.error = error;
-		this.description = description;
 		this.headers = headers;
 	}
 
 	toResponse(): Response {
 		return Response.json(
-			{ error: this.error, message: this.description },
+			{ error: this.error, message: this.message || undefined },
 			{ status: this.status, headers: this.headers },
 		);
 	}
 }
 
 export class InvalidRequestError extends XRPCError {
-	constructor({
-		status = 400,
-		error = 'InvalidRequest',
-		description,
-		headers,
-	}: Partial<XRPCErrorOptions> = {}) {
-		super({ status, error, description, headers });
+	constructor({ status = 400, error = 'InvalidRequest', message, headers }: Partial<XRPCErrorOptions> = {}) {
+		super({ status, error, message, headers });
 	}
 }
 
+export interface AuthRequiredErrorOptions extends Partial<XRPCErrorOptions> {
+	/**
+	 * WWW-Authenticate challenge(s) to attach to the response. the formatted
+	 * header is set on `headers` automatically, and `access-control-expose-headers`
+	 * is appended so browsers can read it from CORS responses.
+	 */
+	wwwAuthenticate?: WWWAuthenticateChallenge | WWWAuthenticateChallenge[];
+}
+
 export class AuthRequiredError extends XRPCError {
 	constructor({
 		status = 401,
 		error = 'AuthenticationRequired',
-		description,
+		message,
 		headers,
-	}: Partial<XRPCErrorOptions> = {}) {
-		super({ status, error, description, headers });
+		wwwAuthenticate,
+	}: AuthRequiredErrorOptions = {}) {
+		let mergedHeaders = headers;
+
+		if (wwwAuthenticate !== undefined) {
+			const target = new Headers(headers);
+			target.set('www-authenticate', formatWWWAuthenticate(wwwAuthenticate));
+			target.append('access-control-expose-headers', 'www-authenticate');
+			mergedHeaders = target;
+		}
+
+		super({ status, error, message, headers: mergedHeaders });
 	}
 }
 
 export class ForbiddenError extends XRPCError {
-	constructor({ status = 403, error = 'Forbidden', description, headers }: Partial<XRPCErrorOptions> = {}) {
-		super({ status, error, description, headers });
+	constructor({ status = 403, error = 'Forbidden', message, headers }: Partial<XRPCErrorOptions> = {}) {
+		super({ status, error, message, headers });
 	}
 }
 
@@ -66,10 +141,10 @@ export class RateLimitExceededError extends XRPCError {
 	constructor({
 		status = 429,
 		error = 'RateLimitExceeded',
-		description,
+		message,
 		headers,
 	}: Partial<XRPCErrorOptions> = {}) {
-		super({ status, error, description, headers });
+		super({ status, error, message, headers });
 	}
 }
 
@@ -77,21 +152,16 @@ export class InternalServerError extends XRPCError {
 	constructor({
 		status = 500,
 		error = 'InternalServerError',
-		description,
+		message,
 		headers,
 	}: Partial<XRPCErrorOptions> = {}) {
-		super({ status, error, description, headers });
+		super({ status, error, message, headers });
 	}
 }
 
 export class UpstreamFailureError extends XRPCError {
-	constructor({
-		status = 502,
-		error = 'UpstreamFailure',
-		description,
-		headers,
-	}: Partial<XRPCErrorOptions> = {}) {
-		super({ status, error, description, headers });
+	constructor({ status = 502, error = 'UpstreamFailure', message, headers }: Partial<XRPCErrorOptions> = {}) {
+		super({ status, error, message, headers });
 	}
 }
 
@@ -99,40 +169,33 @@ export class NotEnoughResourcesError extends XRPCError {
 	constructor({
 		status = 503,
 		error = 'NotEnoughResources',
-		description,
+		message,
 		headers,
 	}: Partial<XRPCErrorOptions> = {}) {
-		super({ status, error, description, headers });
+		super({ status, error, message, headers });
 	}
 }
 
 export class UpstreamTimeoutError extends XRPCError {
-	constructor({
-		status = 504,
-		error = 'UpstreamTimeout',
-		description,
-		headers,
-	}: Partial<XRPCErrorOptions> = {}) {
-		super({ status, error, description, headers });
+	constructor({ status = 504, error = 'UpstreamTimeout', message, headers }: Partial<XRPCErrorOptions> = {}) {
+		super({ status, error, message, headers });
 	}
 }
 
 export interface XRPCSubscriptionErrorOptions {
 	closeCode?: number;
 	error: string;
-	description?: string;
+	message?: string;
 }
 
 export class XRPCSubscriptionError extends Error {
 	readonly closeCode: number;
 	readonly error: string;
-	readonly description?: string;
 
-	constructor({ closeCode = 1008, error, description }: XRPCSubscriptionErrorOptions) {
-		super(`Subscription error: ${error}${description ? ` - ${description}` : ''}`);
+	constructor({ closeCode = 1008, error, message }: XRPCSubscriptionErrorOptions) {
+		super(message);
 
 		this.closeCode = closeCode;
 		this.error = error;
-		this.description = description;
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atcute/xrpc-server",
-  "version": "0.1.12",
+  "version": "1.0.0",
   "description": "a small web framework for handling XRPC operations",
   "license": "0BSD",
   "repository": {
@@ -11,7 +11,8 @@
     "dist/",
     "lib/",
     "!lib/**/*.bench.ts",
-    "!lib/**/*.test.ts"
+    "!lib/**/*.test.ts",
+    "!dist/**/*.{test,bench}.*"
   ],
   "type": "module",
   "exports": {
@@ -24,26 +25,29 @@
   },
   "dependencies": {
     "@badrap/valita": "^0.4.6",
-    "nanoid": "^5.1.7",
+    "nanoid": "^5.1.11",
+    "@atcute/cbor": "^2.3.3",
+    "@atcute/identity-resolver": "^1.2.3",
     "@atcute/crypto": "^2.4.1",
-    "@atcute/cbor": "^2.3.2",
-    "@atcute/lexicons": "^1.2.9",
-    "@atcute/identity-resolver": "^1.2.2",
-    "@atcute/uint8array": "^1.1.1",
-    "@atcute/identity": "^1.1.4",
-    "@atcute/multibase": "^1.2.0"
+    "@atcute/lexicons": "^1.3.1",
+    "@atcute/identity": "^1.1.5",
+    "@atcute/multibase": "^1.2.0",
+    "@atcute/uint8array": "^1.1.1"
   },
   "devDependencies": {
     "@atcute/xrpc-server": "file:",
     "@mary-ext/simple-event-emitter": "^1.0.1",
-    "@types/node": "^25.5.2",
-    "@vitest/coverage-v8": "^4.1.2",
-    "vitest": "^4.1.2",
-    "@atcute/bluesky": "^3.3.0",
-    "@atcute/atproto": "^3.1.10"
+    "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.5",
+    "vitest": "^4.1.5",
+    "@atcute/atproto": "^3.1.12",
+    "@atcute/bluesky": "^3.3.4"
+  },
+  "peerDependencies": {
+    "@atcute/lexicons": "^1.0.0"
   },
   "scripts": {
-    "build": "tsgo --project tsconfig.build.json",
+    "build": "tsgo",
     "test": "vitest --coverage",
     "prepublish": "rm -rf dist; pnpm run build"
   }