@lodestar/api 1.35.0-dev.f80d2d52da → 1.35.0-dev.fcf8d024ea

package/src/utils/client/response.ts

@@ -0,0 +1,205 @@
+import {HeadersExtra, HttpHeader, parseContentTypeHeader} from "../headers.js";
+import {HttpStatusCode} from "../httpStatusCode.js";
+import {Endpoint} from "../types.js";
+import {WireFormat, getWireFormat} from "../wireFormat.js";
+import {ApiError} from "./error.js";
+import {RouteDefinitionExtra} from "./request.js";
+
+export type RawBody =
+  | {type: WireFormat.json; value: unknown}
+  | {type: WireFormat.ssz; value: Uint8Array}
+  | {type?: never; value?: never};
+
+export class ApiResponse<E extends Endpoint> extends Response {
+  private definition: RouteDefinitionExtra<E>;
+  private _wireFormat?: WireFormat | null;
+  private _rawBody?: RawBody;
+  private _errorBody?: string;
+  private _meta?: E["meta"];
+  private _value?: E["return"];
+
+  constructor(definition: RouteDefinitionExtra<E>, body?: BodyInit | null, init?: ResponseInit) {
+    super(body, init);
+    this.definition = definition;
+  }
+
+  wireFormat(): WireFormat | null {
+    if (this._wireFormat === undefined) {
+      if (this.definition.resp.isEmpty) {
+        this._wireFormat = null;
+        return this._wireFormat;
+      }
+
+      const contentType = this.headers.get(HttpHeader.ContentType);
+      if (contentType === null) {
+        if (this.status === HttpStatusCode.NO_CONTENT) {
+          this._wireFormat = null;
+          return this._wireFormat;
+        }
+        throw Error("Content-Type header is required in response");
+      }
+
+      const mediaType = parseContentTypeHeader(contentType);
+      if (mediaType === null) {
+        throw Error(`Unsupported response media type: ${contentType.split(";", 1)[0]}`);
+      }
+
+      const wireFormat = getWireFormat(mediaType);
+
+      const {onlySupport} = this.definition.resp;
+      if (onlySupport !== undefined && wireFormat !== onlySupport) {
+        throw Error(`Method only supports ${onlySupport.toUpperCase()} responses`);
+      }
+
+      this._wireFormat = wireFormat;
+    }
+    return this._wireFormat;
+  }
+
+  async rawBody(): Promise<RawBody> {
+    this.assertOk();
+
+    if (!this._rawBody) {
+      switch (this.wireFormat()) {
+        case WireFormat.json:
+          this._rawBody = {
+            type: WireFormat.json,
+            value: await super.json(),
+          };
+          break;
+        case WireFormat.ssz:
+          this._rawBody = {
+            type: WireFormat.ssz,
+            value: new Uint8Array(await this.arrayBuffer()),
+          };
+          break;
+        default:
+          this._rawBody = {};
+      }
+    }
+    return this._rawBody;
+  }
+
+  meta(): E["meta"] {
+    this.assertOk();
+
+    if (!this._meta) {
+      switch (this.wireFormat()) {
+        case WireFormat.json: {
+          const rawBody = this.resolvedRawBody();
+          const metaJson = this.definition.resp.transform
+            ? this.definition.resp.transform.fromResponse(rawBody.value).meta
+            : rawBody.value;
+          this._meta = this.definition.resp.meta.fromJson(metaJson);
+          break;
+        }
+        case WireFormat.ssz:
+          this._meta = this.definition.resp.meta.fromHeaders(new HeadersExtra(this.headers));
+          break;
+      }
+    }
+    return this._meta;
+  }
+
+  value(): E["return"] {
+    this.assertOk();
+
+    if (!this._value) {
+      const rawBody = this.resolvedRawBody();
+      const meta = this.meta();
+      switch (rawBody.type) {
+        case WireFormat.json: {
+          const dataJson = this.definition.resp.transform
+            ? this.definition.resp.transform.fromResponse(rawBody.value).data
+            : (rawBody.value as Record<string, unknown>)?.data;
+          this._value = this.definition.resp.data.fromJson(dataJson, meta);
+          break;
+        }
+        case WireFormat.ssz:
+          this._value = this.definition.resp.data.deserialize(rawBody.value, meta);
+          break;
+      }
+    }
+    return this._value;
+  }
+
+  ssz(): Uint8Array {
+    this.assertOk();
+
+    const rawBody = this.resolvedRawBody();
+    switch (rawBody.type) {
+      case WireFormat.json:
+        return this.definition.resp.data.serialize(this.value(), this.meta());
+      case WireFormat.ssz:
+        return rawBody.value;
+      default:
+        return new Uint8Array();
+    }
+  }
+
+  json(): Awaited<ReturnType<Response["json"]>> {
+    this.assertOk();
+
+    const rawBody = this.resolvedRawBody();
+    switch (rawBody.type) {
+      case WireFormat.json:
+        return rawBody.value;
+      case WireFormat.ssz:
+        return this.definition.resp.data.toJson(this.value(), this.meta());
+      default:
+        return {};
+    }
+  }
+
+  assertOk(): void {
+    if (!this.ok) {
+      throw this.error();
+    }
+  }
+
+  error(): ApiError | null {
+    if (this.ok) {
+      return null;
+    }
+
+    return new ApiError(this.getErrorMessage(), this.status, this.definition.operationId);
+  }
+
+  async errorBody(): Promise<string> {
+    if (this._errorBody === undefined) {
+      this._errorBody = await this.text();
+    }
+    return this._errorBody;
+  }
+
+  private resolvedRawBody(): RawBody {
+    if (!this._rawBody) {
+      throw Error("rawBody() must be called first");
+    }
+    return this._rawBody;
+  }
+
+  private resolvedErrorBody(): string {
+    if (this._errorBody === undefined) {
+      throw Error("errorBody() must be called first");
+    }
+
+    return this._errorBody;
+  }
+
+  private getErrorMessage(): string {
+    const errBody = this.resolvedErrorBody();
+    try {
+      const errJson = JSON.parse(errBody) as {message?: string; failures?: {message: string}[]};
+      if (errJson.message) {
+        if (errJson.failures) {
+          return `${errJson.message}\n` + errJson.failures.map((e) => e.message).join("\n");
+        }
+        return errJson.message;
+      }
+      return errBody;
+    } catch (_e) {
+      return errBody || this.statusText;
+    }
+  }
+}

package/src/utils/codecs.ts

@@ -0,0 +1,143 @@
+import {ArrayType, ListBasicType, ListCompositeType, Type, isBasicType, isCompositeType} from "@chainsafe/ssz";
+import {ForkName} from "@lodestar/params";
+import {objectToExpectedCase} from "@lodestar/utils";
+import {
+  Endpoint,
+  RequestWithBodyCodec,
+  RequestWithoutBodyCodec,
+  ResponseCodec,
+  ResponseDataCodec,
+  ResponseMetadataCodec,
+  SszRequestMethods,
+} from "./types.js";
+import {WireFormat} from "./wireFormat.js";
+
+// Utility types / codecs
+
+export type EmptyArgs = void;
+export type EmptyRequest = Record<never, never>;
+export type EmptyResponseData = void;
+export type EmptyMeta = void;
+
+// biome-ignore lint/suspicious/noExplicitAny: We can not use `unknown` type here
+export type AnyEndpoint = Endpoint<any, any, any, any, any>;
+// biome-ignore lint/suspicious/noExplicitAny: We can not use `unknown` type here
+export type EmptyRequestEndpoint = Endpoint<any, EmptyArgs, EmptyRequest, any, any>;
+// biome-ignore lint/suspicious/noExplicitAny: We can not use `unknown` type here
+export type EmptyResponseEndpoint = Endpoint<any, any, any, EmptyResponseData, EmptyMeta>;
+
+/** Shortcut for routes that have no params, query */
+export const EmptyRequestCodec: RequestWithoutBodyCodec<EmptyRequestEndpoint> = {
+  writeReq: () => ({}),
+  parseReq: () => {},
+  schema: {},
+};
+
+export function JsonOnlyReq<E extends Endpoint>(
+  req: Omit<RequestWithBodyCodec<E>, keyof SszRequestMethods<E>>
+): RequestWithBodyCodec<E> {
+  return {
+    ...req,
+    writeReqSsz: () => {
+      throw Error("Not implemented");
+    },
+    parseReqSsz: () => {
+      throw Error("Not implemented");
+    },
+    onlySupport: WireFormat.json,
+  };
+}
+
+export const EmptyResponseDataCodec: ResponseDataCodec<EmptyResponseData, EmptyMeta> = {
+  toJson: () => {},
+  fromJson: () => {},
+  serialize: () => new Uint8Array(),
+  deserialize: () => {},
+};
+
+export const EmptyMetaCodec: ResponseMetadataCodec<EmptyMeta> = {
+  toJson: () => {},
+  fromJson: () => {},
+  toHeadersObject: () => ({}),
+  fromHeaders: () => {},
+};
+
+export const EmptyResponseCodec: ResponseCodec<EmptyResponseEndpoint> = {
+  data: EmptyResponseDataCodec,
+  meta: EmptyMetaCodec,
+  isEmpty: true,
+};
+
+export function ArrayOf<T>(elementType: Type<T>, limit = Infinity): ArrayType<Type<T>, unknown, unknown> {
+  if (isCompositeType(elementType)) {
+    return new ListCompositeType(elementType, limit) as unknown as ArrayType<Type<T>, unknown, unknown>;
+  }
+  if (isBasicType(elementType)) {
+    return new ListBasicType(elementType, limit) as unknown as ArrayType<Type<T>, unknown, unknown>;
+  }
+  throw Error(`Unknown type ${elementType.typeName}`);
+}
+
+export function WithMeta<T, M extends {version: ForkName}>(getType: (m: M) => Type<T>): ResponseDataCodec<T, M> {
+  return {
+    toJson: (data, meta: M) => getType(meta).toJson(data),
+    fromJson: (data, meta: M) => getType(meta).fromJson(data),
+    serialize: (data, meta: M) => getType(meta).serialize(data),
+    deserialize: (data, meta: M) => getType(meta).deserialize(data),
+  };
+}
+
+export function WithVersion<T, M extends {version: ForkName}>(
+  getType: (v: ForkName) => Type<T>
+): ResponseDataCodec<T, M> {
+  return {
+    toJson: (data, meta: M) => getType(meta.version).toJson(data),
+    fromJson: (data, meta: M) => getType(meta.version).fromJson(data),
+    serialize: (data, meta: M) => getType(meta.version).serialize(data),
+    deserialize: (data, meta: M) => getType(meta.version).deserialize(data),
+  };
+}
+
+export function JsonOnlyResp<E extends Endpoint>(
+  resp: Omit<ResponseCodec<E>, "data"> & {
+    data: Omit<ResponseCodec<E>["data"], "serialize" | "deserialize">;
+  }
+): ResponseCodec<E> {
+  return {
+    ...resp,
+    data: {
+      ...resp.data,
+      serialize: () => {
+        throw Error("Not implemented");
+      },
+      deserialize: () => {
+        throw Error("Not implemented");
+      },
+    },
+    onlySupport: WireFormat.json,
+  };
+}
+
+export const JsonOnlyResponseCodec: ResponseCodec<AnyEndpoint> = {
+  data: {
+    toJson: (data: Record<string, unknown>) => {
+      // JSON fields use snake case across all existing routes
+      return objectToExpectedCase(data, "snake");
+    },
+    fromJson: (data) => {
+      if (typeof data !== "object" || data === null) {
+        throw Error("JSON must be of type object");
+      }
+      // All JSON inside the JS code must be camel case
+      return objectToExpectedCase(data as Record<string, unknown>, "camel");
+    },
+    serialize: () => {
+      throw Error("Not implemented");
+    },
+    deserialize: () => {
+      throw Error("Not implemented");
+    },
+  },
+  meta: EmptyMetaCodec,
+  onlySupport: WireFormat.json,
+};

package/src/utils/fork.ts

@@ -0,0 +1,44 @@
+import {
+  ForkName,
+  ForkPostAltair,
+  ForkPostBellatrix,
+  ForkPostDeneb,
+  isForkPostAltair,
+  isForkPostBellatrix,
+  isForkPostDeneb,
+} from "@lodestar/params";
+import {SSZTypesFor, sszTypesFor} from "@lodestar/types";
+
+export function toForkName(version: string): ForkName {
+  // Teku returns fork as UPPERCASE
+  version = version.toLowerCase();
+
+  // Un-safe external data, validate version is known ForkName value
+  if (!(version in ForkName)) throw Error(`Invalid version ${version}`);
+
+  return version as ForkName;
+}
+
+export function getPostAltairForkTypes(fork: ForkName): SSZTypesFor<ForkPostAltair> {
+  if (!isForkPostAltair(fork)) {
+    throw Error(`Invalid fork=${fork} for post-altair fork types`);
+  }
+
+  return sszTypesFor(fork);
+}
+
+export function getPostBellatrixForkTypes(fork: ForkName): SSZTypesFor<ForkPostBellatrix> {
+  if (!isForkPostBellatrix(fork)) {
+    throw Error(`Invalid fork=${fork} for post-bellatrix fork types`);
+  }
+
+  return sszTypesFor(fork);
+}
+
+export function getPostDenebForkTypes(fork: ForkName): SSZTypesFor<ForkPostDeneb> {
+  if (!isForkPostDeneb(fork)) {
+    throw Error(`Invalid fork=${fork} for post-deneb fork types`);
+  }
+
+  return sszTypesFor(fork);
+}

package/src/utils/headers.ts

@@ -0,0 +1,173 @@
+import {toBase64} from "@lodestar/utils";
+
+export enum HttpHeader {
+  ContentType = "content-type",
+  Accept = "accept",
+  Authorization = "authorization",
+  /**
+   * Used to indicate which response headers should be made available to
+   * scripts running in the browser, in response to a cross-origin request.
+   * https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers
+   */
+  ExposeHeaders = "access-control-expose-headers",
+}
+
+export enum MediaType {
+  json = "application/json",
+  ssz = "application/octet-stream",
+}
+
+export const SUPPORTED_MEDIA_TYPES = Object.values(MediaType);
+
+function isSupportedMediaType(mediaType: string | null, supported: MediaType[]): mediaType is MediaType {
+  return mediaType !== null && supported.includes(mediaType as MediaType);
+}
+
+export function parseContentTypeHeader(contentType?: string): MediaType | null {
+  if (!contentType) {
+    return null;
+  }
+
+  const mediaType = contentType.split(";", 1)[0].trim().toLowerCase();
+
+  return isSupportedMediaType(mediaType, SUPPORTED_MEDIA_TYPES) ? mediaType : null;
+}
+
+export function parseAcceptHeader(accept?: string, supported = SUPPORTED_MEDIA_TYPES): MediaType | null {
+  if (!accept) {
+    return null;
+  }
+
+  // Respect Quality Values per RFC-9110
+  // Acceptable mime-types are comma separated with optional whitespace
+  return accept
+    .toLowerCase()
+    .split(",")
+    .map((x) => x.trim())
+    .reduce(
+      (best: [number, MediaType | null], current: string): [number, MediaType | null] => {
+        // An optional `;` delimiter is used to separate the mime-type from the weight
+        // Normalize here, using 1 as the default qvalue
+        const quality = current.includes(";") ? current.split(";") : [current, "q=1"];
+
+        let mediaType = quality[0].trim();
+
+        if (mediaType === "*/*") {
+          // Default to json if all media types are accepted
+          mediaType = MediaType.json;
+        }
+
+        // If the mime type isn't acceptable, move on to the next entry
+        if (!isSupportedMediaType(mediaType, supported)) {
+          return best;
+        }
+
+        // Otherwise, the portion after the semicolon has optional whitespace and the constant prefix "q="
+        const weight = quality[1].trim();
+        if (!weight.startsWith("q=")) {
+          // If the format is invalid simply move on to the next entry
+          return best;
+        }
+
+        const qvalue = +weight.replace("q=", "");
+        if (Number.isNaN(qvalue) || qvalue > 1 || qvalue <= 0) {
+          // If we can't convert the qvalue to a valid number, move on
+          return best;
+        }
+
+        if (qvalue < best[0]) {
+          // This mime type is not preferred
+          return best;
+        }
+
+        // This mime type is preferred
+        return [qvalue, mediaType];
+      },
+      [0, null]
+    )[1];
+}
+
+export function setAuthorizationHeader(url: URL, headers: Headers, {bearerToken}: {bearerToken?: string}): void {
+  if (bearerToken && !headers.has(HttpHeader.Authorization)) {
+    headers.set(HttpHeader.Authorization, `Bearer ${bearerToken}`);
+  }
+  if (url.username || url.password) {
+    if (!headers.has(HttpHeader.Authorization)) {
+      headers.set(HttpHeader.Authorization, `Basic ${toBase64(decodeURIComponent(`${url.username}:${url.password}`))}`);
+    }
+    // Remove the username and password from the URL
+    url.username = "";
+    url.password = "";
+  }
+}
+
+export function mergeHeaders(...headersList: (HeadersInit | undefined)[]): Headers {
+  const mergedHeaders = new Headers();
+
+  for (const headers of headersList) {
+    if (!headers) {
+      continue;
+    }
+    if (Array.isArray(headers)) {
+      for (const [key, value] of headers) {
+        mergedHeaders.set(key, value);
+      }
+    } else if (headers instanceof Headers) {
+      for (const [key, value] of headers as unknown as Iterable<[string, string]>) {
+        mergedHeaders.set(key, value);
+      }
+    } else {
+      for (const [key, value] of Object.entries(headers)) {
+        mergedHeaders.set(key, value);
+      }
+    }
+  }
+
+  return mergedHeaders;
+}
+
+/**
+ * Get header from request headers, by default an error will be thrown if the header
+ * is not present. The header can be marked as optional in which case the return value
+ * might be `undefined` but no error will be thrown if header is missing.
+ */
+export function fromHeaders<T extends Record<string, string | undefined>, R extends boolean = true>(
+  headers: T,
+  name: Extract<keyof T, string>,
+  required: R = true as R
+): R extends true ? string : string | undefined {
+  // Fastify converts all headers to lower case
+  const header = headers[name.toLowerCase()];
+
+  if (header === undefined && required) {
+    throw Error(`${name} header is required`);
+  }
+
+  return header as R extends true ? string : string | undefined;
+}
+
+/**
+ * Extension of Headers object returned by Fetch API
+ */
+export class HeadersExtra extends Headers {
+  /**
+   * Get required header from response headers
+   */
+  getRequired(name: string): string {
+    const header = this.get(name);
+
+    if (header === null) {
+      throw Error(`${name} header is required in response`);
+    }
+
+    return header;
+  }
+
+  /**
+   * Get optional header from response headers.
+   * Return default value if it does not exist
+   */
+  getOrDefault(name: string, defaultValue: string): string {
+    return this.get(name) ?? defaultValue;
+  }
+}