@atproto/lex-client 0.0.14 → 0.0.15

package/src/errors.ts

@@ -1,6 +1,7 @@
 import { LexError, LexErrorCode, LexErrorData } from '@atproto/lex-data'
 import {
   InferMethodError,
+  LexValidationError,
   Procedure,
   Query,
   ResultFailure,
@@ -12,6 +13,13 @@ import {
   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 +123,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 +137,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 +178,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(),
     }
+  }
 
-    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 status(): number {
+    return this.response.status
   }
 
-  get body(): LexErrorData {
+  get headers(): Headers {
+    return this.response.headers
+  }
+
+  get body(): LexErrorData<N> {
     return this.payload.body
   }
 }
@@ -240,6 +257,14 @@ export class XrpcAuthenticationError<
         this.response.headers.get('www-authenticate'),
       ) ?? {})
   }
+
+  override toDownstreamError(): DownstreamError {
+    return {
+      status: 401,
+      headers: stripHopByHopHeaders(this.headers),
+      body: this.toJSON(),
+    }
+  }
 }
 
 /**
@@ -280,8 +305,44 @@ 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 invalid XRPC responses that fail schema validation.
+ *
+ * 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() }
   }
 }
 
@@ -326,9 +387,13 @@ export class XrpcInternalError<
     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<'InternalServerError'> {
+    // @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() }
   }
 }
 
@@ -393,3 +458,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
+}

package/src/response.ts

@@ -7,6 +7,7 @@ import {
 } from '@atproto/lex-schema'
 import {
   XrpcAuthenticationError,
+  XrpcInvalidResponseError,
   XrpcResponseError,
   XrpcUpstreamError,
   isXrpcErrorPayload,
@@ -70,7 +71,7 @@ export class XrpcResponse<M extends Procedure | Query>
 
   /**
    * @throws {XrpcResponseError} in case of (valid) XRPC error responses. Use
-   * {@link XrpcResponseError.matchesSchema} to narrow the error type based on
+   * {@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
@@ -162,12 +163,11 @@ export class XrpcResponse<M extends Procedure | Query>
         const result = method.output.schema.safeParse(payload.body)
 
         if (!result.success) {
-          throw new XrpcUpstreamError(
+          throw new XrpcInvalidResponseError(
             method,
             response,
             payload,
-            `Response validation failed: ${result.reason.message}`,
-            { cause: result.reason },
+            result.reason,
           )
         }
       }