@atproto/xrpc-server 0.2.0 → 0.3.1

package/dist/logger.d.ts

@@ -1,2 +1,3 @@
-export declare const logger: import("pino").default.Logger<import("pino").default.LoggerOptions>;
+import { subsystemLogger } from '@atproto/common';
+export declare const logger: ReturnType<typeof subsystemLogger>;
 export default logger;

package/dist/rate-limiter.d.ts

@@ -0,0 +1,29 @@
+import { RateLimiterAbstract, RateLimiterRes } from 'rate-limiter-flexible';
+import { CalcKeyFn, CalcPointsFn, RateLimitExceededError, RateLimiterConsume, RateLimiterI, RateLimiterStatus, XRPCReqContext } from './types';
+export declare type RateLimiterOpts = {
+    keyPrefix: string;
+    durationMs: number;
+    points: number;
+    bypassSecret?: string;
+    calcKey?: CalcKeyFn;
+    calcPoints?: CalcPointsFn;
+    failClosed?: boolean;
+};
+export declare class RateLimiter implements RateLimiterI {
+    limiter: RateLimiterAbstract;
+    private byPassSecret?;
+    private failClosed?;
+    calcKey: CalcKeyFn;
+    calcPoints: CalcPointsFn;
+    constructor(limiter: RateLimiterAbstract, opts: RateLimiterOpts);
+    static memory(opts: RateLimiterOpts): RateLimiter;
+    static redis(storeClient: unknown, opts: RateLimiterOpts): RateLimiter;
+    consume(ctx: XRPCReqContext, opts?: {
+        calcKey?: CalcKeyFn;
+        calcPoints?: CalcPointsFn;
+    }): Promise<RateLimiterStatus | RateLimitExceededError | null>;
+}
+export declare const formatLimiterStatus: (limiter: RateLimiterAbstract, res: RateLimiterRes) => RateLimiterStatus;
+export declare const consumeMany: (ctx: XRPCReqContext, fns: RateLimiterConsume[]) => Promise<RateLimiterStatus | RateLimitExceededError | null>;
+export declare const setResHeaders: (ctx: XRPCReqContext, status: RateLimiterStatus) => void;
+export declare const getTightestLimit: (resps: (RateLimiterStatus | RateLimitExceededError | null)[]) => RateLimiterStatus | RateLimitExceededError | null;

package/dist/server.d.ts

@@ -1,7 +1,7 @@
 import express, { NextFunction, RequestHandler } from 'express';
 import { Lexicons, LexXrpcProcedure, LexXrpcQuery, LexXrpcSubscription } from '@atproto/lexicon';
 import { XrpcStreamServer } from './stream';
-import { XRPCHandler, XRPCHandlerConfig, Options, XRPCStreamHandlerConfig, XRPCStreamHandler } from './types';
+import { XRPCHandler, XRPCHandlerConfig, Options, XRPCStreamHandlerConfig, XRPCStreamHandler, RateLimiterI, RateLimiterConsume } from './types';
 export declare function createServer(lexicons?: unknown[], options?: Options): Server;
 export declare class Server {
     router: import("express-serve-static-core").Express;
@@ -10,6 +10,9 @@ export declare class Server {
     lex: Lexicons;
     options: Options;
     middleware: Record<'json' | 'text', RequestHandler>;
+    globalRateLimiters: RateLimiterI[];
+    sharedRateLimiters: Record<string, RateLimiterI>;
+    routeRateLimiterFns: Record<string, RateLimiterConsume[]>;
     constructor(lexicons?: unknown[], opts?: Options);
     method(nsid: string, configOrFn: XRPCHandlerConfig | XRPCHandler): void;
     addMethod(nsid: string, configOrFn: XRPCHandlerConfig | XRPCHandler): void;
@@ -22,4 +25,5 @@ export declare class Server {
     createHandler(nsid: string, def: LexXrpcQuery | LexXrpcProcedure, handler: XRPCHandler): RequestHandler;
     protected addSubscription(nsid: string, def: LexXrpcSubscription, config: XRPCStreamHandlerConfig): Promise<void>;
     private enableStreamingOnListen;
+    private setupRouteRateLimits;
 }

package/dist/stream/logger.d.ts

@@ -1,2 +1,3 @@
-export declare const logger: import("pino").default.Logger<import("pino").default.LoggerOptions>;
+import { subsystemLogger } from '@atproto/common';
+export declare const logger: ReturnType<typeof subsystemLogger>;
 export default logger;

package/dist/stream/stream.d.ts

@@ -1,5 +1,8 @@
 /// <reference types="node" />
 import { DuplexOptions } from 'stream';
 import { WebSocket } from 'ws';
-export declare function byFrame(ws: WebSocket, options?: DuplexOptions): AsyncGenerator<import("./frames").MessageFrame<unknown> | import("./frames").ErrorFrame<string>, void, unknown>;
-export declare function byMessage(ws: WebSocket, options?: DuplexOptions): AsyncGenerator<import("./frames").MessageFrame<unknown>, void, unknown>;
+import { MessageFrame } from './frames';
+export declare function streamByteChunks(ws: WebSocket, options?: DuplexOptions): import("stream").Duplex;
+export declare function byFrame(ws: WebSocket, options?: DuplexOptions): AsyncGenerator<MessageFrame<unknown> | import("./frames").ErrorFrame<string>, void, unknown>;
+export declare function byMessage(ws: WebSocket, options?: DuplexOptions): AsyncGenerator<MessageFrame<unknown>, void, unknown>;
+export declare function ensureChunkIsMessage(chunk: Uint8Array): MessageFrame<unknown>;

package/dist/stream/subscription.d.ts

@@ -4,6 +4,7 @@ export declare class Subscription<T = unknown> {
         service: string;
         method: string;
         maxReconnectSeconds?: number;
+        heartbeatIntervalMs?: number;
         signal?: AbortSignal;
         validate: (obj: unknown) => T | undefined;
         onReconnectError?: (error: unknown, n: number, initialSetup: boolean) => void;
@@ -13,12 +14,12 @@ export declare class Subscription<T = unknown> {
         service: string;
         method: string;
         maxReconnectSeconds?: number;
+        heartbeatIntervalMs?: number;
         signal?: AbortSignal;
         validate: (obj: unknown) => T | undefined;
         onReconnectError?: (error: unknown, n: number, initialSetup: boolean) => void;
         getParams?: () => Record<string, unknown> | Promise<Record<string, unknown> | undefined> | undefined;
     });
     [Symbol.asyncIterator](): AsyncGenerator<T>;
-    private getSocket;
 }
 export default Subscription;

package/dist/stream/types.d.ts

@@ -7,11 +7,11 @@ export declare const messageFrameHeader: z.ZodObject<{
     op: z.ZodLiteral<FrameType.Message>;
     t: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    t?: string | undefined;
     op: FrameType.Message;
-}, {
     t?: string | undefined;
+}, {
     op: FrameType.Message;
+    t?: string | undefined;
 }>;
 export declare type MessageFrameHeader = z.infer<typeof messageFrameHeader>;
 export declare const errorFrameHeader: z.ZodObject<{
@@ -25,11 +25,11 @@ export declare const errorFrameBody: z.ZodObject<{
     error: z.ZodString;
     message: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    message?: string | undefined;
     error: string;
-}, {
     message?: string | undefined;
+}, {
     error: string;
+    message?: string | undefined;
 }>;
 export declare type ErrorFrameHeader = z.infer<typeof errorFrameHeader>;
 export declare type ErrorFrameBody<T extends string = string> = {
@@ -39,11 +39,11 @@ export declare const frameHeader: z.ZodUnion<[z.ZodObject<{
     op: z.ZodLiteral<FrameType.Message>;
     t: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    t?: string | undefined;
     op: FrameType.Message;
-}, {
     t?: string | undefined;
+}, {
     op: FrameType.Message;
+    t?: string | undefined;
 }>, z.ZodObject<{
     op: z.ZodLiteral<FrameType.Error>;
 }, "strip", z.ZodTypeAny, {

package/dist/stream/websocket-keepalive.d.ts

@@ -0,0 +1,23 @@
+import { WebSocket, ClientOptions } from 'ws';
+export declare class WebSocketKeepAlive {
+    opts: ClientOptions & {
+        getUrl: () => Promise<string>;
+        maxReconnectSeconds?: number;
+        signal?: AbortSignal;
+        heartbeatIntervalMs?: number;
+        onReconnectError?: (error: unknown, n: number, initialSetup: boolean) => void;
+    };
+    ws: WebSocket | null;
+    initialSetup: boolean;
+    reconnects: number | null;
+    constructor(opts: ClientOptions & {
+        getUrl: () => Promise<string>;
+        maxReconnectSeconds?: number;
+        signal?: AbortSignal;
+        heartbeatIntervalMs?: number;
+        onReconnectError?: (error: unknown, n: number, initialSetup: boolean) => void;
+    });
+    [Symbol.asyncIterator](): AsyncGenerator<Uint8Array>;
+    startHeartbeat(ws: WebSocket): void;
+}
+export default WebSocketKeepAlive;

package/dist/types.d.ts

@@ -10,6 +10,11 @@ export declare type Options = {
         blobLimit?: number;
         textLimit?: number;
     };
+    rateLimits?: {
+        creator: RateLimiterCreator;
+        global?: ServerRateLimitDescription[];
+        shared?: ServerRateLimitDescription[];
+    };
 };
 export declare type UndecodedParams = typeof express.request['query'];
 export declare type Primitive = string | number | boolean;
@@ -18,11 +23,11 @@ export declare const handlerInput: zod.ZodObject<{
     encoding: zod.ZodString;
     body: zod.ZodAny;
 }, "strip", zod.ZodTypeAny, {
-    body?: any;
     encoding: string;
-}, {
     body?: any;
+}, {
     encoding: string;
+    body?: any;
 }>;
 export declare type HandlerInput = zod.infer<typeof handlerInput>;
 export declare const handlerAuth: zod.ZodObject<{
@@ -39,12 +44,15 @@ export declare type HandlerAuth = zod.infer<typeof handlerAuth>;
 export declare const handlerSuccess: zod.ZodObject<{
     encoding: zod.ZodString;
     body: zod.ZodAny;
+    headers: zod.ZodOptional<zod.ZodRecord<zod.ZodString, zod.ZodString>>;
 }, "strip", zod.ZodTypeAny, {
-    body?: any;
     encoding: string;
-}, {
     body?: any;
+    headers?: Record<string, string> | undefined;
+}, {
     encoding: string;
+    body?: any;
+    headers?: Record<string, string> | undefined;
 }>;
 export declare type HandlerSuccess = zod.infer<typeof handlerSuccess>;
 export declare const handlerError: zod.ZodObject<{
@@ -52,23 +60,24 @@ export declare const handlerError: zod.ZodObject<{
     error: zod.ZodOptional<zod.ZodString>;
     message: zod.ZodOptional<zod.ZodString>;
 }, "strip", zod.ZodTypeAny, {
+    status: number;
     error?: string | undefined;
     message?: string | undefined;
-    status: number;
 }, {
+    status: number;
     error?: string | undefined;
     message?: string | undefined;
-    status: number;
 }>;
 export declare type HandlerError = zod.infer<typeof handlerError>;
 export declare type HandlerOutput = HandlerSuccess | HandlerError;
-export declare type XRPCHandler = (ctx: {
+export declare type XRPCReqContext = {
     auth: HandlerAuth | undefined;
     params: Params;
     input: HandlerInput | undefined;
     req: express.Request;
     res: express.Response;
-}) => Promise<HandlerOutput> | HandlerOutput | undefined;
+};
+export declare type XRPCHandler = (ctx: XRPCReqContext) => Promise<HandlerOutput> | HandlerOutput | undefined;
 export declare type XRPCStreamHandler = (ctx: {
     auth: HandlerAuth | undefined;
     params: Params;
@@ -83,7 +92,52 @@ export declare type AuthVerifier = (ctx: {
 export declare type StreamAuthVerifier = (ctx: {
     req: IncomingMessage;
 }) => Promise<AuthOutput> | AuthOutput;
+export declare type CalcKeyFn = (ctx: XRPCReqContext) => string;
+export declare type CalcPointsFn = (ctx: XRPCReqContext) => number;
+export interface RateLimiterI {
+    consume: RateLimiterConsume;
+}
+export declare type RateLimiterConsume = (ctx: XRPCReqContext, opts?: {
+    calcKey?: CalcKeyFn;
+    calcPoints?: CalcPointsFn;
+}) => Promise<RateLimiterStatus | RateLimitExceededError | null>;
+export declare type RateLimiterCreator = (opts: {
+    keyPrefix: string;
+    durationMs: number;
+    points: number;
+    calcKey?: (ctx: XRPCReqContext) => string;
+    calcPoints?: (ctx: XRPCReqContext) => number;
+}) => RateLimiterI;
+export declare type ServerRateLimitDescription = {
+    name: string;
+    durationMs: number;
+    points: number;
+    calcKey?: (ctx: XRPCReqContext) => string;
+    calcPoints?: (ctx: XRPCReqContext) => number;
+};
+export declare type SharedRateLimitOpts = {
+    name: string;
+    calcKey?: (ctx: XRPCReqContext) => string;
+    calcPoints?: (ctx: XRPCReqContext) => number;
+};
+export declare type RouteRateLimitOpts = {
+    durationMs: number;
+    points: number;
+    calcKey?: (ctx: XRPCReqContext) => string;
+    calcPoints?: (ctx: XRPCReqContext) => number;
+};
+export declare type HandlerRateLimitOpts = SharedRateLimitOpts | RouteRateLimitOpts;
+export declare const isShared: (opts: HandlerRateLimitOpts) => opts is SharedRateLimitOpts;
+export declare type RateLimiterStatus = {
+    limit: number;
+    duration: number;
+    remainingPoints: number;
+    msBeforeNext: number;
+    consumedPoints: number;
+    isFirstInDuration: boolean;
+};
 export declare type XRPCHandlerConfig = {
+    rateLimit?: HandlerRateLimitOpts | HandlerRateLimitOpts[];
     auth?: AuthVerifier;
     handler: XRPCHandler;
 };
@@ -114,13 +168,17 @@ export declare class AuthRequiredError extends XRPCError {
 export declare class ForbiddenError extends XRPCError {
     constructor(errorMessage?: string, customErrorName?: string);
 }
+export declare class RateLimitExceededError extends XRPCError {
+    status: RateLimiterStatus;
+    constructor(status: RateLimiterStatus, errorMessage?: string, customErrorName?: string);
+}
 export declare class InternalServerError extends XRPCError {
     constructor(errorMessage?: string, customErrorName?: string);
 }
 export declare class UpstreamFailureError extends XRPCError {
     constructor(errorMessage?: string, customErrorName?: string);
 }
-export declare class NotEnoughResoucesError extends XRPCError {
+export declare class NotEnoughResourcesError extends XRPCError {
     constructor(errorMessage?: string, customErrorName?: string);
 }
 export declare class UpstreamTimeoutError extends XRPCError {

package/dist/util.d.ts

@@ -9,3 +9,18 @@ export declare function validateOutput(nsid: string, def: LexXrpcProcedure | Lex
 export declare function normalizeMime(v: string): any;
 export declare function hasBody(req: express.Request): string | true | undefined;
 export declare function processBodyAsBytes(req: express.Request): Promise<Uint8Array>;
+export declare function serverTimingHeader(timings: ServerTiming[]): string;
+export declare class ServerTimer implements ServerTiming {
+    name: string;
+    description?: string | undefined;
+    duration?: number;
+    private startMs?;
+    constructor(name: string, description?: string | undefined);
+    start(): this;
+    stop(): this;
+}
+export interface ServerTiming {
+    name: string;
+    duration?: number;
+    description?: string;
+}

package/package.json

@@ -1,22 +1,7 @@
 {
   "name": "@atproto/xrpc-server",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "main": "dist/index.js",
-  "scripts": {
-    "test": "jest",
-    "prettier": "prettier --check src/",
-    "prettier:fix": "prettier --write src/",
-    "lint": "eslint . --ext .ts,.tsx",
-    "lint:fix": "yarn lint --fix",
-    "verify": "run-p prettier lint",
-    "verify:fix": "yarn prettier:fix && yarn lint:fix",
-    "build": "node ./build.js",
-    "postbuild": "tsc --build tsconfig.build.json",
-    "update-main-to-dist": "node ./update-pkg.js --update-main-to-dist",
-    "update-main-to-src": "node ./update-pkg.js --update-main-to-src",
-    "prepublish": "npm run update-main-to-dist",
-    "postpublish": "npm run update-main-to-src"
-  },
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -24,24 +9,33 @@
     "directory": "packages/xrpc-server"
   },
   "dependencies": {
-    "@atproto/common": "*",
-    "@atproto/crypto": "*",
-    "@atproto/lexicon": "*",
     "cbor-x": "^1.5.1",
     "express": "^4.17.2",
     "http-errors": "^2.0.0",
     "mime-types": "^2.1.35",
+    "rate-limiter-flexible": "^2.4.1",
     "uint8arrays": "3.0.0",
     "ws": "^8.12.0",
-    "zod": "^3.14.2"
+    "zod": "^3.21.4",
+    "@atproto/common": "^0.3.0",
+    "@atproto/crypto": "^0.2.2",
+    "@atproto/lexicon": "^0.2.1"
   },
   "devDependencies": {
-    "@atproto/crypto": "*",
-    "@atproto/xrpc": "*",
     "@types/express": "^4.17.13",
+    "@types/express-serve-static-core": "^4.17.36",
     "@types/http-errors": "^2.0.1",
     "@types/ws": "^8.5.4",
     "get-port": "^6.1.2",
-    "multiformats": "^9.6.4"
-  }
-}
+    "multiformats": "^9.9.0",
+    "@atproto/crypto": "^0.2.2",
+    "@atproto/xrpc": "^0.3.1"
+  },
+  "scripts": {
+    "test": "jest",
+    "build": "node ./build.js",
+    "postbuild": "tsc --build tsconfig.build.json",
+    "update-main-to-dist": "node ../../update-main-to-dist.js packages/xrpc-server"
+  },
+  "types": "dist/index.d.ts"
+}

package/src/auth.ts

@@ -44,7 +44,7 @@ const jsonToB64Url = (json: Record<string, unknown>): string => {
 
 export const verifyJwt = async (
   jwtStr: string,
-  ownDid: string,
+  ownDid: string | null, // null indicates to skip the audience check
   getSigningKey: (did: string) => Promise<string>,
 ): Promise<string> => {
   const parts = jwtStr.split('.')
@@ -57,7 +57,7 @@ export const verifyJwt = async (
   if (Date.now() / 1000 > payload.exp) {
     throw new AuthRequiredError('jwt expired', 'JwtExpired')
   }
-  if (payload.aud !== ownDid) {
+  if (ownDid !== null && payload.aud !== ownDid) {
     throw new AuthRequiredError(
       'jwt audience does not match service did',
       'BadJwtAudience',

package/src/index.ts

@@ -2,3 +2,7 @@ export * from './types'
 export * from './auth'
 export * from './server'
 export * from './stream'
+export * from './rate-limiter'
+
+export type { ServerTiming } from './util'
+export { serverTimingHeader, ServerTimer } from './util'

package/src/logger.ts

@@ -1,5 +1,6 @@
 import { subsystemLogger } from '@atproto/common'
 
-export const logger = subsystemLogger('xrpc-server')
+export const logger: ReturnType<typeof subsystemLogger> =
+  subsystemLogger('xrpc-server')
 
 export default logger

package/src/rate-limiter.ts

@@ -0,0 +1,167 @@
+import {
+  RateLimiterAbstract,
+  RateLimiterMemory,
+  RateLimiterRedis,
+  RateLimiterRes,
+} from 'rate-limiter-flexible'
+import { logger } from './logger'
+import {
+  CalcKeyFn,
+  CalcPointsFn,
+  RateLimitExceededError,
+  RateLimiterConsume,
+  RateLimiterI,
+  RateLimiterStatus,
+  XRPCReqContext,
+} from './types'
+
+export type RateLimiterOpts = {
+  keyPrefix: string
+  durationMs: number
+  points: number
+  bypassSecret?: string
+  calcKey?: CalcKeyFn
+  calcPoints?: CalcPointsFn
+  failClosed?: boolean
+}
+
+export class RateLimiter implements RateLimiterI {
+  public limiter: RateLimiterAbstract
+  private byPassSecret?: string
+  private failClosed?: boolean
+  public calcKey: CalcKeyFn
+  public calcPoints: CalcPointsFn
+
+  constructor(limiter: RateLimiterAbstract, opts: RateLimiterOpts) {
+    this.limiter = limiter
+    this.byPassSecret = opts.bypassSecret
+    this.calcKey = opts.calcKey ?? defaultKey
+    this.calcPoints = opts.calcPoints ?? defaultPoints
+  }
+
+  static memory(opts: RateLimiterOpts): RateLimiter {
+    const limiter = new RateLimiterMemory({
+      keyPrefix: opts.keyPrefix,
+      duration: Math.floor(opts.durationMs / 1000),
+      points: opts.points,
+    })
+    return new RateLimiter(limiter, opts)
+  }
+
+  static redis(storeClient: unknown, opts: RateLimiterOpts): RateLimiter {
+    const limiter = new RateLimiterRedis({
+      storeClient,
+      keyPrefix: opts.keyPrefix,
+      duration: Math.floor(opts.durationMs / 1000),
+      points: opts.points,
+    })
+    return new RateLimiter(limiter, opts)
+  }
+
+  async consume(
+    ctx: XRPCReqContext,
+    opts?: { calcKey?: CalcKeyFn; calcPoints?: CalcPointsFn },
+  ): Promise<RateLimiterStatus | RateLimitExceededError | null> {
+    if (
+      this.byPassSecret &&
+      ctx.req.header('x-ratelimit-bypass') === this.byPassSecret
+    ) {
+      return null
+    }
+    const key = opts?.calcKey ? opts.calcKey(ctx) : this.calcKey(ctx)
+    const points = opts?.calcPoints
+      ? opts.calcPoints(ctx)
+      : this.calcPoints(ctx)
+    if (points < 1) {
+      return null
+    }
+    try {
+      const res = await this.limiter.consume(key, points)
+      return formatLimiterStatus(this.limiter, res)
+    } catch (err) {
+      // yes this library rejects with a res not an error
+      if (err instanceof RateLimiterRes) {
+        const status = formatLimiterStatus(this.limiter, err)
+        return new RateLimitExceededError(status)
+      } else {
+        if (this.failClosed) {
+          throw err
+        }
+        logger.error(
+          {
+            err,
+            keyPrefix: this.limiter.keyPrefix,
+            points: this.limiter.points,
+            duration: this.limiter.duration,
+          },
+          'rate limiter failed to consume points',
+        )
+        return null
+      }
+    }
+  }
+}
+
+export const formatLimiterStatus = (
+  limiter: RateLimiterAbstract,
+  res: RateLimiterRes,
+): RateLimiterStatus => {
+  return {
+    limit: limiter.points,
+    duration: limiter.duration,
+    remainingPoints: res.remainingPoints,
+    msBeforeNext: res.msBeforeNext,
+    consumedPoints: res.consumedPoints,
+    isFirstInDuration: res.isFirstInDuration,
+  }
+}
+
+export const consumeMany = async (
+  ctx: XRPCReqContext,
+  fns: RateLimiterConsume[],
+): Promise<RateLimiterStatus | RateLimitExceededError | null> => {
+  if (fns.length === 0) return null
+  const results = await Promise.all(fns.map((fn) => fn(ctx)))
+  const tightestLimit = getTightestLimit(results)
+  if (tightestLimit === null) {
+    return null
+  } else if (tightestLimit instanceof RateLimitExceededError) {
+    setResHeaders(ctx, tightestLimit.status)
+    return tightestLimit
+  } else {
+    setResHeaders(ctx, tightestLimit)
+    return tightestLimit
+  }
+}
+
+export const setResHeaders = (
+  ctx: XRPCReqContext,
+  status: RateLimiterStatus,
+) => {
+  ctx.res.setHeader('RateLimit-Limit', status.limit)
+  ctx.res.setHeader('RateLimit-Remaining', status.remainingPoints)
+  ctx.res.setHeader(
+    'RateLimit-Reset',
+    Math.floor((Date.now() + status.msBeforeNext) / 1000),
+  )
+  ctx.res.setHeader('RateLimit-Policy', `${status.limit};w=${status.duration}`)
+}
+
+export const getTightestLimit = (
+  resps: (RateLimiterStatus | RateLimitExceededError | null)[],
+): RateLimiterStatus | RateLimitExceededError | null => {
+  let lowest: RateLimiterStatus | null = null
+  for (const resp of resps) {
+    if (resp === null) continue
+    if (resp instanceof RateLimitExceededError) return resp
+    if (lowest === null || resp.remainingPoints < lowest.remainingPoints) {
+      lowest = resp
+    }
+  }
+  return lowest
+}
+
+// when using a proxy, ensure headers are getting forwarded correctly: `app.set('trust proxy', true)`
+// https://expressjs.com/en/guide/behind-proxies.html
+const defaultKey: CalcKeyFn = (ctx: XRPCReqContext) => ctx.req.ip
+const defaultPoints: CalcPointsFn = () => 1