@atproto/xrpc-server 0.0.1 → 0.1.0

package/dist/server.d.ts

@@ -1,19 +1,25 @@
 import express, { NextFunction, RequestHandler } from 'express';
-import { Lexicons, LexXrpcProcedure, LexXrpcQuery } from '@atproto/lexicon';
-import { XRPCHandler, XRPCHandlerConfig, Options } from './types';
+import { Lexicons, LexXrpcProcedure, LexXrpcQuery, LexXrpcSubscription } from '@atproto/lexicon';
+import { XrpcStreamServer } from './stream';
+import { XRPCHandler, XRPCHandlerConfig, Options, XRPCStreamHandlerConfig, XRPCStreamHandler } from './types';
 export declare function createServer(lexicons?: unknown[], options?: Options): Server;
 export declare class Server {
-    router: import("express-serve-static-core").Router;
+    router: import("express-serve-static-core").Express;
     routes: import("express-serve-static-core").Router;
+    subscriptions: Map<string, XrpcStreamServer>;
     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;
+    streamMethod(nsid: string, configOrFn: XRPCStreamHandlerConfig | XRPCStreamHandler): void;
+    addStreamMethod(nsid: string, configOrFn: XRPCStreamHandlerConfig | XRPCStreamHandler): 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;
+    protected addSubscription(nsid: string, def: LexXrpcSubscription, config: XRPCStreamHandlerConfig): Promise<void>;
+    private enableStreamingOnListen;
 }

package/dist/stream/frames.d.ts

@@ -0,0 +1,25 @@
+import { FrameHeader, FrameType, MessageFrameHeader, ErrorFrameHeader, ErrorFrameBody } from './types';
+export declare abstract class Frame {
+    header: FrameHeader;
+    body: unknown;
+    get op(): FrameType;
+    toBytes(): Uint8Array;
+    isMessage(): this is MessageFrame<unknown>;
+    isError(): this is ErrorFrame;
+    static fromBytes(bytes: Uint8Array): MessageFrame<unknown> | ErrorFrame<string>;
+}
+export declare class MessageFrame<T = Record<string, unknown>> extends Frame {
+    header: MessageFrameHeader;
+    body: T;
+    constructor(body: T, opts?: {
+        type?: string;
+    });
+    get type(): string | undefined;
+}
+export declare class ErrorFrame<T extends string = string> extends Frame {
+    header: ErrorFrameHeader;
+    body: ErrorFrameBody<T>;
+    constructor(body: ErrorFrameBody<T>);
+    get code(): T & string;
+    get message(): string | undefined;
+}

package/dist/stream/index.d.ts

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

package/dist/stream/logger.d.ts

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

package/dist/stream/server.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="node" />
+import { IncomingMessage } from 'http';
+import { WebSocketServer, ServerOptions, WebSocket } from 'ws';
+import { Frame } from './frames';
+export declare class XrpcStreamServer {
+    wss: WebSocketServer;
+    constructor(opts: ServerOptions & {
+        handler: Handler;
+    });
+}
+export declare type Handler = (req: IncomingMessage, socket: WebSocket, server: XrpcStreamServer) => AsyncIterable<Frame>;

package/dist/stream/stream.d.ts

@@ -0,0 +1,5 @@
+/// <reference types="node" />
+import { DuplexOptions } from 'stream';
+import { WebSocket } from 'ws';
+export declare function byFrame(ws: WebSocket, options?: DuplexOptions): AsyncGenerator<import("./frames").MessageFrame<unknown> | import("./frames").ErrorFrame<string>, void, unknown>;
+export declare function byMessage(ws: WebSocket, options?: DuplexOptions): AsyncGenerator<import("./frames").MessageFrame<unknown>, void, unknown>;

package/dist/stream/subscription.d.ts

@@ -0,0 +1,24 @@
+import { ClientOptions } from 'ws';
+export declare class Subscription<T = unknown> {
+    opts: ClientOptions & {
+        service: string;
+        method: string;
+        maxReconnectSeconds?: 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;
+    };
+    constructor(opts: ClientOptions & {
+        service: string;
+        method: string;
+        maxReconnectSeconds?: 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;
+    });
+    [Symbol.asyncIterator](): AsyncGenerator<T>;
+    private getSocket;
+}
+export default Subscription;

package/dist/stream/types.d.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+export declare enum FrameType {
+    Message = 1,
+    Error = -1
+}
+export declare const messageFrameHeader: z.ZodObject<{
+    op: z.ZodLiteral<FrameType.Message>;
+    t: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    t?: string | undefined;
+    op: FrameType.Message;
+}, {
+    t?: string | undefined;
+    op: FrameType.Message;
+}>;
+export declare type MessageFrameHeader = z.infer<typeof messageFrameHeader>;
+export declare const errorFrameHeader: z.ZodObject<{
+    op: z.ZodLiteral<FrameType.Error>;
+}, "strip", z.ZodTypeAny, {
+    op: FrameType.Error;
+}, {
+    op: FrameType.Error;
+}>;
+export declare const errorFrameBody: z.ZodObject<{
+    error: z.ZodString;
+    message: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    message?: string | undefined;
+    error: string;
+}, {
+    message?: string | undefined;
+    error: string;
+}>;
+export declare type ErrorFrameHeader = z.infer<typeof errorFrameHeader>;
+export declare type ErrorFrameBody<T extends string = string> = {
+    error: T;
+} & z.infer<typeof errorFrameBody>;
+export declare const frameHeader: z.ZodUnion<[z.ZodObject<{
+    op: z.ZodLiteral<FrameType.Message>;
+    t: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    t?: string | undefined;
+    op: FrameType.Message;
+}, {
+    t?: string | undefined;
+    op: FrameType.Message;
+}>, z.ZodObject<{
+    op: z.ZodLiteral<FrameType.Error>;
+}, "strip", z.ZodTypeAny, {
+    op: FrameType.Error;
+}, {
+    op: FrameType.Error;
+}>]>;
+export declare type FrameHeader = z.infer<typeof frameHeader>;
+export declare class DisconnectError extends Error {
+    wsCode: CloseCode;
+    xrpcCode?: string | undefined;
+    constructor(wsCode?: CloseCode, xrpcCode?: string | undefined);
+}
+export declare enum CloseCode {
+    Normal = 1000,
+    Abnormal = 1006,
+    Policy = 1008
+}

package/dist/types.d.ts

@@ -1,3 +1,5 @@
+/// <reference types="node" />
+import { IncomingMessage } from 'http';
 import express from 'express';
 import zod from 'zod';
 import { ResponseType } from '@atproto/xrpc';
@@ -67,15 +69,27 @@ export declare type XRPCHandler = (ctx: {
     req: express.Request;
     res: express.Response;
 }) => Promise<HandlerOutput> | HandlerOutput | undefined;
+export declare type XRPCStreamHandler = (ctx: {
+    auth: HandlerAuth | undefined;
+    params: Params;
+    req: IncomingMessage;
+}) => AsyncIterable<unknown>;
 export declare type AuthOutput = HandlerAuth | HandlerError;
 export declare type AuthVerifier = (ctx: {
     req: express.Request;
     res: express.Response;
 }) => Promise<AuthOutput> | AuthOutput;
+export declare type StreamAuthVerifier = (ctx: {
+    req: IncomingMessage;
+}) => Promise<AuthOutput> | AuthOutput;
 export declare type XRPCHandlerConfig = {
     auth?: AuthVerifier;
     handler: XRPCHandler;
 };
+export declare type XRPCStreamHandlerConfig = {
+    auth?: StreamAuthVerifier;
+    handler: XRPCStreamHandler;
+};
 export declare class XRPCError extends Error {
     type: ResponseType;
     errorMessage?: string | undefined;
@@ -85,6 +99,7 @@ export declare class XRPCError extends Error {
         error: string | undefined;
         message: string | undefined;
     };
+    get typeName(): string | undefined;
     get typeStr(): string | undefined;
     static fromError(error: unknown): XRPCError;
 }

package/dist/util.d.ts

@@ -1,8 +1,9 @@
 import express from 'express';
-import { Lexicons, LexXrpcProcedure, LexXrpcQuery } from '@atproto/lexicon';
+import { Lexicons, LexXrpcProcedure, LexXrpcQuery, LexXrpcSubscription } from '@atproto/lexicon';
 import { UndecodedParams, Params, HandlerInput, HandlerSuccess, Options } from './types';
-export declare function decodeQueryParams(def: LexXrpcProcedure | LexXrpcQuery, params: UndecodedParams): Params;
+export declare function decodeQueryParams(def: LexXrpcProcedure | LexXrpcQuery | LexXrpcSubscription, params: UndecodedParams): Params;
 export declare function decodeQueryParam(type: string, value: unknown): string | number | boolean | undefined;
+export declare function getQueryParams(url?: string): Record<string, string | string[]>;
 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/xrpc-server",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "main": "dist/index.js",
   "scripts": {
     "test": "jest",
@@ -21,15 +21,21 @@
   "dependencies": {
     "@atproto/common": "*",
     "@atproto/lexicon": "*",
+    "cbor-x": "^1.5.1",
     "express": "^4.17.2",
     "http-errors": "^2.0.0",
     "mime-types": "^2.1.35",
+    "uint8arrays": "3.0.0",
+    "ws": "^8.12.0",
     "zod": "^3.14.2"
   },
   "devDependencies": {
     "@atproto/crypto": "*",
     "@atproto/xrpc": "*",
     "@types/express": "^4.17.13",
-    "@types/http-errors": "^2.0.1"
+    "@types/http-errors": "^2.0.1",
+    "@types/ws": "^8.5.4",
+    "get-port": "^6.1.2",
+    "multiformats": "^9.6.4"
   }
 }

package/src/index.ts

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

package/src/server.ts

@@ -4,7 +4,15 @@ import express, {
   NextFunction,
   RequestHandler,
 } from 'express'
-import { Lexicons, LexXrpcProcedure, LexXrpcQuery } from '@atproto/lexicon'
+import {
+  Lexicons,
+  lexToJson,
+  LexXrpcProcedure,
+  LexXrpcQuery,
+  LexXrpcSubscription,
+} from '@atproto/lexicon'
+import { check, forwardStreamErrors, schema } from '@atproto/common'
+import { ErrorFrame, Frame, MessageFrame, XrpcStreamServer } from './stream'
 import {
   XRPCHandler,
   XRPCError,
@@ -18,8 +26,16 @@ import {
   AuthVerifier,
   isHandlerError,
   Options,
+  XRPCStreamHandlerConfig,
+  XRPCStreamHandler,
+  Params,
 } from './types'
-import { decodeQueryParams, validateInput, validateOutput } from './util'
+import {
+  decodeQueryParams,
+  getQueryParams,
+  validateInput,
+  validateOutput,
+} from './util'
 import log from './logger'
 
 export function createServer(lexicons?: unknown[], options?: Options) {
@@ -27,8 +43,9 @@ export function createServer(lexicons?: unknown[], options?: Options) {
 }
 
 export class Server {
-  router = express.Router()
+  router = express()
   routes = express.Router()
+  subscriptions = new Map<string, XrpcStreamServer>()
   lex = new Lexicons()
   options: Options
   middleware: Record<'json' | 'text', RequestHandler>
@@ -40,6 +57,9 @@ export class Server {
     this.router.use(this.routes)
     this.router.use('/xrpc/:methodId', this.catchall.bind(this))
     this.router.use(errorMiddleware)
+    this.router.once('mount', (app: express.Application) => {
+      this.enableStreamingOnListen(app)
+    })
     this.options = opts ?? {}
     this.middleware = {
       json: express.json({ limit: opts?.payload?.jsonLimit }),
@@ -58,10 +78,32 @@ export class Server {
     const config =
       typeof configOrFn === 'function' ? { handler: configOrFn } : configOrFn
     const def = this.lex.getDef(nsid)
-    if (!def || (def.type !== 'query' && def.type !== 'procedure')) {
+    if (def?.type === 'query' || def?.type === 'procedure') {
+      this.addRoute(nsid, def, config)
+    } else {
       throw new Error(`Lex def for ${nsid} is not a query or a procedure`)
     }
-    this.addRoute(nsid, def, config)
+  }
+
+  streamMethod(
+    nsid: string,
+    configOrFn: XRPCStreamHandlerConfig | XRPCStreamHandler,
+  ) {
+    this.addStreamMethod(nsid, configOrFn)
+  }
+
+  addStreamMethod(
+    nsid: string,
+    configOrFn: XRPCStreamHandlerConfig | XRPCStreamHandler,
+  ) {
+    const config =
+      typeof configOrFn === 'function' ? { handler: configOrFn } : configOrFn
+    const def = this.lex.getDef(nsid)
+    if (def?.type === 'subscription') {
+      this.addSubscription(nsid, def, config)
+    } else {
+      throw new Error(`Lex def for ${nsid} is not a subscription`)
+    }
   }
 
   // schemas
@@ -145,9 +187,9 @@ export class Server {
     return async function (req, res, next) {
       try {
         // validate request
-        const params = decodeQueryParams(def, req.query)
+        let params = decodeQueryParams(def, req.query)
         try {
-          assertValidXrpcParams(params)
+          params = assertValidXrpcParams(params) as Params
         } catch (e) {
           throw new InvalidRequestError(String(e))
         }
@@ -181,10 +223,16 @@ export class Server {
             output?.encoding === 'application/json' ||
             output?.encoding === 'json'
           ) {
-            res.status(200).json(output.body)
-          } else if (output) {
+            const json = lexToJson(output.body)
+            res.status(200).json(json)
+          } else if (output?.body instanceof Readable) {
             res.header('Content-Type', output.encoding)
+            res.status(200)
+            forwardStreamErrors(output.body, res)
+            output.body.pipe(res)
+          } else if (output) {
             res
+              .header('Content-Type', output.encoding)
               .status(200)
               .send(
                 output.body instanceof Uint8Array
@@ -200,6 +248,88 @@ export class Server {
       }
     }
   }
+
+  protected async addSubscription(
+    nsid: string,
+    def: LexXrpcSubscription,
+    config: XRPCStreamHandlerConfig,
+  ) {
+    const assertValidXrpcParams = (params: unknown) =>
+      this.lex.assertValidXrpcParams(nsid, params)
+    this.subscriptions.set(
+      nsid,
+      new XrpcStreamServer({
+        noServer: true,
+        handler: async function* (req) {
+          try {
+            // authenticate request
+            const auth = await config.auth?.({ req })
+            if (isHandlerError(auth)) {
+              throw XRPCError.fromError(auth)
+            }
+            // validate request
+            let params = decodeQueryParams(def, getQueryParams(req.url))
+            try {
+              params = assertValidXrpcParams(params) as Params
+            } catch (e) {
+              throw new InvalidRequestError(String(e))
+            }
+            // stream
+            const items = config.handler({ req, params, auth })
+            for await (const item of items) {
+              if (item instanceof Frame) {
+                yield item
+                continue
+              }
+              const type = item?.['$type']
+              if (!check.is(item, schema.map) || typeof type !== 'string') {
+                yield new MessageFrame(item)
+                continue
+              }
+              const split = type.split('#')
+              let t: string
+              if (
+                split.length === 2 &&
+                (split[0] === '' || split[0] === nsid)
+              ) {
+                t = `#${split[1]}`
+              } else {
+                t = type
+              }
+              const clone = { ...item }
+              delete clone['$type']
+              yield new MessageFrame(clone, { type: t })
+            }
+          } catch (err) {
+            const xrpcErrPayload = XRPCError.fromError(err).payload
+            yield new ErrorFrame({
+              error: xrpcErrPayload.error ?? 'Unknown',
+              message: xrpcErrPayload.message,
+            })
+          }
+        },
+      }),
+    )
+  }
+
+  private enableStreamingOnListen(app: express.Application) {
+    const _listen = app.listen
+    app.listen = (...args) => {
+      // @ts-ignore the args spread
+      const httpServer = _listen.call(app, ...args)
+      httpServer.on('upgrade', (req, socket, head) => {
+        const url = new URL(req.url || '', 'http://x')
+        const sub = url.pathname.startsWith('/xrpc/')
+          ? this.subscriptions.get(url.pathname.replace('/xrpc/', ''))
+          : undefined
+        if (!sub) return socket.destroy()
+        sub.wss.handleUpgrade(req, socket, head, (ws) =>
+          sub.wss.emit('connection', ws, req),
+        )
+      })
+      return httpServer
+    }
+  }
 }
 
 function isHandlerSuccess(v: HandlerOutput): v is HandlerSuccess {

package/src/stream/frames.ts

@@ -0,0 +1,95 @@
+import * as uint8arrays from 'uint8arrays'
+import { cborEncode, cborDecodeMulti } from '@atproto/common'
+import {
+  frameHeader,
+  FrameHeader,
+  FrameType,
+  MessageFrameHeader,
+  ErrorFrameHeader,
+  ErrorFrameBody,
+  errorFrameBody,
+} from './types'
+
+export abstract class Frame {
+  header: FrameHeader
+  body: unknown
+  get op(): FrameType {
+    return this.header.op
+  }
+  toBytes(): Uint8Array {
+    return uint8arrays.concat([cborEncode(this.header), cborEncode(this.body)])
+  }
+  isMessage(): this is MessageFrame<unknown> {
+    return this.op === FrameType.Message
+  }
+  isError(): this is ErrorFrame {
+    return this.op === FrameType.Error
+  }
+  static fromBytes(bytes: Uint8Array) {
+    const decoded = cborDecodeMulti(bytes)
+    if (decoded.length > 2) {
+      throw new Error('Too many CBOR data items in frame')
+    }
+    const header = decoded[0]
+    let body: unknown = kUnset
+    if (decoded.length > 1) {
+      body = decoded[1]
+    }
+    const parsedHeader = frameHeader.safeParse(header)
+    if (!parsedHeader.success) {
+      throw new Error(`Invalid frame header: ${parsedHeader.error.message}`)
+    }
+    if (body === kUnset) {
+      throw new Error('Missing frame body')
+    }
+    const frameOp = parsedHeader.data.op
+    if (frameOp === FrameType.Message) {
+      return new MessageFrame(body, {
+        type: parsedHeader.data.t,
+      })
+    } else if (frameOp === FrameType.Error) {
+      const parsedBody = errorFrameBody.safeParse(body)
+      if (!parsedBody.success) {
+        throw new Error(`Invalid error frame body: ${parsedBody.error.message}`)
+      }
+      return new ErrorFrame(parsedBody.data)
+    } else {
+      const exhaustiveCheck: never = frameOp
+      throw new Error(`Unknown frame op: ${exhaustiveCheck}`)
+    }
+  }
+}
+
+export class MessageFrame<T = Record<string, unknown>> extends Frame {
+  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
+  }
+}
+
+export class ErrorFrame<T extends string = string> extends Frame {
+  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
+  }
+}
+
+const kUnset = Symbol('unset')

package/src/stream/index.ts

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

package/src/stream/logger.ts

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

package/src/stream/server.ts

@@ -0,0 +1,60 @@
+import { IncomingMessage } from 'http'
+import { WebSocketServer, ServerOptions, WebSocket } from 'ws'
+import { ErrorFrame, Frame } from './frames'
+import logger from './logger'
+import { CloseCode, DisconnectError } from './types'
+
+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 iterator = unwrapIterator(handler(req, socket, this))
+        socket.once('close', () => iterator.return?.())
+        const safeFrames = wrapIterator(iterator)
+        for await (const frame of safeFrames) {
+          if (frame instanceof ErrorFrame) {
+            await new Promise((res, rej) => {
+              socket.send(frame.toBytes(), { binary: true }, (err) => {
+                if (err) return rej(err)
+                res(undefined)
+              })
+            })
+            throw new DisconnectError(CloseCode.Policy, frame.body.error)
+          } else {
+            socket.send(frame.toBytes(), { binary: true })
+          }
+        }
+      } 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,
+  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

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