@atproto/xrpc-server 0.11.5 → 0.11.6

package/src/stream/frames.ts

@@ -1,125 +0,0 @@
-import { decodeAll, encode } from '@atproto/lex-cbor'
-import { LexValue, isPlainObject } from '@atproto/lex-data'
-import { XRPCError } from '../errors.js'
-import {
-  ErrorFrameBody,
-  ErrorFrameHeader,
-  FrameHeader,
-  FrameType,
-  MessageFrameHeader,
-  errorFrameBody,
-  frameHeader,
-} from './types.js'
-
-export abstract class Frame<T extends LexValue = LexValue> {
-  abstract header: FrameHeader
-  abstract body: T
-
-  get op(): FrameType {
-    return this.header.op
-  }
-  toBytes(): Uint8Array {
-    return Buffer.concat([encode(this.header), encode(this.body)])
-  }
-  isMessage(): this is MessageFrame {
-    return this.op === FrameType.Message
-  }
-  isError(): this is ErrorFrame {
-    return this.op === FrameType.Error
-  }
-  static fromBytes(bytes: Uint8Array) {
-    const [header, body, ...rest] = decodeAll(bytes)
-    if (rest.length) {
-      throw new Error('Too many CBOR data items in frame')
-    } else if (body === undefined) {
-      throw new Error('Missing frame body')
-    }
-
-    const parsedHeader = frameHeader.safeParse(header)
-    if (!parsedHeader.success) {
-      throw new Error(`Invalid frame header: ${parsedHeader.reason.message}`)
-    }
-    const frameOp = parsedHeader.value.op
-    if (frameOp === FrameType.Message) {
-      return new MessageFrame(body, {
-        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.reason.message}`,
-        )
-      }
-      return new ErrorFrame(parsedBody.value)
-    } else {
-      const exhaustiveCheck: never = frameOp
-      throw new Error(`Unknown frame op: ${exhaustiveCheck}`)
-    }
-  }
-}
-
-export class MessageFrame<T extends LexValue = LexValue> extends Frame<T> {
-  header: MessageFrameHeader
-  body: T
-
-  constructor(body: T, opts?: { type?: string }) {
-    super()
-    this.header =
-      opts?.type !== undefined
-        ? { op: FrameType.Message, t: opts?.type }
-        : { op: FrameType.Message }
-    this.body = body
-  }
-  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<
-  ErrorFrameBody<T>
-> {
-  header: ErrorFrameHeader
-  body: ErrorFrameBody<T>
-
-  constructor(body: ErrorFrameBody<T>) {
-    super()
-    this.header = { op: FrameType.Error }
-    this.body = body
-  }
-  get code() {
-    return this.body.error
-  }
-  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/index.ts

@@ -1,5 +0,0 @@
-export * from './types.js'
-export * from './frames.js'
-export * from './stream.js'
-export * from './subscription.js'
-export * from './server.js'

package/src/stream/logger.ts

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

package/src/stream/server.ts

@@ -1,66 +0,0 @@
-import { IncomingMessage } from 'node:http'
-import type { ServerOptions } from 'ws'
-import { WebSocket, WebSocketServer } from 'ws'
-import { CloseCode, DisconnectError } from '@atproto/ws-client'
-import { ErrorFrame, Frame } from './frames.js'
-import { logger } from './logger.js'
-
-export class XrpcStreamServer {
-  wss: WebSocketServer
-  constructor(opts: ServerOptions & { handler: Handler }) {
-    const { handler, ...serverOpts } = opts
-    this.wss = new WebSocketServer(serverOpts)
-    this.wss.on('connection', async (socket, req) => {
-      socket.on('error', (err) => logger.error(err, 'websocket error'))
-      try {
-        const ac = new AbortController()
-        const iterator = unwrapIterator(handler(req, ac.signal, socket, this))
-        socket.once('close', () => {
-          iterator.return?.()
-          ac.abort()
-        })
-        const safeFrames = wrapIterator(iterator)
-        for await (const frame of safeFrames) {
-          await new Promise((res, rej) => {
-            socket.send(frame.toBytes(), { binary: true }, (err) => {
-              // @TODO this callback may give more aggressive on backpressure than
-              // we ultimately want, but trying it out for the time being.
-              if (err) return rej(err)
-              res(undefined)
-            })
-          })
-          if (frame instanceof ErrorFrame) {
-            throw new DisconnectError(CloseCode.Policy, frame.body.error)
-          }
-        }
-      } catch (err) {
-        if (err instanceof DisconnectError) {
-          return socket.close(err.wsCode, err.xrpcCode)
-        } else {
-          logger.error({ err }, 'websocket server error')
-          return socket.terminate()
-        }
-      }
-      socket.close(CloseCode.Normal)
-    })
-  }
-}
-
-export type Handler = (
-  req: IncomingMessage,
-  signal: AbortSignal,
-  socket: WebSocket,
-  server: XrpcStreamServer,
-) => AsyncIterable<Frame>
-
-function unwrapIterator<T>(iterable: AsyncIterable<T>): AsyncIterator<T> {
-  return iterable[Symbol.asyncIterator]()
-}
-
-function wrapIterator<T>(iterator: AsyncIterator<T>): AsyncIterable<T> {
-  return {
-    [Symbol.asyncIterator]() {
-      return iterator
-    },
-  }
-}

package/src/stream/stream.ts

@@ -1,39 +0,0 @@
-import { DuplexOptions } from 'node:stream'
-import { WebSocket, createWebSocketStream } from 'ws'
-import { ResponseType, XRPCError } from '@atproto/xrpc'
-import { Frame, MessageFrame } from './frames.js'
-
-export function streamByteChunks(ws: WebSocket, options?: DuplexOptions) {
-  return createWebSocketStream(ws, {
-    ...options,
-    readableObjectMode: true, // Ensures frame bytes don't get buffered/combined together
-  })
-}
-
-export async function* byFrame(ws: WebSocket, options?: DuplexOptions) {
-  const wsStream = streamByteChunks(ws, options)
-  for await (const chunk of wsStream) {
-    yield Frame.fromBytes(chunk)
-  }
-}
-
-export async function* byMessage(ws: WebSocket, options?: DuplexOptions) {
-  const wsStream = streamByteChunks(ws, options)
-  for await (const chunk of wsStream) {
-    const msg = ensureChunkIsMessage(chunk)
-    yield msg
-  }
-}
-
-export function ensureChunkIsMessage(chunk: Uint8Array): MessageFrame {
-  const frame = Frame.fromBytes(chunk)
-  if (frame.isMessage()) {
-    return frame
-  } else if (frame.isError()) {
-    // @TODO work -1 error code into XRPCError
-    // @ts-ignore
-    throw new XRPCError(-1, frame.code, frame.message)
-  } else {
-    throw new XRPCError(ResponseType.Unknown, undefined, 'Unknown frame type')
-  }
-}

package/src/stream/subscription.ts

@@ -1,96 +0,0 @@
-import type { ClientOptions } from 'ws'
-import { isPlainObject } from '@atproto/lex-data'
-import { WebSocketKeepAlive } from '@atproto/ws-client'
-import { ensureChunkIsMessage } from './stream.js'
-
-export class Subscription<T = unknown> {
-  constructor(
-    public opts: ClientOptions & {
-      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
-    },
-  ) {}
-
-  async *[Symbol.asyncIterator](): AsyncGenerator<T> {
-    const ws = new WebSocketKeepAlive({
-      ...this.opts,
-      getUrl: async () => {
-        const params = (await this.opts.getParams?.()) ?? {}
-        const query = encodeQueryParams(params)
-        return `${this.opts.service}/xrpc/${this.opts.method}?${query}`
-      },
-    })
-    for await (const chunk of ws) {
-      const message = ensureChunkIsMessage(chunk)
-      const t = message.header.t
-
-      const typedBody = isPlainObject(message.body)
-        ? t !== undefined
-          ? {
-              ...message.body,
-              $type: t.startsWith('#') ? this.opts.method + t : t,
-            }
-          : message.body
-        : undefined
-
-      const result = this.opts.validate(typedBody)
-      if (result !== undefined) {
-        yield result
-      }
-    }
-  }
-}
-
-export default Subscription
-
-function encodeQueryParams(obj: Record<string, unknown>): string {
-  const params = new URLSearchParams()
-  Object.entries(obj).forEach(([key, value]) => {
-    const encoded = encodeQueryParam(value)
-    if (Array.isArray(encoded)) {
-      encoded.forEach((enc) => params.append(key, enc))
-    } else {
-      params.set(key, encoded)
-    }
-  })
-  return params.toString()
-}
-
-// Adapted from xrpc, but without any lex-specific knowledge
-function encodeQueryParam(value: unknown): string | string[] {
-  if (typeof value === 'string') {
-    return value
-  }
-  if (typeof value === 'number') {
-    return value.toString()
-  }
-  if (typeof value === 'boolean') {
-    return value ? 'true' : 'false'
-  }
-  if (typeof value === 'undefined') {
-    return ''
-  }
-  if (typeof value === 'object') {
-    if (value instanceof Date) {
-      return value.toISOString()
-    } else if (Array.isArray(value)) {
-      return value.flatMap(encodeQueryParam)
-    } else if (!value) {
-      return ''
-    }
-  }
-  throw new Error(`Cannot encode ${typeof value}s into query params`)
-}

package/src/stream/types.ts

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

package/src/types.ts

@@ -1,330 +0,0 @@
-import { IncomingMessage } from 'node:http'
-import { Readable } from 'node:stream'
-import { NextFunction, Request, Response } from 'express'
-import { l } from '@atproto/lex-schema'
-import { ErrorResult, XRPCError } from './errors.js'
-import { CalcKeyFn, CalcPointsFn, RateLimiterI } from './rate-limiter.js'
-
-export type Awaitable<T> = T | Promise<T>
-
-export type CatchallHandler = (
-  req: Request,
-  res: Response,
-  next: NextFunction,
-) => unknown
-
-export type Options = {
-  validateResponse?: boolean
-  catchall?: CatchallHandler
-  payload?: RouteOptions
-  rateLimits?: {
-    creator: RateLimiterCreator<HandlerContext>
-    global?: ServerRateLimitDescription<HandlerContext>[]
-    shared?: ServerRateLimitDescription<HandlerContext>[]
-    bypass?: (ctx: HandlerContext) => boolean
-  }
-  /**
-   * By default, errors are converted to {@link XRPCError} using
-   * {@link XRPCError.fromError} before being rendered. If method handlers throw
-   * error objects that are not properly rendered in the HTTP response, this
-   * function can be used to properly convert them to {@link XRPCError}. The
-   * provided function will typically fallback to the default error conversion
-   * (`return XRPCError.fromError(err)`) if the error is not recognized.
-   *
-   * @note This function should not throw errors.
-   */
-  errorParser?: (err: unknown) => XRPCError
-}
-
-export type UndecodedParams = Request['query']
-
-export type Primitive = string | number | boolean
-export type Params = { [P in string]?: undefined | Primitive | Primitive[] }
-
-export type HandlerInput = {
-  encoding: string
-  body: unknown
-}
-
-export type AuthResult = {
-  credentials: unknown
-  artifacts?: unknown
-}
-
-export const headersSchema = l.dict(l.string(), l.string())
-
-export type Headers = l.Infer<typeof headersSchema>
-
-export const handlerSuccess = l.object({
-  encoding: l.string(),
-  body: l.unknown(),
-  headers: l.optional(headersSchema),
-})
-
-export type HandlerSuccess = l.Infer<typeof handlerSuccess>
-
-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 = l.Infer<typeof handlerPipeThroughBuffer>
-
-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 = l.Infer<typeof handlerPipeThroughStream>
-
-export const handlerPipeThrough = l.union([
-  handlerPipeThroughBuffer,
-  handlerPipeThroughStream,
-])
-
-export type HandlerPipeThrough = l.Infer<typeof handlerPipeThrough>
-
-export type Auth = void | AuthResult
-export type Input = void | HandlerInput
-export type Output = void | HandlerSuccess | HandlerPipeThrough | ErrorResult
-
-export type AuthVerifier<C, A extends AuthResult = AuthResult> =
-  | ((ctx: C) => Awaitable<A | ErrorResult>)
-  | ((ctx: C) => Awaitable<A>)
-
-export type MethodAuthContext<P extends Params = Params> = {
-  params: P
-  req: Request
-  res: Response
-}
-
-export type MethodAuthVerifier<
-  A extends AuthResult = AuthResult,
-  P extends Params = Params,
-> = AuthVerifier<MethodAuthContext<P>, A>
-
-export type HandlerContext<
-  A extends Auth = Auth,
-  P extends Params = Params,
-  I extends Input = Input,
-> = MethodAuthContext<P> & {
-  auth: A
-  input: I
-  resetRouteRateLimits: () => Promise<void>
-}
-
-export type MethodHandler<
-  A extends Auth = Auth,
-  P extends Params = Params,
-  I extends Input = Input,
-  O extends Output = Output,
-> = (ctx: HandlerContext<A, P, I>) => Awaitable<O | HandlerPipeThrough>
-
-export type RateLimiterCreator<T extends HandlerContext = HandlerContext> = <
-  C extends T = T,
->(opts: {
-  keyPrefix: string
-  durationMs: number
-  points: number
-  calcKey: CalcKeyFn<C>
-  calcPoints: CalcPointsFn<C>
-  failClosed?: boolean
-}) => RateLimiterI<C>
-
-export type ServerRateLimitDescription<
-  C extends HandlerContext = HandlerContext,
-> = {
-  name: string
-  durationMs: number
-  points: number
-  calcKey?: CalcKeyFn<C>
-  calcPoints?: CalcPointsFn<C>
-  failClosed?: boolean
-}
-
-export type SharedRateLimitOpts<C extends HandlerContext = HandlerContext> = {
-  name: string
-  calcKey?: CalcKeyFn<C>
-  calcPoints?: CalcPointsFn<C>
-}
-
-export type RouteRateLimitOpts<C extends HandlerContext = HandlerContext> = {
-  durationMs: number
-  points: number
-  calcKey?: CalcKeyFn<C>
-  calcPoints?: CalcPointsFn<C>
-}
-
-export type RateLimitOpts<C extends HandlerContext = HandlerContext> =
-  | SharedRateLimitOpts<C>
-  | RouteRateLimitOpts<C>
-
-export function isSharedRateLimitOpts<
-  C extends HandlerContext = HandlerContext,
->(opts: RateLimitOpts<C>): opts is SharedRateLimitOpts<C> {
-  return typeof opts['name'] === 'string'
-}
-
-export type RouteOptions = {
-  blobLimit?: number
-  jsonLimit?: number
-  textLimit?: number
-  paramsParseLoose?: boolean
-}
-
-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,
-  I extends Input = Input,
-  O extends Output = Output,
-> = {
-  handler: MethodHandler<A, P, I, O>
-  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?: MethodRateLimit<A, P, I>
-}
-
-export type MethodConfigOrHandler<
-  A extends Auth = Auth,
-  P extends Params = Params,
-  I extends Input = Input,
-  O extends Output = Output,
-> = MethodHandler<A, P, I, O> | MethodConfig<A, P, I, O>
-
-export type StreamAuthContext<P extends Params = Params> = {
-  params: P
-  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,
-> = AuthVerifier<StreamAuthContext<P>, A>
-
-export type StreamContext<
-  A extends Auth = Auth,
-  P extends Params = Params,
-> = StreamAuthContext<P> & {
-  auth: A
-  signal: AbortSignal
-}
-
-export type StreamHandler<
-  A extends Auth = Auth,
-  P extends Params = Params,
-  O = unknown,
-> = (ctx: StreamContext<A, P>) => AsyncIterable<O>
-
-export type StreamConfig<
-  A extends Auth = Auth,
-  P extends Params = Params,
-  O = unknown,
-> = {
-  auth?: StreamAuthVerifier<Extract<A, AuthResult>, P>
-  handler: StreamHandler<A, P, O>
-}
-
-export type StreamConfigOrHandler<
-  A extends Auth = Auth,
-  P extends Params = Params,
-  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 {
-  // We only need to discriminate between possible Output values
-  return output != null && 'buffer' in output && output['buffer'] !== undefined
-}
-
-export function isHandlerPipeThroughStream(
-  output: Output,
-): output is HandlerPipeThroughStream {
-  // We only need to discriminate between possible Output values
-  return output != null && 'stream' in output && output['stream'] !== undefined
-}