@atproto/xrpc-server 0.2.0 → 0.3.0

package/dist/stream/types.d.ts

@@ -7,11 +7,11 @@ 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;
+    t?: string | undefined;
 }>;
 export declare type MessageFrameHeader = z.infer<typeof messageFrameHeader>;
 export declare const errorFrameHeader: z.ZodObject<{
@@ -25,11 +25,11 @@ 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;
+    message?: string | undefined;
 }>;
 export declare type ErrorFrameHeader = z.infer<typeof errorFrameHeader>;
 export declare type ErrorFrameBody<T extends string = string> = {
@@ -39,11 +39,11 @@ 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;
+    t?: string | undefined;
 }>, z.ZodObject<{
     op: z.ZodLiteral<FrameType.Error>;
 }, "strip", z.ZodTypeAny, {

package/dist/types.d.ts

@@ -18,11 +18,11 @@ export declare const handlerInput: zod.ZodObject<{
     encoding: zod.ZodString;
     body: zod.ZodAny;
 }, "strip", zod.ZodTypeAny, {
-    body?: any;
     encoding: string;
-}, {
     body?: any;
+}, {
     encoding: string;
+    body?: any;
 }>;
 export declare type HandlerInput = zod.infer<typeof handlerInput>;
 export declare const handlerAuth: zod.ZodObject<{
@@ -39,12 +39,15 @@ export declare type HandlerAuth = zod.infer<typeof handlerAuth>;
 export declare const handlerSuccess: zod.ZodObject<{
     encoding: zod.ZodString;
     body: zod.ZodAny;
+    headers: zod.ZodOptional<zod.ZodRecord<zod.ZodString, zod.ZodString>>;
 }, "strip", zod.ZodTypeAny, {
-    body?: any;
     encoding: string;
-}, {
     body?: any;
+    headers?: Record<string, string> | undefined;
+}, {
     encoding: string;
+    body?: any;
+    headers?: Record<string, string> | undefined;
 }>;
 export declare type HandlerSuccess = zod.infer<typeof handlerSuccess>;
 export declare const handlerError: zod.ZodObject<{
@@ -52,13 +55,13 @@ export declare const handlerError: zod.ZodObject<{
     error: zod.ZodOptional<zod.ZodString>;
     message: zod.ZodOptional<zod.ZodString>;
 }, "strip", zod.ZodTypeAny, {
+    status: number;
     error?: string | undefined;
     message?: string | undefined;
-    status: number;
 }, {
+    status: number;
     error?: string | undefined;
     message?: string | undefined;
-    status: number;
 }>;
 export declare type HandlerError = zod.infer<typeof handlerError>;
 export declare type HandlerOutput = HandlerSuccess | HandlerError;

package/dist/util.d.ts

@@ -9,3 +9,18 @@ export declare function validateOutput(nsid: string, def: LexXrpcProcedure | Lex
 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>;
+export declare function serverTimingHeader(timings: ServerTiming[]): string;
+export declare class ServerTimer implements ServerTiming {
+    name: string;
+    description?: string | undefined;
+    duration?: number;
+    private startMs?;
+    constructor(name: string, description?: string | undefined);
+    start(): this;
+    stop(): this;
+}
+export interface ServerTiming {
+    name: string;
+    duration?: number;
+    description?: string;
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@atproto/xrpc-server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "main": "dist/index.js",
   "scripts": {
     "test": "jest",
-    "prettier": "prettier --check src/",
-    "prettier:fix": "prettier --write src/",
+    "prettier": "prettier --check src/ tests/",
+    "prettier:fix": "prettier --write src/ tests/",
     "lint": "eslint . --ext .ts,.tsx",
     "lint:fix": "yarn lint --fix",
     "verify": "run-p prettier lint",
@@ -33,7 +33,7 @@
     "mime-types": "^2.1.35",
     "uint8arrays": "3.0.0",
     "ws": "^8.12.0",
-    "zod": "^3.14.2"
+    "zod": "^3.21.4"
   },
   "devDependencies": {
     "@atproto/crypto": "*",

package/src/auth.ts

@@ -44,7 +44,7 @@ const jsonToB64Url = (json: Record<string, unknown>): string => {
 
 export const verifyJwt = async (
   jwtStr: string,
-  ownDid: string,
+  ownDid: string | null, // null indicates to skip the audience check
   getSigningKey: (did: string) => Promise<string>,
 ): Promise<string> => {
   const parts = jwtStr.split('.')
@@ -57,7 +57,7 @@ export const verifyJwt = async (
   if (Date.now() / 1000 > payload.exp) {
     throw new AuthRequiredError('jwt expired', 'JwtExpired')
   }
-  if (payload.aud !== ownDid) {
+  if (ownDid !== null && payload.aud !== ownDid) {
     throw new AuthRequiredError(
       'jwt audience does not match service did',
       'BadJwtAudience',

package/src/index.ts

@@ -2,3 +2,6 @@ export * from './types'
 export * from './auth'
 export * from './server'
 export * from './stream'
+
+export type { ServerTiming } from './util'
+export { serverTimingHeader, ServerTimer } from './util'

package/src/server.ts

@@ -219,6 +219,12 @@ export class Server {
         if (!outputUnvalidated || isHandlerSuccess(outputUnvalidated)) {
           // validate response
           const output = validateResOutput(outputUnvalidated)
+          // set headers
+          if (output?.headers) {
+            Object.entries(output.headers).forEach(([name, val]) => {
+              res.header(name, val)
+            })
+          }
           // send response
           if (
             output?.encoding === 'application/json' ||
@@ -229,6 +235,7 @@ export class Server {
           } else if (output?.body instanceof Readable) {
             res.header('Content-Type', output.encoding)
             res.status(200)
+            res.once('error', (err) => res.destroy(err))
             forwardStreamErrors(output.body, res)
             output.body.pipe(res)
           } else if (output) {

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>
 

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/bodies.test.ts

@@ -43,7 +43,7 @@ const LEXICONS = [
   },
   {
     lexicon: 1,
-    id: 'io.example.validationTest2',
+    id: 'io.example.validationTestTwo',
     defs: {
       main: {
         type: 'query',
@@ -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/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()
+  })
+})

package/tests/subscriptions.test.ts

@@ -14,7 +14,7 @@ import * as xrpcServer from '../src'
 const LEXICONS = [
   {
     lexicon: 1,
-    id: 'io.example.stream1',
+    id: 'io.example.streamOne',
     defs: {
       main: {
         type: 'subscription',
@@ -37,7 +37,7 @@ const LEXICONS = [
   },
   {
     lexicon: 1,
-    id: 'io.example.stream2',
+    id: 'io.example.streamTwo',
     defs: {
       main: {
         type: 'subscription',
@@ -84,7 +84,7 @@ describe('Subscriptions', () => {
   const server = xrpcServer.createServer(LEXICONS)
   const lex = server.lex
 
-  server.streamMethod('io.example.stream1', async function* ({ params }) {
+  server.streamMethod('io.example.streamOne', async function* ({ params }) {
     const countdown = Number(params.countdown ?? 0)
     for (let i = countdown; i >= 0; i--) {
       await wait(0)
@@ -92,11 +92,11 @@ describe('Subscriptions', () => {
     }
   })
 
-  server.streamMethod('io.example.stream2', async function* ({ params }) {
+  server.streamMethod('io.example.streamTwo', async function* ({ params }) {
     const countdown = Number(params.countdown ?? 0)
     for (let i = countdown; i >= 0; i--) {
       yield {
-        $type: i % 2 === 0 ? '#even' : 'io.example.stream2#odd',
+        $type: i % 2 === 0 ? '#even' : 'io.example.streamTwo#odd',
         count: i,
       }
     }
@@ -124,7 +124,7 @@ describe('Subscriptions', () => {
 
   it('streams messages', async () => {
     const ws = new WebSocket(
-      `ws://localhost:${port}/xrpc/io.example.stream1?countdown=5`,
+      `ws://localhost:${port}/xrpc/io.example.streamOne?countdown=5`,
     )
 
     const frames: Frame[] = []
@@ -144,7 +144,7 @@ describe('Subscriptions', () => {
 
   it('streams messages in a union', async () => {
     const ws = new WebSocket(
-      `ws://localhost:${port}/xrpc/io.example.stream2?countdown=5`,
+      `ws://localhost:${port}/xrpc/io.example.streamTwo?countdown=5`,
     )
 
     const frames: Frame[] = []
@@ -192,7 +192,7 @@ describe('Subscriptions', () => {
   })
 
   it('errors immediately on bad parameter', async () => {
-    const ws = new WebSocket(`ws://localhost:${port}/xrpc/io.example.stream1`)
+    const ws = new WebSocket(`ws://localhost:${port}/xrpc/io.example.streamOne`)
 
     const frames: Frame[] = []
     for await (const frame of byFrame(ws)) {
@@ -245,11 +245,11 @@ describe('Subscriptions', () => {
     it('receives messages w/ skips', async () => {
       const sub = new Subscription({
         service: `ws://localhost:${port}`,
-        method: 'io.example.stream1',
+        method: 'io.example.streamOne',
         getParams: () => ({ countdown: 5 }),
         validate: (obj) => {
           const result = lex.assertValidXrpcMessage<{ count: number }>(
-            'io.example.stream1',
+            'io.example.streamOne',
             obj,
           )
           if (!result.count || result.count % 2) {
@@ -276,12 +276,12 @@ describe('Subscriptions', () => {
       let reconnects = 0
       const sub = new Subscription({
         service: `ws://localhost:${port}`,
-        method: 'io.example.stream1',
+        method: 'io.example.streamOne',
         onReconnectError: () => reconnects++,
         getParams: () => ({ countdown }),
         validate: (obj) => {
           return lex.assertValidXrpcMessage<{ count: number }>(
-            'io.example.stream1',
+            'io.example.streamOne',
             obj,
           )
         },
@@ -307,12 +307,12 @@ describe('Subscriptions', () => {
       const abortController = new AbortController()
       const sub = new Subscription({
         service: `ws://localhost:${port}`,
-        method: 'io.example.stream1',
+        method: 'io.example.streamOne',
         signal: abortController.signal,
         getParams: () => ({ countdown: 10 }),
         validate: (obj) => {
           const result = lex.assertValidXrpcMessage<{ count: number }>(
-            'io.example.stream1',
+            'io.example.streamOne',
             obj,
           )
           return result