@atproto/lex-client 0.0.17 → 0.0.18

package/src/errors.test.ts

@@ -6,7 +6,7 @@ import {
   XrpcInternalError,
   XrpcInvalidResponseError,
   XrpcResponseError,
-  XrpcUpstreamError,
+  XrpcResponseValidationError,
   asXrpcFailure,
 } from './errors.js'
 
@@ -41,13 +41,141 @@ describe(XrpcResponseError, () => {
     })
   }
 
-  it('exposes status from the response', () => {
-    const err = createResponseError(404, 'NotFound')
-    expect(err.reason).toBe(err)
-    expect(err.status).toBe(404)
+  describe('StatusErrorCodes mapping for non-XRPC responses', () => {
+    it('maps 400 to InvalidRequest', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 400 }),
+      )
+      expect(err.error).toBe('InvalidRequest')
+    })
+
+    it('maps 401 to AuthenticationRequired', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 401 }),
+      )
+      expect(err.error).toBe('AuthenticationRequired')
+    })
+
+    it('maps 403 to Forbidden', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 403 }),
+      )
+      expect(err.error).toBe('Forbidden')
+    })
+
+    it('maps 404 to XRPCNotSupported', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 404 }),
+      )
+      expect(err.error).toBe('XRPCNotSupported')
+    })
+
+    it('maps 406 to NotAcceptable', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 406 }),
+      )
+      expect(err.error).toBe('NotAcceptable')
+    })
+
+    it('maps 413 to PayloadTooLarge', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 413 }),
+      )
+      expect(err.error).toBe('PayloadTooLarge')
+    })
+
+    it('maps 415 to UnsupportedMediaType', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 415 }),
+      )
+      expect(err.error).toBe('UnsupportedMediaType')
+    })
+
+    it('maps 429 to RateLimitExceeded', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 429 }),
+      )
+      expect(err.error).toBe('RateLimitExceeded')
+    })
+
+    it('maps 500 to InternalServerError', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 500 }),
+      )
+      expect(err.error).toBe('InternalServerError')
+    })
+
+    it('maps 501 to MethodNotImplemented', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 501 }),
+      )
+      expect(err.error).toBe('MethodNotImplemented')
+    })
+
+    it('maps 502 to UpstreamFailure', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 502 }),
+      )
+      expect(err.error).toBe('UpstreamFailure')
+    })
+
+    it('maps 503 to NotEnoughResources', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 503 }),
+      )
+      expect(err.error).toBe('NotEnoughResources')
+    })
+
+    it('maps 504 to UpstreamTimeout', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 504 }),
+      )
+      expect(err.error).toBe('UpstreamTimeout')
+    })
+
+    it('defaults to InvalidRequest for unmapped 4xx status codes', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 418 }),
+      )
+      expect(err.error).toBe('InvalidRequest')
+    })
+
+    it('defaults to UpstreamFailure for unmapped 5xx status codes', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 599 }),
+      )
+      expect(err.error).toBe('UpstreamFailure')
+    })
+
+    it('uses error from valid XRPC payload instead of status code mapping', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 400 }),
+        {
+          encoding: 'application/json',
+          body: { error: 'CustomError', message: 'Custom message' },
+        },
+      )
+      expect(err.error).toBe('CustomError')
+    })
   })
 
-  it('exposes headers from the response', () => {
+  it('exposes the response object', () => {
     const response = new Response(null, {
       status: 400,
       headers: { 'X-Test': 'value' },
@@ -57,12 +185,13 @@ describe(XrpcResponseError, () => {
       body: { error: 'TestError' },
     })
     expect(err.reason).toBe(err)
-    expect(err.headers.get('X-Test')).toBe('value')
+    expect(err.response.status).toBe(400)
+    expect(err.response.headers.get('X-Test')).toBe('value')
   })
 
   it('exposes body from the payload', () => {
     const err = createResponseError(400, 'TestError', 'details')
-    expect(err.body).toEqual({ error: 'TestError', message: 'details' })
+    expect(err.toJSON()).toEqual({ error: 'TestError', message: 'details' })
   })
 
   describe('toDownstreamError', () => {
@@ -102,13 +231,89 @@ describe(XrpcResponseError, () => {
         message: 'Record not found',
       })
     })
+
+    it('preserves 429 status for rate limiting', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 429 }),
+      )
+      expect(err.toDownstreamError().status).toBe(429)
+    })
+
+    it('converts 500 to 502', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 500 }),
+      )
+      expect(err.toDownstreamError().status).toBe(502)
+    })
+
+    it('strips hop-by-hop headers', () => {
+      const response = new Response(null, {
+        status: 400,
+        headers: {
+          'Content-Type': 'application/json',
+          Connection: 'keep-alive',
+          'Keep-Alive': 'timeout=5',
+          'Transfer-Encoding': 'chunked',
+        },
+      })
+      const err = new XrpcResponseError(testQuery, response, {
+        encoding: 'application/json',
+        body: { error: 'TestError' },
+      })
+      const downstream = err.toDownstreamError()
+
+      expect(downstream.headers?.has('Content-Type')).toBe(true)
+      expect(downstream.headers?.has('Connection')).toBe(false)
+      expect(downstream.headers?.has('Keep-Alive')).toBe(false)
+      expect(downstream.headers?.has('Transfer-Encoding')).toBe(false)
+    })
   })
 
   describe('toJSON', () => {
-    it('returns the payload body', () => {
+    it('returns the payload body for valid XRPC errors', () => {
       const err = createResponseError(400, 'TestError', 'message')
       expect(err.toJSON()).toEqual({ error: 'TestError', message: 'message' })
     })
+
+    it('constructs XRPC error from status code when payload is not valid XRPC', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 429 }),
+        { encoding: 'text/plain', body: 'Rate limit exceeded' },
+      )
+      expect(err.toJSON()).toEqual({
+        error: 'RateLimitExceeded',
+        message: 'Upstream server responded with a 429 error',
+      })
+    })
+
+    it('constructs XRPC error from status code when payload is missing', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 503 }),
+      )
+      expect(err.toJSON()).toEqual({
+        error: 'NotEnoughResources',
+        message: 'Upstream server responded with a 503 error',
+      })
+    })
+
+    it('returns valid XRPC payload unchanged', () => {
+      const err = new XrpcResponseError(
+        testQuery,
+        new Response(null, { status: 400 }),
+        {
+          encoding: 'application/json',
+          body: { error: 'CustomError', message: 'Custom message' },
+        },
+      )
+      expect(err.toJSON()).toEqual({
+        error: 'CustomError',
+        message: 'Custom message',
+      })
+    })
   })
 
   describe('matchesSchemaErrors', () => {
@@ -203,57 +408,63 @@ describe(XrpcAuthenticationError, () => {
 })
 
 // ============================================================================
-// XrpcUpstreamError
+// XrpcInvalidResponseError
 // ============================================================================
 
-describe(XrpcUpstreamError, () => {
-  it('has error code UpstreamFailure', () => {
-    const response = new Response(null, { status: 200 })
-    const err = new XrpcUpstreamError(testQuery, response)
+describe(XrpcInvalidResponseError, () => {
+  it('has error code InvalidResponse', () => {
+    const response = new Response(null, { status: 399 })
+    const err = new XrpcInvalidResponseError(testQuery, response)
     expect(err.reason).toBe(err)
-    expect(err.error).toBe('UpstreamFailure')
+    expect(err.error).toBe('InvalidResponse')
+    expect(err.toDownstreamError()).toMatchObject({
+      status: 502,
+      body: {
+        error: 'InvalidResponse',
+        message: 'Upstream server responded with an invalid status code (399)',
+      },
+    })
   })
 
-  it('toDownstreamError returns 502', () => {
-    const response = new Response(null, { status: 200 })
-    const err = new XrpcUpstreamError(testQuery, response)
-    const downstream = err.toDownstreamError()
-    expect(downstream.status).toBe(502)
+  it('toDownstreamError returns 502 for 500 upstream errors', () => {
+    const response = new Response(null, { status: 500 })
+    const err = new XrpcInvalidResponseError(testQuery, response)
+    expect(err.toDownstreamError().status).toBe(502)
   })
 
   it('shouldRetry is true for retryable status codes', () => {
     const response = new Response(null, { status: 502 })
-    const err = new XrpcUpstreamError(testQuery, response)
+    const err = new XrpcInvalidResponseError(testQuery, response)
     expect(err.shouldRetry()).toBe(true)
   })
 
   it('shouldRetry is false for non-retryable status codes', () => {
-    const response = new Response(null, { status: 200 })
-    const err = new XrpcUpstreamError(testQuery, response)
+    const response = new Response(null, { status: 400 })
+    const err = new XrpcInvalidResponseError(testQuery, response)
     expect(err.shouldRetry()).toBe(false)
   })
 })
 
 // ============================================================================
-// XrpcInvalidResponseError
+// XrpcResponseValidationError
 // ============================================================================
 
-describe(XrpcInvalidResponseError, () => {
-  it('extends XrpcUpstreamError', () => {
+describe(XrpcResponseValidationError, () => {
+  it('extends XrpcInvalidResponseError', () => {
     const response = new Response(null, { status: 200 })
     const validationError = new LexValidationError([
       new IssueInvalidType([], 42, ['string']),
     ])
-    const err = new XrpcInvalidResponseError(
+    const err = new XrpcResponseValidationError(
       testQuery,
       response,
       { encoding: 'application/json', body: { value: 42 } },
       validationError,
     )
 
-    expect(err).toBeInstanceOf(XrpcUpstreamError)
+    expect(err).toBeInstanceOf(XrpcInvalidResponseError)
     expect(err.reason).toBe(err)
-    expect(err.error).toBe('UpstreamFailure')
+    expect(err.error).toBe('InvalidResponse')
     expect(err.cause).toBe(validationError)
   })
 
@@ -261,14 +472,14 @@ describe(XrpcInvalidResponseError, () => {
     const validationError = new LexValidationError([
       new IssueInvalidType([], 42, ['string']),
     ])
-    const err = new XrpcInvalidResponseError(
+    const err = new XrpcResponseValidationError(
       testQuery,
       new Response(null, { status: 200 }),
       { encoding: 'application/json', body: { value: 42 } },
       validationError,
     )
 
-    expect(err.message).toContain('Invalid response:')
+    expect(err.message).toContain('Invalid response payload:')
     expect(err.message).toContain(validationError.message)
   })
 
@@ -276,7 +487,7 @@ describe(XrpcInvalidResponseError, () => {
     const validationError = new LexValidationError([
       new IssueInvalidType([], 42, ['string']),
     ])
-    const err = new XrpcInvalidResponseError(
+    const err = new XrpcResponseValidationError(
       testQuery,
       new Response(null, { status: 200 }),
       { encoding: 'application/json', body: { value: 42 } },

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`
+}