@atcute/xrpc-server 0.1.2 → 0.1.4

package/lib/main/utils/event-emitter.ts

@@ -0,0 +1,116 @@
+/** Converts a tuple into a listener function */
+export type ListenerFor<T extends any[]> = (...args: T) => void;
+
+/** Generic record of the event name and its argument tuple */
+export type EventMap = {
+	[key: string | symbol]: any[];
+};
+
+type MaybeArray<T> = T | T[];
+
+/** Event emitter */
+export class EventEmitter<Events extends EventMap> {
+	#events?: { [E in keyof Events]?: MaybeArray<ListenerFor<Events[E]>> };
+
+	/**
+	 * Appends a listener for the specified event name
+	 * @param name Name of the event
+	 * @param listener Callback that should be invoked when an event is dispatched
+	 * @returns Cleanup function that can be called to remove it
+	 */
+	on<E extends keyof Events>(name: E, listener: ListenerFor<Events[E]>): () => void {
+		let events = this.#events;
+		let existing: MaybeArray<ListenerFor<Events[E]>> | undefined;
+
+		if (events === undefined) {
+			events = this.#events = Object.create(null);
+		} else {
+			existing = events[name];
+		}
+
+		if (existing === undefined) {
+			events![name] = listener;
+		} else if (typeof existing === 'function') {
+			events![name] = [existing, listener];
+		} else {
+			events![name] = existing.concat(listener);
+		}
+
+		// @ts-expect-error: complains about `listener`
+		return this.off.bind(this, name, listener);
+	}
+
+	/**
+	 * Remove listener from the specified event name
+	 * @param name Name of the event
+	 * @param listener Callback to remove
+	 */
+	off<E extends keyof Events>(name: E, listener: ListenerFor<Events[E]>): void {
+		const events = this.#events;
+
+		if (events === undefined) {
+			return;
+		}
+
+		const list = events[name];
+
+		if (list == undefined) {
+			return;
+		}
+
+		if (list === listener) {
+			delete events[name];
+		} else if (typeof list !== 'function') {
+			const index = list.indexOf(listener);
+
+			if (index !== -1) {
+				if (list.length === 2) {
+					// ^ flips the bit, it's either 0 or 1 here.
+					events[name] = list[index ^ 1];
+				} else {
+					events[name] = list.toSpliced(index, 1);
+				}
+			}
+		}
+	}
+
+	/**
+	 * Emit an event with the specified name and its payload
+	 * @param name Name of the event
+	 * @param args Payload for the event
+	 * @returns Whether a listener has been called
+	 */
+	emit<E extends keyof Events>(name: E, ...args: Events[E]): boolean {
+		const events = this.#events;
+
+		if (events === undefined) {
+			return false;
+		}
+
+		const handler = events[name];
+
+		if (handler === undefined) {
+			return false;
+		}
+
+		if (typeof handler === 'function') {
+			handler.apply(this, args);
+		} else {
+			for (let idx = 0, len = handler.length; idx < len; idx++) {
+				handler[idx].apply(this, args);
+			}
+		}
+
+		return true;
+	}
+
+	/**
+	 * Determines if there is a listener on a specified event name
+	 * @param name Name of the event
+	 * @returns Whether there is a listener registered
+	 */
+	has(name: keyof Events): boolean {
+		const events = this.#events;
+		return events !== undefined && name in events;
+	}
+}

package/lib/main/utils/frames.ts

@@ -0,0 +1,71 @@
+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/namespaced.ts

@@ -0,0 +1,5 @@
+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;
+};

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

@@ -0,0 +1,111 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+import type { Promisable } from '../../types/misc.js';
+import type { XRPCRouter } from '../router.js';
+import type { WebSocketAdapter, WebSocketConnection } from '../types/websocket.js';
+import { EventEmitter } from './event-emitter.js';
+
+interface WebSocketHandlerContext {
+	handler: ((ws: WebSocketConnection) => Promisable<void>) | null;
+}
+
+export interface SubscriptionClient extends Disposable {
+	events: EventEmitter<{
+		message: [data: Uint8Array];
+		close: [event: { code: number; reason: string; wasClean: boolean }];
+	}>;
+	dispose(): void;
+}
+
+export interface SubscriptionMock {
+	subscribe(url: string): Promise<SubscriptionClient>;
+}
+
+export class MockWebSocketAdapter implements WebSocketAdapter {
+	#context = new AsyncLocalStorage<WebSocketHandlerContext>();
+
+	upgrade(
+		_request: Request,
+		handler: (ws: WebSocketConnection) => Promisable<void>,
+	): Promisable<Response | undefined> {
+		const ctx = this.#context.getStore();
+		if (!ctx) {
+			return undefined;
+		}
+
+		ctx.handler = handler;
+
+		return new Response(null);
+	}
+
+	attach(router: XRPCRouter): SubscriptionMock {
+		return {
+			subscribe: async (url) => {
+				const ctx: WebSocketHandlerContext = {
+					handler: null,
+				};
+
+				await this.#context.run(ctx, async () => {
+					const urlp = new URL(url, 'http://localhost');
+					const request = new Request(urlp, {
+						headers: {
+							upgrade: 'websocket',
+							connection: 'upgrade',
+						},
+					});
+
+					const response = await router.fetch(request);
+
+					return response;
+				});
+
+				if (!ctx.handler) {
+					throw new Error(`WebSocket upgrade succeeded but no handler was set`);
+				}
+
+				const events = new EventEmitter<{
+					message: [data: Uint8Array];
+					close: [event: { code: number; reason: string; wasClean: boolean }];
+				}>();
+
+				const controller = new AbortController();
+				const signal = controller.signal;
+
+				const connection: WebSocketConnection = {
+					signal: signal,
+					send(data) {
+						events.emit('message', data);
+					},
+					close(code = 1000, reason = '') {
+						if (!signal.aborted) {
+							events.emit('close', { code, reason, wasClean: true });
+							controller.abort();
+						}
+					},
+				};
+
+				{
+					const handler = ctx.handler;
+					setTimeout(() => {
+						handler(connection);
+					}, 1);
+				}
+
+				const client: SubscriptionClient = {
+					events,
+					dispose() {
+						if (!signal.aborted) {
+							events.emit('close', { code: 1000, reason: '', wasClean: true });
+							controller.abort();
+						}
+					},
+					[Symbol.dispose]() {
+						this.dispose();
+					},
+				};
+
+				return client;
+			},
+		};
+	}
+}

package/lib/main/xrpc-error.ts

@@ -78,3 +78,23 @@ export class UpstreamTimeoutError extends XRPCError {
 		super({ status, error, description });
 	}
 }
+
+export interface XRPCSubscriptionErrorOptions {
+	closeCode?: number;
+	error: string;
+	description?: 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}` : ''}`);
+
+		this.closeCode = closeCode;
+		this.error = error;
+		this.description = description;
+	}
+}

package/lib/main/xrpc-handler.ts

@@ -0,0 +1,54 @@
+import type { XRPCProcedureMetadata, XRPCQueryMetadata } from '@atcute/lexicons/validations';
+
+import { XRPCRouter, type XRPCRouterOptions } from './router.js';
+import type { ProcedureConfig, QueryConfig } from './types/operation.js';
+import { unwrapLxm, type Namespaced } from './utils/namespaced.js';
+
+type XrpcHandlerRouterOptions = Pick<XRPCRouterOptions, 'middlewares' | 'handleNotFound' | 'handleException'>;
+
+export type XrpcQueryHandlerOptions<TQuery extends XRPCQueryMetadata> = {
+	lxm: TQuery | Namespaced<TQuery>;
+	routerOptions?: XrpcHandlerRouterOptions;
+} & QueryConfig<TQuery>;
+
+export type XrpcProcedureHandlerOptions<TProcedure extends XRPCProcedureMetadata> =
+	{
+		lxm: TProcedure | Namespaced<TProcedure>;
+		routerOptions?: XrpcHandlerRouterOptions;
+	} & ProcedureConfig<TProcedure>;
+
+export type XrpcHandlerOptions =
+	| XrpcQueryHandlerOptions<XRPCQueryMetadata>
+	| XrpcProcedureHandlerOptions<XRPCProcedureMetadata>;
+
+/**
+ * create a fetch handler for a single xrpc query or procedure.
+ * requests are expected at `/xrpc/<nsid>`.
+ * subscriptions are not supported.
+ */
+export function createXrpcHandler<TQuery extends XRPCQueryMetadata>(
+	options: XrpcQueryHandlerOptions<TQuery>,
+): (request: Request) => Promise<Response>;
+export function createXrpcHandler<TProcedure extends XRPCProcedureMetadata>(
+	options: XrpcProcedureHandlerOptions<TProcedure>,
+): (request: Request) => Promise<Response>;
+export function createXrpcHandler(options: XrpcHandlerOptions): (request: Request) => Promise<Response> {
+	const { lxm, handler, routerOptions } = options;
+
+	const router = new XRPCRouter(routerOptions);
+
+	const schema = unwrapLxm(lxm);
+
+	switch (schema.type) {
+		case 'xrpc_query': {
+			router.addQuery(schema, { handler: handler as QueryConfig<XRPCQueryMetadata>['handler'] });
+			break;
+		}
+		case 'xrpc_procedure': {
+			router.addProcedure(schema, { handler: handler as ProcedureConfig<XRPCProcedureMetadata>['handler'] });
+			break;
+		}
+	}
+
+	return router.fetch;
+}

package/package.json

@@ -1,13 +1,16 @@
 {
   "type": "module",
   "name": "@atcute/xrpc-server",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "a small web framework for handling XRPC operations",
   "license": "0BSD",
   "repository": {
     "url": "https://github.com/mary-ext/atcute",
     "directory": "packages/servers/xrpc-server"
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "files": [
     "dist/",
     "lib/",
@@ -21,23 +24,25 @@
   },
   "dependencies": {
     "@badrap/valita": "^0.4.6",
-    "nanoid": "^5.1.5",
-    "@atcute/crypto": "^2.2.5",
-    "@atcute/identity": "^1.1.1",
-    "@atcute/lexicons": "^1.2.2",
-    "@atcute/identity-resolver": "^1.1.4",
+    "nanoid": "^5.1.6",
+    "@atcute/cbor": "^2.2.8",
+    "@atcute/crypto": "^2.3.0",
+    "@atcute/identity": "^1.1.3",
+    "@atcute/identity-resolver": "^1.2.1",
     "@atcute/multibase": "^1.1.6",
-    "@atcute/uint8array": "^1.0.5"
+    "@atcute/lexicons": "^1.2.5",
+    "@atcute/uint8array": "^1.0.6"
   },
   "devDependencies": {
     "@atcute/xrpc-server": "file:",
-    "@vitest/coverage-v8": "^3.2.4",
-    "vitest": "^3.2.4",
-    "@atcute/atproto": "^3.1.6",
-    "@atcute/bluesky": "^3.2.5"
+    "@types/node": "^22.19.3",
+    "@vitest/coverage-v8": "^4.0.16",
+    "vitest": "^4.0.16",
+    "@atcute/atproto": "^3.1.9",
+    "@atcute/bluesky": "^3.2.14"
   },
   "scripts": {
-    "build": "tsc --project tsconfig.build.json",
+    "build": "tsgo --project tsconfig.build.json",
     "test": "vitest --coverage",
     "prepublish": "rm -rf dist; pnpm run build"
   }