@atproto/lex-client 0.0.3 → 0.0.5

package/src/lexicons/com/atproto/sync/getBlob.defs.ts

@@ -0,0 +1,37 @@
+/*
+ * THIS FILE WAS GENERATED BY "@atproto/lex". DO NOT EDIT.
+ */
+
+import { l } from '@atproto/lex-schema'
+
+const $nsid = 'com.atproto.sync.getBlob'
+
+export { $nsid }
+
+/** Get a blob associated with a given account. Returns the full blob as originally uploaded. Does not require auth; implemented by PDS. */
+const main =
+  /*#__PURE__*/
+  l.query(
+    $nsid,
+    /*#__PURE__*/ l.params({
+      did: /*#__PURE__*/ l.string({ format: 'did' }),
+      cid: /*#__PURE__*/ l.string({ format: 'cid' }),
+    }),
+    /*#__PURE__*/ l.payload('*/*'),
+    [
+      'BlobNotFound',
+      'RepoNotFound',
+      'RepoTakendown',
+      'RepoSuspended',
+      'RepoDeactivated',
+    ],
+  )
+export { main }
+
+export type Params = l.InferMethodParams<typeof main>
+export type Output = l.InferMethodOutput<typeof main>
+export type OutputBody = l.InferMethodOutputBody<typeof main>
+
+export const $lxm = /*#__PURE__*/ main.nsid,
+  $params = main.parameters,
+  $output = main.output

package/src/lexicons/com/atproto/sync/getBlob.ts

@@ -0,0 +1,6 @@
+/*
+ * THIS FILE WAS GENERATED BY "@atproto/lex". DO NOT EDIT.
+ */
+
+export * from './getBlob.defs.js'
+export * as $defs from './getBlob.defs.js'

package/src/lexicons/com/atproto/sync.ts

@@ -0,0 +1,5 @@
+/*
+ * THIS FILE WAS GENERATED BY "@atproto/lex". DO NOT EDIT.
+ */
+
+export * as getBlob from './sync/getBlob.js'

package/src/lexicons/com/atproto.ts

@@ -3,3 +3,4 @@
  */
 
 export * as repo from './atproto/repo.js'
+export * as sync from './atproto/sync.js'

package/src/lexicons.ts

@@ -0,0 +1 @@
+export * as com from './lexicons/com.js'

package/src/types.ts

@@ -10,10 +10,37 @@ export type CallOptions = {
   signal?: AbortSignal
   headers?: HeadersInit
   service?: Service
+
+  /**
+   * Whether to validate the request against the method's input schema. Enabling
+   * this can help catch errors early but may have a performance cost. This
+   * would typically only be set to `true` in development or debugging
+   * scenarios.
+   *
+   * @default false
+   */
   validateRequest?: boolean
+
+  /**
+   * Whether to validate the response against the method's output schema.
+   * Disabling this can improve performance but may lead to runtime errors if
+   * the response does not conform to the expected schema. Only set this to
+   * `false` if you are certain that the upstream service will always return
+   * valid responses.
+   *
+   * @default true
+   */
   validateResponse?: boolean
 }
 
+export type BinaryBodyInit =
+  | Uint8Array
+  | ArrayBuffer
+  | Blob
+  | ReadableStream<Uint8Array>
+  | AsyncIterable<Uint8Array>
+  | string
+
 export type Namespace<T> = T | { main: T }
 
 export function getMain<T extends object>(ns: Namespace<T>): T {

package/src/util.ts

@@ -0,0 +1,84 @@
+import { DidString } from '@atproto/lex-schema'
+
+export type Payload<B = unknown, E extends string = string> = {
+  body: B
+  encoding: E
+}
+
+export function isBlobLike(value: unknown): value is Blob {
+  if (value == null) return false
+  if (typeof value !== 'object') return false
+  if (typeof Blob === 'function' && value instanceof Blob) return true
+
+  // Support for Blobs provided by libraries that don't use the native Blob
+  // (e.g. fetch-blob from node-fetch).
+  // https://github.com/node-fetch/fetch-blob/blob/a1a182e5978811407bef4ea1632b517567dda01f/index.js#L233-L244
+
+  const tag = (value as any)[Symbol.toStringTag]
+  if (tag === 'Blob' || tag === 'File') {
+    return 'stream' in value && typeof value.stream === 'function'
+  }
+
+  return false
+}
+
+export function isAsyncIterable<T>(
+  value: T,
+): value is unknown extends T
+  ? T & AsyncIterable<unknown>
+  : Extract<T, AsyncIterable<any>> {
+  return (
+    value != null && typeof (value as any)[Symbol.asyncIterator] === 'function'
+  )
+}
+
+export function buildAtprotoHeaders(options: {
+  headers?: HeadersInit
+  service?: `${DidString}#${string}`
+  labelers?: Iterable<DidString>
+}): Headers {
+  const headers = new Headers(options?.headers)
+
+  if (options.service && !headers.has('atproto-proxy')) {
+    headers.set('atproto-proxy', options.service)
+  }
+
+  if (options.labelers) {
+    headers.set(
+      'atproto-accept-labelers',
+      [...options.labelers, headers.get('atproto-accept-labelers')?.trim()]
+        .filter(Boolean)
+        .join(', '),
+    )
+  }
+
+  return headers
+}
+
+export function toReadableStream(
+  data: AsyncIterable<Uint8Array>,
+): ReadableStream<Uint8Array> {
+  // Use the native ReadableStream.from() if available.
+  if ('from' in ReadableStream && typeof ReadableStream.from === 'function') {
+    return ReadableStream.from(data)
+  }
+
+  let iterator: AsyncIterator<Uint8Array> | undefined
+  return new ReadableStream({
+    async pull(controller) {
+      try {
+        iterator ??= data[Symbol.asyncIterator]()
+        const result = await iterator!.next()
+        if (result.done) controller.close()
+        else controller.enqueue(result.value)
+      } catch (err) {
+        controller.error(err)
+        iterator = undefined
+      }
+    },
+    async cancel() {
+      await iterator?.return?.()
+      iterator = undefined
+    },
+  })
+}

package/src/xrpc-error.ts

@@ -0,0 +1,195 @@
+import { l } from '@atproto/lex-schema'
+import { Payload } from './util.js'
+
+export type XrpcErrorCode = string
+export const xrpcErrorCodeSchema: l.Schema<XrpcErrorCode> = l.string({
+  minLength: 1,
+})
+
+export class XrpcError<N extends XrpcErrorCode = XrpcErrorCode> extends Error {
+  name = 'XrpcError'
+
+  constructor(
+    readonly error: N,
+    message: string = `An ${error} XRPC error occurred.`,
+    options?: ErrorOptions,
+  ) {
+    super(message, options)
+  }
+}
+
+export type XrpcErrorBody<N extends XrpcErrorCode = XrpcErrorCode> = {
+  error: N
+  message?: string
+}
+export type XrpcErrorPayload<N extends XrpcErrorCode = XrpcErrorCode> = {
+  encoding: 'application/json'
+  body: XrpcErrorBody<N>
+}
+
+const xrpcErrorBodySchema: l.Schema<XrpcErrorBody> = l.object({
+  error: xrpcErrorCodeSchema,
+  message: l.optional(l.string()),
+})
+
+/**
+ * All unsuccessful responses should follow a standard error response
+ * schema. The Content-Type should be application/json, and the payload
+ * should be a JSON object with the following fields:
+ *
+ * - `error` (string, required): type name of the error (generic ASCII
+ *   constant, no whitespace)
+ * - `message` (string, optional): description of the error, appropriate for
+ *   display to humans
+ *
+ * This function checks whether a given payload matches this schema.
+ */
+export function isXrpcErrorPayload(
+  payload: Payload | null,
+): payload is XrpcErrorPayload {
+  return (
+    payload !== null &&
+    payload.encoding === 'application/json' &&
+    xrpcErrorBodySchema.matches(payload.body)
+  )
+}
+
+/**
+ * Interface representing a failed XRPC request result.
+ */
+type XrpcFailureResult<N extends XrpcErrorCode, 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 XrpcResponseError<
+    M extends l.Procedure | l.Query = l.Procedure | l.Query,
+    N extends XrpcErrorCode = XrpcErrorCode,
+  >
+  extends XrpcError<N>
+  implements XrpcFailureResult<N, XrpcResponseError<M, N>>
+{
+  name = 'XrpcResponseError' as const
+
+  constructor(
+    readonly method: M,
+    readonly status: number,
+    readonly headers: Headers,
+    readonly payload: XrpcErrorPayload<N>,
+    options?: ErrorOptions,
+  ) {
+    const { error, message } = payload.body
+    super(error, message, options)
+  }
+
+  readonly success = false
+
+  get reason(): this {
+    return this as this
+  }
+
+  get body(): XrpcErrorBody {
+    return this.payload.body
+  }
+
+  matchesSchema(): this is M extends {
+    errors: readonly (infer E extends string)[]
+  }
+    ? XrpcResponseError<M, E>
+    : never {
+    return this.method.errors?.includes(this.error) ?? false
+  }
+
+  shouldRetry(): boolean {
+    // Do not retry client errors
+    if (this.status < 500) return false
+
+    return true
+  }
+}
+
+/**
+ * This class represents an invalid XRPC response from the server.
+ */
+export class XrpcInvalidResponseError
+  extends XrpcError<'UpstreamFailure'>
+  implements XrpcFailureResult<'UpstreamFailure', XrpcInvalidResponseError>
+{
+  name = 'XrpcInvalidResponseError' as const
+
+  // For debugging purposes, we keep the response details here
+  readonly response: {
+    status: number
+    headers: Headers
+    payload: Payload | null
+  }
+
+  constructor(
+    message: string,
+    response: { status: number; headers: Headers },
+    payload: Payload | null,
+    options?: ErrorOptions,
+  ) {
+    super('UpstreamFailure', message, { cause: options?.cause })
+    this.response = {
+      status: response.status,
+      headers: response.headers,
+      payload,
+    }
+  }
+
+  readonly success = false as const
+
+  get reason(): this {
+    return this
+  }
+
+  matchesSchema(): false {
+    return false
+  }
+
+  shouldRetry(): boolean {
+    // Do not retry client errors
+    return this.response.status >= 500
+  }
+}
+
+export class XrpcUnexpectedError
+  extends XrpcError<'InternalServerError'>
+  implements XrpcFailureResult<'InternalServerError', unknown>
+{
+  name = 'XrpcUnexpectedError' as const
+
+  protected constructor(message: string, options: Required<ErrorOptions>) {
+    super('InternalServerError', message, options)
+  }
+
+  readonly success = false
+
+  get reason() {
+    return this.cause
+  }
+
+  matchesSchema(): false {
+    return false
+  }
+
+  shouldRetry(): boolean {
+    return true
+  }
+
+  static from(
+    cause: unknown,
+    message: string = cause instanceof XrpcError
+      ? cause.message
+      : 'XRPC request failed',
+  ): XrpcUnexpectedError {
+    if (cause instanceof XrpcUnexpectedError) return cause
+    return new XrpcUnexpectedError(message, { cause })
+  }
+}

package/src/xrpc-response.ts

@@ -0,0 +1,213 @@
+import { lexParse } from '@atproto/lex-json'
+import {
+  InferMethodOutputBody,
+  InferMethodOutputEncoding,
+  Procedure,
+  Query,
+  ResultSuccess,
+} from '@atproto/lex-schema'
+import { Payload } from './util.js'
+import {
+  XrpcInvalidResponseError,
+  XrpcResponseError,
+  isXrpcErrorPayload,
+} from './xrpc-error.js'
+
+export type XrpcResponseBody<M extends Procedure | Query> =
+  InferMethodOutputBody<M, Uint8Array>
+
+export type XrpcResponsePayload<M extends Procedure | Query> =
+  InferMethodOutputEncoding<M> extends infer E extends string
+    ? Payload<XrpcResponseBody<M>, E>
+    : null
+
+/**
+ * Small container for XRPC response data.
+ *
+ * @implements {ResultSuccess<XrpcResponse<M>>} for convenience in result handling contexts.
+ */
+export class XrpcResponse<const M extends Procedure | Query>
+  implements ResultSuccess<XrpcResponse<M>>
+{
+  /** @see {@link ResultSuccess.success} */
+  readonly success = true as const
+
+  /** @see {@link ResultSuccess.value} */
+  get value(): this {
+    return this
+  }
+
+  constructor(
+    readonly method: M,
+    readonly status: number,
+    readonly headers: Headers,
+    readonly payload: XrpcResponsePayload<M>,
+  ) {}
+
+  /**
+   * Whether the response payload was parsed as {@link LexValue} (`true`) or is
+   * in binary form {@link Uint8Array} (`false`).
+   */
+  get isParsed() {
+    return this.encoding === 'application/json' && shouldParse(this.method)
+  }
+
+  get encoding() {
+    return this.payload?.encoding as InferMethodOutputEncoding<M>
+  }
+
+  get body() {
+    return this.payload?.body as XrpcResponseBody<M>
+  }
+
+  /**
+   * @throws {XrpcInvalidResponseError} when the response is invalid according
+   * to the method schema.
+   */
+  static async fromFetchResponse<const M extends Procedure | Query>(
+    method: M,
+    response: Response,
+    options?: { validateResponse?: boolean },
+  ): 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.
+
+    // @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 && isXrpcErrorPayload(payload)) {
+        throw new XrpcResponseError(
+          method,
+          response.status,
+          response.headers,
+          payload,
+        )
+      }
+
+      throw new XrpcInvalidResponseError(
+        response.status >= 500
+          ? `Upstream server encountered an error`
+          : response.status >= 400
+            ? `Upstream server returned an invalid response payload`
+            : `Upstream server returned an invalid status code`,
+        response,
+        payload,
+      )
+    }
+
+    // Only parse json if the schema expects it
+    const payload = await readPayload(response, {
+      parse: shouldParse(method),
+    })
+
+    // Response is successful (2xx). Validate payload (data and encoding) against schema.
+    if (method.output.encoding == null) {
+      // Schema expects no payload
+      if (payload) {
+        throw new XrpcInvalidResponseError(
+          `Expected response with no body, got ${payload.encoding}`,
+          response,
+          payload,
+        )
+      }
+    } else {
+      // Schema expects a payload
+      if (!payload || !method.output.matchesEncoding(payload.encoding)) {
+        throw new XrpcInvalidResponseError(
+          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,
+        })
+
+        if (!result.success) {
+          throw new XrpcInvalidResponseError(
+            `Response validation failed: ${result.reason.message}`,
+            response,
+            payload,
+            { cause: result.reason },
+          )
+        }
+      }
+    }
+
+    return new XrpcResponse<M>(
+      method,
+      response.status,
+      response.headers,
+      payload as XrpcResponsePayload<M>,
+    )
+  }
+}
+
+function shouldParse(method: Procedure | Query) {
+  return method.output.encoding === 'application/json'
+}
+
+/**
+ * @note this function always consumes the response body
+ */
+async function readPayload(
+  response: Response,
+  options?: { parse?: boolean },
+): Promise<Payload | null> {
+  // @TODO Should we limit the maximum response size here (this could also be
+  // done by the FetchHandler)?
+
+  const encoding = response.headers
+    .get('content-type')
+    ?.split(';')[0]
+    .trim()
+    .toLowerCase()
+
+  // Response content-type is undefined
+  if (!encoding) {
+    // If the body is empty, return null (= no payload)
+    const body = await response.arrayBuffer()
+    if (body.byteLength === 0) return null
+
+    // If we got data despite no content-type, treat it as binary
+    return {
+      encoding: 'application/octet-stream',
+      body: new Uint8Array(body),
+    }
+  }
+
+  if (options?.parse && encoding === 'application/json') {
+    // @NOTE It might be worth returning the raw bytes here (Uint8Array) and
+    // perform the lex parsing using cborg/json, allowing to do
+    // bytes->LexValue in one step instead of bytes->text->JSON->LexValue.
+    // This would require adding encode/decode utilities to lex-json (similar
+    // 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 XrpcInvalidResponseError(
+        'Invalid JSON response body',
+        response,
+        null,
+        { cause },
+      )
+    }
+  }
+
+  return { encoding, body: new Uint8Array(await response.arrayBuffer()) }
+}