@atproto/lex-client 0.0.14 → 0.0.16

package/src/errors.test.ts

@@ -0,0 +1,415 @@
+import { describe, expect, it } from 'vitest'
+import { IssueInvalidType, LexValidationError, l } from '@atproto/lex-schema'
+import {
+  XrpcAuthenticationError,
+  XrpcFetchError,
+  XrpcInternalError,
+  XrpcInvalidResponseError,
+  XrpcResponseError,
+  XrpcUpstreamError,
+  asXrpcFailure,
+} from './errors.js'
+
+// Minimal method fixture
+const testQuery = l.query(
+  'io.example.test',
+  l.params(),
+  l.jsonPayload({ value: l.string() }),
+  ['TestError', 'AnotherError'],
+)
+
+const testQueryNoErrors = l.query(
+  'io.example.noErrors',
+  l.params(),
+  l.jsonPayload({ value: l.string() }),
+)
+
+// ============================================================================
+// XrpcResponseError
+// ============================================================================
+
+describe(XrpcResponseError, () => {
+  function createResponseError(
+    status: number,
+    errorCode: string,
+    message?: string,
+  ) {
+    const response = new Response(null, { status })
+    return new XrpcResponseError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: errorCode, message },
+    })
+  }
+
+  it('exposes status from the response', () => {
+    const err = createResponseError(404, 'NotFound')
+    expect(err.reason).toBe(err)
+    expect(err.status).toBe(404)
+  })
+
+  it('exposes headers from the response', () => {
+    const response = new Response(null, {
+      status: 400,
+      headers: { 'X-Test': 'value' },
+    })
+    const err = new XrpcResponseError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'TestError' },
+    })
+    expect(err.reason).toBe(err)
+    expect(err.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' })
+  })
+
+  describe('toDownstreamError', () => {
+    it('returns 502 for upstream 500 errors', () => {
+      const err = createResponseError(
+        500,
+        'InternalServerError',
+        'Upstream crashed',
+      )
+      const downstream = err.toDownstreamError()
+
+      expect(downstream.status).toBe(502)
+      expect(downstream.body).toEqual({
+        error: 'InternalServerError',
+        message: 'Upstream crashed',
+      })
+    })
+
+    it('preserves original status for non-500 5xx errors', () => {
+      const err = createResponseError(503, 'ServiceUnavailable', 'Try later')
+      const downstream = err.toDownstreamError()
+
+      expect(downstream.status).toBe(503)
+      expect(downstream.body).toEqual({
+        error: 'ServiceUnavailable',
+        message: 'Try later',
+      })
+    })
+
+    it('preserves original status for 4xx errors', () => {
+      const err = createResponseError(404, 'NotFound', 'Record not found')
+      const downstream = err.toDownstreamError()
+
+      expect(downstream.status).toBe(404)
+      expect(downstream.body).toEqual({
+        error: 'NotFound',
+        message: 'Record not found',
+      })
+    })
+  })
+
+  describe('toJSON', () => {
+    it('returns the payload body', () => {
+      const err = createResponseError(400, 'TestError', 'message')
+      expect(err.toJSON()).toEqual({ error: 'TestError', message: 'message' })
+    })
+  })
+
+  describe('matchesSchemaErrors', () => {
+    it('returns true when error matches method declared errors', () => {
+      const err = createResponseError(400, 'TestError')
+      expect(err.matchesSchemaErrors()).toBe(true)
+    })
+
+    it('returns false for undeclared error codes', () => {
+      const err = createResponseError(400, 'UnknownError')
+      expect(err.matchesSchemaErrors()).toBe(false)
+    })
+
+    it('returns false when method has no declared errors', () => {
+      const response = new Response(null, { status: 400 })
+      const err = new XrpcResponseError(testQueryNoErrors, response, {
+        encoding: 'application/json',
+        body: { error: 'SomeError' },
+      })
+      expect(err.matchesSchemaErrors()).toBe(false)
+    })
+  })
+
+  describe('shouldRetry', () => {
+    it('returns true for retryable status codes', () => {
+      expect(createResponseError(429, 'RateLimit').shouldRetry()).toBe(true)
+      expect(createResponseError(500, 'Internal').shouldRetry()).toBe(true)
+      expect(createResponseError(502, 'BadGateway').shouldRetry()).toBe(true)
+      expect(createResponseError(503, 'Unavailable').shouldRetry()).toBe(true)
+    })
+
+    it('returns false for non-retryable status codes', () => {
+      expect(createResponseError(400, 'BadRequest').shouldRetry()).toBe(false)
+      expect(createResponseError(401, 'Unauthorized').shouldRetry()).toBe(false)
+      expect(createResponseError(404, 'NotFound').shouldRetry()).toBe(false)
+    })
+  })
+})
+
+// ============================================================================
+// XrpcAuthenticationError
+// ============================================================================
+
+describe(XrpcAuthenticationError, () => {
+  it('is never retryable', () => {
+    const response = new Response(null, { status: 401 })
+    const err = new XrpcAuthenticationError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'AuthenticationRequired' },
+    })
+    expect(err.shouldRetry()).toBe(false)
+  })
+
+  it('parses WWW-Authenticate header', () => {
+    const response = new Response(null, {
+      status: 401,
+      headers: {
+        'WWW-Authenticate': 'Bearer realm="api", error="InvalidToken"',
+      },
+    })
+    const err = new XrpcAuthenticationError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'AuthenticationRequired' },
+    })
+    expect(err.reason).toBe(err)
+    expect(err.wwwAuthenticate).toHaveProperty('Bearer')
+  })
+
+  it('returns empty object when no WWW-Authenticate header', () => {
+    const response = new Response(null, { status: 401 })
+    const err = new XrpcAuthenticationError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'AuthenticationRequired' },
+    })
+    expect(err.wwwAuthenticate).toEqual({})
+  })
+
+  it('toDownstreamError always returns 401', () => {
+    const response = new Response(null, { status: 401 })
+    const err = new XrpcAuthenticationError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'AuthenticationRequired', message: 'No token' },
+    })
+    const downstream = err.toDownstreamError()
+
+    expect(downstream.status).toBe(401)
+    expect(downstream.body).toEqual({
+      error: 'AuthenticationRequired',
+      message: 'No token',
+    })
+  })
+})
+
+// ============================================================================
+// XrpcUpstreamError
+// ============================================================================
+
+describe(XrpcUpstreamError, () => {
+  it('has error code UpstreamFailure', () => {
+    const response = new Response(null, { status: 200 })
+    const err = new XrpcUpstreamError(testQuery, response)
+    expect(err.reason).toBe(err)
+    expect(err.error).toBe('UpstreamFailure')
+  })
+
+  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('shouldRetry is true for retryable status codes', () => {
+    const response = new Response(null, { status: 502 })
+    const err = new XrpcUpstreamError(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)
+    expect(err.shouldRetry()).toBe(false)
+  })
+})
+
+// ============================================================================
+// XrpcInvalidResponseError
+// ============================================================================
+
+describe(XrpcInvalidResponseError, () => {
+  it('extends XrpcUpstreamError', () => {
+    const response = new Response(null, { status: 200 })
+    const validationError = new LexValidationError([
+      new IssueInvalidType([], 42, ['string']),
+    ])
+    const err = new XrpcInvalidResponseError(
+      testQuery,
+      response,
+      { encoding: 'application/json', body: { value: 42 } },
+      validationError,
+    )
+
+    expect(err).toBeInstanceOf(XrpcUpstreamError)
+    expect(err.reason).toBe(err)
+    expect(err.error).toBe('UpstreamFailure')
+    expect(err.cause).toBe(validationError)
+  })
+
+  it('includes validation error message', () => {
+    const validationError = new LexValidationError([
+      new IssueInvalidType([], 42, ['string']),
+    ])
+    const err = new XrpcInvalidResponseError(
+      testQuery,
+      new Response(null, { status: 200 }),
+      { encoding: 'application/json', body: { value: 42 } },
+      validationError,
+    )
+
+    expect(err.message).toContain('Invalid response:')
+    expect(err.message).toContain(validationError.message)
+  })
+
+  it('toDownstreamError returns 502', () => {
+    const validationError = new LexValidationError([
+      new IssueInvalidType([], 42, ['string']),
+    ])
+    const err = new XrpcInvalidResponseError(
+      testQuery,
+      new Response(null, { status: 200 }),
+      { encoding: 'application/json', body: { value: 42 } },
+      validationError,
+    )
+    const downstream = err.toDownstreamError()
+    expect(downstream.status).toBe(502)
+  })
+})
+
+// ============================================================================
+// XrpcInternalError
+// ============================================================================
+
+describe(XrpcInternalError, () => {
+  it('has error code InternalServerError', () => {
+    const err = new XrpcInternalError(testQuery)
+    expect(err.reason).toBe(err)
+    expect(err.error).toBe('InternalServerError')
+  })
+
+  it('toJSON does not expose internal details', () => {
+    const err = new XrpcInternalError(
+      testQuery,
+      'Secret database connection string leaked',
+    )
+    const json = err.toJSON()
+
+    expect(json.error).toBe('InternalServerError')
+    expect(json.message).toBe('Internal Server Error')
+    expect(json.message).not.toContain('Secret')
+  })
+
+  it('toDownstreamError returns 500', () => {
+    const err = new XrpcInternalError(testQuery, 'internal details')
+    const downstream = err.toDownstreamError()
+
+    expect(downstream.status).toBe(500)
+    expect(downstream.body.error).toBe('InternalServerError')
+    expect(downstream.body.message).toBe('Internal Server Error')
+  })
+
+  it('is not retryable', () => {
+    const err = new XrpcInternalError(testQuery, 'something broke')
+    expect(err.shouldRetry()).toBe(false)
+  })
+})
+
+// ============================================================================
+// XrpcFetchError
+// ============================================================================
+
+describe(XrpcFetchError, () => {
+  it('extends XrpcInternalError', () => {
+    const err = new XrpcFetchError(testQuery, new TypeError('fetch failed'))
+    expect(err).toBeInstanceOf(XrpcInternalError)
+    expect(err.error).toBe('InternalServerError')
+  })
+
+  it('uses cause message when cause is an Error', () => {
+    const cause = new TypeError('Failed to fetch')
+    const err = new XrpcFetchError(testQuery, cause)
+    expect(err.message).toBe('Unexpected fetchHandler() error: Failed to fetch')
+    expect(err.cause).toBe(cause)
+  })
+
+  it('uses fallback message when cause is not an Error', () => {
+    const err = new XrpcFetchError(testQuery, 'string cause')
+    expect(err.message).toBe('Unexpected fetchHandler() error: string cause')
+    expect(err.cause).toBe('string cause')
+  })
+
+  it('is retryable', () => {
+    const err = new XrpcFetchError(testQuery, new Error('network timeout'))
+    expect(err.shouldRetry()).toBe(true)
+  })
+
+  it('toJSON does not expose internal details', () => {
+    const err = new XrpcFetchError(
+      testQuery,
+      new Error('ECONNREFUSED 10.0.0.1:443'),
+    )
+    const json = err.toJSON()
+
+    expect(json.error).toBe('InternalServerError')
+    expect(json.message).toBe('Failed to perform upstream request')
+    expect(json.message).not.toContain('ECONNREFUSED')
+  })
+
+  it('toDownstreamError returns 502', () => {
+    const err = new XrpcFetchError(testQuery, new Error('DNS lookup failed'))
+    const downstream = err.toDownstreamError()
+
+    expect(downstream.status).toBe(502)
+    expect(downstream.body.error).toBe('InternalServerError')
+    expect(downstream.body.message).toBe('Failed to perform upstream request')
+  })
+})
+
+// ============================================================================
+// asXrpcFailure
+// ============================================================================
+
+describe('asXrpcFailure', () => {
+  it('returns existing XrpcResponseError for the same method', () => {
+    const response = new Response(null, { status: 400 })
+    const err = new XrpcResponseError(testQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'TestError' },
+    })
+    expect(asXrpcFailure(testQuery, err)).toBe(err)
+  })
+
+  it('wraps unknown errors in XrpcInternalError', () => {
+    const err = new TypeError('fetch failed')
+    const failure = asXrpcFailure(testQuery, err)
+
+    expect(failure).toBeInstanceOf(XrpcInternalError)
+    expect(failure.cause).toBe(err)
+  })
+
+  it('wraps XrpcError for a different method in XrpcInternalError', () => {
+    const otherQuery = l.query(
+      'io.example.other',
+      l.params(),
+      l.payload('application/json', l.object({ value: l.string() })),
+    )
+    const response = new Response(null, { status: 400 })
+    const err = new XrpcResponseError(otherQuery, response, {
+      encoding: 'application/json',
+      body: { error: 'TestError' },
+    })
+    const failure = asXrpcFailure(testQuery, err)
+    expect(failure).toBeInstanceOf(XrpcInternalError)
+  })
+})

package/src/errors.ts

@@ -1,17 +1,27 @@
 import { LexError, LexErrorCode, LexErrorData } from '@atproto/lex-data'
 import {
   InferMethodError,
+  LexValidationError,
   Procedure,
   Query,
   ResultFailure,
   lexErrorDataSchema,
 } from '@atproto/lex-schema'
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { Agent } from './agent.js'
 import { XrpcResponsePayload } from './util.js'
 import {
   WWWAuthenticate,
   parseWWWAuthenticateHeader,
 } from './www-authenticate.js'
 
+export type DownstreamError<N extends LexErrorCode = LexErrorCode> = {
+  status: number
+  headers?: Headers
+  encoding?: 'application/json'
+  body: LexErrorData<N>
+}
+
 /**
  * HTTP status codes that indicate a transient error that may succeed on retry.
  *
@@ -115,7 +125,9 @@ export abstract class XrpcError<
    */
   abstract shouldRetry(): boolean
 
-  matchesSchema(): this is XrpcError<M, InferMethodError<M>> {
+  abstract toDownstreamError(): DownstreamError
+
+  matchesSchemaErrors(): this is XrpcError<M, InferMethodError<M>> {
     return this.method.errors?.includes(this.error) ?? false
   }
 }
@@ -127,7 +139,7 @@ export abstract class XrpcError<
  * a non-2xx status with a valid JSON error payload containing `error` and
  * optional `message` fields.
  *
- * Use {@link matchesSchema} to check if the error matches the method's declared
+ * Use {@link matchesSchemaErrors} to check if the error matches the method's declared
  * error types for type-safe error handling.
  *
  * @typeParam M - The XRPC method type
@@ -168,25 +180,32 @@ export class XrpcResponseError<
     return RETRYABLE_HTTP_STATUS_CODES.has(this.response.status)
   }
 
-  override toJSON() {
+  override toJSON(): LexErrorData<N> {
     return this.payload.body
   }
 
-  override toResponse(): Response {
-    // Re-expose schema-valid errors as-is to downstream clients
-    if (this.matchesSchema()) {
-      const status = this.response.status >= 500 ? 502 : this.response.status
-      return Response.json(this.toJSON(), { status })
+  override toDownstreamError(): DownstreamError {
+    // If the upstream server returned a 5xx 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),
+      body: this.toJSON(),
     }
+  }
+
+  get status(): number {
+    return this.response.status
+  }
 
-    return this.response.status >= 500
-      ? // The upstream server had an error, return a generic upstream failure
-        Response.json({ error: 'UpstreamFailure' }, { status: 502 })
-      : // If the error is on our side, return a generic internal server error
-        Response.json({ error: 'InternalServerError' }, { status: 500 })
+  get headers(): Headers {
+    return this.response.headers
   }
 
-  get body(): LexErrorData {
+  get body(): LexErrorData<N> {
     return this.payload.body
   }
 }
@@ -240,6 +259,14 @@ export class XrpcAuthenticationError<
         this.response.headers.get('www-authenticate'),
       ) ?? {})
   }
+
+  override toDownstreamError(): DownstreamError {
+    return {
+      status: 401,
+      headers: stripHopByHopHeaders(this.headers),
+      body: this.toJSON(),
+    }
+  }
 }
 
 /**
@@ -280,23 +307,53 @@ export class XrpcUpstreamError<
     return RETRYABLE_HTTP_STATUS_CODES.has(this.response.status)
   }
 
-  override toResponse(): Response {
-    return Response.json(this.toJSON(), { status: 502 })
+  override toDownstreamError(): DownstreamError {
+    return { status: 502, body: this.toJSON() }
   }
 }
 
 /**
- * Error class for internal/client-side errors during XRPC requests.
+ * Error class for invalid XRPC responses that fail schema validation.
  *
- * 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
+ * This is a specific type of {@link XrpcUpstreamError} 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
+ * XRPC implementation.
+ *
+ * @typeParam M - The XRPC method type
+ */
+export class XrpcInvalidResponseError<
+  M extends Procedure | Query = Procedure | Query,
+> extends XrpcUpstreamError<M> {
+  name = 'XrpcInvalidResponseError'
+
+  constructor(
+    method: M,
+    response: Response,
+    payload: XrpcResponsePayload,
+    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() }
+  }
+}
+
+/**
+ * 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
  */
@@ -318,17 +375,60 @@ 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.
+  override shouldRetry(): boolean {
+    return false
+  }
+
+  override toJSON(): LexErrorData {
+    // @NOTE Do not expose internal error details to downstream clients
+    return { error: this.error, message: 'Internal Server Error' }
+  }
+
+  override toDownstreamError(): DownstreamError {
+    return { status: 500, body: this.toJSON() }
+  }
+}
+
+/**
+ * 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 toResponse(): Response {
-    // Do not expose internal error details to downstream clients
-    return Response.json({ error: this.error }, { status: 500 })
+  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() }
   }
 }
 
@@ -393,3 +493,39 @@ export function asXrpcFailure<M extends Procedure | Query>(
 
   return new XrpcInternalError(method, undefined, { cause })
 }
+
+const HOP_BY_HOP_HEADERS = new Set([
+  'connection',
+  'keep-alive',
+  'proxy-authenticate',
+  'proxy-authorization',
+  'te',
+  'trailer',
+  'transfer-encoding',
+  'upgrade',
+])
+
+function stripHopByHopHeaders(headers: Headers): Headers {
+  const result = new Headers(headers)
+
+  // Remove statically known hop-by-hop headers
+  for (const name of HOP_BY_HOP_HEADERS) {
+    result.delete(name)
+  }
+
+  // Remove headers listed in the "Connection" header
+  const connection = headers.get('connection')
+  if (connection) {
+    for (const name of connection.split(',')) {
+      result.delete(name.trim())
+    }
+  }
+
+  // These are not actually hop-by-hop headers, but we remove them because the
+  // upstream payload gets parsed and re-serialized, so content length and
+  // encoding may no longer be accurate.
+  result.delete('content-length')
+  result.delete('content-encoding')
+
+  return result
+}