@nomicfoundation/hardhat-utils 3.0.0-next.0

package/src/request.ts

@@ -0,0 +1,341 @@
+import type EventEmitter from "node:events";
+import type { ParsedUrlQueryInput } from "node:querystring";
+import type UndiciT from "undici";
+
+import fs from "node:fs";
+import querystring from "node:querystring";
+import stream from "node:stream/promises";
+
+import { ensureError } from "./error.js";
+import {
+  DownloadError,
+  RequestError,
+  DispatcherError,
+} from "./errors/request.js";
+import { move } from "./fs.js";
+import {
+  generateTempFilePath,
+  getBaseDispatcherOptions,
+  getBaseRequestOptions,
+  getBasicDispatcher,
+  getPoolDispatcher,
+  getProxyDispatcher,
+  handleError,
+} from "./internal/request.js";
+
+export const DEFAULT_TIMEOUT_IN_MILLISECONDS = 30_000;
+export const DEFAULT_MAX_REDIRECTS = 10;
+export const DEFAULT_POOL_MAX_CONNECTIONS = 128;
+export const DEFAULT_USER_AGENT = "Hardhat";
+
+export type Dispatcher = UndiciT.Dispatcher;
+export type TestDispatcher = UndiciT.MockAgent;
+export type Interceptable = UndiciT.Interceptable;
+
+/**
+ * Options to configure the dispatcher.
+ *
+ * @param timeout The timeout in milliseconds. Defaults to {@link DEFAULT_TIMEOUT_IN_MILLISECONDS}.
+ * @param proxy The proxy to use. If not provided, no proxy is used.
+ * @param pool Whether to use a pool dispatcher. Defaults to `false`.
+ * @param maxConnections The maximum number of connections to use in the pool. Defaults to {@link DEFAULT_POOL_MAX_CONNECTIONS}.
+ * @param isTestDispatcher Whether to use a test dispatcher. Defaults to `false`. It's highly recommended to use a test dispatcher in tests to avoid hanging tests.
+ */
+export interface DispatcherOptions {
+  timeout?: number;
+  proxy?: string;
+  pool?: boolean;
+  maxConnections?: number;
+  isTestDispatcher?: boolean;
+}
+
+/**
+ * Options to configure a request.
+ *
+ * @param queryParams The query parameters to append to the url.
+ * @param extraHeaders Additional headers to include in the request.
+ * @param abortSignal The signal to abort the request.
+ */
+export interface RequestOptions {
+  queryParams?: Record<string, any>;
+  extraHeaders?: Record<string, string>;
+  abortSignal?: AbortSignal | EventEmitter;
+}
+
+/**
+ * Performs a HTTP request.
+ *
+ * @param url The url to make the request to.
+ * @param requestOptions The options to configure the request. See {@link RequestOptions}.
+ * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
+ * @returns The response data object. See {@link https://undici.nodejs.org/#/docs/api/Dispatcher?id=parameter-responsedata}.
+ * @throws ConnectionRefusedError If the connection is refused by the server.
+ * @throws RequestTimeoutError If the request times out.
+ * @throws RequestError If the request fails for any other reason.
+ */
+export async function getRequest(
+  url: string,
+  requestOptions: RequestOptions = {},
+  dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions,
+): Promise<UndiciT.Dispatcher.ResponseData> {
+  const { request } = await import("undici");
+
+  try {
+    const baseRequestOptions = await getBaseRequestOptions(
+      url,
+      requestOptions,
+      dispatcherOrDispatcherOptions,
+    );
+    return await request(url, {
+      method: "GET",
+      ...baseRequestOptions,
+    });
+  } catch (e) {
+    ensureError(e);
+
+    handleError(e, url);
+
+    throw new RequestError(url, "GET", e);
+  }
+}
+
+/**
+ * Performs a POST request with a JSON body.
+ *
+ * @param url The url to make the request to.
+ * @param body The body of the request, represented as an object.
+ * @param requestOptions The options to configure the request. See {@link RequestOptions}.
+ * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
+ * @returns The response data object. See {@link https://undici.nodejs.org/#/docs/api/Dispatcher?id=parameter-responsedata}.
+ * @throws ConnectionRefusedError If the connection is refused by the server.
+ * @throws RequestTimeoutError If the request times out.
+ * @throws RequestError If the request fails for any other reason.
+ */
+export async function postJsonRequest(
+  url: string,
+  body: unknown,
+  requestOptions: RequestOptions = {},
+  dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions,
+): Promise<UndiciT.Dispatcher.ResponseData> {
+  const { request } = await import("undici");
+
+  try {
+    const { headers, ...baseRequestOptions } = await getBaseRequestOptions(
+      url,
+      requestOptions,
+      dispatcherOrDispatcherOptions,
+    );
+    return await request(url, {
+      method: "POST",
+      ...baseRequestOptions,
+      headers: {
+        ...headers,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (e) {
+    ensureError(e);
+
+    handleError(e, url);
+
+    throw new RequestError(url, "POST", e);
+  }
+}
+
+/**
+ * Performs a POST request with a form body.
+ *
+ * @param url The url to make the request to.
+ * @param body The body of the request, represented as an object.
+ * @param requestOptions The options to configure the request. See {@link RequestOptions}.
+ * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
+ * @returns The response data object. See {@link https://undici.nodejs.org/#/docs/api/Dispatcher?id=parameter-responsedata}.
+ * @throws ConnectionRefusedError If the connection is refused by the server.
+ * @throws RequestTimeoutError If the request times out.
+ * @throws RequestError If the request fails for any other reason.
+ */
+export async function postFormRequest(
+  url: string,
+  body: unknown,
+  requestOptions: RequestOptions = {},
+  dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions,
+): Promise<UndiciT.Dispatcher.ResponseData> {
+  const { request } = await import("undici");
+
+  try {
+    const { headers, ...baseRequestOptions } = await getBaseRequestOptions(
+      url,
+      requestOptions,
+      dispatcherOrDispatcherOptions,
+    );
+    return await request(url, {
+      method: "POST",
+      ...baseRequestOptions,
+      headers: {
+        ...headers,
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- TODO: Add a runtime check for body's type
+      body: querystring.stringify(body as ParsedUrlQueryInput),
+    });
+  } catch (e) {
+    ensureError(e);
+
+    handleError(e, url);
+
+    throw new RequestError(url, "POST", e);
+  }
+}
+
+/**
+ * Downloads a file from a url to a destination path.
+ *
+ * @param url The url to download from.
+ * @param destination The absolute path to save the file to.
+ * @param requestOptions The options to configure the request. See {@link RequestOptions}.
+ * @param dispatcherOrDispatcherOptions Either a dispatcher or dispatcher options. See {@link DispatcherOptions}.
+ * @throws ConnectionRefusedError If the connection is refused by the server.
+ * @throws RequestTimeoutError If the request times out.
+ * @throws DownloadFailedError If the download fails for any other reason.
+ */
+export async function download(
+  url: string,
+  destination: string,
+  requestOptions: RequestOptions = {},
+  dispatcherOrDispatcherOptions?: UndiciT.Dispatcher | DispatcherOptions,
+): Promise<void> {
+  let statusCode: number | undefined;
+
+  try {
+    const response = await getRequest(
+      url,
+      requestOptions,
+      dispatcherOrDispatcherOptions,
+    );
+    const { body } = response;
+    statusCode = response.statusCode;
+
+    if (statusCode < 200 || statusCode >= 300) {
+      throw new Error(await body.text());
+    }
+
+    const tempFilePath = await generateTempFilePath(destination);
+    const fileStream = fs.createWriteStream(tempFilePath);
+    await stream.pipeline(body, fileStream);
+    await move(tempFilePath, destination);
+  } catch (e) {
+    ensureError(e);
+
+    handleError(e, url);
+
+    throw new DownloadError(url, e);
+  }
+}
+
+/**
+ * Creates a dispatcher based on the provided options.
+ * If the `proxy` option is set, it creates a {@link UndiciT.ProxyAgent} dispatcher.
+ * If the `pool` option is set to `true`, it creates a {@link UndiciT.Pool} dispatcher.
+ * Otherwise, it creates a basic {@link UndiciT.Agent} dispatcher.
+ *
+ * @param url The url to make requests to.
+ * @param options The options to configure the dispatcher. See {@link DispatcherOptions}.
+ * @returns The configured dispatcher instance.
+ * @throws DispatcherError If the dispatcher can't be created.
+ */
+export async function getDispatcher(
+  url: string,
+  {
+    timeout,
+    proxy,
+    pool,
+    maxConnections,
+    isTestDispatcher,
+  }: DispatcherOptions = {},
+): Promise<Dispatcher> {
+  try {
+    if (pool !== undefined && proxy !== undefined) {
+      throw new Error(
+        "The pool and proxy options can't be used at the same time",
+      );
+    }
+    const baseOptions = getBaseDispatcherOptions(timeout, isTestDispatcher);
+
+    if (proxy !== undefined) {
+      return await getProxyDispatcher(proxy, baseOptions);
+    }
+
+    if (pool === true) {
+      return await getPoolDispatcher(url, {
+        ...baseOptions,
+        connections: maxConnections ?? DEFAULT_POOL_MAX_CONNECTIONS,
+      });
+    }
+
+    return await getBasicDispatcher(baseOptions);
+  } catch (e) {
+    ensureError(e);
+    throw new DispatcherError(e.message, e);
+  }
+}
+
+export async function getTestDispatcher(
+  options: {
+    timeout?: number;
+  } = {},
+): Promise<TestDispatcher> {
+  const { MockAgent } = await import("undici");
+
+  const baseOptions = getBaseDispatcherOptions(options.timeout, true);
+  return new MockAgent(baseOptions);
+}
+
+/**
+ * Determines whether a proxy should be used for a given url.
+ *
+ * @param url The url to check.
+ * @returns `true` if a proxy should be used for the url, `false` otherwise.
+ */
+export function shouldUseProxy(url: string): boolean {
+  const { hostname } = new URL(url);
+  const noProxy = process.env.NO_PROXY;
+
+  if (hostname === "localhost" || hostname === "127.0.0.1" || noProxy === "*") {
+    return false;
+  }
+
+  if (noProxy !== undefined && noProxy !== "") {
+    const noProxySet = new Set(noProxy.split(","));
+
+    if (noProxySet.has(hostname)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Determines whether an absolute url is valid.
+ *
+ * @param url The url to check.
+ * @returns `true` if the url is valid, `false` otherwise.
+ */
+export function isValidUrl(url: string): boolean {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export {
+  ConnectionRefusedError,
+  DispatcherError,
+  DownloadError,
+  RequestError,
+  RequestTimeoutError,
+  ResponseStatusCodeError,
+} from "./errors/request.js";

package/src/stream.ts

@@ -0,0 +1,16 @@
+import { Writable } from "node:stream";
+
+/**
+ * Creates a Tansform that writes everything to actualWritable, without closing it
+ * when finished.
+ *
+ * This is useful to pipe things to stdout, without closing it, while being
+ * able to await for the result of the pipe to finish.
+ */
+export function createNonClosingWriter(actualWritable: Writable): Writable {
+  return new Writable({
+    write(chunk, encoding, callback) {
+      actualWritable.write(chunk, encoding, callback);
+    },
+  });
+}

package/src/string.ts

@@ -0,0 +1,69 @@
+/**
+ * Converts a word in singular form to a pluralized string based on the number
+ * of items.
+ *
+ * @param singular The singular form of the word.
+ * @param count The number of items. This determines whether the singular or
+ * plural form is used.
+ * @param plural The optional plural form of the word. If not provided, the
+ * plural form is created by appending an "s" to the singular form.
+ * @returns The pluralized string.
+ */
+export function pluralize(
+  singular: string,
+  count: number,
+  plural?: string,
+): string {
+  if (count === 1) {
+    return singular;
+  }
+
+  return plural !== undefined ? plural : `${singular}s`;
+}
+
+/**
+ * Capitalizes the first letter of a string.
+ *
+ * @param str The string to capitalize.
+ * @returns The string with the first letter capitalized.
+ */
+export function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Converts a kebab-case string to camelCase.
+ *
+ * @param str The kebab-case string to convert.
+ * @returns The camelCase string.
+ */
+export function kebabToCamelCase(str: string): string {
+  return str.replace(/-./g, (match) => match.charAt(1).toUpperCase());
+}
+
+/**
+ * Converts a camelCase string to snake_case.
+ *
+ * @param str The camelCase string to convert.
+ * @returns The snake_case string.
+ */
+export function camelToSnakeCase(str: string): string {
+  return str.replace(/[A-Z0-9]/g, (match) => `_${match.toLowerCase()}`);
+}
+
+/**
+ * Converts a camelCase string to kebab-case.
+ *
+ * @param str The camelCase string to convert.
+ * @returns The kebab-case string.
+ */
+export function camelToKebabCase(str: string): string {
+  return str.replace(/[A-Z0-9]/g, (match) => `-${match.toLowerCase()}`);
+}
+
+/**
+ * Ensures a string ends with a slash.
+ */
+export function ensureTrailingSlash(path: string): string {
+  return path.endsWith("/") ? path : path + "/";
+}

package/src/subprocess.ts

@@ -0,0 +1,46 @@
+import { spawn } from "node:child_process";
+
+import {
+  SubprocessFileNotFoundError,
+  SubprocessPathIsDirectoryError,
+} from "./errors/subprocess.js";
+import { exists, isDirectory } from "./fs.js";
+
+/**
+ * Spawns a detached subprocess to execute a given file with optional arguments.
+ *
+ * @param absolutePathToSubProcessFile - The absolute path to the subprocess file to be executed.
+ * @param args - Optional list of string arguments to pass to the subprocess.
+ * @param env - Optional environment key-value pairs to pass to the subprocess.
+ *
+ * The subprocess runs in a detached mode and its standard input/output is ignored.
+ * This function does not wait for the subprocess to complete and the subprocess is unreferenced
+ * to allow the parent process to exit independently.
+ */
+export async function spawnDetachedSubProcess(
+  absolutePathToSubProcessFile: string,
+  args: string[] = [],
+  env: Record<string, string> = {},
+): Promise<void> {
+  if ((await exists(absolutePathToSubProcessFile)) === false) {
+    throw new SubprocessFileNotFoundError(absolutePathToSubProcessFile);
+  }
+
+  if ((await isDirectory(absolutePathToSubProcessFile)) === true) {
+    throw new SubprocessPathIsDirectoryError(absolutePathToSubProcessFile);
+  }
+
+  const subprocessArgs = [absolutePathToSubProcessFile, ...args];
+
+  if (absolutePathToSubProcessFile.endsWith(".ts")) {
+    subprocessArgs.unshift("--import", "tsx/esm");
+  }
+
+  const subprocess = spawn(process.execPath, subprocessArgs, {
+    detached: true,
+    env,
+    stdio: "ignore",
+  });
+
+  subprocess.unref();
+}

package/src/synchronization.ts

@@ -0,0 +1,126 @@
+// Logic explanation: the fs.writeFile function, when used with the wx+ flag, performs an atomic operation to create a file.
+// If multiple processes try to create the same file simultaneously, only one will succeed.
+// This logic can be utilized to implement a mutex.
+// ATTENTION: in the current implementation, there's still a risk of two processes running simultaneously.
+// For example, if processA has locked the mutex and is running, processB will wait.
+// During this wait, processB continuously checks the elapsed time since the mutex lock file was created.
+// If an excessive amount of time has passed, processB will assume ownership of the mutex to avoid stale locks.
+// However, there's a possibility that processB might take ownership because the mutex creation file is outdated, even though processA is still running
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import debug from "debug";
+
+import { ensureError } from "./error.js";
+import { FileSystemAccessError } from "./errors/fs.js";
+import { sleep } from "./lang.js";
+
+const log = debug("hardhat:util:multi-process-mutex");
+const DEFAULT_MAX_MUTEX_LIFESPAN_IN_MS = 60000;
+const MUTEX_LOOP_WAITING_TIME_IN_MS = 100;
+
+export class MultiProcessMutex {
+  readonly #mutexFilePath: string;
+  readonly #mutexLifespanInMs: number;
+
+  constructor(mutexName: string, maxMutexLifespanInMs?: number) {
+    log(`Creating mutex with name '${mutexName}'`);
+
+    this.#mutexFilePath = path.join(os.tmpdir(), `${mutexName}.txt`);
+    this.#mutexLifespanInMs =
+      maxMutexLifespanInMs ?? DEFAULT_MAX_MUTEX_LIFESPAN_IN_MS;
+  }
+
+  public async use<T>(f: () => Promise<T>): Promise<T> {
+    log(`Starting mutex process with mutex file '${this.#mutexFilePath}'`);
+
+    while (true) {
+      if (await this.#tryToAcquireMutex()) {
+        // Mutex has been acquired
+        return this.#executeFunctionAndReleaseMutex(f);
+      }
+
+      // Mutex not acquired
+      if (this.#isMutexFileTooOld()) {
+        // If the mutex file is too old, it likely indicates a stale lock, so the file should be removed
+        log(
+          `Current mutex file is too old, removing it at path '${this.#mutexFilePath}'`,
+        );
+        this.#deleteMutexFile();
+      } else {
+        // wait
+        await sleep(MUTEX_LOOP_WAITING_TIME_IN_MS / 1000);
+      }
+    }
+  }
+
+  async #tryToAcquireMutex() {
+    try {
+      // Create a file only if it does not exist
+      fs.writeFileSync(this.#mutexFilePath, "", { flag: "wx+" });
+      return true;
+    } catch (e) {
+      ensureError<NodeJS.ErrnoException>(e);
+
+      if (e.code === "EEXIST") {
+        // File already exists, so the mutex is already acquired
+        return false;
+      }
+
+      throw new FileSystemAccessError(e.message, e);
+    }
+  }
+
+  async #executeFunctionAndReleaseMutex<T>(f: () => Promise<T>): Promise<T> {
+    log(`Mutex acquired at path '${this.#mutexFilePath}'`);
+
+    try {
+      return await f();
+    } finally {
+      // Release the mutex
+      log(`Mutex released at path '${this.#mutexFilePath}'`);
+      this.#deleteMutexFile();
+      log(`Mutex released at path '${this.#mutexFilePath}'`);
+    }
+  }
+
+  #isMutexFileTooOld(): boolean {
+    let fileStat;
+    try {
+      fileStat = fs.statSync(this.#mutexFilePath);
+    } catch (e) {
+      ensureError<NodeJS.ErrnoException>(e);
+
+      if (e.code === "ENOENT") {
+        // The file might have been deleted by another process while this function was trying to access it.
+        return false;
+      }
+
+      throw new FileSystemAccessError(e.message, e);
+    }
+
+    const now = new Date();
+    const fileDate = new Date(fileStat.ctime);
+    const diff = now.getTime() - fileDate.getTime();
+
+    return diff > this.#mutexLifespanInMs;
+  }
+
+  #deleteMutexFile() {
+    try {
+      log(`Deleting mutex file at path '${this.#mutexFilePath}'`);
+      fs.unlinkSync(this.#mutexFilePath);
+    } catch (e) {
+      ensureError<NodeJS.ErrnoException>(e);
+
+      if (e.code === "ENOENT") {
+        // The file might have been deleted by another process while this function was trying to access it.
+        return;
+      }
+
+      throw new FileSystemAccessError(e.message, e);
+    }
+  }
+}