Merge pull request #1274 from hypercerts-org/feat/timeouts

fix(http): unopiniated timeouts on calls. 1.4.2-alpha.1

Author: bitbeckers

sdk/RELEASE.md

@@ -4,6 +4,8 @@
 
 - Improve ESM support by exporting `index.mjs` instead of `index.js`. @baumstern
 - Added dweb IPFS gateway links and use `Promise.any` call to try and fetch data from multiple gateways.
+- Expose timeout on HTTP requests from storage layer up to client wrapper methods as optional config.
+- Default timeout on calls of 0 ms (no timeout) to avoid issues with large files or multiple IPFS calls.
 
 ## New contributors
 

sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypercerts-org/sdk",
-  "version": "1.4.2-alpha.0",
+  "version": "1.4.2-alpha.1",
   "description": "SDK for hypercerts protocol",
   "repository": "[email protected]:hypercerts-org/hypercerts.git",
   "author": "Hypercerts team",

sdk/src/client.ts

@@ -145,7 +145,7 @@ export class HypercertClient implements HypercertClientInterface {
     const { account } = this.getWallet();
 
     // validate and store metadata
-    const metadataCID = await this.storage.storeMetadata(metaData);
+    const metadataCID = await this.storage.storeMetadata(metaData, { timeout: overrides?.timeout });
 
     const request = await this.simulateRequest(
       account,
@@ -259,11 +259,13 @@ export class HypercertClient implements HypercertClientInterface {
     const tree = parseAllowListEntriesToMerkleTree(allowList);
 
     // store allowlist on IPFS
-    const allowListCID = await this.storage.storeAllowList(allowList, totalUnits);
+    const allowListCID = await this.storage.storeAllowList(allowList, totalUnits, { timeout: overrides?.timeout });
 
     // store metadata on IPFS
-    const metadataCID = await this.storage.storeMetadata({ ...metaData, allowList: allowListCID });
-
+    const metadataCID = await this.storage.storeMetadata(
+      { ...metaData, allowList: allowListCID },
+      { timeout: overrides?.timeout },
+    );
     const request = await this.simulateRequest(
       account,
       "createAllowlist",

sdk/src/storage.ts

@@ -5,6 +5,7 @@ import {
   MalformedDataError,
   StorageError,
   AllowlistEntry,
+  StorageConfigOverrides,
 } from "./types";
 import { logger, getFromIPFS, parseAllowListEntriesToMerkleTree } from "./utils";
 import { uploadAllowlist, uploadMetadata } from "./utils/apis";
@@ -26,11 +27,17 @@ export class HypercertsStorage implements HypercertStorageInterface {
    * If the metadata is valid, it creates a new Blob from the metadata and stores it using the hypercerts API. If the storage operation fails, it throws a `StorageError`.
    *
    * @param {AllowlistEntry[]} allowList - The allowList to store.
+   * @param {bigin} totalUnits - The total number of units in the allowlist.
+   * @param {StorageConfigOverrides} [config] - An optional configuration object.
    * @returns {Promise<string>} A promise that resolves to the CID of the stored metadata.
    * @throws {StorageError} Will throw a `StorageError` if the storage operation fails.
    * @throws {MalformedDataError} Will throw a `MalformedDataError` if the provided metadata is invalid.
    */
-  public async storeAllowList(allowList: AllowlistEntry[], totalUnits: bigint): Promise<string> {
+  public async storeAllowList(
+    allowList: AllowlistEntry[],
+    totalUnits: bigint,
+    config: StorageConfigOverrides = { timeout: 0 },
+  ): Promise<string> {
     const { valid, data, errors: allowlistErrors } = validateAllowlist(allowList, totalUnits);
     if (!valid) {
       throw new MalformedDataError(`Invalid allowList.`, { errors: allowlistErrors });
@@ -42,10 +49,13 @@ export class HypercertsStorage implements HypercertStorageInterface {
 
     logger.debug("Allowlist tree: ", "storage", [tree]);
 
-    const { data: resData, errors: uploadAllowlistErrors } = await uploadAllowlist({
-      allowList: JSON.stringify(tree.dump()),
-      totalUnits: totalUnits.toString(),
-    });
+    const { data: resData, errors: uploadAllowlistErrors } = await uploadAllowlist(
+      {
+        allowList: JSON.stringify(tree.dump()),
+        totalUnits: totalUnits.toString(),
+      },
+      config,
+    );
 
     const allowlistCID = resData?.cid;
 
@@ -65,19 +75,23 @@ export class HypercertsStorage implements HypercertStorageInterface {
    * If the metadata is valid, it creates a new Blob from the metadata and stores it using the hypercerts API. If the storage operation fails, it throws a `StorageError`.
    *
    * @param {HypercertMetadata} data - The Hypercert metadata to store. This should be an object that conforms to the HypercertMetadata type.
+   * @param {StorageConfigOverrides} [config] - An optional configuration object.
    * @returns {Promise<string>} A promise that resolves to the CID of the stored metadata.
    * @throws {StorageError} Will throw a `StorageError` if the storage operation fails.
    * @throws {MalformedDataError} Will throw a `MalformedDataError` if the provided metadata is invalid.
    */
-  public async storeMetadata(metadata: HypercertMetadata): Promise<string> {
+  public async storeMetadata(
+    metadata: HypercertMetadata,
+    config: StorageConfigOverrides = { timeout: 0 },
+  ): Promise<string> {
     const { data, valid, errors: validationErrors } = validateMetaData(metadata);
     if (!valid) {
       throw new MalformedDataError(`Invalid metadata.`, { errors: validationErrors });
     }
 
     logger.debug("Storing HypercertMetaData: ", "storage", [data]);
 
-    const { errors, data: resData } = await uploadMetadata(metadata);
+    const { errors, data: resData } = await uploadMetadata(metadata, config);
 
     const cid = resData?.cid;
 
@@ -97,11 +111,15 @@ export class HypercertsStorage implements HypercertStorageInterface {
    * If the data is valid, it returns the data as a `HypercertMetadata` object.
    *
    * @param {string} cidOrIpfsUri - The CID or IPFS URI of the metadata to retrieve.
+   * @param {StorageConfigOverrides} [config] - An optional configuration object.
    * @returns {Promise<HypercertMetadata>} A promise that resolves to the retrieved metadata.
    * @throws {MalformedDataError} Will throw a `MalformedDataError` if the retrieved data is invalid.
    */
-  public async getMetadata(cidOrIpfsUri: string): Promise<HypercertMetadata> {
-    const res = await getFromIPFS(cidOrIpfsUri);
+  public async getMetadata(
+    cidOrIpfsUri: string,
+    config: StorageConfigOverrides = { timeout: 0 },
+  ): Promise<HypercertMetadata> {
+    const res = await getFromIPFS(cidOrIpfsUri, config);
 
     const validation = validateMetaData(res);
     if (!validation.valid) {
@@ -117,14 +135,14 @@ export class HypercertsStorage implements HypercertStorageInterface {
    * This method first retrieves the data from IPFS using the `getFromIPFS` function. It then parses the retrieved data as JSON and returns it.
    *
    * @param {string} cidOrIpfsUri - The CID or IPFS URI of the data to retrieve.
+   * @param {StorageConfigOverrides} [config] - An optional configuration object.
    * @returns {Promise<any>} A promise that resolves to the retrieved data.
    * @throws {FetchError} Will throw a `FetchError` if the retrieval operation fails.
    * @throws {MalformedDataError} Will throw a `MalformedDataError` if the retrieved data is not a single file.
    *
    * @remarkts Note: The original implementation using the Web3 Storage client is currently commented out due to issues with upstream repos. This will be replaced once those issues are resolved.
    */
-  public async getData(cidOrIpfsUri: string): Promise<unknown> {
-    // TODO: replace current temporary fix or just using NFT.Storage IPFS gateway
-    return await getFromIPFS(cidOrIpfsUri);
+  public async getData(cidOrIpfsUri: string, config: StorageConfigOverrides = { timeout: 0 }): Promise<unknown> {
+    return await getFromIPFS(cidOrIpfsUri, config);
   }
 }

sdk/src/types/client.ts

@@ -7,13 +7,37 @@ import { HypercertMetadata } from "./metadata";
 import { ByteArray, Chain, Hex, PublicClient, WalletClient, GetContractReturnType } from "viem";
 import { HypercertMinterAbi } from "@hypercerts-org/contracts";
 
+/**
+ * Enum to verify the supported chainIds
+ *
+ * @note 10 = Optimism, 42220 = Celo, 11155111 = Sepolia
+ */
 export type SupportedChainIds = 10 | 42220 | 11155111;
-export type SupportedOverrides = {
+
+export type SupportedOverrides = ContractOverrides & StorageConfigOverrides;
+
+/**
+ * Configuration options for the contract interactions.
+ *
+ * @param value The value to send with the transaction (in wei).
+ * @param gasPrice The gas price to use for the transaction (in wei).
+ * @param gasLimit The gas limit to use for the transaction (in wei).
+ */
+export type ContractOverrides = {
   value?: bigint;
   gasPrice?: bigint;
   gasLimit?: bigint;
 };
 
+/**
+ * Configuration options for the Hypercert storage layer.
+ * @param timeout The timeout (im ms) for the HTTP request; for example for uploading metadata or fetching allowlists.
+ */
+export type StorageConfigOverrides = {
+  // Axios timout in ms
+  timeout?: number;
+};
+
 export type Contracts =
   | "HypercertMinterUUPS"
   | "TransferManager"
@@ -84,30 +108,34 @@ export interface HypercertStorageInterface {
   /**
    * Stores the allowlost for a hypercert.
    * @param allowList The metadata to store.
+   * @param {StorageConfigOverrides} [config] - An optional configuration object.
    * @returns A Promise that resolves to the CID of the stored metadata.
    */
-  storeAllowList: (allowList: AllowlistEntry[], totalUnits: bigint) => Promise<string>;
+  storeAllowList: (allowList: AllowlistEntry[], totalUnits: bigint, config?: StorageConfigOverrides) => Promise<string>;
 
   /**
    * Stores the metadata for a hypercert.
    * @param metadata The metadata to store.
+   * @param {StorageConfigOverrides} [config] - An optional configuration object.
    * @returns A Promise that resolves to the CID of the stored metadata.
    */
-  storeMetadata: (metadata: HypercertMetadata) => Promise<string>;
+  storeMetadata: (metadata: HypercertMetadata, config?: StorageConfigOverrides) => Promise<string>;
 
   /**
    * Retrieves the metadata for a hypercerts.
    * @param cidOrIpfsUri The CID or IPFS URI of the metadata to retrieve.
+   * @param {StorageConfigOverrides} [config] - An optional configuration object.
    * @returns A Promise that resolves to the retrieved metadata.
    */
-  getMetadata: (cidOrIpfsUri: string) => Promise<HypercertMetadata>;
+  getMetadata: (cidOrIpfsUri: string, config?: StorageConfigOverrides) => Promise<HypercertMetadata>;
 
   /**
    * Retrieves arbitrary data from IPFS.
    * @param cidOrIpfsUri The CID or IPFS URI of the data to retrieve.
+   * @param {StorageConfigOverrides} [config] - An optional configuration object.
    * @returns A Promise that resolves to the retrieved data.
    */
-  getData: (cidOrIpfsUri: string) => Promise<unknown>;
+  getData: (cidOrIpfsUri: string, config?: StorageConfigOverrides) => Promise<unknown>;
 }
 
 /**

sdk/src/utils/apis.ts

@@ -1,5 +1,5 @@
 import axios from "axios";
-import { HypercertMetadata } from "src/types";
+import { HypercertMetadata, StorageConfigOverrides } from "src/types";
 
 /**
  * Type for the request body when posting to the allowlist endpoint.
@@ -22,18 +22,20 @@ type ResponseData<T> = {
 /**
  * Axios instance configured with the base URL for the hypercert API.
  */
-const api = axios.create({ timeout: 10000, headers: { "Content-Type": "application/json" } });
+const api = axios.create({ headers: { "Content-Type": "application/json" } });
 
 /**
  * Uploads metadata to the API.
  *
- * @param metadata - The metadata to upload. Should be an object that conforms to the HypercertMetadata type.
+ * @param {HypercertMetadata} metadata - The metadata to upload. Should be an object that conforms to the HypercertMetadata type.
+ * @param {StorageConfigOverrides} [config] - An optional configuration object.
  * @returns The response data from the API.
  */
-const uploadMetadata = async (metadata: HypercertMetadata) => {
+const uploadMetadata = async (metadata: HypercertMetadata, config: StorageConfigOverrides = { timeout: 0 }) => {
   const response = await api.post<ResponseData<{ cid: string }>>(
     "https://hypercerts-api-production.up.railway.app/api/v1/web3up/metadata",
     metadata,
+    config,
   );
 
   return response.data;
@@ -42,14 +44,16 @@ const uploadMetadata = async (metadata: HypercertMetadata) => {
 /**
  * Uploads an allowlist to the API.
  *
- * @param req - The request body containing the allowlist and total units. The allowList should be a stringified Merkle tree dump.
+ * @param {HypercertMetadata} req - The request body containing the allowlist and total units. The allowList should be a stringified Merkle tree dump.
+ * @param {StorageConfigOverrides} [config] - An optional configuration object.
  * @returns The response data from the API.
  *
  */
-const uploadAllowlist = async (req: AllowListPostRequest) => {
+const uploadAllowlist = async (req: AllowListPostRequest, config: StorageConfigOverrides = { timeout: 0 }) => {
   const response = await api.post<ResponseData<{ cid: string }>>(
     "https://hypercerts-api-production.up.railway.app/api/v1/web3up/allowlist",
     req,
+    config,
   );
 
   return response.data;

sdk/src/utils/fetchers.ts

@@ -1,3 +1,4 @@
+import { StorageConfigOverrides } from "src/types";
 import { StorageError } from "../types/errors";
 import { logger } from "./logger";
 import axios from "axios";
@@ -9,16 +10,16 @@ import axios from "axios";
  * If the data cannot be fetched from any gateway, it throws a `StorageError`.
  *
  * @param {string} cidOrIpfsUri - The CID or IPFS URI of the data to fetch.
- * @param {number} [timeout=10000] - The timeout for the fetch request in milliseconds. Defaults to 10000ms.
+ * @param {StorageConfigOverrides} [config] - An optional configuration object.
  * @returns {Promise<unknown>} The data fetched from IPFS.
  * @throws {StorageError} Will throw a `StoragjeError` if the data cannot be fetched from either gateway.
  * @async
  */
-const getFromIPFS = async (cidOrIpfsUri: string, timeout: number = 10000): Promise<unknown> => {
+const getFromIPFS = async (cidOrIpfsUri: string, config: StorageConfigOverrides = { timeout: 0 }): Promise<unknown> => {
   const requests = [
-    axios.get(getDwebLinkGatewayUri(cidOrIpfsUri), { timeout }),
-    axios.get(getNftStorageGatewayUri(cidOrIpfsUri), { timeout }),
-    axios.get(getWeb3UpGatewayUri(cidOrIpfsUri), { timeout }),
+    axios.get(getDwebLinkGatewayUri(cidOrIpfsUri), { timeout: config.timeout }),
+    axios.get(getNftStorageGatewayUri(cidOrIpfsUri), { timeout: config.timeout }),
+    axios.get(getWeb3UpGatewayUri(cidOrIpfsUri), { timeout: config.timeout }),
   ];
 
   logger.debug(`Getting metadata for ${cidOrIpfsUri}`);