@atproto/xrpc-server 0.0.1

package/dist/logger.d.ts

@@ -0,0 +1,2 @@
+export declare const logger: import("pino").default.Logger<import("pino").default.LoggerOptions>;
+export default logger;

package/dist/server.d.ts

@@ -0,0 +1,19 @@
+import express, { NextFunction, RequestHandler } from 'express';
+import { Lexicons, LexXrpcProcedure, LexXrpcQuery } from '@atproto/lexicon';
+import { XRPCHandler, XRPCHandlerConfig, Options } from './types';
+export declare function createServer(lexicons?: unknown[], options?: Options): Server;
+export declare class Server {
+    router: import("express-serve-static-core").Router;
+    routes: import("express-serve-static-core").Router;
+    lex: Lexicons;
+    options: Options;
+    middleware: Record<'json' | 'text', RequestHandler>;
+    constructor(lexicons?: unknown[], opts?: Options);
+    method(nsid: string, configOrFn: XRPCHandlerConfig | XRPCHandler): void;
+    addMethod(nsid: string, configOrFn: XRPCHandlerConfig | XRPCHandler): void;
+    addLexicon(doc: unknown): void;
+    addLexicons(docs: unknown[]): 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;
+}

package/dist/types.d.ts

@@ -0,0 +1,115 @@
+import express from 'express';
+import zod from 'zod';
+import { ResponseType } from '@atproto/xrpc';
+export declare type Options = {
+    validateResponse?: boolean;
+    payload?: {
+        jsonLimit?: number;
+        blobLimit?: number;
+        textLimit?: number;
+    };
+};
+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 declare const handlerInput: zod.ZodObject<{
+    encoding: zod.ZodString;
+    body: zod.ZodAny;
+}, "strip", zod.ZodTypeAny, {
+    body?: any;
+    encoding: string;
+}, {
+    body?: any;
+    encoding: string;
+}>;
+export declare type HandlerInput = zod.infer<typeof handlerInput>;
+export declare const handlerAuth: zod.ZodObject<{
+    credentials: zod.ZodAny;
+    artifacts: zod.ZodAny;
+}, "strip", zod.ZodTypeAny, {
+    credentials?: any;
+    artifacts?: any;
+}, {
+    credentials?: any;
+    artifacts?: any;
+}>;
+export declare type HandlerAuth = zod.infer<typeof handlerAuth>;
+export declare const handlerSuccess: zod.ZodObject<{
+    encoding: zod.ZodString;
+    body: zod.ZodAny;
+}, "strip", zod.ZodTypeAny, {
+    body?: any;
+    encoding: string;
+}, {
+    body?: any;
+    encoding: string;
+}>;
+export declare type HandlerSuccess = zod.infer<typeof handlerSuccess>;
+export declare const handlerError: zod.ZodObject<{
+    status: zod.ZodNumber;
+    error: zod.ZodOptional<zod.ZodString>;
+    message: zod.ZodOptional<zod.ZodString>;
+}, "strip", zod.ZodTypeAny, {
+    error?: string | undefined;
+    message?: string | undefined;
+    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: {
+    auth: HandlerAuth | undefined;
+    params: Params;
+    input: HandlerInput | undefined;
+    req: express.Request;
+    res: express.Response;
+}) => Promise<HandlerOutput> | HandlerOutput | undefined;
+export declare type AuthOutput = HandlerAuth | HandlerError;
+export declare type AuthVerifier = (ctx: {
+    req: express.Request;
+    res: express.Response;
+}) => Promise<AuthOutput> | AuthOutput;
+export declare type XRPCHandlerConfig = {
+    auth?: AuthVerifier;
+    handler: XRPCHandler;
+};
+export declare class XRPCError extends Error {
+    type: ResponseType;
+    errorMessage?: string | undefined;
+    customErrorName?: string | undefined;
+    constructor(type: ResponseType, errorMessage?: string | undefined, customErrorName?: string | undefined);
+    get payload(): {
+        error: string | undefined;
+        message: string | undefined;
+    };
+    get typeStr(): string | undefined;
+    static fromError(error: unknown): XRPCError;
+}
+export declare function isHandlerError(v: unknown): v is HandlerError;
+export declare class InvalidRequestError extends XRPCError {
+    constructor(errorMessage?: string, customErrorName?: string);
+}
+export declare class AuthRequiredError extends XRPCError {
+    constructor(errorMessage?: string, customErrorName?: string);
+}
+export declare class ForbiddenError extends XRPCError {
+    constructor(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 {
+    constructor(errorMessage?: string, customErrorName?: string);
+}
+export declare class UpstreamTimeoutError extends XRPCError {
+    constructor(errorMessage?: string, customErrorName?: string);
+}
+export declare class MethodNotImplementedError extends XRPCError {
+    constructor(errorMessage?: string, customErrorName?: string);
+}

package/dist/util.d.ts

@@ -0,0 +1,10 @@
+import express from 'express';
+import { Lexicons, LexXrpcProcedure, LexXrpcQuery } from '@atproto/lexicon';
+import { UndecodedParams, Params, HandlerInput, HandlerSuccess, Options } from './types';
+export declare function decodeQueryParams(def: LexXrpcProcedure | LexXrpcQuery, params: UndecodedParams): Params;
+export declare function decodeQueryParam(type: string, value: unknown): string | number | boolean | undefined;
+export declare function validateInput(nsid: string, def: LexXrpcProcedure | LexXrpcQuery, req: express.Request, opts: Options, 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;
+export declare function processBodyAsBytes(req: express.Request): Promise<Uint8Array>;

package/jest.config.js

@@ -0,0 +1,6 @@
+const base = require('../../jest.config.base.js')
+
+module.exports = {
+  ...base,
+  displayName: 'XRPC Server',
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@atproto/xrpc-server",
+  "version": "0.0.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",
+  "dependencies": {
+    "@atproto/common": "*",
+    "@atproto/lexicon": "*",
+    "express": "^4.17.2",
+    "http-errors": "^2.0.0",
+    "mime-types": "^2.1.35",
+    "zod": "^3.14.2"
+  },
+  "devDependencies": {
+    "@atproto/crypto": "*",
+    "@atproto/xrpc": "*",
+    "@types/express": "^4.17.13",
+    "@types/http-errors": "^2.0.1"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './types'
+export * from './server'

package/src/logger.ts

@@ -0,0 +1,5 @@
+import { subsystemLogger } from '@atproto/common'
+
+export const logger = subsystemLogger('xrpc-server')
+
+export default logger

package/src/server.ts

@@ -0,0 +1,253 @@
+import { Readable } from 'stream'
+import express, {
+  ErrorRequestHandler,
+  NextFunction,
+  RequestHandler,
+} from 'express'
+import { Lexicons, LexXrpcProcedure, LexXrpcQuery } from '@atproto/lexicon'
+import {
+  XRPCHandler,
+  XRPCError,
+  InvalidRequestError,
+  HandlerOutput,
+  HandlerSuccess,
+  handlerSuccess,
+  XRPCHandlerConfig,
+  MethodNotImplementedError,
+  HandlerAuth,
+  AuthVerifier,
+  isHandlerError,
+  Options,
+} from './types'
+import { decodeQueryParams, validateInput, validateOutput } from './util'
+import log from './logger'
+
+export function createServer(lexicons?: unknown[], options?: Options) {
+  return new Server(lexicons, options)
+}
+
+export class Server {
+  router = express.Router()
+  routes = express.Router()
+  lex = new Lexicons()
+  options: Options
+  middleware: Record<'json' | 'text', RequestHandler>
+
+  constructor(lexicons?: unknown[], opts?: Options) {
+    if (lexicons) {
+      this.addLexicons(lexicons)
+    }
+    this.router.use(this.routes)
+    this.router.use('/xrpc/:methodId', this.catchall.bind(this))
+    this.router.use(errorMiddleware)
+    this.options = opts ?? {}
+    this.middleware = {
+      json: express.json({ limit: opts?.payload?.jsonLimit }),
+      text: express.text({ limit: opts?.payload?.textLimit }),
+    }
+  }
+
+  // handlers
+  // =
+
+  method(nsid: string, configOrFn: XRPCHandlerConfig | XRPCHandler) {
+    this.addMethod(nsid, configOrFn)
+  }
+
+  addMethod(nsid: string, configOrFn: XRPCHandlerConfig | XRPCHandler) {
+    const config =
+      typeof configOrFn === 'function' ? { handler: configOrFn } : configOrFn
+    const def = this.lex.getDef(nsid)
+    if (!def || (def.type !== 'query' && def.type !== 'procedure')) {
+      throw new Error(`Lex def for ${nsid} is not a query or a procedure`)
+    }
+    this.addRoute(nsid, def, config)
+  }
+
+  // schemas
+  // =
+
+  addLexicon(doc: unknown) {
+    this.lex.add(doc)
+  }
+
+  addLexicons(docs: unknown[]) {
+    for (const doc of docs) {
+      this.addLexicon(doc)
+    }
+  }
+
+  // http
+  // =
+
+  protected async addRoute(
+    nsid: string,
+    def: LexXrpcQuery | LexXrpcProcedure,
+    config: XRPCHandlerConfig,
+  ) {
+    const verb: 'post' | 'get' = def.type === 'procedure' ? 'post' : 'get'
+    const middleware: RequestHandler[] = []
+    middleware.push(createLocalsMiddleware(nsid))
+    if (config.auth) {
+      middleware.push(createAuthMiddleware(config.auth))
+    }
+    if (verb === 'post') {
+      middleware.push(this.middleware.json)
+      middleware.push(this.middleware.text)
+    }
+    this.routes[verb](
+      `/xrpc/${nsid}`,
+      ...middleware,
+      this.createHandler(nsid, def, config.handler),
+    )
+  }
+
+  async catchall(
+    req: express.Request,
+    _res: express.Response,
+    next: NextFunction,
+  ) {
+    const def = this.lex.getDef(req.params.methodId)
+    if (!def) {
+      return next(new MethodNotImplementedError())
+    }
+    // validate method
+    if (def.type === 'query' && req.method !== 'GET') {
+      return next(
+        new InvalidRequestError(
+          `Incorrect HTTP method (${req.method}) expected GET`,
+        ),
+      )
+    } else if (def.type === 'procedure' && req.method !== 'POST') {
+      return next(
+        new InvalidRequestError(
+          `Incorrect HTTP method (${req.method}) expected POST`,
+        ),
+      )
+    }
+    return next()
+  }
+
+  createHandler(
+    nsid: string,
+    def: LexXrpcQuery | LexXrpcProcedure,
+    handler: XRPCHandler,
+  ): RequestHandler {
+    const validateReqInput = (req: express.Request) =>
+      validateInput(nsid, def, req, this.options, this.lex)
+    const validateResOutput =
+      this.options.validateResponse === false
+        ? (output?: HandlerSuccess) => output
+        : (output?: HandlerSuccess) =>
+            validateOutput(nsid, def, output, this.lex)
+    const assertValidXrpcParams = (params: unknown) =>
+      this.lex.assertValidXrpcParams(nsid, params)
+    return async function (req, res, next) {
+      try {
+        // validate request
+        const params = decodeQueryParams(def, req.query)
+        try {
+          assertValidXrpcParams(params)
+        } catch (e) {
+          throw new InvalidRequestError(String(e))
+        }
+        const input = validateReqInput(req)
+
+        if (input?.body instanceof Readable) {
+          // If the body stream errors at any time, abort the request
+          input.body.once('error', next)
+        }
+
+        const locals: RequestLocals = req[kRequestLocals]
+
+        // run the handler
+        const outputUnvalidated = await handler({
+          params,
+          input,
+          auth: locals.auth,
+          req,
+          res,
+        })
+
+        if (isHandlerError(outputUnvalidated)) {
+          throw XRPCError.fromError(outputUnvalidated)
+        }
+
+        if (!outputUnvalidated || isHandlerSuccess(outputUnvalidated)) {
+          // validate response
+          const output = validateResOutput(outputUnvalidated)
+          // send response
+          if (
+            output?.encoding === 'application/json' ||
+            output?.encoding === 'json'
+          ) {
+            res.status(200).json(output.body)
+          } else if (output) {
+            res.header('Content-Type', output.encoding)
+            res
+              .status(200)
+              .send(
+                output.body instanceof Uint8Array
+                  ? Buffer.from(output.body)
+                  : output.body,
+              )
+          } else {
+            res.status(200).end()
+          }
+        }
+      } catch (err: unknown) {
+        next(err)
+      }
+    }
+  }
+}
+
+function isHandlerSuccess(v: HandlerOutput): v is HandlerSuccess {
+  return handlerSuccess.safeParse(v).success
+}
+
+const kRequestLocals = Symbol('requestLocals')
+
+function createLocalsMiddleware(nsid: string): RequestHandler {
+  return function (req, _res, next) {
+    const locals: RequestLocals = { auth: undefined, nsid }
+    req[kRequestLocals] = locals
+    return next()
+  }
+}
+
+type RequestLocals = {
+  auth: HandlerAuth | undefined
+  nsid: string
+}
+
+function createAuthMiddleware(verifier: AuthVerifier): RequestHandler {
+  return async function (req, res, next) {
+    try {
+      const result = await verifier({ req, res })
+      if (isHandlerError(result)) {
+        throw XRPCError.fromError(result)
+      }
+      const locals: RequestLocals = req[kRequestLocals]
+      locals.auth = result
+      next()
+    } catch (err: unknown) {
+      next(err)
+    }
+  }
+}
+
+const errorMiddleware: ErrorRequestHandler = function (err, req, res, next) {
+  const locals: RequestLocals | undefined = req[kRequestLocals]
+  const methodSuffix = locals ? ` method ${locals.nsid}` : ''
+  if (err instanceof XRPCError) {
+    log.error(err, `error in xrpc${methodSuffix}`)
+  } else {
+    log.error(err, `unhandled exception in xrpc${methodSuffix}`)
+  }
+  if (res.headersSent) {
+    return next(err)
+  }
+  const xrpcError = XRPCError.fromError(err)
+  return res.status(xrpcError.type).json(xrpcError.payload)
+}

package/src/types.ts

@@ -0,0 +1,159 @@
+import express from 'express'
+import { isHttpError } from 'http-errors'
+import zod from 'zod'
+import { ResponseType, ResponseTypeStrings } from '@atproto/xrpc'
+
+export type Options = {
+  validateResponse?: boolean
+  payload?: {
+    jsonLimit?: number
+    blobLimit?: number
+    textLimit?: number
+  }
+}
+
+export type UndecodedParams = typeof express.request['query']
+
+export type Primitive = string | number | boolean
+export type Params = Record<string, Primitive | Primitive[] | undefined>
+
+export const handlerInput = zod.object({
+  encoding: zod.string(),
+  body: zod.any(),
+})
+export type HandlerInput = zod.infer<typeof handlerInput>
+
+export const handlerAuth = zod.object({
+  credentials: zod.any(),
+  artifacts: zod.any(),
+})
+export type HandlerAuth = zod.infer<typeof handlerAuth>
+
+export const handlerSuccess = zod.object({
+  encoding: zod.string(),
+  body: zod.any(),
+})
+export type HandlerSuccess = zod.infer<typeof handlerSuccess>
+
+export const handlerError = zod.object({
+  status: zod.number(),
+  error: zod.string().optional(),
+  message: zod.string().optional(),
+})
+export type HandlerError = zod.infer<typeof handlerError>
+
+export type HandlerOutput = HandlerSuccess | HandlerError
+
+export type XRPCHandler = (ctx: {
+  auth: HandlerAuth | undefined
+  params: Params
+  input: HandlerInput | undefined
+  req: express.Request
+  res: express.Response
+}) => Promise<HandlerOutput> | HandlerOutput | undefined
+
+export type AuthOutput = HandlerAuth | HandlerError
+
+export type AuthVerifier = (ctx: {
+  req: express.Request
+  res: express.Response
+}) => Promise<AuthOutput> | AuthOutput
+
+export type XRPCHandlerConfig = {
+  auth?: AuthVerifier
+  handler: XRPCHandler
+}
+
+export class XRPCError extends Error {
+  constructor(
+    public type: ResponseType,
+    public errorMessage?: string,
+    public customErrorName?: string,
+  ) {
+    super(errorMessage)
+  }
+
+  get payload() {
+    return {
+      error: this.customErrorName,
+      message:
+        this.type === ResponseType.InternalServerError
+          ? this.typeStr // Do not respond with error details for 500s
+          : this.errorMessage || this.typeStr,
+    }
+  }
+
+  get typeStr(): string | undefined {
+    return ResponseTypeStrings[this.type]
+  }
+
+  static fromError(error: unknown) {
+    if (error instanceof XRPCError) {
+      return error
+    }
+    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')
+    }
+    resultErr.cause = error
+    return resultErr
+  }
+}
+
+export function isHandlerError(v: unknown): v is HandlerError {
+  return handlerError.safeParse(v).success
+}
+
+export class InvalidRequestError extends XRPCError {
+  constructor(errorMessage?: string, customErrorName?: string) {
+    super(ResponseType.InvalidRequest, errorMessage, customErrorName)
+  }
+}
+
+export class AuthRequiredError extends XRPCError {
+  constructor(errorMessage?: string, customErrorName?: string) {
+    super(ResponseType.AuthRequired, errorMessage, customErrorName)
+  }
+}
+
+export class ForbiddenError extends XRPCError {
+  constructor(errorMessage?: string, customErrorName?: string) {
+    super(ResponseType.Forbidden, errorMessage, customErrorName)
+  }
+}
+
+export class InternalServerError extends XRPCError {
+  constructor(errorMessage?: string, customErrorName?: string) {
+    super(ResponseType.InternalServerError, errorMessage, customErrorName)
+  }
+}
+
+export class UpstreamFailureError extends XRPCError {
+  constructor(errorMessage?: string, customErrorName?: string) {
+    super(ResponseType.UpstreamFailure, errorMessage, customErrorName)
+  }
+}
+
+export class NotEnoughResoucesError extends XRPCError {
+  constructor(errorMessage?: string, customErrorName?: string) {
+    super(ResponseType.NotEnoughResouces, errorMessage, customErrorName)
+  }
+}
+
+export class UpstreamTimeoutError extends XRPCError {
+  constructor(errorMessage?: string, customErrorName?: string) {
+    super(ResponseType.UpstreamTimeout, errorMessage, customErrorName)
+  }
+}
+
+export class MethodNotImplementedError extends XRPCError {
+  constructor(errorMessage?: string, customErrorName?: string) {
+    super(ResponseType.MethodNotImplemented, errorMessage, customErrorName)
+  }
+}