@atproto/xrpc-server 0.10.14 → 0.10.16

package/src/types.ts

@@ -1,7 +1,7 @@
 import { IncomingMessage } from 'node:http'
 import { Readable } from 'node:stream'
 import { NextFunction, Request, Response } from 'express'
-import { z } from 'zod'
+import { l } from '@atproto/lex-schema'
 import { ErrorResult, XRPCError } from './errors'
 import { CalcKeyFn, CalcPointsFn, RateLimiterI } from './rate-limiter'
 
@@ -51,44 +51,50 @@ export type AuthResult = {
   artifacts?: unknown
 }
 
-export const headersSchema = z.record(z.string())
+export const headersSchema = l.dict(l.string(), l.string())
 
-export type Headers = z.infer<typeof headersSchema>
+export type Headers = l.Infer<typeof headersSchema>
 
-export const handlerSuccess = z.object({
-  encoding: z.string(),
-  body: z.any(),
-  headers: headersSchema.optional(),
+export const handlerSuccess = l.object({
+  encoding: l.string(),
+  body: l.unknown(),
+  headers: l.optional(headersSchema),
 })
 
-export type HandlerSuccess = z.infer<typeof handlerSuccess>
+export type HandlerSuccess = l.Infer<typeof handlerSuccess>
 
-export const handlerPipeThroughBuffer = z.object({
-  encoding: z.string(),
-  buffer: z.instanceof(Buffer),
-  headers: headersSchema.optional(),
+export const handlerPipeThroughBuffer = l.object({
+  encoding: l.string(),
+  buffer: l.custom(
+    (v): v is Buffer => v instanceof Buffer,
+    'Expected a Buffer',
+  ),
+  headers: l.optional(headersSchema),
 })
 
-export type HandlerPipeThroughBuffer = z.infer<typeof handlerPipeThroughBuffer>
+export type HandlerPipeThroughBuffer = l.Infer<typeof handlerPipeThroughBuffer>
 
-export const handlerPipeThroughStream = z.object({
-  encoding: z.string(),
-  stream: z.instanceof(Readable),
-  headers: headersSchema.optional(),
+export const handlerPipeThroughStream = l.object({
+  encoding: l.string(),
+  stream: l.custom(
+    (v): v is Readable => v instanceof Readable,
+    'Expected a Readable stream',
+  ),
+  headers: l.optional(headersSchema),
 })
 
-export type HandlerPipeThroughStream = z.infer<typeof handlerPipeThroughStream>
+export type HandlerPipeThroughStream = l.Infer<typeof handlerPipeThroughStream>
 
-export const handlerPipeThrough = z.union([
+export const handlerPipeThrough = l.union([
   handlerPipeThroughBuffer,
   handlerPipeThroughStream,
 ])
 
-export type HandlerPipeThrough = z.infer<typeof handlerPipeThrough>
+export type HandlerPipeThrough = l.Infer<typeof handlerPipeThrough>
 
 export type Auth = void | AuthResult
 export type Input = void | HandlerInput
-export type Output = void | HandlerSuccess | ErrorResult
+export type Output = void | HandlerSuccess | HandlerPipeThrough | ErrorResult
 
 export type AuthVerifier<C, A extends AuthResult = AuthResult> =
   | ((ctx: C) => Awaitable<A | ErrorResult>)
@@ -173,6 +179,19 @@ export type RouteOptions = {
   textLimit?: number
 }
 
+export type MethodAuth<
+  A extends Auth = Auth,
+  P extends Params = Params,
+> = MethodAuthVerifier<Extract<A, AuthResult>, P>
+
+export type MethodRateLimit<
+  A extends Auth = Auth,
+  P extends Params = Params,
+  I extends Input = Input,
+> =
+  | RateLimitOpts<HandlerContext<A, P, I>>
+  | RateLimitOpts<HandlerContext<A, P, I>>[]
+
 export type MethodConfig<
   A extends Auth = Auth,
   P extends Params = Params,
@@ -180,11 +199,21 @@ export type MethodConfig<
   O extends Output = Output,
 > = {
   handler: MethodHandler<A, P, I, O>
-  auth?: MethodAuthVerifier<Extract<A, AuthResult>, P>
+  auth?: MethodAuth<A, P>
+  opts?: RouteOptions
+  rateLimit?: MethodRateLimit<A, P, I>
+}
+
+export type MethodConfigWithAuth<
+  A extends Auth = Auth,
+  P extends Params = Params,
+  I extends Input = Input,
+  O extends Output = Output,
+> = {
+  handler: MethodHandler<A, P, I, O>
+  auth: MethodAuth<A, P>
   opts?: RouteOptions
-  rateLimit?:
-    | RateLimitOpts<HandlerContext<A, P, I>>
-    | RateLimitOpts<HandlerContext<A, P, I>>[]
+  rateLimit?: MethodRateLimit<A, P, I>
 }
 
 export type MethodConfigOrHandler<
@@ -199,6 +228,43 @@ export type StreamAuthContext<P extends Params = Params> = {
   req: IncomingMessage
 }
 
+export type LexMethodParams<M extends l.Procedure | l.Query | l.Subscription> =
+  l.InferMethodParams<M>
+
+export type LexMethodInput<M extends l.Procedure | l.Query> =
+  l.InferMethodInput<M, Readable>
+
+export type LexMethodOutput<M extends l.Procedure | l.Query> =
+  l.InferMethodOutput<M, Readable> extends undefined
+    ? l.InferMethodOutput<M, Uint8Array | Readable> | void
+    : l.InferMethodOutput<M, Uint8Array | Readable>
+
+export type LexMethodMessage<M extends l.Subscription> = l.InferMethodMessage<M>
+
+export type LexMethodHandler<
+  M extends l.Procedure | l.Query,
+  A extends Auth = Auth,
+> = MethodHandler<A, LexMethodParams<M>, LexMethodInput<M>, LexMethodOutput<M>>
+
+export type LexMethodConfig<
+  M extends l.Procedure | l.Query,
+  A extends Auth = Auth,
+> = MethodConfig<A, LexMethodParams<M>, LexMethodInput<M>, LexMethodOutput<M>>
+
+export type LexSubscriptionHandler<
+  M extends l.Subscription,
+  A extends Auth = Auth,
+> = StreamHandler<
+  Extract<A, AuthResult>,
+  LexMethodParams<M>,
+  LexMethodMessage<M>
+>
+
+export type LexSubscriptionConfig<
+  M extends l.Subscription,
+  A extends Auth = Auth,
+> = StreamConfig<A, LexMethodParams<M>, LexMethodMessage<M>>
+
 export type StreamAuthVerifier<
   A extends AuthResult = AuthResult,
   P extends Params = Params,
@@ -233,6 +299,21 @@ export type StreamConfigOrHandler<
   O = unknown,
 > = StreamHandler<A, P, O> | StreamConfig<A, P, O>
 
+export function isHandlerSuccess(output: Output): output is HandlerSuccess {
+  // We only need to discriminate between possible Output values
+  return (
+    output != null &&
+    'body' in output && // body is non optional (contrary to what type inference may suggest)
+    'encoding' in output &&
+    // Allows using objects that extends HandlerSuccess with a "status" field as
+    // output, as long as the status is < 400, in order to avoid being confused
+    // with ErrorResult objects.
+    (!('status' in output) ||
+      output.status == null ||
+      Number(output.status) < 400)
+  )
+}
+
 export function isHandlerPipeThroughBuffer(
   output: Output,
 ): output is HandlerPipeThroughBuffer {

package/src/util.ts

@@ -1,29 +1,61 @@
 import assert from 'node:assert'
 import { IncomingMessage, OutgoingMessage } from 'node:http'
 import { Duplex, Readable, pipeline } from 'node:stream'
-import { Request, Response, json, text } from 'express'
+import {
+  Request as ExpressRequest,
+  Response as ExpressResponse,
+  json,
+  text,
+} from 'express'
 import { contentType } from 'mime-types'
 import { MaxSizeChecker, createDecoders } from '@atproto/common'
+import { jsonToLex } from '@atproto/lex-json'
+import { l } from '@atproto/lex-schema'
 import {
-  LexXrpcBody,
-  LexXrpcProcedure,
-  LexXrpcQuery,
-  LexXrpcSubscription,
+  type LexXrpcBody,
+  type LexXrpcProcedure,
+  type LexXrpcQuery,
+  type LexXrpcSubscription,
   Lexicons,
-  jsonToLex,
+  jsonToLex as jsonToLexWithBlobRef,
 } from '@atproto/lexicon'
 import { ResponseType } from '@atproto/xrpc'
-import { InternalServerError, InvalidRequestError, XRPCError } from './errors'
 import {
-  Awaitable,
-  HandlerSuccess,
+  ErrorResult,
+  InternalServerError,
+  InvalidRequestError,
+  XRPCError,
+} from './errors'
+import {
+  Auth,
   Input,
+  LexMethodInput,
+  LexMethodOutput,
+  LexMethodParams,
+  Output,
   Params,
   RouteOptions,
   UndecodedParams,
   handlerSuccess,
 } from './types'
 
+export type ParamsVerifierInternal<P extends Params = Params> = (
+  req: IncomingMessage | ExpressRequest,
+) => P
+
+export type AuthVerifierInternal<C, A extends Auth = Auth> = (
+  ctx: C,
+) => Promise<Exclude<A, ErrorResult>>
+
+export type InputVerifierInternal<I extends Input = Input> = (
+  req: ExpressRequest,
+  res: ExpressResponse,
+) => Promise<I>
+
+export type OutputVerifierInternal<O extends Output = Output> = (
+  handleOutput: O,
+) => void
+
 export const asArray = <T>(arr: T | T[]): T[] =>
   Array.isArray(arr) ? arr : [arr]
 
@@ -38,7 +70,7 @@ export function setHeaders(
   }
 }
 
-export function decodeQueryParams(
+function decodeQueryParams(
   def: LexXrpcProcedure | LexXrpcQuery | LexXrpcSubscription,
   params: UndecodedParams,
 ): Params {
@@ -81,26 +113,37 @@ export function decodeQueryParam(
   }
 }
 
-export type QueryParams = Record<string, undefined | string | string[]>
-export function getQueryParams(url = ''): QueryParams {
-  const result: QueryParams = Object.create(null)
+export function getSearchParams(url?: string): URLSearchParams | undefined {
+  if (!url) return undefined
 
   const queryStringIdx = url.indexOf('?')
-  if (queryStringIdx === -1) return result
+  if (queryStringIdx === -1) return undefined
 
   const queryString = url.slice(queryStringIdx + 1)
-  if (queryString === '') return result
+  if (queryString.length === 0) return undefined
 
-  const searchParams = new URLSearchParams(queryString)
-  for (const key of searchParams.keys()) {
-    if (key === '__proto__') {
-      // Prevent prototype pollution
-      throw new InvalidRequestError(
-        `Invalid query parameter: ${key}`,
-        'InvalidQueryParameter',
-      )
-    }
+  return new URLSearchParams(queryString)
+}
+
+export function getQueryParams(
+  req: IncomingMessage | ExpressRequest,
+): UndecodedParams {
+  if ('query' in req) return req.query
 
+  const result: UndecodedParams = Object.create(null)
+
+  const searchParams = getSearchParams(req.url)
+  if (!searchParams) return result
+
+  if (searchParams.has('__proto__')) {
+    // Prevent prototype pollution
+    throw new InvalidRequestError(
+      `Invalid query parameter: __proto__`,
+      'InvalidQueryParameter',
+    )
+  }
+
+  for (const key of searchParams.keys()) {
     const values = searchParams.getAll(key)
     result[key] = values.length === 1 ? values[0] : values
   }
@@ -108,14 +151,49 @@ export function getQueryParams(url = ''): QueryParams {
   return result
 }
 
-export function createInputVerifier(
+export function createLexiconParamsVerifier<P extends Params = Params>(
+  nsid: string,
+  def: LexXrpcQuery | LexXrpcProcedure | LexXrpcSubscription,
+  lexicons: Lexicons,
+): ParamsVerifierInternal<P> {
+  return (req) => {
+    const queryParams = getQueryParams(req)
+    const params = decodeQueryParams(def, queryParams)
+    try {
+      return lexicons.assertValidXrpcParams(nsid, params) as P
+    } catch (e) {
+      // @NOTE WE historically did not check for specific error types here,
+      throw new InvalidRequestError(String(e))
+    }
+  }
+}
+
+export function createSchemaParamsVerifier<
+  M extends l.Procedure | l.Query | l.Subscription,
+>(ns: l.Main<M>): ParamsVerifierInternal<LexMethodParams<M>> {
+  const schema = l.getMain(ns)
+  return (req) => {
+    const urlSearchParams = getSearchParams(req.url) ?? new URLSearchParams()
+    try {
+      const params = schema.parameters.fromURLSearchParams(urlSearchParams)
+      return params as LexMethodParams<M>
+    } catch (err) {
+      if (err instanceof l.LexValidationError) {
+        throw new InvalidRequestError(err.message)
+      }
+      throw err
+    }
+  }
+}
+
+export function createLexiconInputVerifier<I extends Input = Input>(
   nsid: string,
   def: LexXrpcProcedure | LexXrpcQuery,
   options: RouteOptions,
   lexicons: Lexicons,
-): (req: Request, res: Response) => Awaitable<Input> {
+): InputVerifierInternal<I> {
   if (def.type === 'query' || !def.input) {
-    return (req) => {
+    return async (req) => {
       // @NOTE We allow (and ignore) "empty" bodies
       if (getBodyPresence(req) === 'present') {
         throw new InvalidRequestError(
@@ -123,7 +201,7 @@ export function createInputVerifier(
         )
       }
 
-      return undefined
+      return undefined as I
     }
   }
 
@@ -159,11 +237,13 @@ export function createInputVerifier(
 
     if (input.schema) {
       try {
-        const lexBody = req.body ? jsonToLex(req.body) : req.body
+        const lexBody = req.body ? jsonToLexWithBlobRef(req.body) : req.body
         req.body = lexicons.assertValidXrpcInput(nsid, lexBody)
-      } catch (e) {
+      } catch (cause) {
         throw new InvalidRequestError(
-          e instanceof Error ? e.message : String(e),
+          cause instanceof Error ? cause.message : String(cause),
+          undefined,
+          { cause },
         )
       }
     }
@@ -172,54 +252,169 @@ export function createInputVerifier(
     // otherwise, we pass along a decoded readable stream
     const body = req.readableEnded ? req.body : decodeBodyStream(req, blobLimit)
 
-    return { encoding: reqEncoding, body }
+    return { encoding: reqEncoding, body } as I
   }
 }
 
-export function validateOutput(
+export function createSchemaInputVerifier<M extends l.Procedure | l.Query>(
+  ns: l.Main<M>,
+  options: RouteOptions,
+): InputVerifierInternal<LexMethodInput<M>> {
+  const schema = l.getMain(ns)
+  const { blobLimit } = options
+
+  const input: l.Payload | undefined =
+    'input' in schema ? schema.input : undefined
+
+  if (!input?.encoding) {
+    //
+    return async (req) => {
+      if (getBodyPresence(req) === 'present') {
+        throw new InvalidRequestError(
+          `A request body was provided when none was expected`,
+        )
+      }
+
+      return undefined as LexMethodInput<M>
+    }
+  }
+
+  const bodyParser = createBodyParser(input.encoding, options)
+
+  return async (req, res) => {
+    if (getBodyPresence(req) === 'missing') {
+      throw new InvalidRequestError(
+        `A request body is expected but none was provided`,
+      )
+    }
+
+    const reqEncoding = parseReqEncoding(req)
+    if (!input.matchesEncoding(reqEncoding)) {
+      throw new InvalidRequestError(
+        `Wrong request encoding (Content-Type): ${reqEncoding}`,
+      )
+    }
+
+    if (bodyParser) {
+      await bodyParser(req, res)
+    }
+
+    if (input.schema) {
+      try {
+        const lexBody = req.body ? jsonToLex(req.body) : req.body
+        req.body = input.schema.parse(lexBody)
+      } catch (cause) {
+        throw new InvalidRequestError(
+          cause instanceof Error ? cause.message : String(cause),
+          undefined,
+          { cause },
+        )
+      }
+    }
+
+    // if middleware already got the body, we pass that along as input
+    // otherwise, we pass along a decoded readable stream
+    const body = req.readableEnded ? req.body : decodeBodyStream(req, blobLimit)
+
+    return { encoding: reqEncoding, body } as LexMethodInput<M>
+  }
+}
+
+export function createLexiconOutputVerifier<O extends Output = Output>(
   nsid: string,
   def: LexXrpcProcedure | LexXrpcQuery,
-  output: HandlerSuccess | void,
   lexicons: Lexicons,
-): void {
-  if (def.output) {
-    // An output is expected
-    if (output === undefined) {
+): OutputVerifierInternal<O> {
+  const outputDef = def.output
+
+  // Expects no output
+  if (!outputDef) {
+    return (handlerOutput) => {
+      if (handlerOutput !== undefined) {
+        throw new InternalServerError(
+          `A response body was provided when none was expected`,
+        )
+      }
+    }
+  }
+
+  // An output is expected
+  return (handlerOutput) => {
+    if (handlerOutput === undefined) {
       throw new InternalServerError(
         `A response body is expected but none was provided`,
       )
     }
 
+    if (!('encoding' in handlerOutput)) {
+      // Ensure handlerOutput is valid ErrorResult
+      if ('status' in handlerOutput && handlerOutput.status >= 400) {
+        return
+      }
+
+      throw new InternalServerError(`Invalid handler output: missing encoding`)
+    }
+
+    if (!('body' in handlerOutput)) {
+      // Ensure handlerOutput is valid HandlerPipeThrough
+      if ('stream' in handlerOutput || 'buffer' in handlerOutput) {
+        return // Validation is ignored for pipe-through outputs
+      }
+
+      throw new InternalServerError(`Invalid handler output: missing body`)
+    }
+
     // Fool-proofing (should not be necessary due to type system)
-    const result = handlerSuccess.safeParse(output)
+    const result = handlerSuccess.safeParse(handlerOutput)
     if (!result.success) {
       throw new InternalServerError(`Invalid handler output`, undefined, {
-        cause: result.error,
+        cause: result.reason,
       })
     }
 
     // output mime
-    const { encoding } = output
-    if (!encoding || !isValidEncoding(def.output, encoding)) {
+    const { encoding } = handlerOutput
+    if (!isValidEncoding(outputDef, encoding)) {
       throw new InternalServerError(`Invalid response encoding: ${encoding}`)
     }
 
     // output schema
-    if (def.output.schema) {
-      try {
-        output.body = lexicons.assertValidXrpcOutput(nsid, output.body)
-      } catch (e) {
-        throw new InternalServerError(
-          e instanceof Error ? e.message : String(e),
-        )
-      }
+    try {
+      lexicons.assertValidXrpcOutput(nsid, handlerOutput.body)
+      // @TODO Since the output verifier is typically enabled in dev/tests and
+      // disabled in production, we don't want to assign the (altered) output
+      // back to the handlerOutput object, as this would cause different
+      // behaviors between environments. Instead, we should compare the value
+      // returned by assertValidXrpcOutput with the original output and throw if
+      // they differ (indicating that the output was mutated during validation,
+      // e.g. due to default values being applied).
+    } catch (cause) {
+      const message =
+        cause instanceof Error ? cause.message : 'Output body validation failed'
+      throw new InternalServerError(message, undefined, { cause })
     }
-  } else {
-    // Expects no output
-    if (output !== undefined) {
-      throw new InternalServerError(
-        `A response body was provided when none was expected`,
-      )
+  }
+}
+
+export function createSchemaOutputVerifier<M extends l.Procedure | l.Query>(
+  ns: l.Main<M>,
+): OutputVerifierInternal<LexMethodOutput<M>> {
+  const outputSchema = l.getMain(ns).output
+  return (handlerOutput) => {
+    // @NOTE If the user of the lib wants to return an output that doesn't
+    // conform to the schema, they can use HandlerPipeThrough return types
+    if (!outputSchema.matchesEncoding(handlerOutput?.encoding)) {
+      throw new InternalServerError('Output encoding mismatch')
+    }
+    if (outputSchema.schema) {
+      const result = outputSchema.schema.safeValidate(handlerOutput?.body)
+      if (!result.success) {
+        throw new InternalServerError(result.reason.message, undefined, {
+          cause: result.reason,
+        })
+      }
+    } else if (!outputSchema.encoding && handlerOutput?.body !== undefined) {
+      throw new InternalServerError('Output body not expected')
     }
   }
 }
@@ -251,12 +446,29 @@ function trimString(str: string): string {
   return str.trim()
 }
 
-function isValidEncoding(output: LexXrpcBody, encoding: string) {
+function isValidEncoding(output: LexXrpcBody, encoding?: string) {
+  if (!encoding) return false
+
   const normalized = normalizeMime(encoding)
   if (!normalized) return false
 
   const allowed = parseDefEncoding(output)
-  return allowed.includes(ENCODING_ANY) || allowed.includes(normalized)
+  if (!allowed.length) return false
+
+  if (allowed.includes(ENCODING_ANY)) return true
+  if (allowed.includes(normalized)) return true
+
+  // Check for wildcard matches (e.g. normalized=application/json, allowed=application/*)
+  for (const allowedEnc of allowed) {
+    if (
+      allowedEnc.endsWith('/*') &&
+      normalized.startsWith(allowedEnc.slice(0, -1))
+    ) {
+      return true
+    }
+  }
+
+  return false
 }
 
 type BodyPresence = 'missing' | 'empty' | 'present'
@@ -277,7 +489,7 @@ function createBodyParser(inputEncoding: string, options: RouteOptions) {
   const jsonParser = json({ limit: jsonLimit })
   const textParser = text({ limit: textLimit })
   // Transform json and text parser middlewares into a single function
-  return (req: Request, res: Response) => {
+  return (req: ExpressRequest, res: ExpressResponse) => {
     return new Promise<void>((resolve, reject) => {
       jsonParser(req, res, (err) => {
         if (err) return reject(XRPCError.fromError(err))
@@ -377,7 +589,7 @@ export interface ServerTiming {
   description?: string
 }
 
-export const parseReqNsid = (req: Request | IncomingMessage) =>
+export const parseReqNsid = (req: ExpressRequest | IncomingMessage) =>
   parseUrlNsid('originalUrl' in req ? req.originalUrl : req.url || '/')
 
 /**