@atproto/lex-server 0.0.11 → 0.0.13

package/dist/{lex-server.d.ts → lex-router.d.ts}

@@ -1,4 +1,5 @@
-import { InferMethodInput, InferMethodMessage, InferMethodOutput, InferMethodOutputBody, InferMethodOutputEncoding, InferMethodParams, Main, NsidString, Procedure, Query, Subscription } from '@atproto/lex-schema';
+import { DidString, InferMethodInput, InferMethodMessage, InferMethodOutput, InferMethodOutputBody, InferMethodOutputEncoding, InferMethodParams, Main, NsidString, Procedure, Query, Subscription } from '@atproto/lex-schema';
+import { LexServerError } from './errors.js';
 type Awaitable<T> = T | Promise<T>;
 /**
  * Union type representing the supported Lexicon method types.
@@ -270,7 +271,7 @@ export type LexRouterSubscriptionConfig<Method extends Subscription = Subscripti
  * ```typescript
  * const authHandler: LexRouterAuth<UserCredentials> = async (ctx) => {
  *   const token = ctx.request.headers.get('authorization')
- *   if (!token) throw new LexError('AuthenticationRequired', 'Missing token')
+ *   if (!token) throw new LexServerAuthError('AuthenticationRequired', 'Missing token')
  *   return { userId: await verifyToken(token) }
  * }
  * ```
@@ -299,8 +300,9 @@ export type LexRouterAuthContext<Method extends LexMethod = LexMethod> = {
  * // Simple token-based auth
  * const tokenAuth: LexRouterAuth<{ userId: string }> = async ({ request }) => {
  *   const token = request.headers.get('authorization')?.replace('Bearer ', '')
- *   if (!token) throw new LexError('AuthenticationRequired', 'Token required')
+ *   if (!token) throw new LexServerAuthError('AuthenticationRequired', 'Token required')
  *   const userId = await verifyToken(token)
+ *   if (!userId) throw new LexServerAuthError('AuthenticationRequired', 'Invalid token')
  *   return { userId }
  * }
  *
@@ -315,14 +317,18 @@ export type LexRouterAuth<Credentials = unknown, Method extends LexMethod = LexM
  *
  * Used for logging and monitoring errors that occur during request handling.
  */
-export type LexErrorHandlerContext = {
-    /** The error that was thrown during handling. */
-    error: unknown;
-    /** The original HTTP request that triggered the error. */
+export type HandlerErrorContext = {
     request: Request;
-    /** The Lexicon method that was being executed. */
     method: LexMethod;
+    error: LexServerError;
+};
+export type HandlerErrorHook = (ctx: HandlerErrorContext) => void | Promise<void>;
+export type SocketErrorContext = {
+    request: Request;
+    method: Subscription;
+    error: unknown;
 };
+export type SocketErrorHook = (ctx: SocketErrorContext) => void | Promise<void>;
 /**
  * Function that upgrades an HTTP request to a WebSocket connection.
  *
@@ -346,6 +352,10 @@ export type UpgradeWebSocket = (request: Request) => {
     /** The HTTP response to return (101 Switching Protocols). */
     response: Response;
 };
+export type HealthCheckHandler = (request: Request) => Awaitable<{
+    [x: string]: unknown;
+    status: 'ok';
+}>;
 /**
  * Configuration options for the {@link LexRouter}.
  *
@@ -364,25 +374,45 @@ export type UpgradeWebSocket = (request: Request) => {
  */
 export type LexRouterOptions = {
     /**
-     * Function to upgrade HTTP requests to WebSocket connections.
-     * Required for subscription methods. Defaults to Deno's built-in
-     * upgradeWebSocket if available.
+     * Function to upgrade HTTP requests to WebSocket connections. Required for
+     * subscription methods. Defaults to Deno's built-in
+     * {@link globalThis.upgradeWebSocket} if available. For NodeJS, use the
+     * homonymous export from `@atproto/lex-server/nodejs`.
      */
     upgradeWebSocket?: UpgradeWebSocket;
     /**
-     * Callback invoked when an error occurs during request handling.
-     * Useful for logging and error reporting. Not called for client-induced
-     * errors (e.g., request abortion).
+     * Callback invoked when an error occurs during request handling. Useful for
+     * logging and error reporting. Not called for client-induced errors (e.g.,
+     * request abortion).
+     */
+    onHandlerError?: HandlerErrorHook;
+    /**
+     * Optional hook for handling errors during generation of WebSocket messages.
      */
-    onHandlerError?: (ctx: LexErrorHandlerContext) => void | Promise<void>;
+    onSocketError?: SocketErrorHook;
     /**
-     * High water mark for WebSocket backpressure (in bytes).
-     * When buffered data exceeds this, the handler will wait before sending more.
+     * Optional health check handler. If provided, this function will be called
+     * for requests to the /xrpc/_health endpoint, allowing for custom health
+     * check logic and responses.
+     *
+     * If not provided, the server will respond to /xrpc/_health requests with a
+     * default JSON response of `{ status: 'ok' }`.
+     */
+    healthCheck?: HealthCheckHandler;
+    /**
+     * Optional fallback handler for requests that are not /xrpc/ paths. Can be
+     * used to serve static files or other routes. If not provided, non-/xrpc/
+     * requests will return 404 responses.
+     */
+    fallback?: FetchHandler;
+    /**
+     * High water mark for WebSocket backpressure (in bytes). When buffered data
+     * exceeds this, the handler will wait before sending more.
      */
     highWaterMark?: number;
     /**
-     * Low water mark for WebSocket backpressure (in bytes).
-     * The handler resumes sending when buffered data drops below this.
+     * Low water mark for WebSocket backpressure (in bytes). The handler resumes
+     * sending when buffered data drops below this.
      */
     lowWaterMark?: number;
 };
@@ -527,7 +557,7 @@ export declare class LexRouter {
     add<M extends LexMethod, Credentials = unknown>(ns: Main<M>, config: M extends Subscription ? LexRouterSubscriptionHandler<M, Credentials> | LexRouterSubscriptionConfig<M, Credentials> : M extends Query | Procedure ? LexRouterMethodHandler<M, Credentials> | LexRouterMethodConfig<M, Credentials> : never): this;
     private buildMethodHandler;
     private buildSubscriptionHandler;
-    private handleError;
+    private handlerError;
     /**
      * The main fetch handler for processing XRPC requests.
      *
@@ -559,5 +589,9 @@ export declare class LexRouter {
      */
     fetch: FetchHandler;
 }
+export type ServiceProxyInfo = {
+    did: DidString;
+    serviceId: string;
+};
 export {};
-//# sourceMappingURL=lex-server.d.ts.map
+//# sourceMappingURL=lex-router.d.ts.map

package/dist/lex-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lex-router.d.ts","sourceRoot":"","sources":["../src/lex-router.ts"],"names":[],"mappings":"AASA,OAAO,EACL,SAAS,EACT,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,yBAAyB,EACzB,iBAAiB,EACjB,IAAI,EACJ,UAAU,EACV,SAAS,EACT,KAAK,EACL,YAAY,EAIb,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAM5C,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;AAElC;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,SAAS,GAAG,YAAY,CAAA;AAExD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAA;IAChB,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,mCAAmC;IACnC,SAAS,EAAE,KAAK,GAAG,KAAK,CAAA;CACzB,CAAA;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,mCAAmC;IACnC,SAAS,EAAE,MAAM,GAAG,YAAY,CAAA;CACjC,CAAA;AAED;;;;;GAKG;AACH,MAAM,MAAM,IAAI,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAA;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,IAAI,GAAG,IAAI,IAAI;IAClD,sDAAsD;IACtD,UAAU,EAAE,CAAC,CAAA;IACb,iEAAiE;IACjE,SAAS,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;CACzB,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,YAAY,GAAG,CACzB,OAAO,EAAE,OAAO,EAChB,UAAU,CAAC,EAAE,cAAc,KACxB,OAAO,CAAC,QAAQ,CAAC,CAAA;AAEtB;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,uBAAuB,CAAC,MAAM,SAAS,SAAS,EAAE,WAAW,IAAI;IAC3E,+DAA+D;IAC/D,WAAW,EAAE,WAAW,CAAA;IACxB,uFAAuF;IACvF,KAAK,EAAE,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IACrC,iDAAiD;IACjD,MAAM,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAA;IACjC,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAA;IAChB,oEAAoE;IACpE,MAAM,EAAE,WAAW,CAAA;IACnB,oDAAoD;IACpD,UAAU,CAAC,EAAE,cAAc,CAAA;CAC5B,CAAA;AAED,KAAK,wBAAwB,CAAC,CAAC,IAAI,CAAC,SAAS,SAAS,GAAG,IAAI,GACzD;IAAE,QAAQ,CAAC,EAAE,SAAS,CAAC;IAAC,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,GAC1C,CAAC,CAAA;AAEL;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,MAAM,sBAAsB,CAAC,MAAM,SAAS,KAAK,GAAG,SAAS,IAC/D,QAAQ,GACR,CAAC;IACC,OAAO,CAAC,EAAE,WAAW,CAAA;CACtB,GAAG,CAAC,yBAAyB,CAAC,MAAM,CAAC,SAAS,kBAAkB,GAC7D;IAEE,QAAQ,CAAC,EAAE,kBAAkB,CAAA;IAC7B,IAAI,EAAE,qBAAqB,CAAC,MAAM,CAAC,CAAA;CACpC,GACD,wBAAwB,CAAC,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;AAEvE;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,sBAAsB,CAChC,MAAM,SAAS,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,EACpD,WAAW,GAAG,OAAO,IACnB,CACF,GAAG,EAAE,uBAAuB,CAAC,MAAM,EAAE,WAAW,CAAC,KAC9C,SAAS,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,qBAAqB,CAC/B,MAAM,SAAS,KAAK,GAAG,SAAS,GAAG,KAAK,GAAG,SAAS,EACpD,WAAW,GAAG,OAAO,IACnB;IACF,uDAAuD;IACvD,OAAO,EAAE,sBAAsB,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;IACpD,kFAAkF;IAClF,IAAI,EAAE,aAAa,CAAC,WAAW,EAAE,MAAM,CAAC,CAAA;CACzC,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,4BAA4B,CACtC,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,WAAW,GAAG,OAAO,IACnB,CACF,GAAG,EAAE,uBAAuB,CAAC,MAAM,EAAE,WAAW,CAAC,KAC9C,aAAa,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,2BAA2B,CACrC,MAAM,SAAS,YAAY,GAAG,YAAY,EAC1C,WAAW,GAAG,OAAO,IACnB;IACF,8DAA8D;IAC9D,OAAO,EAAE,4BAA4B,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;IAC1D,kFAAkF;IAClF,IAAI,EAAE,aAAa,CAAC,WAAW,EAAE,MAAM,CAAC,CAAA;CACzC,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,SAAS,GAAG,SAAS,IAAI;IACvE,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,MAAM,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAA;IACjC,wCAAwC;IACxC,OAAO,EAAE,OAAO,CAAA;IAChB,oDAAoD;IACpD,UAAU,CAAC,EAAE,cAAc,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,aAAa,CACvB,WAAW,GAAG,OAAO,EACrB,MAAM,SAAS,SAAS,GAAG,SAAS,IAClC,CAAC,GAAG,EAAE,oBAAoB,CAAC,MAAM,CAAC,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;AAE7E;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,SAAS,CAAA;IACjB,KAAK,EAAE,cAAc,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC7B,GAAG,EAAE,mBAAmB,KACrB,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAEzB,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,EAAE,YAAY,CAAA;IACpB,KAAK,EAAE,OAAO,CAAA;CACf,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;AAE/E;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK;IACnD,8DAA8D;IAC9D,MAAM,EAAE,SAAS,CAAA;IACjB,6DAA6D;IAC7D,QAAQ,EAAE,QAAQ,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,OAAO,KACb,SAAS,CAAC;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAC,MAAM,EAAE,IAAI,CAAA;CAAE,CAAC,CAAA;AAEtD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IACnC;;;;OAIG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAA;IACjC;;OAEG;IACH,aAAa,CAAC,EAAE,eAAe,CAAA;IAC/B;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAA;IAChC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,qBAAa,SAAS;IASR,QAAQ,CAAC,OAAO,EAAE,gBAAgB;IAR9C,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,UAAU,EAAE,YAAY,CAAC,CAAY;IAE5D;;;;OAIG;gBACkB,OAAO,GAAE,gBAAqB;IAEnD;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,SAAS,YAAY,EACxB,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,EACX,OAAO,EAAE,4BAA4B,CAAC,CAAC,EAAE,IAAI,CAAC,GAC7C,IAAI;IACP;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,SAAS,YAAY,EAAE,WAAW,EACrC,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,EACX,MAAM,EAAE,2BAA2B,CAAC,CAAC,EAAE,WAAW,CAAC,GAClD,IAAI;IACP;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,SAAS,KAAK,GAAG,SAAS,EAC7B,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,EACX,OAAO,EAAE,sBAAsB,CAAC,CAAC,EAAE,IAAI,CAAC,GACvC,IAAI;IACP;;;;;;OAMG;IACH,GAAG,CAAC,CAAC,SAAS,KAAK,GAAG,SAAS,EAAE,WAAW,EAC1C,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,EACX,MAAM,EAAE,qBAAqB,CAAC,CAAC,EAAE,WAAW,CAAC,GAC5C,IAAI;IACP;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,GAAG,CAAC,CAAC,SAAS,SAAS,EAAE,WAAW,GAAG,OAAO,EAC5C,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC,EACX,MAAM,EAAE,CAAC,SAAS,YAAY,GAEtB,4BAA4B,CAAC,CAAC,EAAE,WAAW,CAAC,GAC5C,2BAA2B,CAAC,CAAC,EAAE,WAAW,CAAC,GAC/C,CAAC,SAAS,KAAK,GAAG,SAAS,GAErB,sBAAsB,CAAC,CAAC,EAAE,WAAW,CAAC,GACtC,qBAAqB,CAAC,CAAC,EAAE,WAAW,CAAC,GACzC,KAAK,GACV,IAAI;IAuCP,OAAO,CAAC,kBAAkB;IAyE1B,OAAO,CAAC,wBAAwB;YA+JlB,YAAY;IAkB1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,KAAK,EAAE,YAAY,CAiElB;CACF;AA6GD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,EAAE,SAAS,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA"}

package/dist/{lex-server.js → lex-router.js}

@@ -5,7 +5,10 @@ const lex_cbor_1 = require("@atproto/lex-cbor");
 const lex_data_1 = require("@atproto/lex-data");
 const lex_json_1 = require("@atproto/lex-json");
 const lex_schema_1 = require("@atproto/lex-schema");
+const errors_js_1 = require("./errors.js");
 const drain_websocket_js_1 = require("./lib/drain-websocket.js");
+const XRPC_PATH_PREFIX = '/xrpc/';
+const XRPC_HEALTH_CHECK_PATH = '/xrpc/_health';
 /**
  * XRPC router for handling AT Protocol Lexicon methods.
  *
@@ -88,16 +91,17 @@ class LexRouter {
     }
     add(ns, config) {
         const method = (0, lex_schema_1.getMain)(ns);
-        if (this.handlers.has(method.nsid)) {
+        const nsid = normalizeNsid(method.nsid);
+        if (this.handlers.has(nsid)) {
             throw new TypeError(`Method ${method.nsid} already registered`);
         }
         const methodConfig = typeof config === 'function'
             ? { handler: config, auth: undefined }
             : config;
-        const fetch = method.type === 'subscription'
+        const handler = method.type === 'subscription'
             ? this.buildSubscriptionHandler(method, methodConfig.handler, methodConfig.auth)
             : this.buildMethodHandler(method, methodConfig.handler, methodConfig.auth);
-        this.handlers.set(method.nsid, fetch);
+        this.handlers.set(nsid, handler);
         return this;
     }
     buildMethodHandler(method, methodHandler, auth) {
@@ -111,7 +115,7 @@ class LexRouter {
                 (method.type === 'query' &&
                     request.method !== 'GET' &&
                     request.method !== 'HEAD')) {
-                return Response.json({ error: 'InvalidRequest', message: 'Method not allowed' }, { status: 405 });
+                return invalidRequestResponse('Method not allowed', 405);
             }
             try {
                 const url = new URL(request.url);
@@ -149,34 +153,28 @@ class LexRouter {
                 });
             }
             catch (error) {
-                return this.handleError(request, method, error);
+                return this.handlerError(request, method, error);
             }
         };
     }
     buildSubscriptionHandler(method, methodHandler, auth) {
-        const { onHandlerError, upgradeWebSocket = globalThis.Deno?.upgradeWebSocket, } = this.options;
+        const { onSocketError, upgradeWebSocket = globalThis.Deno?.upgradeWebSocket, } = this.options;
         if (!upgradeWebSocket) {
             throw new TypeError('WebSocket upgrade not supported in this environment. Please provide an upgradeWebSocket option when creating the LexRouter.');
         }
         return async (request, connection) => {
             if (request.method !== 'GET') {
-                return Response.json({ error: 'InvalidRequest', message: 'Method not allowed' }, { status: 405 });
+                return invalidRequestResponse('Method not allowed', 405);
             }
             if (request.headers.get('connection')?.toLowerCase() !== 'upgrade' ||
                 request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
-                return Response.json({
-                    error: 'InvalidRequest',
-                    message: 'XRPC subscriptions are only available over WebSocket',
-                }, {
-                    status: 426,
-                    headers: {
-                        Connection: 'Upgrade',
-                        Upgrade: 'websocket',
-                    },
+                return invalidRequestResponse('XRPC subscriptions are only available over WebSocket', 426, {
+                    Connection: 'Upgrade',
+                    Upgrade: 'websocket',
                 });
             }
             if (request.signal.aborted) {
-                return Response.json({ error: 'RequestAborted', message: 'The request was aborted' }, { status: 499 });
+                return invalidRequestResponse('Request aborted', 499);
             }
             try {
                 const { response, socket } = upgradeWebSocket(request);
@@ -186,11 +184,6 @@ class LexRouter {
                 const abortController = new AbortController();
                 const { signal } = abortController;
                 const abort = () => abortController.abort();
-                const onMessage = (event) => {
-                    const error = new lex_data_1.LexError('InvalidRequest', 'XRPC subscriptions do not accept messages', { cause: event });
-                    socket.send(encodeErrorFrame(error));
-                    socket.close(1008, error.error);
-                };
                 const onOpen = async () => {
                     try {
                         const url = new URL(request.url);
@@ -208,10 +201,23 @@ class LexRouter {
                             signal,
                         });
                         const iterator = iterable[Symbol.asyncIterator]();
-                        signal.addEventListener('abort', async () => {
-                            // @NOTE will cause the process to crash if this throws
-                            await iterator.return?.();
-                        });
+                        if (iterator.return) {
+                            signal.addEventListener('abort', () => {
+                                // @NOTE if iterator.return() throws, and no onSocketError is
+                                // provided, or if onSocketError itself throws, the error will
+                                // be unhandled, causing the process to crash. This is
+                                // intentional, as it surfaces critical errors that occur
+                                // during cleanup of the subscription.
+                                void new Promise((resolve) => {
+                                    // Wrapping in new Promise to catch any potential sync errors thrown by iterator.return()
+                                    resolve(iterator.return());
+                                }).catch(onSocketError
+                                    ? (error) => onSocketError({ request, method, error })
+                                    : null);
+                            }, {
+                                once: true,
+                            });
+                        }
                         while (!signal.aborted && socket.readyState === 1) {
                             const result = await iterator.next();
                             if (result.done)
@@ -230,17 +236,24 @@ class LexRouter {
                     catch (error) {
                         // If the socket is still open, send an error frame before closing
                         if (socket.readyState === 1) {
-                            const lexError = error instanceof lex_data_1.LexError
-                                ? error
-                                : new lex_data_1.LexError('InternalError', 'An internal error occurred');
-                            socket.send(encodeErrorFrame(lexError));
-                            socket.close(
+                            const isLexError = error instanceof lex_data_1.LexError;
                             // https://www.rfc-editor.org/rfc/rfc6455#section-7.4.1
-                            error instanceof lex_data_1.LexError ? 1008 : 1011, lexError.error);
+                            const code = isLexError && method.errors?.includes(error.error)
+                                ? 1008 // Policy Violation for known LexErrors
+                                : 1011; // Internal Error for unexpected errors
+                            if (isLexError) {
+                                socket.send(encodeErrorFrame(error.toJSON()));
+                                socket.close(code, error.error);
+                            }
+                            else {
+                                const error = 'InternalServerError';
+                                const message = 'An internal error occurred';
+                                socket.send(encodeErrorFrame({ error, message }));
+                                socket.close(code, error);
+                            }
                         }
-                        // Only report unexpected processing errors
-                        if (onHandlerError && !isAbortReason(request.signal, error)) {
-                            await onHandlerError({ error, request, method });
+                        if (onSocketError && !isAbortReason(signal, error)) {
+                            await onSocketError({ request, method, error });
                         }
                     }
                     finally {
@@ -254,20 +267,20 @@ class LexRouter {
                 return response;
             }
             catch (error) {
-                return this.handleError(request, method, error);
+                return this.handlerError(request, method, error);
             }
         };
     }
-    async handleError(request, method, error) {
+    async handlerError(request, method, cause) {
         // Only report unexpected processing errors
+        if (isAbortReason(request.signal, cause)) {
+            return Response.json({ error: 'RequestAborted' }, { status: 499 });
+        }
+        const error = errors_js_1.LexServerError.from(cause);
         const { onHandlerError } = this.options;
-        if (onHandlerError && !isAbortReason(request.signal, error)) {
+        if (onHandlerError)
             await onHandlerError({ error, request, method });
-        }
-        if (error instanceof lex_data_1.LexError) {
-            return error.toResponse();
-        }
-        return Response.json({ error: 'InternalError', message: 'An internal error occurred' }, { status: 500 });
+        return error.toResponse();
     }
     /**
      * The main fetch handler for processing XRPC requests.
@@ -299,17 +312,47 @@ class LexRouter {
      * ```
      */
     fetch = async (request, connection) => {
-        const nsid = extractMethodNsid(request);
-        const fetch = nsid
-            ? this.handlers.get(nsid)
-            : undefined;
-        if (fetch)
-            return fetch(request, connection);
-        if (!nsid || !(0, lex_schema_1.isNsidString)(nsid)) {
-            return Response.json({
-                error: 'InvalidRequest',
-                message: 'Invalid XRPC method path',
-            }, { status: 404 });
+        const { pathname } = new URL(request.url);
+        const atprotoProxy = request.headers.get('atproto-proxy');
+        if (!pathname.startsWith(XRPC_PATH_PREFIX)) {
+            // Handle non XRPC paths
+            const { fallback } = this.options;
+            if (fallback)
+                return fallback(request, connection);
+            return new Response('Not Found', { status: 404 });
+        }
+        if (pathname === XRPC_HEALTH_CHECK_PATH) {
+            if (request.method !== 'GET') {
+                return invalidRequestResponse('Method not allowed', 405);
+            }
+            if (atprotoProxy != null) {
+                return invalidRequestResponse('atproto-proxy header is not allowed on health check endpoint');
+            }
+            const { healthCheck } = this.options;
+            const data = healthCheck ? await healthCheck(request) : { status: 'ok' };
+            return Response.json(data);
+        }
+        const subPath = pathname.slice(XRPC_PATH_PREFIX.length);
+        if (!(0, lex_schema_1.isNsidString)(subPath)) {
+            return invalidRequestResponse('Invalid NSID in URL path');
+        }
+        const nsid = normalizeNsid(subPath);
+        if (atprotoProxy == null) {
+            const handler = this.handlers.get(nsid);
+            if (handler)
+                return handler(request, connection);
+        }
+        else {
+            // Handle service proxying logic.
+            const proxyInfo = parseAtprotoProxyHeader(atprotoProxy);
+            if (!proxyInfo) {
+                return invalidRequestResponse(`Invalid atproto-proxy header value: ${atprotoProxy}`);
+            }
+            // @TODO actually implement service proxying logic here. The reason it was
+            // not done already is because we want to perform all the heavy lifting
+            // here, while still allowing the possibility to override the endpoint
+            // resolution, etc.
+            // @NOTE see ./service-auth.ts for potential common code (did resolver, etc.)
         }
         return Response.json({
             error: 'MethodNotImplemented',
@@ -318,16 +361,6 @@ class LexRouter {
     };
 }
 exports.LexRouter = LexRouter;
-function extractMethodNsid(request) {
-    const { pathname } = new URL(request.url);
-    if (!pathname.startsWith('/xrpc/'))
-        return null;
-    if (pathname.includes('/', 6))
-        return null;
-    // We don't really need to validate the NSID here, the existence of the route
-    // (which is looked up based on an NSID) is sufficient.
-    return pathname.slice(6);
-}
 async function getProcedureInput(request) {
     const encodingRaw = request.headers
         .get('content-type')
@@ -341,7 +374,10 @@ async function getProcedureInput(request) {
             ? 'application/octet-stream'
             : undefined);
     if (!this.input.matchesEncoding(encoding)) {
-        throw new lex_data_1.LexError('InvalidRequest', `Invalid content-type: ${encoding}`);
+        throw new errors_js_1.LexServerError(400, {
+            error: 'InvalidRequest',
+            message: `Invalid content-type: ${encoding}`,
+        });
     }
     if (this.input.encoding === 'application/json') {
         // @TODO limit size?
@@ -361,14 +397,27 @@ async function getQueryInput(request) {
     if (request.body ||
         request.headers.has('content-type') ||
         request.headers.has('content-length')) {
-        throw new lex_data_1.LexError('InvalidRequest', 'GET requests must not have a body');
+        throw new errors_js_1.LexServerError(400, {
+            error: 'InvalidRequest',
+            message: 'GET requests must not have a body',
+        });
     }
     return undefined;
 }
+function onMessage(_event) {
+    const error = 'InvalidRequest';
+    const message = 'XRPC subscriptions do not accept messages';
+    this.send(encodeErrorFrame({ error, message }));
+    // 1003 indicates that an endpoint is terminating the connection
+    // because it has received a type of data it cannot accept (e.g., an
+    // endpoint that understands only text data MAY send this if it
+    // receives a binary message).
+    this.close(1003, error);
+}
 // Pre-encoded frame header for error frames
 const ERROR_FRAME_HEADER = /*#__PURE__*/ (0, lex_cbor_1.encode)({ op: -1 });
-function encodeErrorFrame(error) {
-    return (0, lex_data_1.ui8Concat)([ERROR_FRAME_HEADER, (0, lex_cbor_1.encode)(error.toJSON())]);
+function encodeErrorFrame(errorData) {
+    return (0, lex_data_1.ui8Concat)([ERROR_FRAME_HEADER, (0, lex_cbor_1.encode)(errorData)]);
 }
 // Pre-encoded frame header for message frames with unknown type
 const UNKNOWN_MESSAGE_FRAME_HEADER = /*#__PURE__*/ (0, lex_cbor_1.encode)({ op: 1 });
@@ -392,9 +441,56 @@ function encodeMessageFrame(method, value) {
     return (0, lex_data_1.ui8Concat)([UNKNOWN_MESSAGE_FRAME_HEADER, (0, lex_cbor_1.encode)(value)]);
 }
 function isAbortReason(signal, error) {
-    if (!signal.aborted || signal.reason == null)
-        return false;
-    return (error === signal.reason ||
-        (error instanceof Error && error.cause === signal.reason));
+    return (signal.aborted &&
+        signal.reason != null &&
+        error instanceof Error &&
+        (error === signal.reason || error.cause === signal.reason));
+}
+function parseAtprotoProxyHeader(value) {
+    // /!\ Hot path
+    // (fast) sanity check to avoid unnecessary parsing for non-DID values
+    if (!value.startsWith('did:'))
+        return null;
+    // The format is expected to be `did:example:service#serviceId`
+    const hashIndex = value.indexOf('#');
+    if (hashIndex === -1)
+        return null;
+    const fragmentIndex = hashIndex + 1;
+    // Basic validation if the fragment
+    if (fragmentIndex === value.length)
+        return null;
+    if (value.includes('#', fragmentIndex))
+        return null;
+    if (value.includes(' ', fragmentIndex))
+        return null;
+    const did = value.slice(0, hashIndex);
+    if (!(0, lex_schema_1.isDidString)(did))
+        return null;
+    const serviceId = value.slice(fragmentIndex);
+    return { did, serviceId };
+}
+function normalizeNsid(nsid) {
+    const lastDotIdx = nsid.lastIndexOf('.');
+    // The domain name part of the NSID is case-insensitive, but the last part is
+    // case-sensitive. Normalize the domain part to lowercase.
+    if (lastDotIdx !== -1 && hasUpperCase(nsid, 0, lastDotIdx)) {
+        return `${nsid.slice(0, lastDotIdx).toLowerCase()}.${nsid.slice(lastDotIdx + 1)}`;
+    }
+    return nsid;
+}
+function hasUpperCase(str, start = 0, end = str.length) {
+    for (let i = start; i < end; i++) {
+        const code = str.charCodeAt(i);
+        if (code >= 0x41 && code <= 0x5a) {
+            return true;
+        }
+    }
+    return false;
+}
+function invalidRequestResponse(message, status = 400, headers) {
+    return Response.json({
+        error: 'InvalidRequest',
+        message,
+    }, { status, headers });
 }
-//# sourceMappingURL=lex-server.js.map
+//# sourceMappingURL=lex-router.js.map