@atproto/xrpc-server 0.4.1 → 0.4.3

package/dist/rate-limiter.d.ts

@@ -1,6 +1,6 @@
 import { RateLimiterAbstract, RateLimiterRes } from 'rate-limiter-flexible';
 import { CalcKeyFn, CalcPointsFn, RateLimitExceededError, RateLimiterConsume, RateLimiterI, RateLimiterStatus, XRPCReqContext } from './types';
-export declare type RateLimiterOpts = {
+export type RateLimiterOpts = {
     keyPrefix: string;
     durationMs: number;
     points: number;

package/dist/server.d.ts

@@ -22,7 +22,7 @@ export declare class Server {
     addLexicons(docs: LexiconDoc[]): void;
     protected addRoute(nsid: string, def: LexXrpcQuery | LexXrpcProcedure, config: XRPCHandlerConfig): Promise<void>;
     catchall(req: express.Request, _res: express.Response, next: NextFunction): Promise<void>;
-    createHandler(nsid: string, def: LexXrpcQuery | LexXrpcProcedure, handler: XRPCHandler): RequestHandler;
+    createHandler(nsid: string, def: LexXrpcQuery | LexXrpcProcedure, routeCfg: XRPCHandlerConfig): RequestHandler;
     protected addSubscription(nsid: string, def: LexXrpcSubscription, config: XRPCStreamHandlerConfig): Promise<void>;
     private enableStreamingOnListen;
     private setupRouteRateLimits;

package/dist/stream/server.d.ts

@@ -8,4 +8,4 @@ export declare class XrpcStreamServer {
         handler: Handler;
     });
 }
-export declare type Handler = (req: IncomingMessage, signal: AbortSignal, socket: WebSocket, server: XrpcStreamServer) => AsyncIterable<Frame>;
+export type Handler = (req: IncomingMessage, signal: AbortSignal, socket: WebSocket, server: XrpcStreamServer) => AsyncIterable<Frame>;

package/dist/stream/types.d.ts

@@ -13,7 +13,7 @@ export declare const messageFrameHeader: z.ZodObject<{
     op: FrameType.Message;
     t?: string | undefined;
 }>;
-export declare type MessageFrameHeader = z.infer<typeof messageFrameHeader>;
+export type MessageFrameHeader = z.infer<typeof messageFrameHeader>;
 export declare const errorFrameHeader: z.ZodObject<{
     op: z.ZodLiteral<FrameType.Error>;
 }, "strip", z.ZodTypeAny, {
@@ -31,8 +31,8 @@ export declare const errorFrameBody: z.ZodObject<{
     error: string;
     message?: string | undefined;
 }>;
-export declare type ErrorFrameHeader = z.infer<typeof errorFrameHeader>;
-export declare type ErrorFrameBody<T extends string = string> = {
+export type ErrorFrameHeader = z.infer<typeof errorFrameHeader>;
+export type ErrorFrameBody<T extends string = string> = {
     error: T;
 } & z.infer<typeof errorFrameBody>;
 export declare const frameHeader: z.ZodUnion<[z.ZodObject<{
@@ -51,7 +51,7 @@ export declare const frameHeader: z.ZodUnion<[z.ZodObject<{
 }, {
     op: FrameType.Error;
 }>]>;
-export declare type FrameHeader = z.infer<typeof frameHeader>;
+export type FrameHeader = z.infer<typeof frameHeader>;
 export declare class DisconnectError extends Error {
     wsCode: CloseCode;
     xrpcCode?: string | undefined;

package/dist/types.d.ts

@@ -3,7 +3,7 @@ import { IncomingMessage } from 'http';
 import express from 'express';
 import zod from 'zod';
 import { ResponseType } from '@atproto/xrpc';
-export declare type Options = {
+export type Options = {
     validateResponse?: boolean;
     payload?: {
         jsonLimit?: number;
@@ -16,9 +16,9 @@ export declare type Options = {
         shared?: ServerRateLimitDescription[];
     };
 };
-export declare type UndecodedParams = typeof express.request['query'];
-export declare type Primitive = string | number | boolean;
-export declare type Params = Record<string, Primitive | Primitive[] | undefined>;
+export type UndecodedParams = typeof express.request['query'];
+export type Primitive = string | number | boolean;
+export type Params = Record<string, Primitive | Primitive[] | undefined>;
 export declare const handlerInput: zod.ZodObject<{
     encoding: zod.ZodString;
     body: zod.ZodAny;
@@ -29,7 +29,7 @@ export declare const handlerInput: zod.ZodObject<{
     encoding: string;
     body?: any;
 }>;
-export declare type HandlerInput = zod.infer<typeof handlerInput>;
+export type HandlerInput = zod.infer<typeof handlerInput>;
 export declare const handlerAuth: zod.ZodObject<{
     credentials: zod.ZodAny;
     artifacts: zod.ZodAny;
@@ -40,7 +40,7 @@ export declare const handlerAuth: zod.ZodObject<{
     credentials?: any;
     artifacts?: any;
 }>;
-export declare type HandlerAuth = zod.infer<typeof handlerAuth>;
+export type HandlerAuth = zod.infer<typeof handlerAuth>;
 export declare const handlerSuccess: zod.ZodObject<{
     encoding: zod.ZodString;
     body: zod.ZodAny;
@@ -54,7 +54,21 @@ export declare const handlerSuccess: zod.ZodObject<{
     body?: any;
     headers?: Record<string, string> | undefined;
 }>;
-export declare type HandlerSuccess = zod.infer<typeof handlerSuccess>;
+export type HandlerSuccess = zod.infer<typeof handlerSuccess>;
+export declare const handlerPipeThrough: zod.ZodObject<{
+    encoding: zod.ZodString;
+    buffer: zod.ZodType<ArrayBuffer, zod.ZodTypeDef, ArrayBuffer>;
+    headers: zod.ZodOptional<zod.ZodRecord<zod.ZodString, zod.ZodString>>;
+}, "strip", zod.ZodTypeAny, {
+    encoding: string;
+    buffer: ArrayBuffer;
+    headers?: Record<string, string> | undefined;
+}, {
+    encoding: string;
+    buffer: ArrayBuffer;
+    headers?: Record<string, string> | undefined;
+}>;
+export type HandlerPipeThrough = zod.infer<typeof handlerPipeThrough>;
 export declare const handlerError: zod.ZodObject<{
     status: zod.ZodNumber;
     error: zod.ZodOptional<zod.ZodString>;
@@ -68,67 +82,67 @@ export declare const handlerError: zod.ZodObject<{
     error?: string | undefined;
     message?: string | undefined;
 }>;
-export declare type HandlerError = zod.infer<typeof handlerError>;
-export declare type HandlerOutput = HandlerSuccess | HandlerError;
-export declare type XRPCReqContext = {
+export type HandlerError = zod.infer<typeof handlerError>;
+export type HandlerOutput = HandlerSuccess | HandlerPipeThrough | HandlerError;
+export type XRPCReqContext = {
     auth: HandlerAuth | undefined;
     params: Params;
     input: HandlerInput | undefined;
     req: express.Request;
     res: express.Response;
 };
-export declare type XRPCHandler = (ctx: XRPCReqContext) => Promise<HandlerOutput> | HandlerOutput | undefined;
-export declare type XRPCStreamHandler = (ctx: {
+export type XRPCHandler = (ctx: XRPCReqContext) => Promise<HandlerOutput> | HandlerOutput | undefined;
+export type XRPCStreamHandler = (ctx: {
     auth: HandlerAuth | undefined;
     params: Params;
     req: IncomingMessage;
     signal: AbortSignal;
 }) => AsyncIterable<unknown>;
-export declare type AuthOutput = HandlerAuth | HandlerError;
-export declare type AuthVerifier = (ctx: {
+export type AuthOutput = HandlerAuth | HandlerError;
+export type AuthVerifier = (ctx: {
     req: express.Request;
     res: express.Response;
 }) => Promise<AuthOutput> | AuthOutput;
-export declare type StreamAuthVerifier = (ctx: {
+export type StreamAuthVerifier = (ctx: {
     req: IncomingMessage;
 }) => Promise<AuthOutput> | AuthOutput;
-export declare type CalcKeyFn = (ctx: XRPCReqContext) => string;
-export declare type CalcPointsFn = (ctx: XRPCReqContext) => number;
+export type CalcKeyFn = (ctx: XRPCReqContext) => string | null;
+export type CalcPointsFn = (ctx: XRPCReqContext) => number;
 export interface RateLimiterI {
     consume: RateLimiterConsume;
 }
-export declare type RateLimiterConsume = (ctx: XRPCReqContext, opts?: {
+export type RateLimiterConsume = (ctx: XRPCReqContext, opts?: {
     calcKey?: CalcKeyFn;
     calcPoints?: CalcPointsFn;
 }) => Promise<RateLimiterStatus | RateLimitExceededError | null>;
-export declare type RateLimiterCreator = (opts: {
+export type RateLimiterCreator = (opts: {
     keyPrefix: string;
     durationMs: number;
     points: number;
-    calcKey?: (ctx: XRPCReqContext) => string;
-    calcPoints?: (ctx: XRPCReqContext) => number;
+    calcKey?: CalcKeyFn;
+    calcPoints?: CalcPointsFn;
 }) => RateLimiterI;
-export declare type ServerRateLimitDescription = {
+export type ServerRateLimitDescription = {
     name: string;
     durationMs: number;
     points: number;
-    calcKey?: (ctx: XRPCReqContext) => string;
-    calcPoints?: (ctx: XRPCReqContext) => number;
+    calcKey?: CalcKeyFn;
+    calcPoints?: CalcPointsFn;
 };
-export declare type SharedRateLimitOpts = {
+export type SharedRateLimitOpts = {
     name: string;
-    calcKey?: (ctx: XRPCReqContext) => string;
-    calcPoints?: (ctx: XRPCReqContext) => number;
+    calcKey?: CalcKeyFn;
+    calcPoints?: CalcPointsFn;
 };
-export declare type RouteRateLimitOpts = {
+export type RouteRateLimitOpts = {
     durationMs: number;
     points: number;
-    calcKey?: (ctx: XRPCReqContext) => string;
-    calcPoints?: (ctx: XRPCReqContext) => number;
+    calcKey?: CalcKeyFn;
+    calcPoints?: CalcPointsFn;
 };
-export declare type HandlerRateLimitOpts = SharedRateLimitOpts | RouteRateLimitOpts;
+export type HandlerRateLimitOpts = SharedRateLimitOpts | RouteRateLimitOpts;
 export declare const isShared: (opts: HandlerRateLimitOpts) => opts is SharedRateLimitOpts;
-export declare type RateLimiterStatus = {
+export type RateLimiterStatus = {
     limit: number;
     duration: number;
     remainingPoints: number;
@@ -136,12 +150,16 @@ export declare type RateLimiterStatus = {
     consumedPoints: number;
     isFirstInDuration: boolean;
 };
-export declare type XRPCHandlerConfig = {
+export type RouteOpts = {
+    blobLimit?: number;
+};
+export type XRPCHandlerConfig = {
+    opts?: RouteOpts;
     rateLimit?: HandlerRateLimitOpts | HandlerRateLimitOpts[];
     auth?: AuthVerifier;
     handler: XRPCHandler;
 };
-export declare type XRPCStreamHandlerConfig = {
+export type XRPCStreamHandlerConfig = {
     auth?: StreamAuthVerifier;
     handler: XRPCStreamHandler;
 };

package/dist/util.d.ts

@@ -1,10 +1,10 @@
 import express from 'express';
 import { Lexicons, LexXrpcProcedure, LexXrpcQuery, LexXrpcSubscription } from '@atproto/lexicon';
-import { UndecodedParams, Params, HandlerInput, HandlerSuccess, Options } from './types';
+import { UndecodedParams, Params, HandlerInput, HandlerSuccess, RouteOpts } from './types';
 export declare function decodeQueryParams(def: LexXrpcProcedure | LexXrpcQuery | LexXrpcSubscription, params: UndecodedParams): Params;
 export declare function decodeQueryParam(type: string, value: unknown): string | number | boolean | undefined;
 export declare function getQueryParams(url?: string): Record<string, string | string[]>;
-export declare function validateInput(nsid: string, def: LexXrpcProcedure | LexXrpcQuery, req: express.Request, opts: Options, lexicons: Lexicons): HandlerInput | undefined;
+export declare function validateInput(nsid: string, def: LexXrpcProcedure | LexXrpcQuery, req: express.Request, opts: RouteOpts, lexicons: Lexicons): HandlerInput | undefined;
 export declare function validateOutput(nsid: string, def: LexXrpcProcedure | LexXrpcQuery, output: HandlerSuccess | undefined, lexicons: Lexicons): HandlerSuccess | undefined;
 export declare function normalizeMime(v: string): any;
 export declare function hasBody(req: express.Request): string | true | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/xrpc-server",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "license": "MIT",
   "description": "atproto HTTP API (XRPC) server library",
   "keywords": [
@@ -25,7 +25,7 @@
     "zod": "^3.21.4",
     "@atproto/common": "^0.3.3",
     "@atproto/crypto": "^0.3.0",
-    "@atproto/lexicon": "^0.3.0"
+    "@atproto/lexicon": "^0.3.2"
   },
   "devDependencies": {
     "@types/express": "^4.17.13",
@@ -36,8 +36,8 @@
     "jose": "^4.15.4",
     "key-encoder": "^2.0.3",
     "multiformats": "^9.9.0",
-    "@atproto/crypto": "^0.3.0",
-    "@atproto/xrpc": "^0.4.0"
+    "@atproto/xrpc": "^0.4.2",
+    "@atproto/crypto": "^0.3.0"
   },
   "scripts": {
     "test": "jest",

package/src/rate-limiter.ts

@@ -75,6 +75,9 @@ export class RateLimiter implements RateLimiterI {
       return null
     }
     const key = opts?.calcKey ? opts.calcKey(ctx) : this.calcKey(ctx)
+    if (key === null) {
+      return null
+    }
     const points = opts?.calcPoints
       ? opts.calcPoints(ctx)
       : this.calcPoints(ctx)

package/src/server.ts

@@ -36,6 +36,8 @@ import {
   RateLimiterConsume,
   isShared,
   RateLimitExceededError,
+  HandlerPipeThrough,
+  handlerPipeThrough,
 } from './types'
 import {
   decodeQueryParams,
@@ -173,7 +175,7 @@ export class Server {
     this.routes[verb](
       `/xrpc/${nsid}`,
       ...middleware,
-      this.createHandler(nsid, def, config.handler),
+      this.createHandler(nsid, def, config),
     )
   }
 
@@ -206,10 +208,13 @@ export class Server {
   createHandler(
     nsid: string,
     def: LexXrpcQuery | LexXrpcProcedure,
-    handler: XRPCHandler,
+    routeCfg: XRPCHandlerConfig,
   ): RequestHandler {
+    const routeOpts = {
+      blobLimit: routeCfg.opts?.blobLimit ?? this.options.payload?.blobLimit,
+    }
     const validateReqInput = (req: express.Request) =>
-      validateInput(nsid, def, req, this.options, this.lex)
+      validateInput(nsid, def, req, routeOpts, this.lex)
     const validateResOutput =
       this.options.validateResponse === false
         ? (output?: HandlerSuccess) => output
@@ -248,20 +253,32 @@ export class Server {
         }
 
         // handle rate limits
-        if (consumeRateLimit) {
-          const result = await consumeRateLimit(reqCtx)
-          if (result instanceof RateLimitExceededError) {
-            return next(result)
-          }
+        const result = await consumeRateLimit(reqCtx)
+        if (result instanceof RateLimitExceededError) {
+          return next(result)
         }
 
         // run the handler
-        const outputUnvalidated = await handler(reqCtx)
+        const outputUnvalidated = await routeCfg.handler(reqCtx)
 
         if (isHandlerError(outputUnvalidated)) {
           throw XRPCError.fromError(outputUnvalidated)
         }
 
+        if (outputUnvalidated && isHandlerPipeThrough(outputUnvalidated)) {
+          // set headers
+          if (outputUnvalidated?.headers) {
+            Object.entries(outputUnvalidated.headers).forEach(([name, val]) => {
+              res.header(name, val)
+            })
+          }
+          res
+            .header('Content-Type', outputUnvalidated.encoding)
+            .status(200)
+            .send(Buffer.from(outputUnvalidated.buffer))
+          return
+        }
+
         if (!outputUnvalidated || isHandlerSuccess(outputUnvalidated)) {
           // validate response
           const output = validateResOutput(outputUnvalidated)
@@ -447,6 +464,26 @@ function isHandlerSuccess(v: HandlerOutput): v is HandlerSuccess {
   return handlerSuccess.safeParse(v).success
 }
 
+function isHandlerPipeThrough(v: HandlerOutput): v is HandlerPipeThrough {
+  if (v === null || typeof v !== 'object') {
+    return false
+  }
+  if (!isString(v['encoding']) || !(v['buffer'] instanceof ArrayBuffer)) {
+    return false
+  }
+  if (v['headers'] !== undefined) {
+    if (v['headers'] === null || typeof v['headers'] !== 'object') {
+      return false
+    }
+    if (!Object.values(v['headers']).every(isString)) {
+      return false
+    }
+  }
+  return true
+}
+
+const isString = (val: unknown): val is string => typeof val === 'string'
+
 const kRequestLocals = Symbol('requestLocals')
 
 function createLocalsMiddleware(nsid: string): RequestHandler {

package/src/types.ts

@@ -46,6 +46,13 @@ export const handlerSuccess = zod.object({
 })
 export type HandlerSuccess = zod.infer<typeof handlerSuccess>
 
+export const handlerPipeThrough = zod.object({
+  encoding: zod.string(),
+  buffer: zod.instanceof(ArrayBuffer),
+  headers: zod.record(zod.string()).optional(),
+})
+export type HandlerPipeThrough = zod.infer<typeof handlerPipeThrough>
+
 export const handlerError = zod.object({
   status: zod.number(),
   error: zod.string().optional(),
@@ -53,7 +60,7 @@ export const handlerError = zod.object({
 })
 export type HandlerError = zod.infer<typeof handlerError>
 
-export type HandlerOutput = HandlerSuccess | HandlerError
+export type HandlerOutput = HandlerSuccess | HandlerPipeThrough | HandlerError
 
 export type XRPCReqContext = {
   auth: HandlerAuth | undefined
@@ -85,7 +92,7 @@ export type StreamAuthVerifier = (ctx: {
   req: IncomingMessage
 }) => Promise<AuthOutput> | AuthOutput
 
-export type CalcKeyFn = (ctx: XRPCReqContext) => string
+export type CalcKeyFn = (ctx: XRPCReqContext) => string | null
 export type CalcPointsFn = (ctx: XRPCReqContext) => number
 
 export interface RateLimiterI {
@@ -101,29 +108,29 @@ export type RateLimiterCreator = (opts: {
   keyPrefix: string
   durationMs: number
   points: number
-  calcKey?: (ctx: XRPCReqContext) => string
-  calcPoints?: (ctx: XRPCReqContext) => number
+  calcKey?: CalcKeyFn
+  calcPoints?: CalcPointsFn
 }) => RateLimiterI
 
 export type ServerRateLimitDescription = {
   name: string
   durationMs: number
   points: number
-  calcKey?: (ctx: XRPCReqContext) => string
-  calcPoints?: (ctx: XRPCReqContext) => number
+  calcKey?: CalcKeyFn
+  calcPoints?: CalcPointsFn
 }
 
 export type SharedRateLimitOpts = {
   name: string
-  calcKey?: (ctx: XRPCReqContext) => string
-  calcPoints?: (ctx: XRPCReqContext) => number
+  calcKey?: CalcKeyFn
+  calcPoints?: CalcPointsFn
 }
 
 export type RouteRateLimitOpts = {
   durationMs: number
   points: number
-  calcKey?: (ctx: XRPCReqContext) => string
-  calcPoints?: (ctx: XRPCReqContext) => number
+  calcKey?: CalcKeyFn
+  calcPoints?: CalcPointsFn
 }
 
 export type HandlerRateLimitOpts = SharedRateLimitOpts | RouteRateLimitOpts
@@ -143,7 +150,12 @@ export type RateLimiterStatus = {
   isFirstInDuration: boolean
 }
 
+export type RouteOpts = {
+  blobLimit?: number
+}
+
 export type XRPCHandlerConfig = {
+  opts?: RouteOpts
   rateLimit?: HandlerRateLimitOpts | HandlerRateLimitOpts[]
   auth?: AuthVerifier
   handler: XRPCHandler

package/src/util.ts

@@ -19,8 +19,8 @@ import {
   handlerSuccess,
   InvalidRequestError,
   InternalServerError,
-  Options,
   XRPCError,
+  RouteOpts,
 } from './types'
 
 export function decodeQueryParams(
@@ -82,7 +82,7 @@ export function validateInput(
   nsid: string,
   def: LexXrpcProcedure | LexXrpcQuery,
   req: express.Request,
-  opts: Options,
+  opts: RouteOpts,
   lexicons: Lexicons,
 ): HandlerInput | undefined {
   // request expectation
@@ -139,7 +139,7 @@ export function validateInput(
   if (req.readableEnded) {
     body = req.body
   } else {
-    body = decodeBodyStream(req, opts.payload?.blobLimit)
+    body = decodeBodyStream(req, opts.blobLimit)
   }
 
   return {