headplane/app/server/headscale/api/error.ts

import { errors } from "undici";

/**
 * Helper function that determines if an error is a Node.js exception
 * @param - The error to check
 * @returns True if the error is a Node.js exception, false otherwise
 */
function isNodeNetworkError(error: unknown): error is NodeJS.ErrnoException {
  return error != null && typeof error === "object" && "code" in error && "errno" in error;
}

/**
 * A friendly error representation for Headscale connection issues.
 */
export interface HeadscaleConnectionError {
  requestUrl: string;
  errorCode: string;
  errorMessage: string;
  extraData: Record<string, unknown> | null;
}

/**
 * Convert an Undici error into a friendly HeadscaleAPIError.
 * This is used to avoid exposing rough error edges to the user.
 *
 * @param error - The Undici error to convert.
 * @param requestUrl - The URL of the request that caused the error.
 * @returns A friendly HeadscaleAPIError.
 */
export function undiciToFriendlyError(
  error: unknown,
  requestUrl: string,
): HeadscaleConnectionError {
  // MARK: Do we need to go deeper into causes here?
  if (error instanceof AggregateError) {
    error = error.errors[0];
  }

  if (error instanceof errors.UndiciError) {
    return {
      requestUrl,
      errorCode: error.code,
      errorMessage: error.message,
      extraData: null,
    };
  }

  if (isNodeNetworkError(error)) {
    return {
      requestUrl,
      errorCode: error.code ?? "UNKNOWN_NODE_NETWORK_ERROR",
      errorMessage: error.message,
      extraData: {
        syscall: error.syscall,
        path: error.path,
        errno: error.errno,
      },
    };
  }

  return {
    requestUrl,
    errorCode: "UNKNOWN_ERROR",
    errorMessage: "An unknown error occured",
    extraData: null,
  };
}