@atproto/lex-client 0.0.17 → 0.0.19

package/src/errors.ts

@@ -1,4 +1,9 @@
-import { LexError, LexErrorCode, LexErrorData } from '@atproto/lex-data'
+import {
+  LexError,
+  LexErrorCode,
+  LexErrorData,
+  LexValue,
+} from '@atproto/lex-data'
 import {
   InferMethodError,
   LexValidationError,
@@ -15,6 +20,28 @@ import {
   parseWWWAuthenticateHeader,
 } from './www-authenticate.js'
 
+/**
+ * Mapping that allows generating an XRPC error code from an HTTP status code
+ * when the response does not contain a valid XRPC error payload. This is used
+ * to convert non-XRPC error responses from upstream servers into a standardized
+ * XRPC error for downstream clients.
+ */
+const StatusErrorCodes = new Map<number, LexErrorCode>([
+  [400, 'InvalidRequest'],
+  [401, 'AuthenticationRequired'],
+  [403, 'Forbidden'],
+  [404, 'XRPCNotSupported'],
+  [406, 'NotAcceptable'],
+  [413, 'PayloadTooLarge'],
+  [415, 'UnsupportedMediaType'],
+  [429, 'RateLimitExceeded'],
+  [500, 'InternalServerError'],
+  [501, 'MethodNotImplemented'],
+  [502, 'UpstreamFailure'],
+  [503, 'NotEnoughResources'],
+  [504, 'UpstreamTimeout'],
+])
+
 export type { XrpcUnknownResponsePayload }
 
 export type DownstreamError<N extends LexErrorCode = LexErrorCode> = {
@@ -90,7 +117,7 @@ export function isXrpcErrorPayload(
  * @typeParam TReason - The reason type for ResultFailure
  *
  * @see {@link XrpcResponseError} - For valid XRPC error responses
- * @see {@link XrpcUpstreamError} - For invalid/unexpected responses
+ * @see {@link XrpcInvalidResponseError} - For invalid/unexpected responses
  * @see {@link XrpcInternalError} - For network/internal errors
  */
 export abstract class XrpcError<
@@ -160,17 +187,23 @@ export abstract class XrpcError<
  */
 export class XrpcResponseError<
   M extends Procedure | Query = Procedure | Query,
-  N extends LexErrorCode = InferMethodError<M> | LexErrorCode,
-> extends XrpcError<M, N, XrpcResponseError<M, N>> {
+> extends XrpcError<M, LexErrorCode, XrpcResponseError<M>> {
   name = 'XrpcResponseError'
 
   constructor(
     method: M,
     readonly response: Response,
-    readonly payload: XrpcErrorPayload<N>,
+    readonly payload?: XrpcUnknownResponsePayload,
     options?: ErrorOptions,
   ) {
-    const { error, message } = payload.body
+    const { error, message } = isXrpcErrorPayload(payload)
+      ? payload.body
+      : {
+          error:
+            StatusErrorCodes.get(response.status) ??
+            (response.status >= 500 ? 'UpstreamFailure' : 'InvalidRequest'),
+          message: buildResponseOverviewMessage(response),
+        }
     super(method, error, message, options)
   }
 
@@ -182,19 +215,27 @@ export class XrpcResponseError<
     return RETRYABLE_HTTP_STATUS_CODES.has(this.response.status)
   }
 
-  override toJSON(): LexErrorData<N> {
-    return this.payload.body
+  override toJSON(): LexErrorData {
+    // Return the original error payload if it's a valid XRPC error, otherwise
+    // convert to an XRPC error format.
+    const { payload } = this
+    if (isXrpcErrorPayload(payload)) {
+      return payload.body
+    }
+
+    return super.toJSON()
   }
 
   override toDownstreamError(): DownstreamError {
-    // If the upstream server returned a 5xx error, we want to return a 502 Bad
+    const { status, headers } = this.response
+    // If the upstream server returned a 500 error, we want to return a 502 Bad
     // Gateway to downstream clients, as the issue is with the upstream server,
     // not us. We still return the original error code and message in the body
     // for transparency, but we do not want to expose internal server errors
     // from the upstream server as-is to downstream clients.
     return {
-      status: this.response.status === 500 ? 502 : this.status,
-      headers: stripHopByHopHeaders(this.headers),
+      status: status === 500 ? 502 : status,
+      headers: stripHopByHopHeaders(headers),
       body: this.toJSON(),
     }
   }
@@ -207,8 +248,8 @@ export class XrpcResponseError<
     return this.response.headers
   }
 
-  get body(): LexErrorData<N> {
-    return this.payload.body
+  get body(): undefined | Uint8Array | LexValue {
+    return this.payload?.body
   }
 }
 
@@ -242,8 +283,7 @@ export type { WWWAuthenticate }
  */
 export class XrpcAuthenticationError<
   M extends Procedure | Query = Procedure | Query,
-  N extends LexErrorCode = LexErrorCode,
-> extends XrpcResponseError<M, N> {
+> extends XrpcResponseError<M> {
   name = 'XrpcAuthenticationError'
 
   override shouldRetry(): boolean {
@@ -261,14 +301,6 @@ export class XrpcAuthenticationError<
         this.response.headers.get('www-authenticate'),
       ) ?? {})
   }
-
-  override toDownstreamError(): DownstreamError {
-    return {
-      status: 401,
-      headers: stripHopByHopHeaders(this.headers),
-      body: this.toJSON(),
-    }
-  }
 }
 
 /**
@@ -281,24 +313,25 @@ export class XrpcAuthenticationError<
  * - Non-JSON error responses
  * - Responses from non-XRPC endpoints
  *
- * The error code is always 'UpstreamFailure' and maps to HTTP 502 Bad Gateway
- * when converted to a response.
+ * The error code is always 'InvalidResponse' and maps to HTTP 502 Bad Gateway
+ * when converted to a response. This should allow downstream clients to
+ * determine at which boundary the error occurred.
  *
  * @typeParam M - The XRPC method type
  */
-export class XrpcUpstreamError<
+export class XrpcInvalidResponseError<
   M extends Procedure | Query = Procedure | Query,
-> extends XrpcError<M, 'UpstreamFailure', XrpcUpstreamError<M>> {
-  name = 'XrpcUpstreamError'
+> extends XrpcError<M, 'InvalidResponse', XrpcInvalidResponseError<M>> {
+  name = 'XrpcInvalidResponseError'
 
   constructor(
     method: M,
     readonly response: Response,
-    readonly payload: XrpcUnknownResponsePayload | null = null,
-    message: string = `Unexpected upstream XRPC response`,
+    readonly payload?: XrpcUnknownResponsePayload,
+    message: string = buildResponseOverviewMessage(response),
     options?: ErrorOptions,
   ) {
-    super(method, 'UpstreamFailure', message, options)
+    super(method, 'InvalidResponse', message, options)
   }
 
   override get reason(): this {
@@ -317,7 +350,7 @@ export class XrpcUpstreamError<
 /**
  * Error class for invalid XRPC responses that fail schema validation.
  *
- * This is a specific type of {@link XrpcUpstreamError} that indicates the
+ * This is a specific type of {@link XrpcInvalidResponseError} that indicates the
  * upstream server returned a response that was structurally valid but did not
  * conform to the expected schema for the method. This likely indicates a
  * mismatch between client and server versions or an issue with the server's
@@ -325,10 +358,10 @@ export class XrpcUpstreamError<
  *
  * @typeParam M - The XRPC method type
  */
-export class XrpcInvalidResponseError<
+export class XrpcResponseValidationError<
   M extends Procedure | Query = Procedure | Query,
-> extends XrpcUpstreamError<M> {
-  name = 'XrpcInvalidResponseError'
+> extends XrpcInvalidResponseError<M> {
+  name = 'XrpcResponseValidationError'
 
   constructor(
     method: M,
@@ -336,17 +369,13 @@ export class XrpcInvalidResponseError<
     payload: XrpcUnknownResponsePayload,
     readonly cause: LexValidationError,
   ) {
-    super(method, response, payload, `Invalid response: ${cause.message}`, {
-      cause,
-    })
-  }
-
-  override toDownstreamError(): DownstreamError {
-    // @NOTE This could be reflected as both a 500 ("we" are at fault) and 502
-    // ("they" are at fault). We are using 502 here to allow downstream clients
-    // to determine that the issue lies at the interface between us and the
-    // upstream server, rather than an issue with our internal processing.
-    return { status: 502, body: this.toJSON() }
+    super(
+      method,
+      response,
+      payload,
+      `Invalid response payload: ${cause.message}`,
+      { cause },
+    )
   }
 }
 
@@ -448,7 +477,7 @@ export class XrpcFetchError<
  * if (result.success) {
  *   console.log(result.body) // XrpcResponse
  * } else {
- *   // result is XrpcFailure (XrpcResponseError | XrpcUpstreamError | XrpcInternalError)
+ *   // result is XrpcFailure (XrpcResponseError | XrpcInvalidResponseError | XrpcInternalError)
  *   console.error(result.error, result.message)
  * }
  * ```
@@ -457,7 +486,7 @@ export type XrpcFailure<M extends Procedure | Query = Procedure | Query> =
   // The server returned a valid XRPC error response
   | XrpcResponseError<M>
   // The response was not a valid XRPC response, or it does not match the schema
-  | XrpcUpstreamError<M>
+  | XrpcInvalidResponseError<M>
   // Something went wrong (network error, etc.)
   | XrpcInternalError<M>
 
@@ -487,7 +516,7 @@ export function asXrpcFailure<M extends Procedure | Query>(
 ): XrpcFailure<M> {
   if (
     cause instanceof XrpcResponseError ||
-    cause instanceof XrpcUpstreamError ||
+    cause instanceof XrpcInvalidResponseError ||
     cause instanceof XrpcInternalError
   ) {
     if (cause.method === method) return cause
@@ -531,3 +560,11 @@ function stripHopByHopHeaders(headers: Headers): Headers {
 
   return result
 }
+
+function buildResponseOverviewMessage(response: Response): string {
+  if (response.status < 400) {
+    return `Upstream server responded with an invalid status code (${response.status})`
+  }
+
+  return `Upstream server responded with a ${response.status} error`
+}

package/src/lexicons/com/atproto/repo/uploadBlob.defs.ts

@@ -15,9 +15,7 @@ const main =
     $nsid,
     /*#__PURE__*/ l.params(),
     /*#__PURE__*/ l.payload('*/*'),
-    /*#__PURE__*/ l.jsonPayload({
-      blob: /*#__PURE__*/ l.blob({ allowLegacy: false }),
-    }),
+    /*#__PURE__*/ l.jsonPayload({ blob: /*#__PURE__*/ l.blob() }),
   )
 export { main }
 

package/src/response.ts

@@ -1,4 +1,4 @@
-import { LexParseOptions, lexParse } from '@atproto/lex-json'
+import { LexParseOptions, lexParseJsonBytes } from '@atproto/lex-json'
 import {
   InferMethodOutputEncoding,
   InferOutput,
@@ -13,8 +13,7 @@ import {
   XrpcAuthenticationError,
   XrpcInvalidResponseError,
   XrpcResponseError,
-  XrpcUpstreamError,
-  isXrpcErrorPayload,
+  XrpcResponseValidationError,
 } from './errors.js'
 import {
   EncodingString,
@@ -58,7 +57,7 @@ export type XrpcResponseBody<M extends Procedure | Query> =
   M['output'] extends Payload<infer TEncoding, infer TSchema>
     ? TEncoding extends string
       ? InferBodyType<TEncoding, TSchema>
-      : undefined
+      : undefined | LexValue | Uint8Array
     : never
 
 /**
@@ -75,7 +74,9 @@ export type XrpcResponsePayload<M extends Procedure | Query> =
           encoding: InferEncodingType<TEncoding>
           body: InferBodyType<TEncoding, TSchema>
         }
-      : undefined
+      : // If the schema does not specify an output encoding, anything could be
+        // returned, including no payload at all (undefined).
+        undefined | { body: LexValue | Uint8Array; encoding: string }
     : never
 
 export type XrpcResponseOptions = {
@@ -170,7 +171,7 @@ export class XrpcResponse<M extends Procedure | Query>
    * {@link XrpcResponseError.matchesSchemaErrors} to narrow the error type based on
    * the method's declared error schema. This can be narrowed further as a
    * {@link XrpcAuthenticationError} if the error is an authentication error.
-   * @throws {XrpcUpstreamError} when the response is not a valid XRPC
+   * @throws {XrpcInvalidResponseError} 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>(
@@ -182,63 +183,62 @@ export class XrpcResponse<M extends Procedure | Query>
     // 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
+    // Always turn 4xx/5xx responses into XrpcResponseError
+    if (response.status >= 400) {
       const payload = await readPayload(method, response, {
-        parse: { strict: options?.strictResponseProcessing ?? true },
+        // Always parse errors in non-strict mode
+        parse: { strict: false },
       })
 
-      // Properly formatted XRPC error response ?
-      if (response.status >= 400 && isXrpcErrorPayload(payload)) {
-        throw response.status === 401
-          ? new XrpcAuthenticationError<M>(method, response, payload)
-          : new XrpcResponseError<M>(method, response, payload)
+      if (response.status === 401) {
+        throw new XrpcAuthenticationError<M>(method, response, payload)
       }
 
-      // Invalid XRPC response (we probably did not hit an XRPC implementation)
-      throw new XrpcUpstreamError(
+      throw new XrpcResponseError<M>(method, response, payload)
+    }
+
+    // @NOTE redirect is set to 'follow', so we shouldn't get 3xx responses here
+    if (response.status < 200 || response.status >= 300) {
+      await response.body?.cancel()
+
+      throw new XrpcInvalidResponseError(
         method,
         response,
-        payload,
-        response.status >= 500
-          ? 'Upstream server encountered an error'
-          : response.status >= 400
-            ? 'Invalid response payload'
-            : 'Invalid response status code',
+        undefined,
+        `Unexpected status code ${response.status}`,
       )
     }
 
     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,
-      },
+      // Parse response if there is a schema, or if the encoding is
+      // "application/json"
+      parse:
+        method.output.schema || method.output.encoding === CONTENT_TYPE_JSON
+          ? { strict: options?.strictResponseProcessing ?? true }
+          : // If there is no declared output encoding, we'll parse the output (in loose mode)
+            method.output.encoding == null
+            ? { strict: false }
+            : false,
     })
 
+    if (!method.output.matchesEncoding(payload?.encoding)) {
+      throw new XrpcInvalidResponseError(
+        method,
+        response,
+        payload,
+        `Expected ${stringifyEncoding(method.output.encoding)} response (got ${stringifyEncoding(payload?.encoding)})`,
+      )
+    }
+
     // Response is successful (2xx). Validate payload (data and encoding) against schema.
-    if (method.output.encoding == null) {
-      // Schema expects no payload
-      if (payload) {
-        throw new XrpcUpstreamError(
-          method,
-          response,
-          payload,
-          `Expected response with no body, got ${payload.encoding}`,
-        )
-      }
-    } else {
-      // Schema expects a payload
-      if (!payload || !method.output.matchesEncoding(payload.encoding)) {
-        throw new XrpcUpstreamError(
-          method,
-          response,
-          payload,
-          payload
-            ? `Expected ${method.output.encoding} response, got ${payload.encoding}`
-            : `Expected non-empty response with content-type ${method.output.encoding}`,
-        )
-      }
+    if (method.output.encoding != null) {
+      // If the schema specifies an output, verify that the response properly
+      // matches the expected format (encoding and schema, if present). If no
+      // output is specified, any payload could be returned.
+
+      // Needed for type safety. Should never happen since matchesEncoding()
+      // should return not succeed if there is a schema encoding but no payload.
+      if (!payload) throw new Error('Expected payload')
 
       // Assert valid response body.
       if (method.output.schema && options?.validateResponse !== false) {
@@ -247,7 +247,7 @@ export class XrpcResponse<M extends Procedure | Query>
         })
 
         if (!result.success) {
-          throw new XrpcInvalidResponseError(
+          throw new XrpcResponseValidationError(
             method,
             response,
             payload,
@@ -323,19 +323,10 @@ async function readPayload(
     }
 
     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()
-
-      // @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) }
+      const arrayBuffer = await response.arrayBuffer()
+      const bytes = new Uint8Array(arrayBuffer)
+      const body = lexParseJsonBytes(bytes, options.parse)
+      return { encoding, body }
     }
 
     const arrayBuffer = await response.arrayBuffer()
@@ -343,12 +334,16 @@ async function readPayload(
   } catch (cause) {
     const message = 'Unable to parse response payload'
     const messageDetail = cause instanceof TypeError ? cause.message : undefined
-    throw new XrpcUpstreamError(
+    throw new XrpcInvalidResponseError(
       method,
       response,
-      null,
+      undefined,
       messageDetail ? `${message}: ${messageDetail}` : message,
       { cause },
     )
   }
 }
+
+function stringifyEncoding(encoding: string | undefined) {
+  return encoding ? `"${encoding}"` : 'no payload'
+}