@atproto/lex-client 0.0.15 → 0.0.17

package/src/errors.ts

@@ -7,12 +7,16 @@ import {
   ResultFailure,
   lexErrorDataSchema,
 } from '@atproto/lex-schema'
-import { XrpcResponsePayload } from './util.js'
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { Agent } from './agent.js'
+import { XrpcUnknownResponsePayload } from './types.js'
 import {
   WWWAuthenticate,
   parseWWWAuthenticateHeader,
 } from './www-authenticate.js'
 
+export type { XrpcUnknownResponsePayload }
+
 export type DownstreamError<N extends LexErrorCode = LexErrorCode> = {
   status: number
   headers?: Headers
@@ -66,7 +70,7 @@ export type XrpcErrorPayload<N extends LexErrorCode = LexErrorCode> = {
  * This function checks whether a given payload matches this schema.
  */
 export function isXrpcErrorPayload(
-  payload: XrpcResponsePayload | null | undefined,
+  payload: XrpcUnknownResponsePayload | null | undefined,
 ): payload is XrpcErrorPayload {
   return (
     payload != null &&
@@ -290,7 +294,7 @@ export class XrpcUpstreamError<
   constructor(
     method: M,
     readonly response: Response,
-    readonly payload: XrpcResponsePayload | null = null,
+    readonly payload: XrpcUnknownResponsePayload | null = null,
     message: string = `Unexpected upstream XRPC response`,
     options?: ErrorOptions,
   ) {
@@ -329,7 +333,7 @@ export class XrpcInvalidResponseError<
   constructor(
     method: M,
     response: Response,
-    payload: XrpcResponsePayload,
+    payload: XrpcUnknownResponsePayload,
     readonly cause: LexValidationError,
   ) {
     super(method, response, payload, `Invalid response: ${cause.message}`, {
@@ -347,17 +351,11 @@ export class XrpcInvalidResponseError<
 }
 
 /**
- * Error class for internal/client-side errors during XRPC requests.
- *
- * This represents errors that occur before or during the request that are not
- * server responses, such as:
- * - Network errors (connection refused, DNS failure)
- * - Request timeouts
- * - Request aborted via AbortSignal
- * - Invalid request construction
+ * Error class for unexpected internal/client-side errors during XRPC requests.
  *
- * The error code is always 'InternalServerError' and these errors are
- * optimistically considered retryable.
+ * The error code is always 'InternalServerError' and these errors not
+ * considered retryable as they stem from unforeseen issues in the
+ * implementation.
  *
  * @typeParam M - The XRPC method type
  */
@@ -379,15 +377,11 @@ export class XrpcInternalError<
     return this
   }
 
-  override shouldRetry(): true {
-    // Ideally, we would inspect the reason to determine if it's retryable
-    // (by detecting network errors, timeouts, etc.). Since these cases are
-    // highly platform-dependent, we optimistically assume all internal
-    // errors are retryable.
-    return true
+  override shouldRetry(): boolean {
+    return false
   }
 
-  override toJSON(): LexErrorData<'InternalServerError'> {
+  override toJSON(): LexErrorData {
     // @NOTE Do not expose internal error details to downstream clients
     return { error: this.error, message: 'Internal Server Error' }
   }
@@ -397,6 +391,49 @@ export class XrpcInternalError<
   }
 }
 
+/**
+ * Special case of XrpcInternalError that specifically represents errors thrown
+ * by {@link Agent.fetchHandler} during the XRPC request. This includes:
+ * - Network errors (connection refused, DNS failure)
+ * - Request timeouts
+ * - Request aborted via AbortSignal
+ *
+ * These errors are optimistically considered retryable, as many fetch errors
+ * are transient and may succeed on retry.
+ */
+export class XrpcFetchError<
+  M extends Procedure | Query = Procedure | Query,
+> extends XrpcInternalError<M> {
+  name = 'XrpcFetchError'
+
+  constructor(method: M, cause: unknown) {
+    const message = cause instanceof Error ? cause.message : String(cause)
+    super(method, `Unexpected fetchHandler() error: ${message}`, { cause })
+  }
+
+  override shouldRetry(): boolean {
+    // Ideally, we would inspect the reason to determine if it's retryable (by
+    // detecting network errors, timeouts, etc.). Since these cases are highly
+    // platform-dependent, we optimistically assume all fetch errors are
+    // transient and retryable.
+    return true
+  }
+
+  override toJSON(): LexErrorData {
+    // @NOTE Do not expose internal error details to downstream clients
+    return { error: this.error, message: 'Failed to perform upstream request' }
+  }
+
+  override toDownstreamError(): DownstreamError {
+    // While it might technically be a 500 error, we use 502 Bad Gateway here to
+    // indicate that the error occurred while communicating with the upstream
+    // server, allowing downstream clients to distinguish between errors in our
+    // internal processing (500) and errors in the upstream server or network
+    // (502).
+    return { status: 502, body: this.toJSON() }
+  }
+}
+
 /**
  * Union type of all possible XRPC failure types.
  *

package/src/response.ts

@@ -1,9 +1,13 @@
-import { lexParse } from '@atproto/lex-json'
+import { LexParseOptions, lexParse } from '@atproto/lex-json'
 import {
   InferMethodOutputEncoding,
+  InferOutput,
+  LexValue,
+  Payload,
   Procedure,
   Query,
   ResultSuccess,
+  Validator,
 } from '@atproto/lex-schema'
 import {
   XrpcAuthenticationError,
@@ -12,12 +16,104 @@ import {
   XrpcUpstreamError,
   isXrpcErrorPayload,
 } from './errors.js'
-import { XrpcResponseBody, XrpcResponsePayload } from './util.js'
+import {
+  EncodingString,
+  XrpcUnknownResponsePayload,
+  isEncodingString,
+} from './types.js'
 
 const CONTENT_TYPE_BINARY = 'application/octet-stream'
 const CONTENT_TYPE_JSON = 'application/json'
 
-export type { XrpcResponseBody, XrpcResponsePayload }
+// @NOTE the output schema is used in "parse" mode (safeParse), which means that
+// defaults will be applied and coercions will be performed, so we need to use
+// InferOutput here to get the final parsed type, not Infer/InferInput. For this
+// reason, we cannot use InferMethodOutputBody and InferMethodOutput from
+// lex-schema here.
+
+type InferEncodingType<TEncoding extends string> = TEncoding extends '*/*'
+  ? EncodingString
+  : TEncoding extends `${infer T extends string}/*`
+    ? `${T}/${string}`
+    : TEncoding
+
+type InferBodyType<
+  TEncoding extends string,
+  TSchema,
+> = TSchema extends Validator
+  ? InferOutput<TSchema>
+  : TEncoding extends `application/json`
+    ? LexValue
+    : Uint8Array
+
+/**
+ * The body type of an XRPC response, inferred from the method's output schema.
+ *
+ * For JSON responses, this is the parsed LexValue. For binary responses,
+ * this is a Uint8Array.
+ *
+ * @typeParam M - The XRPC method type (Procedure or Query)
+ */
+export type XrpcResponseBody<M extends Procedure | Query> =
+  M['output'] extends Payload<infer TEncoding, infer TSchema>
+    ? TEncoding extends string
+      ? InferBodyType<TEncoding, TSchema>
+      : undefined
+    : never
+
+/**
+ * The full payload type of an XRPC response, including body and encoding.
+ *
+ * Returns `null` for methods that have no output.
+ *
+ * @typeParam M - The XRPC method type (Procedure or Query)
+ */
+export type XrpcResponsePayload<M extends Procedure | Query> =
+  M['output'] extends Payload<infer TEncoding, infer TSchema>
+    ? TEncoding extends string
+      ? {
+          encoding: InferEncodingType<TEncoding>
+          body: InferBodyType<TEncoding, TSchema>
+        }
+      : undefined
+    : never
+
+export type XrpcResponseOptions = {
+  /**
+   * 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
+
+  /**
+   * Whether to strictly process response payloads according to Lex encoding
+   * rules. By default, the client will reject responses with invalid Lex data
+   * (floats and invalid $bytes / $link objects).
+   *
+   * Setting this option to `false` will allow the client to accept such
+   * responses in a non-strict mode, where invalid Lex data will be returned
+   * as-is (e.g., floats will not be rejected, and invalid $bytes / $link
+   * objects will not be converted to Uint8Array / Cid). When in non-strict
+   * mode, the validation will also be relaxed when validating the response
+   * against the method's output schema, allowing values that do not strictly
+   * conform to the schema (e.g. datetime strings that are not valid RFC3339
+   * format, blobs that are not of the right size/mime-type, etc.) to be
+   * accepted as long as their basic structure is correct.
+   *
+   * When validation is enabled (the default), the values defined through the
+   * method schema will be enforced, ensuring that the client can still process
+   * the response even if the server returns invalid Lex data.
+   *
+   * @default true
+   * @see {@link LexParseOptions.strict}
+   */
+  strictResponseProcessing?: boolean
+}
 
 /**
  * Small container for XRPC response data.
@@ -80,7 +176,7 @@ export class XrpcResponse<M extends Procedure | Query>
   static async fromFetchResponse<const M extends Procedure | Query>(
     method: M,
     response: Response,
-    options?: { validateResponse?: boolean },
+    options?: XrpcResponseOptions,
   ): Promise<XrpcResponse<M>> {
     // @NOTE The body MUST either be read or canceled to avoid resource leaks.
     // Since nothing should cause an exception before "readPayload" is
@@ -89,17 +185,9 @@ export class XrpcResponse<M extends Procedure | Query>
     // @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 }).catch(
-        (cause) => {
-          throw new XrpcUpstreamError(
-            method,
-            response,
-            null,
-            'Unable to parse response payload',
-            { cause },
-          )
-        },
-      )
+      const payload = await readPayload(method, response, {
+        parse: { strict: options?.strictResponseProcessing ?? true },
+      })
 
       // Properly formatted XRPC error response ?
       if (response.status >= 400 && isXrpcErrorPayload(payload)) {
@@ -121,17 +209,11 @@ export class XrpcResponse<M extends Procedure | Query>
       )
     }
 
-    // Only parse json if the schema expects it
-    const payload = await readPayload(response, {
-      parse: method.output.encoding === CONTENT_TYPE_JSON,
-    }).catch((cause) => {
-      throw new XrpcUpstreamError(
-        method,
-        response,
-        null,
-        'Unable to parse response payload',
-        { cause },
-      )
+    const payload = await readPayload(method, response, {
+      // Only parse json if the schema expects it
+      parse: method.output.encoding === CONTENT_TYPE_JSON && {
+        strict: options?.strictResponseProcessing ?? true,
+      },
     })
 
     // Response is successful (2xx). Validate payload (data and encoding) against schema.
@@ -160,7 +242,9 @@ export class XrpcResponse<M extends Procedure | Query>
 
       // Assert valid response body.
       if (method.output.schema && options?.validateResponse !== false) {
-        const result = method.output.schema.safeParse(payload.body)
+        const result = method.output.schema.safeParse(payload.body, {
+          strict: options?.strictResponseProcessing ?? true,
+        })
 
         if (!result.success) {
           throw new XrpcInvalidResponseError(
@@ -170,6 +254,18 @@ export class XrpcResponse<M extends Procedure | Query>
             result.reason,
           )
         }
+
+        const parsedPayload = {
+          body: result.value,
+          encoding: payload.encoding,
+        } as XrpcResponsePayload<M>
+
+        return new XrpcResponse<M>(
+          method,
+          response.status,
+          response.headers,
+          parsedPayload,
+        )
       }
     }
 
@@ -182,50 +278,77 @@ export class XrpcResponse<M extends Procedure | Query>
   }
 }
 
+type ReadPayloadOptions = {
+  /**
+   * Whether to parse the response body as JSON and convert it to LexValue.
+   *
+   * @default false
+   */
+  parse?: false | LexParseOptions
+}
+
 /**
  * @note this function always consumes the response body
  */
 async function readPayload(
+  method: Query | Procedure,
   response: Response,
-  options?: { parse?: boolean },
-): Promise<XrpcResponsePayload> {
-  // @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 undefined (= no payload)
-    const body = await response.arrayBuffer()
-    if (body.byteLength === 0) return undefined
-
-    // If we got data despite no content-type, treat it as binary
-    return {
-      encoding: CONTENT_TYPE_BINARY,
-      body: new Uint8Array(body),
+  options?: ReadPayloadOptions,
+): Promise<undefined | XrpcUnknownResponsePayload> {
+  try {
+    // @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 undefined (= no payload)
+      const arrayBuffer = await response.arrayBuffer()
+      if (arrayBuffer.byteLength === 0) return undefined
+
+      // If we got data despite no content-type, treat it as binary
+      return {
+        encoding: CONTENT_TYPE_BINARY,
+        body: new Uint8Array(arrayBuffer),
+      }
     }
-  }
 
-  if (options?.parse && encoding === CONTENT_TYPE_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()
+    if (!isEncodingString(encoding)) {
+      throw new TypeError(`Invalid content-type "${encoding}" in response`)
+    }
 
-    // @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 (?)
+    if (options?.parse && encoding === CONTENT_TYPE_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()
 
-    // @TODO verify statement above
-    return { encoding, body: lexParse(text) }
-  }
+      // @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, options.parse) }
+    }
 
-  return { encoding, body: new Uint8Array(await response.arrayBuffer()) }
+    const arrayBuffer = await response.arrayBuffer()
+    return { encoding, body: new Uint8Array(arrayBuffer) }
+  } catch (cause) {
+    const message = 'Unable to parse response payload'
+    const messageDetail = cause instanceof TypeError ? cause.message : undefined
+    throw new XrpcUpstreamError(
+      method,
+      response,
+      null,
+      messageDetail ? `${message}: ${messageDetail}` : message,
+      { cause },
+    )
+  }
 }

package/src/types.ts

@@ -1,6 +1,6 @@
-import { DidString, UnknownString } from '@atproto/lex-schema'
+import { DidString, LexValue, UnknownString } from '@atproto/lex-schema'
 
-export type { DidString, UnknownString }
+export type { DidString, LexValue, UnknownString }
 
 /**
  * Service identifier fragment for DID service endpoints.
@@ -22,44 +22,6 @@ export type DidServiceIdentifier = 'atproto_labeler' | UnknownString
  */
 export type Service = `${DidString}#${DidServiceIdentifier}`
 
-/**
- * Common options available for all XRPC calls.
- *
- * These options can be passed to any method that makes XRPC requests,
- * including `xrpc()`, `call()`, and record operations.
- */
-export type CallOptions = {
-  /** Labeler DIDs to request labels from for content moderation. */
-  labelers?: Iterable<DidString>
-  /** AbortSignal to cancel the request. */
-  signal?: AbortSignal
-  /** Additional HTTP headers to include in the request. */
-  headers?: HeadersInit
-  /** Service proxy identifier for routing requests through a specific service. */
-  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
-}
-
 /**
  * Valid input types for binary request bodies.
  *
@@ -92,3 +54,18 @@ export type BinaryBodyInit =
   | ReadableStream<Uint8Array>
   | AsyncIterable<Uint8Array>
   | string
+
+export type EncodingString = `${string}/${string}`
+
+export function isEncodingString(
+  contentType: string,
+): contentType is EncodingString {
+  return contentType.includes('/')
+}
+
+export type XrpcUnknownResponsePayload<
+  TBinary extends BinaryBodyInit = Uint8Array,
+> = {
+  encoding: EncodingString
+  body: LexValue | TBinary
+}