@atproto/lex-client 0.0.9 → 0.0.11

package/src/errors.ts

@@ -1,28 +1,26 @@
 import { LexError, LexErrorCode, LexErrorData } from '@atproto/lex-data'
-import { l } from '@atproto/lex-schema'
-import { Payload } from './util.js'
+import {
+  InferMethodError,
+  Procedure,
+  Query,
+  ResultFailure,
+  lexErrorDataSchema,
+} from '@atproto/lex-schema'
+import { XrpcPayload } from './util.js'
+import {
+  WWWAuthenticate,
+  parseWWWAuthenticateHeader,
+} from './www-authenticate.js'
+
+export const RETRYABLE_HTTP_STATUS_CODES: ReadonlySet<number> = new Set([
+  408, 425, 429, 500, 502, 503, 504, 522, 524,
+])
 
 export { LexError }
 export type { LexErrorCode, LexErrorData }
 
-export type LexRpcErrorPayload<N extends LexErrorCode = LexErrorCode> = Payload<
-  LexErrorData<N>,
-  'application/json'
->
-
-export class LexRpcError<
-  N extends LexErrorCode = LexErrorCode,
-> extends LexError<N> {
-  name = 'LexRpcError'
-
-  constructor(
-    error: N,
-    message: string = `${error} Lexicon RPC error`,
-    options?: ErrorOptions,
-  ) {
-    super(error, message, options)
-  }
-}
+export type XrpcErrorPayload<N extends LexErrorCode = LexErrorCode> =
+  XrpcPayload<LexErrorData<N>, 'application/json'>
 
 /**
  * All unsuccessful responses should follow a standard error response
@@ -36,174 +34,209 @@ export class LexRpcError<
  *
  * This function checks whether a given payload matches this schema.
  */
-export function isLexRpcErrorPayload(
-  payload: Payload | null,
-): payload is LexRpcErrorPayload {
+export function isXrpcErrorPayload(
+  payload: XrpcPayload | null,
+): payload is XrpcErrorPayload {
   return (
     payload !== null &&
     payload.encoding === 'application/json' &&
-    l.lexErrorData.matches(payload.body)
+    lexErrorDataSchema.matches(payload.body)
   )
 }
 
-/**
- * Interface representing a failed XRPC request result.
- */
-type LexRpcFailureResult<N extends LexErrorCode, E> = l.ResultFailure<E> & {
-  readonly error: N
-  shouldRetry(): boolean
-  matchesSchema(): boolean
-}
-
-/**
- * Class used to represent an HTTP request that resulted in an XRPC method error
- * That is, a non-2xx response with a valid XRPC error payload.
- */
-export class LexRpcResponseError<
-    M extends l.Procedure | l.Query = l.Procedure | l.Query,
+export abstract class XrpcError<
+    M extends Procedure | Query = Procedure | Query,
     N extends LexErrorCode = LexErrorCode,
+    TReason = unknown,
   >
-  extends LexRpcError<N>
-  implements LexRpcFailureResult<N, LexRpcResponseError<M, N>>
+  extends LexError<N>
+  implements ResultFailure<TReason>
 {
-  name = 'LexRpcResponseError'
+  name = 'XrpcError'
 
   constructor(
     readonly method: M,
-    readonly status: number,
-    readonly headers: Headers,
-    readonly payload: LexRpcErrorPayload<N>,
+    error: N,
+    message: string = `${error} Lexicon RPC error`,
     options?: ErrorOptions,
   ) {
-    const { error, message } = payload.body
     super(error, message, options)
   }
 
-  readonly success = false
+  /**
+   * @see {@link ResultFailure.success}
+   */
+  readonly success = false as const
+
+  /**
+   * @see {@link ResultFailure.reason}
+   */
+  abstract readonly reason: TReason
+
+  /**
+   * Indicates whether the error is transient and can be retried.
+   */
+  abstract shouldRetry(): boolean
 
-  get reason(): this {
-    return this as this
+  matchesSchema(): this is XrpcError<M, InferMethodError<M>> {
+    return this.method.errors?.includes(this.error) ?? false
   }
+}
 
-  get body(): LexErrorData {
-    return this.payload.body
+/**
+ * Class used to represent an HTTP request that resulted in an XRPC method
+ * error. That is, a non-2xx response with a valid XRPC error payload.
+ */
+export class XrpcResponseError<
+  M extends Procedure | Query = Procedure | Query,
+  N extends LexErrorCode = InferMethodError<M> | LexErrorCode,
+> extends XrpcError<M, N, XrpcResponseError<M, N>> {
+  name = 'XrpcResponseError'
+
+  constructor(
+    method: M,
+    readonly response: Response,
+    readonly payload: XrpcErrorPayload<N>,
+    options?: ErrorOptions,
+  ) {
+    const { error, message } = payload.body
+    super(method, error, message, options)
   }
 
-  matchesSchema(): this is M extends {
-    errors: readonly (infer E extends string)[]
+  override get reason(): this {
+    return this
   }
-    ? LexRpcResponseError<M, E>
-    : never {
-    return this.method.errors?.includes(this.error) ?? false
+
+  override shouldRetry(): boolean {
+    return RETRYABLE_HTTP_STATUS_CODES.has(this.response.status)
   }
 
-  shouldRetry(): boolean {
-    // Do not retry client errors
-    if (this.status < 500) return false
+  override toJSON() {
+    return this.payload.body
+  }
 
-    return true
+  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 })
+    }
+
+    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 })
   }
 
-  toJSON() {
+  get body(): LexErrorData {
     return this.payload.body
   }
+}
+
+export type { WWWAuthenticate }
+export class XrpcAuthenticationError<
+  M extends Procedure | Query = Procedure | Query,
+  N extends LexErrorCode = LexErrorCode,
+> extends XrpcResponseError<M, N> {
+  name = 'XrpcAuthenticationError'
+
+  override shouldRetry(): boolean {
+    return false
+  }
 
-  toResponse(): Response {
-    const { status, headers } = this
-    return Response.json(this.toJSON(), { status, headers })
+  #wwwAuthenticate?: WWWAuthenticate
+  get wwwAuthenticate(): WWWAuthenticate {
+    return (this.#wwwAuthenticate ??=
+      parseWWWAuthenticateHeader(
+        this.response.headers.get('www-authenticate'),
+      ) ?? {})
   }
 }
 
 /**
- * This class represents an invalid XRPC response from the server.
+ * This class represents invalid or unprocessable XRPC response from the
+ * upstream server.
  */
-export class LexRpcUpstreamError<
-    N extends 'InvalidResponse' | 'UpstreamFailure' =
-      | 'InvalidResponse'
-      | 'UpstreamFailure',
-  >
-  extends LexRpcError<N>
-  implements LexRpcFailureResult<N, LexRpcUpstreamError<N>>
-{
-  name = 'LexRpcUpstreamError' as const
-
-  // For debugging purposes, we keep the response details here
-  readonly response: {
-    status: number
-    headers: Headers
-    payload: Payload | null
-  }
+export class XrpcUpstreamError<
+  M extends Procedure | Query = Procedure | Query,
+> extends XrpcError<M, 'UpstreamFailure', XrpcUpstreamError<M>> {
+  name = 'XrpcUpstreamError'
 
   constructor(
-    error: N,
-    message: string,
-    response: { status: number; headers: Headers },
-    payload: Payload | null,
+    method: M,
+    readonly response: Response,
+    readonly payload: XrpcPayload | null,
+    message: string = `Unexpected upstream XRPC response`,
     options?: ErrorOptions,
   ) {
-    super(error, message, { cause: options?.cause })
-    this.response = {
-      status: response.status,
-      headers: response.headers,
-      payload,
-    }
+    super(method, 'UpstreamFailure', message, options)
   }
 
-  readonly success = false as const
-
-  get reason(): this {
+  override get reason(): this {
     return this
   }
 
-  matchesSchema(): false {
-    return false
+  override shouldRetry(): boolean {
+    return RETRYABLE_HTTP_STATUS_CODES.has(this.response.status)
   }
 
-  shouldRetry(): boolean {
-    // Do not retry client errors
-    return this.response.status >= 500
-  }
-
-  toResponse(): Response {
+  override toResponse(): Response {
     return Response.json(this.toJSON(), { status: 502 })
   }
 }
 
-export class LexRpcUnexpectedError
-  extends LexRpcError<'InternalServerError'>
-  implements LexRpcFailureResult<'InternalServerError', unknown>
-{
-  name = 'LexRpcUnexpectedError' as const
+export class XrpcInternalError<
+  M extends Procedure | Query = Procedure | Query,
+> extends XrpcError<M, 'InternalServerError', XrpcInternalError<M>> {
+  name = 'XrpcInternalError'
 
-  protected constructor(message: string, options: Required<ErrorOptions>) {
-    super('InternalServerError', message, options)
+  constructor(method: M, message?: string, options?: ErrorOptions) {
+    super(
+      method,
+      'InternalServerError',
+      message ?? 'Unable to fulfill XRPC request',
+      options,
+    )
   }
 
-  readonly success = false
-
-  get reason() {
-    return this.cause
-  }
-
-  matchesSchema(): false {
-    return false
+  override get reason(): this {
+    return this
   }
 
-  shouldRetry(): boolean {
+  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.
     return true
   }
 
-  toResponse(): Response {
-    return Response.json(this.toJSON(), { status: 500 })
+  override toResponse(): Response {
+    // Do not expose internal error details to downstream clients
+    return Response.json({ error: this.error }, { status: 500 })
   }
+}
 
-  static from(
-    cause: unknown,
-    message: string = cause instanceof LexError
-      ? cause.message
-      : 'XRPC request failed',
-  ): LexRpcUnexpectedError {
-    if (cause instanceof LexRpcUnexpectedError) return cause
-    return new LexRpcUnexpectedError(message, { cause })
+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>
+  // Something went wrong (network error, etc.)
+  | XrpcInternalError<M>
+
+export function asXrpcFailure<M extends Procedure | Query>(
+  method: M,
+  cause: unknown,
+): XrpcFailure<M> {
+  if (
+    cause instanceof XrpcResponseError ||
+    cause instanceof XrpcUpstreamError ||
+    cause instanceof XrpcInternalError
+  ) {
+    if (cause.method === method) return cause
   }
+
+  return new XrpcInternalError(method, undefined, { cause })
 }

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

@@ -17,7 +17,10 @@ const main =
       repo: /*#__PURE__*/ l.string({ format: 'at-identifier' }),
       collection: /*#__PURE__*/ l.string({ format: 'nsid' }),
       limit: /*#__PURE__*/ l.optional(
-        /*#__PURE__*/ l.integer({ minimum: 1, maximum: 100, default: 50 }),
+        /*#__PURE__*/ l.withDefault(
+          /*#__PURE__*/ l.integer({ minimum: 1, maximum: 100 }),
+          50,
+        ),
       ),
       cursor: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
       reverse: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),

package/src/response.ts

@@ -7,27 +7,28 @@ import {
   ResultSuccess,
 } from '@atproto/lex-schema'
 import {
-  LexRpcResponseError,
-  LexRpcUpstreamError,
-  isLexRpcErrorPayload,
+  XrpcAuthenticationError,
+  XrpcResponseError,
+  XrpcUpstreamError,
+  isXrpcErrorPayload,
 } from './errors.js'
-import { Payload } from './util.js'
+import { XrpcPayload } from './util.js'
 
-export type LexRpcResponseBody<M extends Procedure | Query> =
+export type XrpcResponseBody<M extends Procedure | Query> =
   InferMethodOutputBody<M, Uint8Array>
 
-export type LexRpcResponsePayload<M extends Procedure | Query> =
+export type XrpcResponsePayload<M extends Procedure | Query> =
   InferMethodOutputEncoding<M> extends infer E extends string
-    ? Payload<LexRpcResponseBody<M>, E>
+    ? XrpcPayload<XrpcResponseBody<M>, E>
     : null
 
 /**
  * Small container for XRPC response data.
  *
- * @implements {ResultSuccess<LexRpcResponse<M>>} for convenience in result handling contexts.
+ * @implements {ResultSuccess<XrpcResponse<M>>} for convenience in result handling contexts.
  */
-export class LexRpcResponse<const M extends Procedure | Query>
-  implements ResultSuccess<LexRpcResponse<M>>
+export class XrpcResponse<M extends Procedure | Query>
+  implements ResultSuccess<XrpcResponse<M>>
 {
   /** @see {@link ResultSuccess.success} */
   readonly success = true as const
@@ -41,7 +42,7 @@ export class LexRpcResponse<const M extends Procedure | Query>
     readonly method: M,
     readonly status: number,
     readonly headers: Headers,
-    readonly payload: LexRpcResponsePayload<M>,
+    readonly payload: XrpcResponsePayload<M>,
   ) {}
 
   /**
@@ -57,21 +58,22 @@ export class LexRpcResponse<const M extends Procedure | Query>
   }
 
   get body() {
-    return this.payload?.body as LexRpcResponseBody<M>
+    return this.payload?.body as XrpcResponseBody<M>
   }
 
   /**
-   * @throws {LexRpcResponseError} in case of (valid) XRPC error responses. Use
-   * {@link LexRpcResponseError.matchesSchema} to narrow the error type based on
-   * the method's declared error schema.
-   * @throws {LexRpcUpstreamError} when the response is not a valid XRPC
+   * @throws {XrpcResponseError} in case of (valid) XRPC error responses. Use
+   * {@link XrpcResponseError.matchesSchema} 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
    * response, or if the response does not conform to the method's schema.
    */
   static async fromFetchResponse<const M extends Procedure | Query>(
     method: M,
     response: Response,
     options?: { validateResponse?: boolean },
-  ): Promise<LexRpcResponse<M>> {
+  ): Promise<XrpcResponse<M>> {
     // @NOTE The body MUST either be read or canceled to avoid resource leaks.
     // Since nothing should cause an exception before "readPayload" is
     // called, we can safely not use a try/finally here.
@@ -79,88 +81,96 @@ export class LexRpcResponse<const M extends Procedure | Query>
     // @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
-      const payload = await readPayload(response, { parse: true })
-
-      if (response.status >= 400 && isLexRpcErrorPayload(payload)) {
-        throw new LexRpcResponseError(
-          method,
-          response.status,
-          response.headers,
-          payload,
-        )
-      }
+      const payload = await readPayload(response, { parse: true }).catch(
+        (cause) => {
+          throw new XrpcUpstreamError(
+            method,
+            response,
+            null,
+            'Unable to parse response payload',
+            { cause },
+          )
+        },
+      )
 
-      if (response.status >= 500) {
-        throw new LexRpcUpstreamError(
-          'UpstreamFailure',
-          `Upstream server encountered an error`,
-          response,
-          payload,
-        )
+      // 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)
       }
 
-      throw new LexRpcUpstreamError(
-        'InvalidResponse',
-        response.status >= 400
-          ? `Upstream server returned an invalid response payload`
-          : `Upstream server returned an invalid status code`,
+      // Invalid XRPC response (we probably did not hit an XRPC implementation)
+      throw new XrpcUpstreamError(
+        method,
         response,
         payload,
+        response.status >= 500
+          ? 'Upstream server encountered an error'
+          : response.status >= 400
+            ? 'Invalid response payload'
+            : 'Invalid response status code',
       )
     }
 
     // Only parse json if the schema expects it
     const payload = await readPayload(response, {
       parse: shouldParse(method),
+    }).catch((cause) => {
+      throw new XrpcUpstreamError(
+        method,
+        response,
+        null,
+        'Unable to parse response payload',
+        { cause },
+      )
     })
 
     // Response is successful (2xx). Validate payload (data and encoding) against schema.
     if (method.output.encoding == null) {
       // Schema expects no payload
       if (payload) {
-        throw new LexRpcUpstreamError(
-          'InvalidResponse',
-          `Expected response with no body, got ${payload.encoding}`,
+        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 LexRpcUpstreamError(
-          'InvalidResponse',
+        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}`,
-          response,
-          payload,
         )
       }
 
       // Assert valid response body.
       if (method.output.schema && options?.validateResponse !== false) {
-        const result = method.output.schema.safeParse(payload.body, {
-          allowTransform: false,
-        })
+        const result = method.output.schema.safeParse(payload.body)
 
         if (!result.success) {
-          throw new LexRpcUpstreamError(
-            'InvalidResponse',
-            `Response validation failed: ${result.reason.message}`,
+          throw new XrpcUpstreamError(
+            method,
             response,
             payload,
+            `Response validation failed: ${result.reason.message}`,
             { cause: result.reason },
           )
         }
       }
     }
 
-    return new LexRpcResponse<M>(
+    return new XrpcResponse<M>(
       method,
       response.status,
       response.headers,
-      payload as LexRpcResponsePayload<M>,
+      payload as XrpcResponsePayload<M>,
     )
   }
 }
@@ -175,7 +185,7 @@ function shouldParse(method: Procedure | Query) {
 async function readPayload(
   response: Response,
   options?: { parse?: boolean },
-): Promise<Payload | null> {
+): Promise<XrpcPayload | null> {
   // @TODO Should we limit the maximum response size here (this could also be
   // done by the FetchHandler)?
 
@@ -206,22 +216,12 @@ async function readPayload(
     // to @ipld/dag-json)
     const text = await response.text()
 
-    try {
-      // @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) }
-    } catch (cause) {
-      throw new LexRpcUpstreamError(
-        'InvalidResponse',
-        'Invalid JSON response body',
-        response,
-        null,
-        { cause },
-      )
-    }
+    // @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) }
   }
 
   return { encoding, body: new Uint8Array(await response.arrayBuffer()) }

package/src/util.ts

@@ -1,6 +1,6 @@
 import { DidString } from '@atproto/lex-schema'
 
-export type Payload<B = unknown, E extends string = string> = {
+export type XrpcPayload<B = unknown, E extends string = string> = {
   body: B
   encoding: E
 }