@atproto/xrpc-server 0.1.0 → 0.3.0

package/src/stream/server.ts

@@ -12,20 +12,24 @@ export class XrpcStreamServer {
     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 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) {
-          if (frame instanceof ErrorFrame) {
-            await new Promise((res, rej) => {
-              socket.send(frame.toBytes(), { binary: true }, (err) => {
-                if (err) return rej(err)
-                res(undefined)
-              })
+          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)
-          } else {
-            socket.send(frame.toBytes(), { binary: true })
           }
         }
       } catch (err) {
@@ -43,6 +47,7 @@ export class XrpcStreamServer {
 
 export type Handler = (
   req: IncomingMessage,
+  signal: AbortSignal,
   socket: WebSocket,
   server: XrpcStreamServer,
 ) => AsyncIterable<Frame>

package/src/types.ts

@@ -37,6 +37,7 @@ export type HandlerAuth = zod.infer<typeof handlerAuth>
 export const handlerSuccess = zod.object({
   encoding: zod.string(),
   body: zod.any(),
+  headers: zod.record(zod.string()).optional(),
 })
 export type HandlerSuccess = zod.infer<typeof handlerSuccess>
 
@@ -61,6 +62,7 @@ export type XRPCStreamHandler = (ctx: {
   auth: HandlerAuth | undefined
   params: Params
   req: IncomingMessage
+  signal: AbortSignal
 }) => AsyncIterable<unknown>
 
 export type AuthOutput = HandlerAuth | HandlerError

package/src/util.ts

@@ -1,3 +1,4 @@
+import assert from 'assert'
 import { Readable, Transform } from 'stream'
 import { createDeflate, createGunzip } from 'zlib'
 import express from 'express'
@@ -266,3 +267,35 @@ function decodeBodyStream(
 
   return stream
 }
+
+export function serverTimingHeader(timings: ServerTiming[]) {
+  return timings
+    .map((timing) => {
+      let header = timing.name
+      if (timing.duration) header += `;dur=${timing.duration}`
+      if (timing.description) header += `;desc="${timing.description}"`
+      return header
+    })
+    .join(', ')
+}
+
+export class ServerTimer implements ServerTiming {
+  public duration?: number
+  private startMs?: number
+  constructor(public name: string, public description?: string) {}
+  start() {
+    this.startMs = Date.now()
+    return this
+  }
+  stop() {
+    assert(this.startMs, "timer hasn't been started")
+    this.duration = Date.now() - this.startMs
+    return this
+  }
+}
+
+export interface ServerTiming {
+  name: string
+  duration?: number
+  description?: string
+}

package/tests/auth.test.ts

@@ -82,7 +82,7 @@ describe('Auth', () => {
       )
       throw new Error('Didnt throw')
     } catch (e: any) {
-      expect(e instanceof XRPCError).toBeTruthy()
+      expect(e).toBeInstanceOf(XRPCError)
       expect(e.success).toBeFalsy()
       expect(e.error).toBe('AuthenticationRequired')
       expect(e.message).toBe('Authentication Required')
@@ -105,7 +105,7 @@ describe('Auth', () => {
       )
       throw new Error('Didnt throw')
     } catch (e: any) {
-      expect(e instanceof XRPCError).toBeTruthy()
+      expect(e).toBeInstanceOf(XRPCError)
       expect(e.success).toBeFalsy()
       expect(e.error).toBe('InvalidRequest')
       expect(e.message).toBe('Input/present must be true')

package/tests/bodies.test.ts

@@ -23,7 +23,7 @@ const LEXICONS = [
             required: ['foo'],
             properties: {
               foo: { type: 'string' },
-              bar: { type: 'float' },
+              bar: { type: 'integer' },
             },
           },
         },
@@ -34,7 +34,7 @@ const LEXICONS = [
             required: ['foo'],
             properties: {
               foo: { type: 'string' },
-              bar: { type: 'float' },
+              bar: { type: 'integer' },
             },
           },
         },
@@ -43,7 +43,7 @@ const LEXICONS = [
   },
   {
     lexicon: 1,
-    id: 'io.example.validationTest2',
+    id: 'io.example.validationTestTwo',
     defs: {
       main: {
         type: 'query',
@@ -54,7 +54,7 @@ const LEXICONS = [
             required: ['foo'],
             properties: {
               foo: { type: 'string' },
-              bar: { type: 'float' },
+              bar: { type: 'integer' },
             },
           },
         },
@@ -101,7 +101,7 @@ describe('Bodies', () => {
       body: ctx.input?.body,
     }),
   )
-  server.method('io.example.validationTest2', () => ({
+  server.method('io.example.validationTestTwo', () => ({
     encoding: 'json',
     body: { wrong: 'data' },
   }))
@@ -175,7 +175,7 @@ describe('Bodies', () => {
       return logger.error(obj, ...args)
     }
 
-    await expect(client.call('io.example.validationTest2')).rejects.toThrow(
+    await expect(client.call('io.example.validationTestTwo')).rejects.toThrow(
       'Internal Server Error',
     )
     expect(error).toEqual(`Output must have the property "foo"`)

package/tests/errors.test.ts

@@ -26,6 +26,15 @@ const LEXICONS = [
       },
     },
   },
+  {
+    lexicon: 1,
+    id: 'io.example.throwFalsyValue',
+    defs: {
+      main: {
+        type: 'query',
+      },
+    },
+  },
   {
     lexicon: 1,
     id: 'io.example.query',
@@ -107,6 +116,9 @@ describe('Errors', () => {
       return { status: 400 }
     }
   })
+  server.method('io.example.throwFalsyValue', () => {
+    throw ''
+  })
   server.method('io.example.query', () => {
     return undefined
   })
@@ -140,7 +152,7 @@ describe('Errors', () => {
       })
       throw new Error('Didnt throw')
     } catch (e) {
-      expect(e instanceof XRPCError).toBeTruthy()
+      expect(e).toBeInstanceOf(XRPCError)
       expect((e as XRPCError).success).toBeFalsy()
       expect((e as XRPCError).error).toBe('Foo')
       expect((e as XRPCError).message).toBe('It was this one!')
@@ -151,18 +163,27 @@ describe('Errors', () => {
       })
       throw new Error('Didnt throw')
     } catch (e) {
-      expect(e instanceof XRPCError).toBeTruthy()
+      expect(e).toBeInstanceOf(XRPCError)
       expect((e as XRPCError).success).toBeFalsy()
       expect((e as XRPCError).error).toBe('Bar')
       expect((e as XRPCError).message).toBe('It was that one!')
     }
+    try {
+      await client.call('io.example.throwFalsyValue')
+      throw new Error('Didnt throw')
+    } catch (e) {
+      expect(e instanceof XRPCError).toBeTruthy()
+      expect((e as XRPCError).success).toBeFalsy()
+      expect((e as XRPCError).error).toBe('InternalServerError')
+      expect((e as XRPCError).message).toBe('Internal Server Error')
+    }
     try {
       await client.call('io.example.error', {
         which: 'other',
       })
       throw new Error('Didnt throw')
     } catch (e) {
-      expect(e instanceof XRPCError).toBeTruthy()
+      expect(e).toBeInstanceOf(XRPCError)
       expect((e as XRPCError).success).toBeFalsy()
       expect((e as XRPCError).error).toBe('InvalidRequest')
       expect((e as XRPCError).message).toBe('Invalid Request')
@@ -171,8 +192,8 @@ describe('Errors', () => {
       await client.call('io.example.invalidResponse')
       throw new Error('Didnt throw')
     } catch (e: any) {
-      expect(e instanceof XRPCError).toBeTruthy()
-      expect(e instanceof XRPCInvalidResponseError).toBeTruthy()
+      expect(e).toBeInstanceOf(XRPCError)
+      expect(e).toBeInstanceOf(XRPCInvalidResponseError)
       expect(e.success).toBeFalsy()
       expect(e.error).toBe('Invalid Response')
       expect(e.message).toBe(
@@ -193,7 +214,7 @@ describe('Errors', () => {
       await badClient.call('io.example.query')
       throw new Error('Didnt throw')
     } catch (e: any) {
-      expect(e instanceof XRPCError).toBeTruthy()
+      expect(e).toBeInstanceOf(XRPCError)
       expect(e.success).toBeFalsy()
       expect(e.error).toBe('InvalidRequest')
       expect(e.message).toBe('Incorrect HTTP method (POST) expected GET')
@@ -202,7 +223,7 @@ describe('Errors', () => {
       await badClient.call('io.example.procedure')
       throw new Error('Didnt throw')
     } catch (e: any) {
-      expect(e instanceof XRPCError).toBeTruthy()
+      expect(e).toBeInstanceOf(XRPCError)
       expect(e.success).toBeFalsy()
       expect(e.error).toBe('InvalidRequest')
       expect(e.message).toBe('Incorrect HTTP method (GET) expected POST')
@@ -211,7 +232,7 @@ describe('Errors', () => {
       await badClient.call('io.example.doesNotExist')
       throw new Error('Didnt throw')
     } catch (e: any) {
-      expect(e instanceof XRPCError).toBeTruthy()
+      expect(e).toBeInstanceOf(XRPCError)
       expect(e.success).toBeFalsy()
       expect(e.error).toBe('MethodNotImplemented')
       expect(e.message).toBe('Method Not Implemented')

package/tests/parameters.test.ts

@@ -13,11 +13,10 @@ const LEXICONS = [
         type: 'query',
         parameters: {
           type: 'params',
-          required: ['str', 'int', 'num', 'bool', 'arr'],
+          required: ['str', 'int', 'bool', 'arr'],
           properties: {
             str: { type: 'string', minLength: 2, maxLength: 10 },
             int: { type: 'integer', minimum: 2, maximum: 10 },
-            num: { type: 'float', minimum: 2, maximum: 10 },
             bool: { type: 'boolean' },
             arr: { type: 'array', items: { type: 'integer' }, maxLength: 2 },
             def: { type: 'integer', default: 0 },
@@ -57,7 +56,6 @@ describe('Parameters', () => {
     const res1 = await client.call('io.example.paramTest', {
       str: 'valid',
       int: 5,
-      num: 5.5,
       bool: true,
       arr: [1, 2],
       def: 5,
@@ -65,7 +63,6 @@ describe('Parameters', () => {
     expect(res1.success).toBeTruthy()
     expect(res1.data.str).toBe('valid')
     expect(res1.data.int).toBe(5)
-    expect(res1.data.num).toBe(5.5)
     expect(res1.data.bool).toBe(true)
     expect(res1.data.arr).toEqual([1, 2])
     expect(res1.data.def).toEqual(5)
@@ -73,14 +70,12 @@ describe('Parameters', () => {
     const res2 = await client.call('io.example.paramTest', {
       str: 10,
       int: '5',
-      num: '5.5',
       bool: 'foo',
       arr: '3',
     })
     expect(res2.success).toBeTruthy()
     expect(res2.data.str).toBe('10')
     expect(res2.data.int).toBe(5)
-    expect(res2.data.num).toBe(5.5)
     expect(res2.data.bool).toBe(true)
     expect(res2.data.arr).toEqual([3])
     expect(res2.data.def).toEqual(0)
@@ -90,7 +85,6 @@ describe('Parameters', () => {
       client.call('io.example.paramTest', {
         str: 'n',
         int: 5,
-        num: 5.5,
         bool: true,
         arr: [1],
       }),
@@ -99,7 +93,6 @@ describe('Parameters', () => {
       client.call('io.example.paramTest', {
         str: 'loooooooooooooong',
         int: 5,
-        num: 5.5,
         bool: true,
         arr: [1],
       }),
@@ -107,7 +100,6 @@ describe('Parameters', () => {
     await expect(
       client.call('io.example.paramTest', {
         int: 5,
-        num: 5.5,
         bool: true,
         arr: [1],
       }),
@@ -117,7 +109,6 @@ describe('Parameters', () => {
       client.call('io.example.paramTest', {
         str: 'valid',
         int: -1,
-        num: 5.5,
         bool: true,
         arr: [1],
       }),
@@ -126,7 +117,6 @@ describe('Parameters', () => {
       client.call('io.example.paramTest', {
         str: 'valid',
         int: 11,
-        num: 5.5,
         bool: true,
         arr: [1],
       }),
@@ -134,7 +124,6 @@ describe('Parameters', () => {
     await expect(
       client.call('io.example.paramTest', {
         str: 'valid',
-        num: 5.5,
         bool: true,
         arr: [1],
       }),
@@ -144,34 +133,6 @@ describe('Parameters', () => {
       client.call('io.example.paramTest', {
         str: 'valid',
         int: 5,
-        num: -5.5,
-        bool: true,
-        arr: [1],
-      }),
-    ).rejects.toThrow('num can not be less than 2')
-    await expect(
-      client.call('io.example.paramTest', {
-        str: 'valid',
-        int: 5,
-        num: 50.5,
-        bool: true,
-        arr: [1],
-      }),
-    ).rejects.toThrow('num can not be greater than 10')
-    await expect(
-      client.call('io.example.paramTest', {
-        str: 'valid',
-        int: 5,
-        bool: true,
-        arr: [1],
-      }),
-    ).rejects.toThrow(`Params must have the property "num"`)
-
-    await expect(
-      client.call('io.example.paramTest', {
-        str: 'valid',
-        int: 5,
-        num: 5.5,
         arr: [1],
       }),
     ).rejects.toThrow(`Params must have the property "bool"`)
@@ -180,7 +141,6 @@ describe('Parameters', () => {
       client.call('io.example.paramTest', {
         str: 'valid',
         int: 5,
-        num: 5.5,
         bool: true,
         arr: [],
       }),
@@ -189,7 +149,6 @@ describe('Parameters', () => {
       client.call('io.example.paramTest', {
         str: 'valid',
         int: 5,
-        num: 5.5,
         bool: true,
         arr: [1, 2, 3],
       }),

package/tests/procedures.test.ts

@@ -8,7 +8,7 @@ import * as xrpcServer from '../src'
 const LEXICONS = [
   {
     lexicon: 1,
-    id: 'io.example.ping1',
+    id: 'io.example.pingOne',
     defs: {
       main: {
         type: 'procedure',
@@ -26,7 +26,7 @@ const LEXICONS = [
   },
   {
     lexicon: 1,
-    id: 'io.example.ping2',
+    id: 'io.example.pingTwo',
     defs: {
       main: {
         type: 'procedure',
@@ -41,7 +41,7 @@ const LEXICONS = [
   },
   {
     lexicon: 1,
-    id: 'io.example.ping3',
+    id: 'io.example.pingThree',
     defs: {
       main: {
         type: 'procedure',
@@ -56,7 +56,7 @@ const LEXICONS = [
   },
   {
     lexicon: 1,
-    id: 'io.example.ping4',
+    id: 'io.example.pingFour',
     defs: {
       main: {
         type: 'procedure',
@@ -84,17 +84,17 @@ const LEXICONS = [
 describe('Procedures', () => {
   let s: http.Server
   const server = xrpcServer.createServer(LEXICONS)
-  server.method('io.example.ping1', (ctx: { params: xrpcServer.Params }) => {
+  server.method('io.example.pingOne', (ctx: { params: xrpcServer.Params }) => {
     return { encoding: 'text/plain', body: ctx.params.message }
   })
   server.method(
-    'io.example.ping2',
+    'io.example.pingTwo',
     (ctx: { params: xrpcServer.Params; input?: xrpcServer.HandlerInput }) => {
       return { encoding: 'text/plain', body: ctx.input?.body }
     },
   )
   server.method(
-    'io.example.ping3',
+    'io.example.pingThree',
     async (ctx: {
       params: xrpcServer.Params
       input?: xrpcServer.HandlerInput
@@ -112,7 +112,7 @@ describe('Procedures', () => {
     },
   )
   server.method(
-    'io.example.ping4',
+    'io.example.pingFour',
     (ctx: { params: xrpcServer.Params; input?: xrpcServer.HandlerInput }) => {
       return {
         encoding: 'application/json',
@@ -133,14 +133,14 @@ describe('Procedures', () => {
   })
 
   it('serves requests', async () => {
-    const res1 = await client.call('io.example.ping1', {
+    const res1 = await client.call('io.example.pingOne', {
       message: 'hello world',
     })
     expect(res1.success).toBeTruthy()
     expect(res1.headers['content-type']).toBe('text/plain; charset=utf-8')
     expect(res1.data).toBe('hello world')
 
-    const res2 = await client.call('io.example.ping2', {}, 'hello world', {
+    const res2 = await client.call('io.example.pingTwo', {}, 'hello world', {
       encoding: 'text/plain',
     })
     expect(res2.success).toBeTruthy()
@@ -148,7 +148,7 @@ describe('Procedures', () => {
     expect(res2.data).toBe('hello world')
 
     const res3 = await client.call(
-      'io.example.ping3',
+      'io.example.pingThree',
       {},
       new TextEncoder().encode('hello world'),
       { encoding: 'application/octet-stream' },
@@ -158,7 +158,7 @@ describe('Procedures', () => {
     expect(new TextDecoder().decode(res3.data)).toBe('hello world')
 
     const res4 = await client.call(
-      'io.example.ping4',
+      'io.example.pingFour',
       {},
       { message: 'hello world' },
     )

package/tests/queries.test.ts

@@ -7,7 +7,7 @@ import * as xrpcServer from '../src'
 const LEXICONS = [
   {
     lexicon: 1,
-    id: 'io.example.ping1',
+    id: 'io.example.pingOne',
     defs: {
       main: {
         type: 'query',
@@ -25,7 +25,7 @@ const LEXICONS = [
   },
   {
     lexicon: 1,
-    id: 'io.example.ping2',
+    id: 'io.example.pingTwo',
     defs: {
       main: {
         type: 'query',
@@ -43,7 +43,7 @@ const LEXICONS = [
   },
   {
     lexicon: 1,
-    id: 'io.example.ping3',
+    id: 'io.example.pingThree',
     defs: {
       main: {
         type: 'query',
@@ -69,21 +69,25 @@ const LEXICONS = [
 describe('Queries', () => {
   let s: http.Server
   const server = xrpcServer.createServer(LEXICONS)
-  server.method('io.example.ping1', (ctx: { params: xrpcServer.Params }) => {
+  server.method('io.example.pingOne', (ctx: { params: xrpcServer.Params }) => {
     return { encoding: 'text/plain', body: ctx.params.message }
   })
-  server.method('io.example.ping2', (ctx: { params: xrpcServer.Params }) => {
+  server.method('io.example.pingTwo', (ctx: { params: xrpcServer.Params }) => {
     return {
       encoding: 'application/octet-stream',
       body: new TextEncoder().encode(String(ctx.params.message)),
     }
   })
-  server.method('io.example.ping3', (ctx: { params: xrpcServer.Params }) => {
-    return {
-      encoding: 'application/json',
-      body: { message: ctx.params.message },
-    }
-  })
+  server.method(
+    'io.example.pingThree',
+    (ctx: { params: xrpcServer.Params }) => {
+      return {
+        encoding: 'application/json',
+        body: { message: ctx.params.message },
+        headers: { 'x-test-header-name': 'test-value' },
+      }
+    },
+  )
   xrpc.addLexicons(LEXICONS)
 
   let client: ServiceClient
@@ -97,25 +101,26 @@ describe('Queries', () => {
   })
 
   it('serves requests', async () => {
-    const res1 = await client.call('io.example.ping1', {
+    const res1 = await client.call('io.example.pingOne', {
       message: 'hello world',
     })
     expect(res1.success).toBeTruthy()
     expect(res1.headers['content-type']).toBe('text/plain; charset=utf-8')
     expect(res1.data).toBe('hello world')
 
-    const res2 = await client.call('io.example.ping2', {
+    const res2 = await client.call('io.example.pingTwo', {
       message: 'hello world',
     })
     expect(res2.success).toBeTruthy()
     expect(res2.headers['content-type']).toBe('application/octet-stream')
     expect(new TextDecoder().decode(res2.data)).toBe('hello world')
 
-    const res3 = await client.call('io.example.ping3', {
+    const res3 = await client.call('io.example.pingThree', {
       message: 'hello world',
     })
     expect(res3.success).toBeTruthy()
     expect(res3.headers['content-type']).toBe('application/json; charset=utf-8')
     expect(res3.data?.message).toBe('hello world')
+    expect(res3.headers['x-test-header-name']).toEqual('test-value')
   })
 })

package/tests/responses.test.ts

@@ -0,0 +1,77 @@
+import * as http from 'http'
+import getPort from 'get-port'
+import xrpc, { ServiceClient } from '@atproto/xrpc'
+import { byteIterableToStream } from '@atproto/common'
+import { createServer, closeServer } from './_util'
+import * as xrpcServer from '../src'
+
+const LEXICONS = [
+  {
+    lexicon: 1,
+    id: 'io.example.readableStream',
+    defs: {
+      main: {
+        type: 'query',
+        parameters: {
+          type: 'params',
+          properties: {
+            shouldErr: { type: 'boolean' },
+          },
+        },
+        output: {
+          encoding: 'application/vnd.ipld.car',
+        },
+      },
+    },
+  },
+]
+
+describe('Responses', () => {
+  let s: http.Server
+  const server = xrpcServer.createServer(LEXICONS)
+  server.method(
+    'io.example.readableStream',
+    async (ctx: { params: xrpcServer.Params }) => {
+      async function* iter(): AsyncIterable<Uint8Array> {
+        for (let i = 0; i < 5; i++) {
+          yield new Uint8Array([i])
+        }
+        if (ctx.params.shouldErr) {
+          throw new Error('error')
+        }
+      }
+      return {
+        encoding: 'application/vnd.ipld.car',
+        body: byteIterableToStream(iter()),
+      }
+    },
+  )
+  xrpc.addLexicons(LEXICONS)
+
+  let client: ServiceClient
+  let url: string
+  beforeAll(async () => {
+    const port = await getPort()
+    s = await createServer(port, server)
+    url = `http://localhost:${port}`
+    client = xrpc.service(url)
+  })
+  afterAll(async () => {
+    await closeServer(s)
+  })
+
+  it('returns readable streams of bytes', async () => {
+    const res = await client.call('io.example.readableStream', {
+      shouldErr: false,
+    })
+    const expected = new Uint8Array([0, 1, 2, 3, 4])
+    expect(res.data).toEqual(expected)
+  })
+
+  it('handles errs on readable streams of bytes', async () => {
+    const attempt = client.call('io.example.readableStream', {
+      shouldErr: true,
+    })
+    await expect(attempt).rejects.toThrow()
+  })
+})