@atproto/lex-client 0.0.4 → 0.0.6

package/src/response.ts

@@ -1,25 +1,33 @@
+import { lexParse } from '@atproto/lex-json'
 import {
-  InferPayloadBody,
-  InferPayloadEncoding,
+  InferMethodOutputBody,
+  InferMethodOutputEncoding,
   Procedure,
   Query,
   ResultSuccess,
 } from '@atproto/lex-schema'
+import {
+  LexRpcResponseError,
+  LexRpcUpstreamError,
+  isLexRpcErrorPayload,
+} from './errors.js'
+import { Payload } from './util.js'
 
-export type XrpcResponseEncoding<M extends Procedure | Query> =
-  InferPayloadEncoding<M['output']>
+export type LexRpcResponseBody<M extends Procedure | Query> =
+  InferMethodOutputBody<M, Uint8Array>
 
-export type XrpcResponseBody<M extends Procedure | Query> = InferPayloadBody<
-  M['output']
->
+export type LexRpcResponsePayload<M extends Procedure | Query> =
+  InferMethodOutputEncoding<M> extends infer E extends string
+    ? Payload<LexRpcResponseBody<M>, E>
+    : null
 
 /**
  * Small container for XRPC response data.
  *
- * @implements {ResultSuccess<XrpcResponse<M>>} for convenience in result handling contexts.
+ * @implements {ResultSuccess<LexRpcResponse<M>>} for convenience in result handling contexts.
  */
-export class XrpcResponse<M extends Procedure | Query>
-  implements ResultSuccess<XrpcResponse<M>>
+export class LexRpcResponse<const M extends Procedure | Query>
+  implements ResultSuccess<LexRpcResponse<M>>
 {
   /** @see {@link ResultSuccess.success} */
   readonly success = true as const
@@ -29,14 +37,192 @@ export class XrpcResponse<M extends Procedure | Query>
     return this
   }
 
-  get encoding(): XrpcResponseEncoding<M> {
-    return this.method.output?.encoding
-  }
-
   constructor(
     readonly method: M,
     readonly status: number,
     readonly headers: Headers,
-    readonly body: XrpcResponseBody<M>,
+    readonly payload: LexRpcResponsePayload<M>,
   ) {}
+
+  /**
+   * Whether the response payload was parsed as {@link LexValue} (`true`) or is
+   * in binary form {@link Uint8Array} (`false`).
+   */
+  get isParsed() {
+    return this.encoding === 'application/json' && shouldParse(this.method)
+  }
+
+  get encoding() {
+    return this.payload?.encoding as InferMethodOutputEncoding<M>
+  }
+
+  get body() {
+    return this.payload?.body as LexRpcResponseBody<M>
+  }
+
+  /**
+   * @throws {LexRpcResponseError} in case of (valid) XRPC error responses. Use
+   * {@link LexRpcResponseError.matchesSchema} to narrow the error type based on
+   * the method's declared error schema.
+   * @throws {LexRpcUpstreamError} when the response is not a valid XRPC
+   * response, or if the response does not conform to the method's schema.
+   */
+  static async fromFetchResponse<const M extends Procedure | Query>(
+    method: M,
+    response: Response,
+    options?: { validateResponse?: boolean },
+  ): Promise<LexRpcResponse<M>> {
+    // @NOTE The body MUST either be read or canceled to avoid resource leaks.
+    // Since nothing should cause an exception before "readPayload" is
+    // called, we can safely not use a try/finally here.
+
+    // @NOTE redirect is set to 'follow', so we shouldn't get 3xx responses here
+    if (response.status < 200 || response.status >= 300) {
+      // Always parse json for error responses
+      const payload = await readPayload(response, { parse: true })
+
+      if (response.status >= 400 && isLexRpcErrorPayload(payload)) {
+        throw new LexRpcResponseError(
+          method,
+          response.status,
+          response.headers,
+          payload,
+        )
+      }
+
+      if (response.status >= 500) {
+        throw new LexRpcUpstreamError(
+          'UpstreamFailure',
+          `Upstream server encountered an error`,
+          response,
+          payload,
+        )
+      }
+
+      throw new LexRpcUpstreamError(
+        'InvalidResponse',
+        response.status >= 400
+          ? `Upstream server returned an invalid response payload`
+          : `Upstream server returned an invalid status code`,
+        response,
+        payload,
+      )
+    }
+
+    // Only parse json if the schema expects it
+    const payload = await readPayload(response, {
+      parse: shouldParse(method),
+    })
+
+    // Response is successful (2xx). Validate payload (data and encoding) against schema.
+    if (method.output.encoding == null) {
+      // Schema expects no payload
+      if (payload) {
+        throw new LexRpcUpstreamError(
+          'InvalidResponse',
+          `Expected response with no body, got ${payload.encoding}`,
+          response,
+          payload,
+        )
+      }
+    } else {
+      // Schema expects a payload
+      if (!payload || !method.output.matchesEncoding(payload.encoding)) {
+        throw new LexRpcUpstreamError(
+          'InvalidResponse',
+          payload
+            ? `Expected ${method.output.encoding} response, got ${payload.encoding}`
+            : `Expected non-empty response with content-type ${method.output.encoding}`,
+          response,
+          payload,
+        )
+      }
+
+      // Assert valid response body.
+      if (method.output.schema && options?.validateResponse !== false) {
+        const result = method.output.schema.safeParse(payload.body, {
+          allowTransform: false,
+        })
+
+        if (!result.success) {
+          throw new LexRpcUpstreamError(
+            'InvalidResponse',
+            `Response validation failed: ${result.reason.message}`,
+            response,
+            payload,
+            { cause: result.reason },
+          )
+        }
+      }
+    }
+
+    return new LexRpcResponse<M>(
+      method,
+      response.status,
+      response.headers,
+      payload as LexRpcResponsePayload<M>,
+    )
+  }
+}
+
+function shouldParse(method: Procedure | Query) {
+  return method.output.encoding === 'application/json'
+}
+
+/**
+ * @note this function always consumes the response body
+ */
+async function readPayload(
+  response: Response,
+  options?: { parse?: boolean },
+): Promise<Payload | null> {
+  // @TODO Should we limit the maximum response size here (this could also be
+  // done by the FetchHandler)?
+
+  const encoding = response.headers
+    .get('content-type')
+    ?.split(';')[0]
+    .trim()
+    .toLowerCase()
+
+  // Response content-type is undefined
+  if (!encoding) {
+    // If the body is empty, return null (= no payload)
+    const body = await response.arrayBuffer()
+    if (body.byteLength === 0) return null
+
+    // If we got data despite no content-type, treat it as binary
+    return {
+      encoding: 'application/octet-stream',
+      body: new Uint8Array(body),
+    }
+  }
+
+  if (options?.parse && encoding === 'application/json') {
+    // @NOTE It might be worth returning the raw bytes here (Uint8Array) and
+    // perform the lex parsing using cborg/json, allowing to do
+    // bytes->LexValue in one step instead of bytes->text->JSON->LexValue.
+    // This would require adding encode/decode utilities to lex-json (similar
+    // to @ipld/dag-json)
+    const text = await response.text()
+
+    try {
+      // @NOTE Using `lexParse(text)` (instead of `jsonToLex(json)`) here as
+      // using a reviver function during JSON.parse should be faster than
+      // parsing to JSON then converting to Lex (?)
+
+      // @TODO verify statement above
+      return { encoding, body: lexParse(text) }
+    } catch (cause) {
+      throw new LexRpcUpstreamError(
+        'InvalidResponse',
+        'Invalid JSON response body',
+        response,
+        null,
+        { cause },
+      )
+    }
+  }
+
+  return { encoding, body: new Uint8Array(await response.arrayBuffer()) }
 }

package/src/types.ts

@@ -10,12 +10,33 @@ export type CallOptions = {
   signal?: AbortSignal
   headers?: HeadersInit
   service?: Service
+
+  /**
+   * Whether to validate the request against the method's input schema. Enabling
+   * this can help catch errors early but may have a performance cost. This
+   * would typically only be set to `true` in development or debugging
+   * scenarios.
+   *
+   * @default false
+   */
   validateRequest?: boolean
+
+  /**
+   * Whether to validate the response against the method's output schema.
+   * Disabling this can improve performance but may lead to runtime errors if
+   * the response does not conform to the expected schema. Only set this to
+   * `false` if you are certain that the upstream service will always return
+   * valid responses.
+   *
+   * @default true
+   */
   validateResponse?: boolean
 }
 
-export type Namespace<T> = T | { main: T }
-
-export function getMain<T extends object>(ns: Namespace<T>): T {
-  return 'main' in ns ? ns.main : ns
-}
+export type BinaryBodyInit =
+  | Uint8Array
+  | ArrayBuffer
+  | Blob
+  | ReadableStream<Uint8Array>
+  | AsyncIterable<Uint8Array>
+  | string

package/src/util.ts

@@ -0,0 +1,84 @@
+import { DidString } from '@atproto/lex-schema'
+
+export type Payload<B = unknown, E extends string = string> = {
+  body: B
+  encoding: E
+}
+
+export 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 as any)[Symbol.toStringTag]
+  if (tag === 'Blob' || tag === 'File') {
+    return 'stream' in value && typeof value.stream === 'function'
+  }
+
+  return false
+}
+
+export function isAsyncIterable<T>(
+  value: T,
+): value is unknown extends T
+  ? T & AsyncIterable<unknown>
+  : Extract<T, AsyncIterable<any>> {
+  return (
+    value != null && typeof (value as any)[Symbol.asyncIterator] === 'function'
+  )
+}
+
+export function buildAtprotoHeaders(options: {
+  headers?: HeadersInit
+  service?: `${DidString}#${string}`
+  labelers?: Iterable<DidString>
+}): Headers {
+  const headers = new Headers(options?.headers)
+
+  if (options.service && !headers.has('atproto-proxy')) {
+    headers.set('atproto-proxy', options.service)
+  }
+
+  if (options.labelers) {
+    headers.set(
+      'atproto-accept-labelers',
+      [...options.labelers, headers.get('atproto-accept-labelers')?.trim()]
+        .filter(Boolean)
+        .join(', '),
+    )
+  }
+
+  return headers
+}
+
+export function toReadableStream(
+  data: AsyncIterable<Uint8Array>,
+): ReadableStream<Uint8Array> {
+  // Use the native ReadableStream.from() if available.
+  if ('from' in ReadableStream && typeof ReadableStream.from === 'function') {
+    return ReadableStream.from(data)
+  }
+
+  let iterator: AsyncIterator<Uint8Array> | undefined
+  return new ReadableStream({
+    async pull(controller) {
+      try {
+        iterator ??= data[Symbol.asyncIterator]()
+        const result = await iterator!.next()
+        if (result.done) controller.close()
+        else controller.enqueue(result.value)
+      } catch (err) {
+        controller.error(err)
+        iterator = undefined
+      }
+    },
+    async cancel() {
+      await iterator?.return?.()
+      iterator = undefined
+    },
+  })
+}