@atproto/xrpc-server 0.10.14 → 0.10.15

package/src/server.ts

@@ -6,12 +6,11 @@ import express, {
   Application,
   ErrorRequestHandler,
   Express,
-  Request,
   RequestHandler,
   Router,
 } from 'express'
-import { check, schema } from '@atproto/common'
-import { LexMap, LexValue } from '@atproto/lex-data'
+import { LexValue } from '@atproto/lex-data'
+import { l } from '@atproto/lex-schema'
 import {
   LexXrpcProcedure,
   LexXrpcQuery,
@@ -26,7 +25,6 @@ import {
   MethodNotImplementedError,
   XRPCError,
   excludeErrorResult,
-  isErrorResult,
 } from './errors'
 import log, { LOGGER_NAME } from './logger'
 import {
@@ -44,28 +42,46 @@ import {
   AuthVerifier,
   CatchallHandler,
   HandlerContext,
-  HandlerSuccess,
   Input,
+  LexMethodConfig,
+  LexMethodHandler,
+  LexMethodInput,
+  LexMethodOutput,
+  LexMethodParams,
+  LexSubscriptionConfig,
+  LexSubscriptionHandler,
+  MethodAuthContext,
   MethodConfig,
   MethodConfigOrHandler,
+  MethodHandler,
   Options,
+  Output,
   Params,
   RouteOptions,
   ServerRateLimitDescription,
+  StreamAuthContext,
   StreamConfig,
   StreamConfigOrHandler,
+  StreamContext,
   isHandlerPipeThroughBuffer,
   isHandlerPipeThroughStream,
+  isHandlerSuccess,
   isSharedRateLimitOpts,
 } from './types'
 import {
+  AuthVerifierInternal,
+  InputVerifierInternal,
+  OutputVerifierInternal,
+  ParamsVerifierInternal,
   asArray,
-  createInputVerifier,
-  decodeQueryParams,
+  createLexiconInputVerifier,
+  createLexiconOutputVerifier,
+  createLexiconParamsVerifier,
+  createSchemaInputVerifier,
+  createSchemaOutputVerifier,
+  createSchemaParamsVerifier,
   extractUrlNsid,
-  getQueryParams,
   setHeaders,
-  validateOutput,
 } from './util'
 
 export function createServer(lexicons?: LexiconDoc[], options?: Options) {
@@ -114,13 +130,145 @@ export class Server {
     }
   }
 
+  listen(port: number, callback?: () => void) {
+    return this.router.listen(port, callback)
+  }
+
   // handlers
   // =
 
+  // Routes with auth
+  add<M extends l.Procedure | l.Query | l.Subscription, A extends AuthResult>(
+    ns: l.Main<M>,
+    config: M extends l.Procedure | l.Query
+      ? LexMethodConfig<M, A> & { auth: Exclude<unknown, void> }
+      : M extends l.Subscription
+        ? LexSubscriptionConfig<M, A> & { auth: Exclude<unknown, void> }
+        : never,
+  ): void
+  // Routes without auth
+  add<M extends l.Procedure | l.Query | l.Subscription>(
+    ns: l.Main<M>,
+    config: M extends l.Procedure | l.Query
+      ? LexMethodConfig<M, void> | LexMethodHandler<M, void>
+      : M extends l.Subscription
+        ? LexSubscriptionConfig<M, void> | LexSubscriptionHandler<M, void>
+        : never,
+  ): void
+  add<M extends l.Procedure | l.Query | l.Subscription, A extends Auth>(
+    ns: l.Main<M>,
+    configOfHandler: M extends l.Procedure | l.Query
+      ? LexMethodConfig<M, A> | LexMethodHandler<M, A>
+      : M extends l.Subscription
+        ? LexSubscriptionConfig<M, A> | LexSubscriptionHandler<M, A>
+        : never,
+  ): void {
+    const schema = l.getMain(ns)
+    const config =
+      typeof configOfHandler === 'function'
+        ? { handler: configOfHandler }
+        : configOfHandler
+    switch (schema.type) {
+      case 'procedure':
+        return this.addProcedureSchema(
+          schema,
+          config as LexMethodConfig<l.Procedure, A>,
+        )
+      case 'query':
+        return this.addQuerySchema(
+          schema,
+          config as LexMethodConfig<l.Query, A>,
+        )
+      case 'subscription':
+        return this.addSubscriptionSchema(
+          schema,
+          config as LexSubscriptionConfig<l.Subscription, A>,
+        )
+      default:
+        throw new TypeError(
+          // @ts-expect-error should never happen
+          `Unsupported schema ${schema.nsid} of type ${schema.type}`,
+        )
+    }
+  }
+
+  protected addProcedureSchema<M extends l.Procedure, A extends Auth>(
+    schema: M,
+    config: LexMethodConfig<M, A>,
+  ): void {
+    this.routes.post(
+      `/xrpc/${schema.nsid}`,
+      this.createHandlerInternal<
+        A,
+        LexMethodParams<M>,
+        LexMethodInput<M>,
+        LexMethodOutput<M>
+      >(
+        this.createAuthVerifier(config),
+        this.createSchemaParamsVerifier(schema),
+        this.createSchemaInputVerifier(schema, config.opts),
+        this.createRouteRateLimiter(schema.nsid, config),
+        config.handler,
+        this.createSchemaOutputVerifier(schema),
+      ),
+    )
+  }
+
+  protected addQuerySchema<M extends l.Query, A extends Auth>(
+    schema: M,
+    config: LexMethodConfig<M, A>,
+  ): void {
+    this.routes.get(
+      `/xrpc/${schema.nsid}`,
+      this.createHandlerInternal<
+        A,
+        LexMethodParams<M>,
+        LexMethodInput<M>,
+        LexMethodOutput<M>
+      >(
+        this.createAuthVerifier(config),
+        this.createSchemaParamsVerifier(schema),
+        this.createSchemaInputVerifier(schema, config.opts),
+        this.createRouteRateLimiter(schema.nsid, config),
+        config.handler,
+        this.createSchemaOutputVerifier(schema),
+      ),
+    )
+  }
+
+  protected addSubscriptionSchema<
+    M extends l.Subscription,
+    A extends Auth = void,
+  >(schema: M, config: LexSubscriptionConfig<M, A>): void {
+    const { handler } = config
+    const messageSchema =
+      this.options.validateResponse === false ? undefined : schema.message
+
+    return this.addSubscriptionInternal(
+      schema.nsid,
+      this.createSchemaParamsVerifier(schema),
+      this.createAuthVerifier(config),
+      // Wrap the handler to validate outgoing messages if a message schema
+      // is available
+      messageSchema
+        ? async function* (ctx) {
+            for await (const item of handler(ctx)) {
+              if (item instanceof Frame) {
+                messageSchema.validate(item.body)
+                yield item
+              } else {
+                yield messageSchema.validate(item)
+              }
+            }
+          }
+        : handler,
+    )
+  }
+
   method<A extends Auth = Auth>(
     nsid: string,
     configOrFn: MethodConfigOrHandler<A>,
-  ) {
+  ): void {
     this.addMethod(nsid, configOrFn)
   }
 
@@ -140,14 +288,14 @@ export class Server {
 
   streamMethod<A extends Auth = Auth>(
     nsid: string,
-    configOrFn: StreamConfigOrHandler<A>,
+    configOrFn: StreamConfigOrHandler<A, Params>,
   ) {
     this.addStreamMethod(nsid, configOrFn)
   }
 
   addStreamMethod<A extends Auth = Auth>(
     nsid: string,
-    configOrFn: StreamConfigOrHandler<A>,
+    configOrFn: StreamConfigOrHandler<A, Params>,
   ) {
     const config =
       typeof configOrFn === 'function' ? { handler: configOrFn } : configOrFn
@@ -239,66 +387,43 @@ export class Server {
     }
   }
 
-  protected createParamsVerifier(
-    nsid: string,
-    def: LexXrpcQuery | LexXrpcProcedure | LexXrpcSubscription,
-  ) {
-    return (req: Request | IncomingMessage): Params => {
-      const queryParams = 'query' in req ? req.query : getQueryParams(req.url)
-      const params: Params = decodeQueryParams(def, queryParams)
-      try {
-        return this.lex.assertValidXrpcParams(nsid, params) as Params
-      } catch (e) {
-        throw new InvalidRequestError(String(e))
-      }
-    }
-  }
-
-  protected createInputVerifier(
+  createHandler<
+    A extends Auth = Auth,
+    P extends Params = Params,
+    I extends Input = Input,
+    O extends Output = Output,
+  >(
     nsid: string,
     def: LexXrpcQuery | LexXrpcProcedure,
-    routeOpts: RouteOptions,
-  ) {
-    return createInputVerifier(nsid, def, routeOpts, this.lex)
-  }
-
-  protected createAuthVerifier<C, A extends Auth>(cfg: {
-    auth?: AuthVerifier<C, A & AuthResult>
-  }): null | ((ctx: C) => Promise<A>) {
-    const { auth } = cfg
-    if (!auth) return null
-
-    return async (ctx: C) => {
-      const result = await auth(ctx)
-      return excludeErrorResult(result)
-    }
+    cfg: MethodConfig<A, P, I, O>,
+  ): RequestHandler {
+    return this.createHandlerInternal<A, P, I, O>(
+      this.createAuthVerifier(cfg),
+      this.createLexiconParamsVerifier<P>(nsid, def),
+      this.createLexiconInputVerifier<I>(nsid, def, cfg.opts),
+      this.createRouteRateLimiter(nsid, cfg),
+      cfg.handler,
+      this.createLexiconOutputVerifier<O>(nsid, def),
+    )
   }
 
-  createHandler<A extends Auth = Auth>(
-    nsid: string,
-    def: LexXrpcQuery | LexXrpcProcedure,
-    cfg: MethodConfig<A>,
+  protected createHandlerInternal<
+    A extends Auth,
+    P extends Params,
+    I extends Input,
+    O extends Output,
+  >(
+    authVerifier: AuthVerifierInternal<MethodAuthContext<P>, A> | null,
+    paramsVerifier: ParamsVerifierInternal<P>,
+    inputVerifier: InputVerifierInternal<I>,
+    routeLimiter: RouteRateLimiter<HandlerContext<A, P, I>> | undefined,
+    handler: MethodHandler<A, P, I, O>,
+    validateResOutput: null | OutputVerifierInternal<O>,
   ): RequestHandler {
-    const authVerifier = this.createAuthVerifier(cfg)
-    const paramsVerifier = this.createParamsVerifier(nsid, def)
-    const inputVerifier = this.createInputVerifier(nsid, def, {
-      blobLimit: cfg.opts?.blobLimit ?? this.options.payload?.blobLimit,
-      jsonLimit: cfg.opts?.jsonLimit ?? this.options.payload?.jsonLimit,
-      textLimit: cfg.opts?.textLimit ?? this.options.payload?.textLimit,
-    })
-
-    const validateResOutput =
-      this.options.validateResponse === false
-        ? null
-        : (output: void | HandlerSuccess) =>
-            validateOutput(nsid, def, output, this.lex)
-
-    const routeLimiter = this.createRouteRateLimiter(nsid, cfg)
-
     return async function (req, res, next) {
       try {
         // parse & validate params
-        const params: Params = paramsVerifier(req)
+        const params = paramsVerifier(req)
 
         // authenticate request
         const auth: A = authVerifier
@@ -306,9 +431,9 @@ export class Server {
           : (undefined as A)
 
         // parse & validate input
-        const input: Input = await inputVerifier(req, res)
+        const input: I = await inputVerifier(req, res)
 
-        const ctx: HandlerContext<A> = {
+        const ctx: HandlerContext<A, P, I> = {
           params,
           input,
           auth,
@@ -321,7 +446,7 @@ export class Server {
         if (routeLimiter) await routeLimiter.handle(ctx)
 
         // run the handler
-        const output = await cfg.handler(ctx)
+        const output = (await handler(ctx)) as O
 
         if (!output) {
           validateResOutput?.(output)
@@ -337,25 +462,25 @@ export class Server {
           res.status(200)
           res.header('Content-Type', output.encoding)
           res.end(output.buffer)
-        } else if (isErrorResult(output)) {
-          next(XRPCError.fromError(output))
-        } else {
+        } else if (isHandlerSuccess(output)) {
           validateResOutput?.(output)
 
           res.status(200)
           setHeaders(res, output.headers)
 
-          if (
-            output.encoding === 'application/json' ||
-            output.encoding === 'json'
-          ) {
+          const encoding =
+            output.encoding === 'json' ? 'application/json' : output.encoding
+
+          res.header('Content-Type', encoding)
+
+          if (output.body instanceof Readable) {
+            // The "Readable" check comes first to avoid calling "lexToJson" on
+            // a stream, which would be a bug.
+            await pipeline(output.body, res)
+          } else if (encoding === 'application/json') {
             const json = lexToJson(output.body)
             res.json(json)
-          } else if (output.body instanceof Readable) {
-            res.header('Content-Type', output.encoding)
-            await pipeline(output.body, res)
           } else {
-            res.header('Content-Type', output.encoding)
             res.send(
               Buffer.isBuffer(output.body)
                 ? output.body
@@ -364,6 +489,8 @@ export class Server {
                   : output.body,
             )
           }
+        } else {
+          next(XRPCError.fromError(output))
         }
       } catch (err: unknown) {
         // Express will not call the next middleware (errorMiddleware in this case)
@@ -381,12 +508,24 @@ export class Server {
   protected async addSubscription<A extends Auth = Auth>(
     nsid: string,
     def: LexXrpcSubscription,
-    cfg: StreamConfig<A>,
+    cfg: StreamConfig<A, Params>,
   ) {
-    const paramsVerifier = this.createParamsVerifier(nsid, def)
-    const authVerifier = this.createAuthVerifier(cfg)
+    this.addSubscriptionInternal(
+      nsid,
+      this.createLexiconParamsVerifier(nsid, def),
+      this.createAuthVerifier(cfg),
+      // @NOTE outgoing messages are not validated against the lexicon schema
+      // (unlike the handlers for @atproto/lex based subscriptions)
+      cfg.handler,
+    )
+  }
 
-    const { handler } = cfg
+  protected addSubscriptionInternal<A extends Auth, P extends Params>(
+    nsid: string,
+    paramsVerifier: ParamsVerifierInternal<P>,
+    authVerifier: AuthVerifierInternal<StreamAuthContext<P>, A> | null,
+    handler: (ctx: StreamContext<A, P>) => AsyncIterable<unknown>,
+  ) {
     this.subscriptions.set(
       nsid,
       new XrpcStreamServer({
@@ -395,46 +534,98 @@ export class Server {
           try {
             // validate request
             const params = paramsVerifier(req)
+
             // authenticate request
             const auth = authVerifier
               ? await authVerifier({ req, params })
               : (undefined as A)
+
             // stream
             for await (const item of handler({ req, params, auth, signal })) {
-              if (item instanceof Frame) {
-                yield item
-                continue
-              }
-              const type = item?.['$type']
-              if (!check.is(item, schema.map) || typeof type !== 'string') {
-                yield new MessageFrame(item as LexValue)
-                continue
-              }
-              const split = type.split('#')
-              let t: string
-              if (
-                split.length === 2 &&
-                (split[0] === '' || split[0] === nsid)
-              ) {
-                t = `#${split[1]}`
-              } else {
-                t = type
-              }
-              const { $type: _, ...clone } = item as LexMap
-              yield new MessageFrame(clone, { type: t })
+              yield item instanceof Frame
+                ? item
+                : MessageFrame.fromLexValue(item as LexValue, nsid)
             }
           } catch (err) {
-            const xrpcErrPayload = XRPCError.fromError(err).payload
-            yield new ErrorFrame({
-              error: xrpcErrPayload.error ?? 'Unknown',
-              message: xrpcErrPayload.message,
-            })
+            yield ErrorFrame.fromError(err)
           }
         },
       }),
     )
   }
 
+  private createAuthVerifier<C, A extends AuthResult>(cfg: {
+    auth?: AuthVerifier<C, A>
+  }): null | AuthVerifierInternal<C, A> {
+    const { auth } = cfg
+    if (!auth) return null
+
+    return async (ctx) => {
+      const result = await auth(ctx)
+      return excludeErrorResult(result)
+    }
+  }
+
+  private createLexiconParamsVerifier<P extends Params = Params>(
+    nsid: string,
+    def: LexXrpcQuery | LexXrpcProcedure | LexXrpcSubscription,
+  ) {
+    return createLexiconParamsVerifier<P>(nsid, def, this.lex)
+  }
+
+  private createLexiconInputVerifier<I extends Input = Input>(
+    nsid: string,
+    def: LexXrpcQuery | LexXrpcProcedure,
+    opts?: RouteOptions,
+  ): InputVerifierInternal<I> {
+    return createLexiconInputVerifier(
+      nsid,
+      def,
+      {
+        blobLimit: opts?.blobLimit ?? this.options.payload?.blobLimit,
+        jsonLimit: opts?.jsonLimit ?? this.options.payload?.jsonLimit,
+        textLimit: opts?.textLimit ?? this.options.payload?.textLimit,
+      },
+      this.lex,
+    )
+  }
+
+  private createLexiconOutputVerifier<O extends Output = Output>(
+    nsid: string,
+    def: LexXrpcQuery | LexXrpcProcedure,
+  ): null | OutputVerifierInternal<O> {
+    if (this.options.validateResponse === false) {
+      return null
+    }
+    return createLexiconOutputVerifier(nsid, def, this.lex)
+  }
+
+  private createSchemaParamsVerifier<
+    M extends l.Procedure | l.Query | l.Subscription,
+  >(ns: l.Main<M>): ParamsVerifierInternal<LexMethodParams<M>> {
+    return createSchemaParamsVerifier<M>(ns)
+  }
+
+  private createSchemaInputVerifier<M extends l.Procedure | l.Query>(
+    ns: l.Main<M>,
+    opts?: RouteOptions,
+  ): InputVerifierInternal<LexMethodInput<M>> {
+    return createSchemaInputVerifier<M>(ns, {
+      blobLimit: opts?.blobLimit ?? this.options.payload?.blobLimit,
+      jsonLimit: opts?.jsonLimit ?? this.options.payload?.jsonLimit,
+      textLimit: opts?.textLimit ?? this.options.payload?.textLimit,
+    })
+  }
+
+  private createSchemaOutputVerifier<M extends l.Procedure | l.Query>(
+    ns: l.Main<M>,
+  ): null | OutputVerifierInternal<LexMethodOutput<M>> {
+    if (this.options.validateResponse === false) {
+      return null
+    }
+    return createSchemaOutputVerifier<M>(ns)
+  }
+
   private enableStreamingOnListen(app: Application) {
     const _listen = app.listen
     app.listen = (...args) => {
@@ -452,10 +643,15 @@ export class Server {
     }
   }
 
-  private createRouteRateLimiter<A extends Auth, C extends HandlerContext>(
+  private createRouteRateLimiter<
+    A extends Auth,
+    P extends Params,
+    I extends Input,
+    O extends Output,
+  >(
     nsid: string,
-    config: MethodConfig<A>,
-  ): RouteRateLimiter<C> | undefined {
+    config: MethodConfig<A, P, I, O>,
+  ): RouteRateLimiter<HandlerContext<A, P, I>> | undefined {
     // @NOTE global & shared rate limiters are instantiated with a context of
     // HandlerContext which is compatible (more generic) with the context of
     // this route specific rate limiters (C). For this reason, it's safe to

package/src/stream/frames.ts

@@ -1,4 +1,6 @@
-import { LexValue, decodeAll, encode } from '@atproto/lex-cbor'
+import { decodeAll, encode } from '@atproto/lex-cbor'
+import { LexValue, isPlainObject } from '@atproto/lex-data'
+import { XRPCError } from '../errors'
 import {
   ErrorFrameBody,
   ErrorFrameHeader,
@@ -35,19 +37,21 @@ export abstract class Frame<T extends LexValue = LexValue> {
 
     const parsedHeader = frameHeader.safeParse(header)
     if (!parsedHeader.success) {
-      throw new Error(`Invalid frame header: ${parsedHeader.error.message}`)
+      throw new Error(`Invalid frame header: ${parsedHeader.reason.message}`)
     }
-    const frameOp = parsedHeader.data.op
+    const frameOp = parsedHeader.value.op
     if (frameOp === FrameType.Message) {
       return new MessageFrame(body, {
-        type: parsedHeader.data.t,
+        type: parsedHeader.value.t,
       })
     } else if (frameOp === FrameType.Error) {
       const parsedBody = errorFrameBody.safeParse(body)
       if (!parsedBody.success) {
-        throw new Error(`Invalid error frame body: ${parsedBody.error.message}`)
+        throw new Error(
+          `Invalid error frame body: ${parsedBody.reason.message}`,
+        )
       }
-      return new ErrorFrame(parsedBody.data)
+      return new ErrorFrame(parsedBody.value)
     } else {
       const exhaustiveCheck: never = frameOp
       throw new Error(`Unknown frame op: ${exhaustiveCheck}`)
@@ -70,6 +74,29 @@ export class MessageFrame<T extends LexValue = LexValue> extends Frame<T> {
   get type() {
     return this.header.t
   }
+
+  static fromLexValue(data: LexValue, nsid: string) {
+    if (!isPlainObject(data)) {
+      return new MessageFrame(data)
+    }
+
+    const $type = data?.['$type']
+    if (typeof $type !== 'string') {
+      return new MessageFrame(data)
+    }
+
+    let type: string
+
+    const split = $type.split('#')
+    if (split.length === 2 && (split[0] === '' || split[0] === nsid)) {
+      type = `#${split[1]}`
+    } else {
+      type = $type
+    }
+
+    const { $type: _, ...clone } = data
+    return new MessageFrame(clone, { type })
+  }
 }
 
 export class ErrorFrame<T extends string = string> extends Frame<
@@ -89,4 +116,10 @@ export class ErrorFrame<T extends string = string> extends Frame<
   get message() {
     return this.body.message
   }
+
+  static fromError(err: unknown): ErrorFrame {
+    if (err instanceof ErrorFrame) return err
+    const { error = 'Unknown', message } = XRPCError.fromError(err).payload
+    return new ErrorFrame({ error, message })
+  }
 }

package/src/stream/types.ts

@@ -1,27 +1,27 @@
-import { z } from 'zod'
+import { l } from '@atproto/lex-schema'
 
 export enum FrameType {
   Message = 1,
   Error = -1,
 }
 
-export const messageFrameHeader = z.object({
-  op: z.literal(FrameType.Message), // Frame op
-  t: z.string().optional(), // Message body type discriminator
+export const messageFrameHeader = l.object({
+  op: l.literal(FrameType.Message), // Frame op
+  t: l.optional(l.string()), // Message body type discriminator
 })
-export type MessageFrameHeader = z.infer<typeof messageFrameHeader>
+export type MessageFrameHeader = l.Infer<typeof messageFrameHeader>
 
-export const errorFrameHeader = z.object({
-  op: z.literal(FrameType.Error),
+export const errorFrameHeader = l.object({
+  op: l.literal(FrameType.Error),
 })
-export const errorFrameBody = z.object({
-  error: z.string(), // Error code
-  message: z.string().optional(), // Error message
+export const errorFrameBody = l.object({
+  error: l.string(), // Error code
+  message: l.optional(l.string()), // Error message
 })
-export type ErrorFrameHeader = z.infer<typeof errorFrameHeader>
-export type ErrorFrameBody<T extends string = string> = { error: T } & z.infer<
+export type ErrorFrameHeader = l.Infer<typeof errorFrameHeader>
+export type ErrorFrameBody<T extends string = string> = { error: T } & l.Infer<
   typeof errorFrameBody
 >
 
-export const frameHeader = z.union([messageFrameHeader, errorFrameHeader])
-export type FrameHeader = z.infer<typeof frameHeader>
+export const frameHeader = l.union([messageFrameHeader, errorFrameHeader])
+export type FrameHeader = l.Infer<typeof frameHeader>