Better diagnostics for download errors

packages/adaptor-api/package.json

@@ -11,6 +11,9 @@
     "lint": "pnpm eslint --quiet --concurrency auto .",
     "lint:verbose": "pnpm eslint --concurrency auto ."
   },
+  "dependencies": {
+    "@nexusmods/contracts": "workspace:*"
+  },
   "peerDependencies": {
     "rolldown": "catalog:"
   },

packages/adaptor-api/src/fs/filesystem.ts

@@ -1,5 +1,7 @@
 /// <reference lib="webworker" />
 
+import type { FileSystemErrorCode } from "@nexusmods/contracts";
+
 import type { Pattern } from "./matcher";
 import type { QualifiedPath, ResolvedPath } from "./paths";
 
@@ -301,16 +303,7 @@ export type DirectoryStatus = StatusTime & {
   readonly hardlinkCount: number;
 };
 
-/** @public */
-export type FileSystemErrorCode =
-  | "already exists"
-  | "directory not empty"
-  | "no permissions"
-  | "no space"
-  | "not a directory"
-  | "not a file"
-  | "not found"
-  | "generic";
+export type { FileSystemErrorCode };
 
 /** @public */
 export class FileSystemError extends Error {

packages/contracts/eslint.config.mjs

@@ -0,0 +1,5 @@
+import { defineConfig } from "eslint/config";
+
+import { baseConfig } from "../../eslint.config.base.mjs";
+
+export default defineConfig([...baseConfig(import.meta.dirname)]);

packages/contracts/package.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://www.schemastore.org/package.json",
+  "name": "@nexusmods/contracts",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "pnpm tsdown",
+    "typecheck": "pnpm tsc -p ./tsconfig.json",
+    "lint": "pnpm eslint --quiet --concurrency auto .",
+    "lint:verbose": "pnpm eslint --concurrency auto ."
+  },
+  "exports": {
+    ".": {
+      "development": "./src/lib.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "import": "./dist/index.js",
+        "require": "./dist/index.cjs"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.cts"
+}

packages/contracts/src/fs.ts

@@ -0,0 +1,18 @@
+/**
+ * Semantic filesystem error code.
+ *
+ * Single source of truth shared by the filesystem contract in
+ * `@nexusmods/adaptor-api/fs` (which normalizes raw Node errors into these
+ * codes).
+ *
+ * @public
+ */
+export type FileSystemErrorCode =
+  | "already exists"
+  | "directory not empty"
+  | "no permissions"
+  | "no space"
+  | "not a directory"
+  | "not a file"
+  | "not found"
+  | "generic";

packages/contracts/src/lib.ts

@@ -0,0 +1 @@
+export type { FileSystemErrorCode } from "./fs";

packages/contracts/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://www.schemastore.org/tsconfig.json",
+  "extends": "../../tsconfig.strict.json",
+  "include": ["./src/**/*.ts"],
+  "compilerOptions": {
+    "composite": true,
+    "noEmit": true,
+    "target": "esnext",
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "customConditions": ["development"],
+    "lib": ["ESNext"],
+    "types": [],
+    "allowJs": false,
+    "isolatedDeclarations": true,
+    "noUncheckedSideEffectImports": true
+  }
+}

packages/contracts/tsdown.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: {
+    index: "./src/lib.ts",
+  },
+  format: ["esm", "cjs"],
+  platform: "neutral",
+  tsconfig: "./tsconfig.json",
+  dts: { sourcemap: true },
+  exports: {
+    devExports: "development",
+  },
+});

src/main/src/downloading/downloader.ts

@@ -1,6 +1,7 @@
 import { type FileHandle as NodeFileHandle, access, open } from "node:fs/promises";
 import type { IncomingHttpHeaders } from "node:http";
 
+import type { FileSystemErrorCode } from "@nexusmods/adaptor-api/fs";
 import { getErrorCode, unknownToError } from "@vortex/shared";
 import type {
   ByteRange,
@@ -18,6 +19,7 @@ import type { RateLimiter } from "limiter";
 import PQueue from "p-queue";
 import type { CookieJar } from "tough-cookie";
 
+import { parseNodeError } from "../filesystem/parse-node-error";
 import { isCancellation, toNetworkError } from "./errors";
 import type { ProgressReporter } from "./progress";
 import type { NormalizedResource } from "./resolver";
@@ -44,6 +46,12 @@ export type TimeoutOptions = {
   stall: number;
 };
 
+function fsErrorMessage(verb: string, filePath: string, reason: FileSystemErrorCode): string {
+  return reason === "generic"
+    ? `Failed to ${verb} ${filePath}`
+    : `Failed to ${verb} ${filePath}: ${reason}`;
+}
+
 /** @internal */
 export async function download<T>(
   resource: T,
@@ -142,16 +150,22 @@ export async function download<T>(
     const fd = await open(dest, flag);
     handle = { fd, path: dest };
   } catch (err) {
-    throw new DownloadError({ code: "fs-error", path: dest }, `Failed to open ${dest}`, err);
+    const { code: reason, isTransient } = parseNodeError(err);
+    throw new DownloadError(
+      { code: "fs-error", path: dest, reason, isTransient },
+      fsErrorMessage("open", dest, reason),
+      err,
+    );
   }
 
   if (checkpoint && probe.size) {
     try {
       await handle.fd.truncate(probe.size);
     } catch (err) {
+      const { code: reason, isTransient } = parseNodeError(err);
       throw new DownloadError(
-        { code: "fs-error", path: handle.path },
-        `Failed to truncate ${handle.path}`,
+        { code: "fs-error", path: handle.path, reason, isTransient },
+        fsErrorMessage("truncate", handle.path, reason),
         err,
       );
     }
@@ -432,9 +446,10 @@ async function downloadStream(
         if (progress) progress.bytesWritten += result.bytesWritten;
         writePosition += result.bytesWritten;
       } catch (err) {
+        const { code: reason, isTransient } = parseNodeError(err);
         throw new DownloadError(
-          { code: "fs-error", path: handle.path },
-          `Failed to write to ${handle.path}`,
+          { code: "fs-error", path: handle.path, reason, isTransient },
+          fsErrorMessage("write to", handle.path, reason),
           err,
         );
       }

src/main/src/filesystem/backend.ts

@@ -19,7 +19,6 @@ import { Readable, Writable } from "node:stream";
 import type {
   DirectoryStatus,
   FileStatus,
-  FileSystemErrorCode,
   StatResult,
   Status,
   StatusTime,
@@ -28,67 +27,7 @@ import type { Pattern, ResolvedPath } from "@nexusmods/adaptor-api/fs";
 import type { FileSystemBackend as NodeFileSystemBackend } from "@nexusmods/adaptor-api/fs";
 import { FileSystemError, matches } from "@nexusmods/adaptor-api/fs";
 
-interface ParsedNodeError {
-  code: FileSystemErrorCode;
-  isTransient: boolean;
-  originalCode: string;
-}
-
-function parseNodeError(err: unknown): ParsedNodeError {
-  if (!(err instanceof Error)) {
-    return { code: "generic", isTransient: false, originalCode: "" };
-  }
-
-  // https://nodejs.org/api/errors.html
-  // NOTE(erri120): Node.js is inconsistent when it comes to data on Errors.
-  // The error code that we care about is on err.info.code or err.code if err.info doesn't exist
-
-  if (!("code" in err) || typeof err.code !== "string") {
-    return { code: "generic", isTransient: false, originalCode: "" };
-  }
-
-  const originalCode =
-    "info" in err &&
-    typeof err.info === "object" &&
-    err.info !== null &&
-    "code" in err.info &&
-    typeof err.info.code === "string"
-      ? err.info.code
-      : err.code;
-
-  // NOTE(erri120): Node.js uses POSIX error names as codes
-  // https://www.man7.org/linux/man-pages/man3/errno.3.html
-  // https://nodejs.org/api/errors.html#common-system-errors
-  if (originalCode === "EACCES" || originalCode === "EPERM") {
-    // EACCES: Permission denied (POSIX.1-2001).
-    // EPERM: Operation not permitted (POSIX.1-2001).
-    return { code: "no permissions", isTransient: false, originalCode };
-  } else if (originalCode === "ENOENT") {
-    // ENOENT: No such file or directory (POSIX.1-2001).
-    return { code: "not found", isTransient: false, originalCode };
-  } else if (originalCode === "EEXIST") {
-    // EEXIST: File exists (POSIX.1-2001).
-    return { code: "already exists", isTransient: false, originalCode };
-  } else if (originalCode === "ENOSPC") {
-    // ENOSPC: No space left on device (POSIX.1-2001)
-    return { code: "no space", isTransient: false, originalCode };
-  } else if (originalCode === "ENOTDIR") {
-    // ENOTDIR: Not a directory (POSIX.1-2001).
-    return { code: "not a directory", isTransient: false, originalCode };
-  } else if (originalCode === "EISDIR") {
-    // EISDIR: Is a directory (POSIX.1-2001).
-    return { code: "not a file", isTransient: false, originalCode };
-  } else if (originalCode === "ENOTEMPTY") {
-    // ENOTEMPTY: Directory not empty (POSIX.1-2001).
-    return { code: "directory not empty", isTransient: false, originalCode };
-  } else if (originalCode === "EMFILE" || originalCode === "EBUSY") {
-    // EMFILE: Too many open files (POSIX.1-2001).
-    // EBUSY: Device or resource busy (POSIX.1-2001)
-    return { code: "generic", isTransient: true, originalCode };
-  } else {
-    return { code: "generic", isTransient: false, originalCode };
-  }
-}
+import { parseNodeError } from "./parse-node-error";
 
 /**
  * Node-backed implementation of {@link NodeFileSystemBackend}. Operates on

src/main/src/filesystem/parse-node-error.ts

@@ -0,0 +1,70 @@
+import type { FileSystemErrorCode } from "@nexusmods/adaptor-api/fs";
+
+export interface ParsedNodeError {
+  code: FileSystemErrorCode;
+  isTransient: boolean;
+  originalCode: string;
+}
+
+/**
+ * Normalizes a raw Node.js error into a semantic {@link FileSystemErrorCode}.
+ * Node is inconsistent about where it puts the error code, so this mirrors the
+ * mapping used by the filesystem backend and is the single place download I/O
+ * (which uses `node:fs` directly rather than the filesystem service) reuses to
+ * avoid leaking raw errno strings into the rest of the app.
+ */
+export function parseNodeError(err: unknown): ParsedNodeError {
+  if (!(err instanceof Error)) {
+    return { code: "generic", isTransient: false, originalCode: "" };
+  }
+
+  // https://nodejs.org/api/errors.html
+  // NOTE(erri120): Node.js is inconsistent when it comes to data on Errors.
+  // The error code that we care about is on err.info.code or err.code if err.info doesn't exist
+
+  if (!("code" in err) || typeof err.code !== "string") {
+    return { code: "generic", isTransient: false, originalCode: "" };
+  }
+
+  const originalCode =
+    "info" in err &&
+    typeof err.info === "object" &&
+    err.info !== null &&
+    "code" in err.info &&
+    typeof err.info.code === "string"
+      ? err.info.code
+      : err.code;
+
+  // NOTE(erri120): Node.js uses POSIX error names as codes
+  // https://www.man7.org/linux/man-pages/man3/errno.3.html
+  // https://nodejs.org/api/errors.html#common-system-errors
+  if (originalCode === "EACCES" || originalCode === "EPERM") {
+    // EACCES: Permission denied (POSIX.1-2001).
+    // EPERM: Operation not permitted (POSIX.1-2001).
+    return { code: "no permissions", isTransient: false, originalCode };
+  } else if (originalCode === "ENOENT") {
+    // ENOENT: No such file or directory (POSIX.1-2001).
+    return { code: "not found", isTransient: false, originalCode };
+  } else if (originalCode === "EEXIST") {
+    // EEXIST: File exists (POSIX.1-2001).
+    return { code: "already exists", isTransient: false, originalCode };
+  } else if (originalCode === "ENOSPC") {
+    // ENOSPC: No space left on device (POSIX.1-2001)
+    return { code: "no space", isTransient: false, originalCode };
+  } else if (originalCode === "ENOTDIR") {
+    // ENOTDIR: Not a directory (POSIX.1-2001).
+    return { code: "not a directory", isTransient: false, originalCode };
+  } else if (originalCode === "EISDIR") {
+    // EISDIR: Is a directory (POSIX.1-2001).
+    return { code: "not a file", isTransient: false, originalCode };
+  } else if (originalCode === "ENOTEMPTY") {
+    // ENOTEMPTY: Directory not empty (POSIX.1-2001).
+    return { code: "directory not empty", isTransient: false, originalCode };
+  } else if (originalCode === "EMFILE" || originalCode === "EBUSY") {
+    // EMFILE: Too many open files (POSIX.1-2001).
+    // EBUSY: Device or resource busy (POSIX.1-2001)
+    return { code: "generic", isTransient: true, originalCode };
+  } else {
+    return { code: "generic", isTransient: false, originalCode };
+  }
+}