@atproto/xrpc 0.4.3 → 0.5.1-rc.0

package/src/util.ts

@@ -6,12 +6,28 @@ import {
 } from '@atproto/lexicon'
 import {
   CallOptions,
-  Headers,
+  errorResponseBody,
+  ErrorResponseBody,
+  Gettable,
   QueryParams,
   ResponseType,
   XRPCError,
 } from './types'
 
+const ReadableStream =
+  globalThis.ReadableStream ||
+  (class {
+    constructor() {
+      // This anonymous class will never pass any "instanceof" check and cannot
+      // be instantiated.
+      throw new Error('ReadableStream is not supported in this environment')
+    }
+  } as typeof globalThis.ReadableStream)
+
+export function isErrorResponseBody(v: unknown): v is ErrorResponseBody {
+  return errorResponseBody.safeParse(v).success
+}
+
 export function getMethodSchemaHTTPMethod(
   schema: LexXrpcProcedure | LexXrpcQuery,
 ) {
@@ -27,33 +43,43 @@ export function constructMethodCallUri(
   serviceUri: URL,
   params?: QueryParams,
 ): string {
-  const uri = new URL(serviceUri)
-  uri.pathname = `/xrpc/${nsid}`
-
-  // given parameters
-  if (params) {
-    for (const [key, value] of Object.entries(params)) {
-      const paramSchema = schema.parameters?.properties?.[key]
-      if (!paramSchema) {
-        throw new Error(`Invalid query parameter: ${key}`)
-      }
-      if (value !== undefined) {
-        if (paramSchema.type === 'array') {
-          const vals: typeof value[] = []
-          vals.concat(value).forEach((val) => {
-            uri.searchParams.append(
-              key,
-              encodeQueryParam(paramSchema.items.type, val),
-            )
-          })
-        } else {
-          uri.searchParams.set(key, encodeQueryParam(paramSchema.type, value))
+  const uri = new URL(constructMethodCallUrl(nsid, schema, params), serviceUri)
+  return uri.toString()
+}
+
+export function constructMethodCallUrl(
+  nsid: string,
+  schema: LexXrpcProcedure | LexXrpcQuery,
+  params?: QueryParams,
+): string {
+  const pathname = `/xrpc/${encodeURIComponent(nsid)}`
+  if (!params) return pathname
+
+  const searchParams: [string, string][] = []
+
+  for (const [key, value] of Object.entries(params)) {
+    const paramSchema = schema.parameters?.properties?.[key]
+    if (!paramSchema) {
+      throw new Error(`Invalid query parameter: ${key}`)
+    }
+    if (value !== undefined) {
+      if (paramSchema.type === 'array') {
+        const values = Array.isArray(value) ? value : [value]
+        for (const val of values) {
+          searchParams.push([
+            key,
+            encodeQueryParam(paramSchema.items.type, val),
+          ])
         }
+      } else {
+        searchParams.push([key, encodeQueryParam(paramSchema.type, value)])
       }
     }
   }
 
-  return uri.toString()
+  if (!searchParams.length) return pathname
+
+  return `${pathname}?${new URLSearchParams(searchParams).toString()}`
 }
 
 export function encodeQueryParam(
@@ -85,100 +111,274 @@ export function encodeQueryParam(
   throw new Error(`Unsupported query param type: ${type}`)
 }
 
-export function normalizeHeaders(headers: Headers): Headers {
-  const normalized: Headers = {}
-  for (const [header, value] of Object.entries(headers)) {
-    normalized[header.toLowerCase()] = value
-  }
-
-  return normalized
-}
-
 export function constructMethodCallHeaders(
   schema: LexXrpcProcedure | LexXrpcQuery,
-  data?: any,
+  data?: unknown,
   opts?: CallOptions,
 ): Headers {
-  const headers: Headers = opts?.headers || {}
+  // Not using `new Headers(opts?.headers)` to avoid duplicating headers values
+  // due to inconsistent casing in headers name. In case of multiple headers
+  // with the same name (but using a different case), the last one will be used.
+
+  // new Headers({ 'content-type': 'foo', 'Content-Type': 'bar' }).get('content-type')
+  // => 'foo, bar'
+  const headers = new Headers()
+
+  if (opts?.headers) {
+    for (const name in opts.headers) {
+      if (headers.has(name)) {
+        throw new TypeError(`Duplicate header: ${name}`)
+      }
+
+      const value = opts.headers[name]
+      if (value != null) {
+        headers.set(name, value)
+      }
+    }
+  }
+
   if (schema.type === 'procedure') {
     if (opts?.encoding) {
-      headers['Content-Type'] = opts.encoding
-    }
-    if (data && typeof data === 'object') {
-      if (!headers['Content-Type']) {
-        headers['Content-Type'] = 'application/json'
+      headers.set('content-type', opts.encoding)
+    } else if (!headers.has('content-type') && typeof data !== 'undefined') {
+      // Special handling of BodyInit types before falling back to JSON encoding
+      if (
+        data instanceof ArrayBuffer ||
+        data instanceof ReadableStream ||
+        ArrayBuffer.isView(data)
+      ) {
+        headers.set('content-type', 'application/octet-stream')
+      } else if (data instanceof FormData) {
+        // Note: The multipart form data boundary is missing from the header
+        // we set here, making that header invalid. This special case will be
+        // handled in encodeMethodCallBody()
+        headers.set('content-type', 'multipart/form-data')
+      } else if (data instanceof URLSearchParams) {
+        headers.set(
+          'content-type',
+          'application/x-www-form-urlencoded;charset=UTF-8',
+        )
+      } else if (isBlobLike(data)) {
+        headers.set('content-type', data.type || 'application/octet-stream')
+      } else if (typeof data === 'string') {
+        headers.set('content-type', 'text/plain;charset=UTF-8')
+      }
+      // At this point, data is not a valid BodyInit type.
+      else if (isIterable(data)) {
+        headers.set('content-type', 'application/octet-stream')
+      } else if (
+        typeof data === 'boolean' ||
+        typeof data === 'number' ||
+        typeof data === 'string' ||
+        typeof data === 'object' // covers "null"
+      ) {
+        headers.set('content-type', 'application/json')
+      } else {
+        // symbol, function, bigint
+        throw new XRPCError(
+          ResponseType.InvalidRequest,
+          `Unsupported data type: ${typeof data}`,
+        )
       }
     }
   }
   return headers
 }
 
+export function combineHeaders(
+  headersInit: undefined | HeadersInit,
+  defaultHeaders?: Iterable<[string, undefined | Gettable<null | string>]>,
+): undefined | HeadersInit {
+  if (!defaultHeaders) return headersInit
+
+  let headers: Headers | undefined = undefined
+
+  for (const [name, definition] of defaultHeaders) {
+    // Ignore undefined values (allowed for convenience when using
+    // Object.entries).
+    if (definition === undefined) continue
+
+    // Lazy initialization of the headers object
+    headers ??= new Headers(headersInit)
+
+    if (headers.has(name)) continue
+
+    const value = typeof definition === 'function' ? definition() : definition
+
+    if (typeof value === 'string') headers.set(name, value)
+    else if (value === null) headers.delete(name)
+    else throw new TypeError(`Invalid "${name}" header value: ${typeof value}`)
+  }
+
+  return headers ?? headersInit
+}
+
+function isBlobLike(value: unknown): value is Blob {
+  if (value == null) return false
+  if (typeof value !== 'object') return false
+  if (typeof Blob === 'function' && value instanceof Blob) return true
+
+  // Support for Blobs provided by libraries that don't use the native Blob
+  // (e.g. fetch-blob from node-fetch).
+  // https://github.com/node-fetch/fetch-blob/blob/a1a182e5978811407bef4ea1632b517567dda01f/index.js#L233-L244
+
+  const tag = value[Symbol.toStringTag]
+  if (tag === 'Blob' || tag === 'File') {
+    return 'stream' in value && typeof value.stream === 'function'
+  }
+
+  return false
+}
+
+export function isBodyInit(value: unknown): value is BodyInit {
+  switch (typeof value) {
+    case 'string':
+      return true
+    case 'object':
+      return (
+        value instanceof ArrayBuffer ||
+        value instanceof FormData ||
+        value instanceof URLSearchParams ||
+        value instanceof ReadableStream ||
+        ArrayBuffer.isView(value) ||
+        isBlobLike(value)
+      )
+    default:
+      return false
+  }
+}
+
+export function isIterable(
+  value: unknown,
+): value is Iterable<unknown> | AsyncIterable<unknown> {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    (Symbol.iterator in value || Symbol.asyncIterator in value)
+  )
+}
+
 export function encodeMethodCallBody(
   headers: Headers,
-  data?: any,
-): ArrayBuffer | undefined {
-  if (!headers['content-type'] || typeof data === 'undefined') {
+  data?: unknown,
+): BodyInit | undefined {
+  // Silently ignore the body if there is no content-type header.
+  const contentType = headers.get('content-type')
+  if (!contentType) {
     return undefined
   }
-  if (data instanceof ArrayBuffer) {
+
+  if (typeof data === 'undefined') {
+    // This error would be returned by the server, but we can catch it earlier
+    // to avoid un-necessary requests. Note that a content-length of 0 does not
+    // necessary mean that the body is "empty" (e.g. an empty txt file).
+    throw new XRPCError(
+      ResponseType.InvalidRequest,
+      `A request body is expected but none was provided`,
+    )
+  }
+
+  if (isBodyInit(data)) {
+    if (data instanceof FormData && contentType === 'multipart/form-data') {
+      // fetch() will encode FormData payload itself, but it won't override the
+      // content-type header if already present. This would cause the boundary
+      // to be missing from the content-type header, resulting in a 400 error.
+      // Deleting the content-type header here to let fetch() re-create it.
+      headers.delete('content-type')
+    }
+
+    // Will be encoded by the fetch API.
     return data
   }
-  if (headers['content-type'].startsWith('text/')) {
-    return new TextEncoder().encode(data.toString())
+
+  if (isIterable(data)) {
+    // Note that some environments support using Iterable & AsyncIterable as the
+    // body (e.g. Node's fetch), but not all of them do (browsers).
+    return iterableToReadableStream(data)
   }
-  if (headers['content-type'].startsWith('application/json')) {
-    return new TextEncoder().encode(stringifyLex(data))
+
+  if (contentType.startsWith('text/')) {
+    return new TextEncoder().encode(String(data))
+  }
+  if (contentType.startsWith('application/json')) {
+    const json = stringifyLex(data)
+    // Server would return a 400 error if the JSON is invalid (e.g. trying to
+    // JSONify a function, or an object that implements toJSON() poorly).
+    if (json === undefined) {
+      throw new XRPCError(
+        ResponseType.InvalidRequest,
+        `Failed to encode request body as JSON`,
+      )
+    }
+    return new TextEncoder().encode(json)
   }
-  return data
+
+  // At this point, "data" is not a valid BodyInit value, and we don't know how
+  // to encode it into one. Passing it to fetch would result in an error. Let's
+  // throw our own error instead.
+
+  const type =
+    !data || typeof data !== 'object'
+      ? typeof data
+      : data.constructor !== Object &&
+          typeof data.constructor === 'function' &&
+          typeof data.constructor?.name === 'string'
+        ? data.constructor.name
+        : 'object'
+
+  throw new XRPCError(
+    ResponseType.InvalidRequest,
+    `Unable to encode ${type} as ${contentType} data`,
+  )
 }
 
-export function httpResponseCodeToEnum(status: number): ResponseType {
-  let resCode: ResponseType
-  if (status in ResponseType) {
-    resCode = status
-  } else if (status >= 100 && status < 200) {
-    resCode = ResponseType.XRPCNotSupported
-  } else if (status >= 200 && status < 300) {
-    resCode = ResponseType.Success
-  } else if (status >= 300 && status < 400) {
-    resCode = ResponseType.XRPCNotSupported
-  } else if (status >= 400 && status < 500) {
-    resCode = ResponseType.InvalidRequest
-  } else {
-    resCode = ResponseType.InternalServerError
-  }
-  return resCode
+/**
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/from_static}
+ */
+function iterableToReadableStream(
+  iterable: Iterable<unknown> | AsyncIterable<unknown>,
+): ReadableStream<Uint8Array> {
+  // Use the native ReadableStream.from() if available.
+  if ('from' in ReadableStream && typeof ReadableStream.from === 'function') {
+    return ReadableStream.from(iterable)
+  }
+
+  // If you see this error, consider using a polyfill for ReadableStream. For
+  // example, the "web-streams-polyfill" package:
+  // https://github.com/MattiasBuelens/web-streams-polyfill
+
+  throw new TypeError(
+    'ReadableStream.from() is not supported in this environment. ' +
+      'It is required to support using iterables as the request body. ' +
+      'Consider using a polyfill or re-write your code to use a different body type.',
+  )
 }
 
 export function httpResponseBodyParse(
   mimeType: string | null,
   data: ArrayBuffer | undefined,
 ): any {
-  if (mimeType) {
-    if (mimeType.includes('application/json') && data?.byteLength) {
-      try {
+  try {
+    if (mimeType) {
+      if (mimeType.includes('application/json')) {
         const str = new TextDecoder().decode(data)
         return jsonStringToLex(str)
-      } catch (e) {
-        throw new XRPCError(
-          ResponseType.InvalidResponse,
-          `Failed to parse response body: ${String(e)}`,
-        )
       }
-    }
-    if (mimeType.startsWith('text/') && data?.byteLength) {
-      try {
+      if (mimeType.startsWith('text/')) {
         return new TextDecoder().decode(data)
-      } catch (e) {
-        throw new XRPCError(
-          ResponseType.InvalidResponse,
-          `Failed to parse response body: ${String(e)}`,
-        )
       }
     }
+    if (data instanceof ArrayBuffer) {
+      return new Uint8Array(data)
+    }
+    return data
+  } catch (cause) {
+    throw new XRPCError(
+      ResponseType.InvalidResponse,
+      undefined,
+      `Failed to parse response body: ${String(cause)}`,
+      undefined,
+      { cause },
+    )
   }
-  if (data instanceof ArrayBuffer) {
-    return new Uint8Array(data)
-  }
-  return data
 }

package/src/xrpc-client.ts

@@ -0,0 +1,107 @@
+import { LexiconDoc, Lexicons, ValidationError } from '@atproto/lexicon'
+import {
+  FetchHandler,
+  FetchHandlerOptions,
+  buildFetchHandler,
+} from './fetch-handler'
+import {
+  CallOptions,
+  QueryParams,
+  ResponseType,
+  XRPCError,
+  XRPCInvalidResponseError,
+  XRPCResponse,
+  httpResponseCodeToEnum,
+} from './types'
+import {
+  constructMethodCallHeaders,
+  constructMethodCallUrl,
+  encodeMethodCallBody,
+  getMethodSchemaHTTPMethod,
+  httpResponseBodyParse,
+  isErrorResponseBody,
+} from './util'
+
+export class XrpcClient {
+  readonly fetchHandler: FetchHandler
+  readonly lex: Lexicons
+
+  constructor(
+    fetchHandlerOpts: FetchHandler | FetchHandlerOptions,
+    // "Lexicons" is redundant here (because that class implements
+    // "Iterable<LexiconDoc>") but we keep it for explicitness:
+    lex: Lexicons | Iterable<LexiconDoc>,
+  ) {
+    this.fetchHandler = buildFetchHandler(fetchHandlerOpts)
+
+    this.lex = lex instanceof Lexicons ? lex : new Lexicons(lex)
+  }
+
+  async call(
+    methodNsid: string,
+    params?: QueryParams,
+    data?: unknown,
+    opts?: CallOptions,
+  ): Promise<XRPCResponse> {
+    const def = this.lex.getDefOrThrow(methodNsid)
+    if (!def || (def.type !== 'query' && def.type !== 'procedure')) {
+      throw new TypeError(
+        `Invalid lexicon: ${methodNsid}. Must be a query or procedure.`,
+      )
+    }
+
+    // @TODO: should we validate the params and data here?
+    // this.lex.assertValidXrpcParams(methodNsid, params)
+    // if (data !== undefined) {
+    //   this.lex.assertValidXrpcInput(methodNsid, data)
+    // }
+
+    const reqUrl = constructMethodCallUrl(methodNsid, def, params)
+    const reqMethod = getMethodSchemaHTTPMethod(def)
+    const reqHeaders = constructMethodCallHeaders(def, data, opts)
+    const reqBody = encodeMethodCallBody(reqHeaders, data)
+
+    // The duplex field is required for streaming bodies, but not yet reflected
+    // anywhere in docs or types. See whatwg/fetch#1438, nodejs/node#46221.
+    const init: RequestInit & { duplex: 'half' } = {
+      method: reqMethod,
+      headers: reqHeaders,
+      body: reqBody,
+      duplex: 'half',
+      signal: opts?.signal,
+    }
+
+    try {
+      const response = await this.fetchHandler.call(undefined, reqUrl, init)
+
+      const resStatus = response.status
+      const resHeaders = Object.fromEntries(response.headers.entries())
+      const resBodyBytes = await response.arrayBuffer()
+      const resBody = httpResponseBodyParse(
+        response.headers.get('content-type'),
+        resBodyBytes,
+      )
+
+      const resCode = httpResponseCodeToEnum(resStatus)
+      if (resCode !== ResponseType.Success) {
+        const { error = undefined, message = undefined } =
+          resBody && isErrorResponseBody(resBody) ? resBody : {}
+        throw new XRPCError(resCode, error, message, resHeaders)
+      }
+
+      try {
+        this.lex.assertValidXrpcOutput(methodNsid, resBody)
+      } catch (e: unknown) {
+        if (e instanceof ValidationError) {
+          throw new XRPCInvalidResponseError(methodNsid, e, resBody)
+        }
+
+        throw e
+      }
+
+      return new XRPCResponse(resBody, resHeaders)
+    } catch (err) {
+      throw XRPCError.from(err)
+    }
+  }
+}

package/tsconfig.build.json

@@ -1,4 +1,8 @@
 {
-  "extends": "./tsconfig.json",
-  "exclude": ["**/*.spec.ts", "**/*.test.ts"]
+  "extends": "../../tsconfig/isomorphic.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["./src"]
 }

package/tsconfig.json

@@ -1,13 +1,4 @@
 {
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "./src",
-    "outDir": "./dist", // Your outDir,
-    "emitDeclarationOnly": true
-  },
-  "include": ["./src", "__tests__/**/**.ts"],
-  "references": [
-    { "path": "../common/tsconfig.build.json" },
-    { "path": "../lexicon/tsconfig.build.json" }
-  ]
+  "include": [],
+  "references": [{ "path": "./tsconfig.build.json" }]
 }

package/babel.config.js

@@ -1 +0,0 @@
-module.exports = require('../../babel.config.js')

package/build.js

@@ -1,14 +0,0 @@
-const { nodeExternalsPlugin } = require('esbuild-node-externals')
-
-const buildShallow =
-  process.argv.includes('--shallow') || process.env.ATP_BUILD_SHALLOW === 'true'
-
-require('esbuild').build({
-  logLevel: 'info',
-  entryPoints: ['src/index.ts'],
-  bundle: true,
-  sourcemap: true,
-  outdir: 'dist',
-  platform: 'node',
-  plugins: buildShallow ? [nodeExternalsPlugin()] : [],
-})