@atproto/xrpc-server 0.6.4 → 0.7.1

package/src/server.ts

@@ -1,14 +1,4 @@
-import { Readable } from 'stream'
-import express, {
-  Application,
-  Express,
-  Router,
-  Request,
-  Response,
-  ErrorRequestHandler,
-  NextFunction,
-  RequestHandler,
-} from 'express'
+import { check, schema } from '@atproto/common'
 import {
   LexiconDoc,
   Lexicons,
@@ -17,31 +7,45 @@ import {
   LexXrpcQuery,
   LexXrpcSubscription,
 } from '@atproto/lexicon'
-import { check, forwardStreamErrors, schema } from '@atproto/common'
+import express, {
+  Application,
+  ErrorRequestHandler,
+  Express,
+  NextFunction,
+  Request,
+  RequestHandler,
+  Response,
+  Router,
+} from 'express'
+import { Readable } from 'node:stream'
+import { pipeline } from 'node:stream/promises'
+
+import log from './logger'
+import { consumeMany } from './rate-limiter'
 import { ErrorFrame, Frame, MessageFrame, XrpcStreamServer } from './stream'
 import {
-  XRPCHandler,
-  XRPCError,
-  InvalidRequestError,
-  HandlerOutput,
-  HandlerSuccess,
-  handlerSuccess,
-  XRPCHandlerConfig,
-  MethodNotImplementedError,
-  HandlerAuth,
   AuthVerifier,
+  HandlerAuth,
+  HandlerPipeThrough,
+  HandlerSuccess,
+  InternalServerError,
+  InvalidRequestError,
   isHandlerError,
+  isHandlerPipeThroughBuffer,
+  isHandlerPipeThroughStream,
+  isShared,
+  MethodNotImplementedError,
   Options,
-  XRPCStreamHandlerConfig,
-  XRPCStreamHandler,
   Params,
-  InternalServerError,
-  XRPCReqContext,
-  RateLimiterI,
   RateLimiterConsume,
-  isShared,
+  RateLimiterI,
   RateLimitExceededError,
-  HandlerPipeThrough,
+  XRPCError,
+  XRPCHandler,
+  XRPCHandlerConfig,
+  XRPCReqContext,
+  XRPCStreamHandler,
+  XRPCStreamHandlerConfig,
 } from './types'
 import {
   decodeQueryParams,
@@ -49,8 +53,6 @@ import {
   validateInput,
   validateOutput,
 } from './util'
-import log from './logger'
-import { consumeMany } from './rate-limiter'
 
 export function createServer(lexicons?: LexiconDoc[], options?: Options) {
   return new Server(lexicons, options)
@@ -243,8 +245,8 @@ export class Server {
       validateInput(nsid, def, req, routeOpts, this.lex)
     const validateResOutput =
       this.options.validateResponse === false
-        ? (output?: HandlerSuccess) => output
-        : (output?: HandlerSuccess) =>
+        ? null
+        : (output: undefined | HandlerSuccess) =>
             validateOutput(nsid, def, output, this.lex)
     const assertValidXrpcParams = (params: unknown) =>
       this.lex.assertValidXrpcParams(nsid, params)
@@ -280,59 +282,48 @@ export class Server {
         }
 
         // run the handler
-        const outputUnvalidated = await routeCfg.handler(reqCtx)
+        const output = await routeCfg.handler(reqCtx)
+
+        if (!output) {
+          validateResOutput?.(output)
+          res.status(200)
+          res.end()
+        } else if (isHandlerPipeThroughStream(output)) {
+          setHeaders(res, output)
+          res.status(200)
+          res.header('Content-Type', output.encoding)
+          await pipeline(output.stream, res)
+        } else if (isHandlerPipeThroughBuffer(output)) {
+          setHeaders(res, output)
+          res.status(200)
+          res.header('Content-Type', output.encoding)
+          res.end(output.buffer)
+        } else if (isHandlerError(output)) {
+          next(XRPCError.fromError(output))
+        } else {
+          validateResOutput?.(output)
 
-        if (isHandlerError(outputUnvalidated)) {
-          throw XRPCError.fromError(outputUnvalidated)
-        }
+          res.status(200)
+          setHeaders(res, output)
 
-        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)
-          // set headers
-          if (output?.headers) {
-            Object.entries(output.headers).forEach(([name, val]) => {
-              res.header(name, val)
-            })
-          }
-          // send response
           if (
-            output?.encoding === 'application/json' ||
-            output?.encoding === 'json'
+            output.encoding === 'application/json' ||
+            output.encoding === 'json'
           ) {
             const json = lexToJson(output.body)
-            res.status(200).json(json)
-          } else if (output?.body instanceof Readable) {
+            res.json(json)
+          } else if (output.body instanceof Readable) {
             res.header('Content-Type', output.encoding)
-            res.status(200)
-            res.once('error', (err) => res.destroy(err))
-            forwardStreamErrors(output.body, res)
-            output.body.pipe(res)
-          } else if (output) {
-            res
-              .header('Content-Type', output.encoding)
-              .status(200)
-              .send(
-                output.body instanceof Uint8Array
+            await pipeline(output.body, res)
+          } else {
+            res.header('Content-Type', output.encoding)
+            res.send(
+              Buffer.isBuffer(output.body)
+                ? output.body
+                : output.body instanceof Uint8Array
                   ? Buffer.from(output.body)
                   : output.body,
-              )
-          } else {
-            res.status(200).end()
+            )
           }
         }
       } catch (err: unknown) {
@@ -364,7 +355,7 @@ export class Server {
             // authenticate request
             const auth = await config.auth?.({ req })
             if (isHandlerError(auth)) {
-              throw XRPCError.fromError(auth)
+              throw XRPCError.fromHandlerError(auth)
             }
             // validate request
             let params = decodeQueryParams(def, getQueryParams(req.url))
@@ -481,30 +472,18 @@ export class Server {
   }
 }
 
-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
+function setHeaders(
+  res: Response,
+  result: HandlerSuccess | HandlerPipeThrough,
+) {
+  const { headers } = result
+  if (headers) {
+    for (const [name, val] of Object.entries(headers)) {
+      if (val != null) res.header(name, val)
     }
   }
-  return true
 }
 
-const isString = (val: unknown): val is string => typeof val === 'string'
-
 const kRequestLocals = Symbol('requestLocals')
 
 function createLocalsMiddleware(nsid: string): RequestHandler {
@@ -525,7 +504,7 @@ function createAuthMiddleware(verifier: AuthVerifier): RequestHandler {
     try {
       const result = await verifier({ req, res })
       if (isHandlerError(result)) {
-        throw XRPCError.fromError(result)
+        throw XRPCError.fromHandlerError(result)
       }
       const locals: RequestLocals = req[kRequestLocals]
       locals.auth = result

package/src/types.ts

@@ -1,12 +1,14 @@
-import { IncomingMessage } from 'http'
-import express from 'express'
-import { isHttpError } from 'http-errors'
-import zod from 'zod'
 import {
   ResponseType,
-  ResponseTypeStrings,
   ResponseTypeNames,
+  ResponseTypeStrings,
+  XRPCError as XRPCClientError,
 } from '@atproto/xrpc'
+import express from 'express'
+import { IncomingMessage } from 'http'
+import { isHttpError } from 'http-errors'
+import { Readable } from 'stream'
+import zod from 'zod'
 
 export type CatchallHandler = (
   req: express.Request,
@@ -46,18 +48,40 @@ export const handlerAuth = zod.object({
 })
 export type HandlerAuth = zod.infer<typeof handlerAuth>
 
+export const headersSchema = zod.record(zod.string())
+
 export const handlerSuccess = zod.object({
   encoding: zod.string(),
   body: zod.any(),
-  headers: zod.record(zod.string()).optional(),
+  headers: headersSchema.optional(),
 })
 export type HandlerSuccess = zod.infer<typeof handlerSuccess>
 
-export const handlerPipeThrough = zod.object({
+export const handlerPipeThroughBuffer = zod.object({
   encoding: zod.string(),
-  buffer: zod.instanceof(ArrayBuffer),
-  headers: zod.record(zod.string()).optional(),
+  buffer: zod.instanceof(Buffer),
+  headers: headersSchema.optional(),
 })
+
+export type HandlerPipeThroughBuffer = zod.infer<
+  typeof handlerPipeThroughBuffer
+>
+
+export const handlerPipeThroughStream = zod.object({
+  encoding: zod.string(),
+  stream: zod.instanceof(Readable),
+  headers: headersSchema.optional(),
+})
+
+export type HandlerPipeThroughStream = zod.infer<
+  typeof handlerPipeThroughStream
+>
+
+export const handlerPipeThrough = zod.union([
+  handlerPipeThroughBuffer,
+  handlerPipeThroughStream,
+])
+
 export type HandlerPipeThrough = zod.infer<typeof handlerPipeThrough>
 
 export const handlerError = zod.object({
@@ -186,8 +210,9 @@ export class XRPCError extends Error {
     public type: ResponseType,
     public errorMessage?: string,
     public customErrorName?: string,
+    options?: ErrorOptions,
   ) {
-    super(errorMessage)
+    super(errorMessage, options)
   }
 
   get payload() {
@@ -208,22 +233,36 @@ export class XRPCError extends Error {
     return ResponseTypeStrings[this.type]
   }
 
-  static fromError(error: unknown) {
-    if (error instanceof XRPCError) {
-      return error
+  static fromError(cause: unknown): XRPCError {
+    if (cause instanceof XRPCError) {
+      return cause
     }
-    let resultErr: XRPCError
-    if (isHttpError(error)) {
-      resultErr = new XRPCError(error.status, error.message, error.name)
-    } else if (isHandlerError(error)) {
-      resultErr = new XRPCError(error.status, error.message, error.error)
-    } else if (error instanceof Error) {
-      resultErr = new InternalServerError(error.message)
-    } else {
-      resultErr = new InternalServerError('Unexpected internal server error')
+
+    if (cause instanceof XRPCClientError) {
+      return new XRPCError(cause.status, cause.message, cause.error, { cause })
+    }
+
+    if (isHttpError(cause)) {
+      return new XRPCError(cause.status, cause.message, cause.name, { cause })
     }
-    resultErr.cause = error
-    return resultErr
+
+    if (isHandlerError(cause)) {
+      return this.fromHandlerError(cause)
+    }
+
+    if (cause instanceof Error) {
+      return new InternalServerError(cause.message, undefined, { cause })
+    }
+
+    return new InternalServerError(
+      'Unexpected internal server error',
+      undefined,
+      { cause },
+    )
+  }
+
+  static fromHandlerError(err: HandlerError): XRPCError {
+    return new XRPCError(err.status, err.message, err.error, { cause: err })
   }
 }
 
@@ -237,21 +276,67 @@ export function isHandlerError(v: unknown): v is HandlerError {
   )
 }
 
+export function isHandlerPipeThroughBuffer(
+  v: HandlerOutput,
+): v is HandlerPipeThroughBuffer {
+  // We only need to discriminate between possible HandlerOutput values
+  return v['buffer'] !== undefined
+}
+
+export function isHandlerPipeThroughStream(
+  v: HandlerOutput,
+): v is HandlerPipeThroughStream {
+  // We only need to discriminate between possible HandlerOutput values
+  return v['stream'] !== undefined
+}
+
 export class InvalidRequestError extends XRPCError {
-  constructor(errorMessage?: string, customErrorName?: string) {
-    super(ResponseType.InvalidRequest, errorMessage, customErrorName)
+  constructor(
+    errorMessage?: string,
+    customErrorName?: string,
+    options?: ErrorOptions,
+  ) {
+    super(ResponseType.InvalidRequest, errorMessage, customErrorName, options)
+  }
+
+  [Symbol.hasInstance](instance: unknown): boolean {
+    return (
+      instance instanceof XRPCError &&
+      instance.type === ResponseType.InvalidRequest
+    )
   }
 }
 
 export class AuthRequiredError extends XRPCError {
-  constructor(errorMessage?: string, customErrorName?: string) {
-    super(ResponseType.AuthRequired, errorMessage, customErrorName)
+  constructor(
+    errorMessage?: string,
+    customErrorName?: string,
+    options?: ErrorOptions,
+  ) {
+    super(ResponseType.AuthRequired, errorMessage, customErrorName, options)
+  }
+
+  [Symbol.hasInstance](instance: unknown): boolean {
+    return (
+      instance instanceof XRPCError &&
+      instance.type === ResponseType.AuthRequired
+    )
   }
 }
 
 export class ForbiddenError extends XRPCError {
-  constructor(errorMessage?: string, customErrorName?: string) {
-    super(ResponseType.Forbidden, errorMessage, customErrorName)
+  constructor(
+    errorMessage?: string,
+    customErrorName?: string,
+    options?: ErrorOptions,
+  ) {
+    super(ResponseType.Forbidden, errorMessage, customErrorName, options)
+  }
+
+  [Symbol.hasInstance](instance: unknown): boolean {
+    return (
+      instance instanceof XRPCError && instance.type === ResponseType.Forbidden
+    )
   }
 }
 
@@ -260,37 +345,120 @@ export class RateLimitExceededError extends XRPCError {
     public status: RateLimiterStatus,
     errorMessage?: string,
     customErrorName?: string,
+    options?: ErrorOptions,
   ) {
-    super(ResponseType.RateLimitExceeded, errorMessage, customErrorName)
+    super(
+      ResponseType.RateLimitExceeded,
+      errorMessage,
+      customErrorName,
+      options,
+    )
+  }
+
+  [Symbol.hasInstance](instance: unknown): boolean {
+    return (
+      instance instanceof XRPCError &&
+      instance.type === ResponseType.RateLimitExceeded
+    )
   }
 }
 
 export class InternalServerError extends XRPCError {
-  constructor(errorMessage?: string, customErrorName?: string) {
-    super(ResponseType.InternalServerError, errorMessage, customErrorName)
+  constructor(
+    errorMessage?: string,
+    customErrorName?: string,
+    options?: ErrorOptions,
+  ) {
+    super(
+      ResponseType.InternalServerError,
+      errorMessage,
+      customErrorName,
+      options,
+    )
+  }
+
+  [Symbol.hasInstance](instance: unknown): boolean {
+    return (
+      instance instanceof XRPCError &&
+      instance.type === ResponseType.InternalServerError
+    )
   }
 }
 
 export class UpstreamFailureError extends XRPCError {
-  constructor(errorMessage?: string, customErrorName?: string) {
-    super(ResponseType.UpstreamFailure, errorMessage, customErrorName)
+  constructor(
+    errorMessage?: string,
+    customErrorName?: string,
+    options?: ErrorOptions,
+  ) {
+    super(ResponseType.UpstreamFailure, errorMessage, customErrorName, options)
+  }
+
+  [Symbol.hasInstance](instance: unknown): boolean {
+    return (
+      instance instanceof XRPCError &&
+      instance.type === ResponseType.UpstreamFailure
+    )
   }
 }
 
 export class NotEnoughResourcesError extends XRPCError {
-  constructor(errorMessage?: string, customErrorName?: string) {
-    super(ResponseType.NotEnoughResources, errorMessage, customErrorName)
+  constructor(
+    errorMessage?: string,
+    customErrorName?: string,
+    options?: ErrorOptions,
+  ) {
+    super(
+      ResponseType.NotEnoughResources,
+      errorMessage,
+      customErrorName,
+      options,
+    )
+  }
+
+  [Symbol.hasInstance](instance: unknown): boolean {
+    return (
+      instance instanceof XRPCError &&
+      instance.type === ResponseType.NotEnoughResources
+    )
   }
 }
 
 export class UpstreamTimeoutError extends XRPCError {
-  constructor(errorMessage?: string, customErrorName?: string) {
-    super(ResponseType.UpstreamTimeout, errorMessage, customErrorName)
+  constructor(
+    errorMessage?: string,
+    customErrorName?: string,
+    options?: ErrorOptions,
+  ) {
+    super(ResponseType.UpstreamTimeout, errorMessage, customErrorName, options)
+  }
+
+  [Symbol.hasInstance](instance: unknown): boolean {
+    return (
+      instance instanceof XRPCError &&
+      instance.type === ResponseType.UpstreamTimeout
+    )
   }
 }
 
 export class MethodNotImplementedError extends XRPCError {
-  constructor(errorMessage?: string, customErrorName?: string) {
-    super(ResponseType.MethodNotImplemented, errorMessage, customErrorName)
+  constructor(
+    errorMessage?: string,
+    customErrorName?: string,
+    options?: ErrorOptions,
+  ) {
+    super(
+      ResponseType.MethodNotImplemented,
+      errorMessage,
+      customErrorName,
+      options,
+    )
+  }
+
+  [Symbol.hasInstance](instance: unknown): boolean {
+    return (
+      instance instanceof XRPCError &&
+      instance.type === ResponseType.MethodNotImplemented
+    )
   }
 }