@atproto/lex-client 0.0.13 → 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,
           )
         }
       }

package/src/xrpc.ts

@@ -4,6 +4,7 @@ import {
   InferInput,
   InferPayload,
   Main,
+  NsidString,
   Params,
   Payload,
   Procedure,
@@ -12,7 +13,7 @@ import {
   Subscription,
   getMain,
 } from '@atproto/lex-schema'
-import { Agent } from './agent.js'
+import { Agent, AgentOptions, buildAgent } from './agent.js'
 import { XrpcFailure, asXrpcFailure } from './errors.js'
 import { XrpcResponse } from './response.js'
 import { BinaryBodyInit, CallOptions } from './types.js'
@@ -77,8 +78,7 @@ export type XrpcOptions<M extends Procedure | Query = Procedure | Query> =
 /**
  * Makes an XRPC request and throws on failure.
  *
- * This is the low-level function for making XRPC calls. For most use cases,
- * prefer using {@link Client.xrpc} which provides a more ergonomic API.
+ * This is the low-level function for making XRPC calls.
  *
  * @param agent - The {@link Agent} to use for making the request
  * @param ns - The lexicon method definition
@@ -88,28 +88,35 @@ export type XrpcOptions<M extends Procedure | Query = Procedure | Query> =
  *
  * @example
  * ```typescript
+ * const response = await xrpc('https://bsky.network', com.atproto.identity.resolveHandle, {
+ *   params: { handle: "atproto.com" }
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
  * const response = await xrpc(agent, app.bsky.feed.getTimeline.main, {
  *   params: { limit: 50 }
  * })
  * ```
  */
 export async function xrpc<const M extends Query | Procedure>(
-  agent: Agent,
+  agentOpts: Agent | AgentOptions,
   ns: NonNullable<unknown> extends XrpcOptions<M>
     ? Main<M>
     : Restricted<'This XRPC method requires an "options" argument'>,
 ): Promise<XrpcResponse<M>>
 export async function xrpc<const M extends Query | Procedure>(
-  agent: Agent,
+  agentOpts: Agent | AgentOptions,
   ns: Main<M>,
   options: XrpcOptions<M>,
 ): Promise<XrpcResponse<M>>
 export async function xrpc<const M extends Query | Procedure>(
-  agent: Agent,
+  agentOpts: Agent | AgentOptions,
   ns: Main<M>,
   options: XrpcOptions<M> = {} as XrpcOptions<M>,
 ): Promise<XrpcResponse<M>> {
-  const response = await xrpcSafe<M>(agent, ns, options)
+  const response = await xrpcSafe<M>(agentOpts, ns, options)
   if (response.success) return response
   else throw response
 }
@@ -141,7 +148,7 @@ export type XrpcResult<M extends Procedure | Query> =
  *
  * @example
  * ```typescript
- * const result = await xrpcSafe(agent, app.bsky.actor.getProfile.main, {
+ * const result = await xrpcSafe('https://example.com', app.bsky.actor.getProfile, {
  *   params: { actor: 'alice.bsky.social' }
  * })
  *
@@ -153,24 +160,25 @@ export type XrpcResult<M extends Procedure | Query> =
  * ```
  */
 export async function xrpcSafe<const M extends Query | Procedure>(
-  agent: Agent,
+  agentOpts: Agent | AgentOptions,
   ns: NonNullable<unknown> extends XrpcOptions<M>
     ? Main<M>
     : Restricted<'This XRPC method requires an "options" argument'>,
 ): Promise<XrpcResult<M>>
 export async function xrpcSafe<const M extends Query | Procedure>(
-  agent: Agent,
+  agentOpts: Agent | AgentOptions,
   ns: Main<M>,
   options: XrpcOptions<M>,
 ): Promise<XrpcResult<M>>
 export async function xrpcSafe<const M extends Query | Procedure>(
-  agent: Agent,
+  agentOpts: Agent | AgentOptions,
   ns: Main<M>,
   options: XrpcOptions<M> = {} as XrpcOptions<M>,
 ): Promise<XrpcResult<M>> {
   options.signal?.throwIfAborted()
   const method: M = getMain(ns)
   try {
+    const agent = buildAgent(agentOpts)
     const url = xrpcRequestUrl(method, options)
     const request = xrpcRequestInit(method, options)
     const response = await agent.fetchHandler(url, request)
@@ -183,14 +191,14 @@ export async function xrpcSafe<const M extends Query | Procedure>(
 function xrpcRequestUrl<M extends Procedure | Query | Subscription>(
   method: M,
   options: CallOptions & { params?: Params },
-) {
-  const path = `/xrpc/${method.nsid}`
+): `/xrpc/${NsidString}${'' | `?${string}`}` {
+  const path = `/xrpc/${method.nsid}` as const
 
   const queryString = method.parameters
     ?.toURLSearchParams(options.params ?? {})
     .toString()
 
-  return queryString ? `${path}?${queryString}` : path
+  return queryString ? (`${path}?${queryString}` as const) : path
 }
 
 function xrpcRequestInit<T extends Procedure | Query>(