+6

.changeset/xrpc-server-health-check.md

reviewed

··· 1 1 + --- 2 2 + '@atcute/xrpc-server': minor 3 3 + --- 4 4 + 5 5 + add `handleHealthCheck` router option. when set, `/xrpc/_health` dispatches to it; this endpoint is 6 6 + non-standard, so callers opt in and own the response body and status.

+14

packages/servers/xrpc-server/README.md

reviewed

··· 147 147 `ForbiddenError`, `RateLimitExceededError`, `InternalServerError`, `UpstreamFailureError`, 148 148 `NotEnoughResourcesError`, `UpstreamTimeoutError`. 149 149 150 150 + ### health check 151 151 + 152 152 + the router can optionally answer `/xrpc/_health` if you pass `handleHealthCheck`. this endpoint is 153 153 + non-standard — consumers decide the response shape and status. 154 154 + 155 155 + ```ts 156 156 + const router = new XRPCRouter({ 157 157 + async handleHealthCheck() { 158 158 + const healthy = await pingDatabase(); 159 159 + return Response.json({ status: healthy ? 'ok' : 'degraded' }, { status: healthy ? 200 : 503 }); 160 160 + }, 161 161 + }); 162 162 + ``` 163 163 + 150 164 ### subscriptions 151 165 152 166 subscriptions provide real-time streaming over WebSocket. they require a runtime-specific adapter:

+38

packages/servers/xrpc-server/lib/main/router.test.ts

reviewed

··· 32 32 expect(response.status).toBe(404); 33 33 }); 34 34 35 35 + it('falls through to handleNotFound when handleHealthCheck is not set', async () => { 36 36 + const router = new XRPCRouter(); 37 37 + 38 38 + const request = new Request('http://example.com/xrpc/_health', { method: 'GET' }); 39 39 + const response = await router.fetch(request); 40 40 + 41 41 + expect(response.status).toBe(404); 42 42 + }); 43 43 + 44 44 + it('invokes handleHealthCheck on /xrpc/_health', async () => { 45 45 + const mock = vi.fn(() => Response.json({ status: 'ok', version: '1.0' })); 46 46 + const router = new XRPCRouter({ handleHealthCheck: mock }); 47 47 + 48 48 + const request = new Request('http://example.com/xrpc/_health', { method: 'GET' }); 49 49 + const response = await router.fetch(request); 50 50 + 51 51 + expect(mock).toHaveBeenCalledExactlyOnceWith(request); 52 52 + expect(response.status).toBe(200); 53 53 + expect(await response.json()).toEqual({ status: 'ok', version: '1.0' }); 54 54 + }); 55 55 + 56 56 + it('runs handleHealthCheck through handleException when it throws', async () => { 57 57 + const router = new XRPCRouter({ 58 58 + handleHealthCheck: () => { 59 59 + throw new Error('boom'); 60 60 + }, 61 61 + }); 62 62 + 63 63 + const request = new Request('http://example.com/xrpc/_health', { method: 'GET' }); 64 64 + const response = await router.fetch(request); 65 65 + 66 66 + expect(response.status).toBe(500); 67 67 + expect(await response.json()).toEqual({ 68 68 + error: 'InternalServerError', 69 69 + message: 'an exception happened whilst processing this request', 70 70 + }); 71 71 + }); 72 72 + 35 73 it('accepts HEAD requests on query routes', async () => { 36 74 const querySchema = v.query('com.example.query', { 37 75 params: null,

+23

packages/servers/xrpc-server/lib/main/router.ts

reviewed

··· 38 38 export type FetchMiddleware = Middleware<[request: Request], Promise<Response>>; 39 39 40 40 export type NotFoundHandler = (request: Request) => Promisable<Response>; 41 41 + export type HealthCheckHandler = (request: Request) => Promisable<Response>; 41 42 export type ExceptionHandler = (error: unknown, request: Request) => Promisable<Response>; 42 43 export type SubscriptionExceptionHandler = (error: unknown, request: Request) => void; 43 44 ··· 67 68 export interface XRPCRouterOptions { 68 69 middlewares?: FetchMiddleware[]; 69 70 handleNotFound?: NotFoundHandler; 71 71 + /** 72 72 + * optional handler for `/xrpc/_health`. when provided, the router answers 73 73 + * health-check requests by invoking this handler; when absent, the path 74 74 + * falls through to `handleNotFound`. `_health` is not part of the atproto 75 75 + * XRPC spec, so callers opt in explicitly. 76 76 + */ 77 77 + handleHealthCheck?: HealthCheckHandler; 70 78 handleException?: ExceptionHandler; 71 79 handleSubscriptionException?: SubscriptionExceptionHandler; 72 80 websocket?: WebSocketAdapter; ··· 75 83 export class XRPCRouter { 76 84 #handlers: Record<string, InternalRouteData> = {}; 77 85 #handleNotFound: NotFoundHandler; 86 86 + #handleHealthCheck?: HealthCheckHandler; 78 87 #handleException: ExceptionHandler; 79 88 #handleSubscriptionException: SubscriptionExceptionHandler; 80 89 #websocket?: WebSocketAdapter; ··· 85 94 middlewares = [], 86 95 handleException = defaultExceptionHandler, 87 96 handleNotFound = defaultNotFoundHandler, 97 97 + handleHealthCheck, 88 98 handleSubscriptionException = defaultSubscriptionExceptionHandler, 89 99 websocket, 90 100 }: XRPCRouterOptions = {}) { ··· 93 103 this.fetch = (request) => runner(request); 94 104 this.#handleException = handleException; 95 105 this.#handleNotFound = handleNotFound; 106 106 + this.#handleHealthCheck = handleHealthCheck; 96 107 this.#handleSubscriptionException = handleSubscriptionException; 97 108 this.#websocket = websocket; 98 109 } ··· 106 117 } 107 118 108 119 const nsid = pathname.slice('/xrpc/'.length); 120 120 + 121 121 + if (nsid === '_health' && this.#handleHealthCheck !== undefined) { 122 122 + try { 123 123 + return await this.#handleHealthCheck(request); 124 124 + } catch (err) { 125 125 + if (request.signal.aborted) { 126 126 + return new Response(null, { status: 499 }); 127 127 + } 128 128 + 129 129 + return this.#handleException(err, request); 130 130 + } 131 131 + } 109 132 110 133 const route = this.#handlers[nsid]; 111 134 if (route === undefined) {