Build ENSRainbow config

apps/ensrainbow/package.json

@@ -40,7 +40,8 @@
     "protobufjs": "^7.4.0",
     "viem": "catalog:",
     "yargs": "^17.7.2",
-    "@fast-csv/parse": "^5.0.0"
+    "@fast-csv/parse": "^5.0.0",
+    "zod": "catalog:"
   },
   "devDependencies": {
     "@ensnode/shared-configs": "workspace:*",

apps/ensrainbow/src/cli.test.ts

@@ -4,7 +4,8 @@ import { join } from "node:path";
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { DEFAULT_PORT, getEnvPort } from "@/lib/env";
+import { ENSRAINBOW_DEFAULT_PORT } from "@/config/defaults";
+import { getEnvPort } from "@/lib/env";
 
 import { createCLI, validatePortConfiguration } from "./cli";
 
@@ -38,26 +39,36 @@ describe("CLI", () => {
   });
 
   describe("getEnvPort", () => {
-    it("should return DEFAULT_PORT when PORT is not set", () => {
-      expect(getEnvPort()).toBe(DEFAULT_PORT);
+    it("should return ENSRAINBOW_DEFAULT_PORT when PORT is not set", () => {
+      expect(getEnvPort()).toBe(ENSRAINBOW_DEFAULT_PORT);
     });
 
-    it("should return port from environment variable", () => {
+    it("should return port from environment variable", async () => {
       const customPort = 4000;
-      process.env.PORT = customPort.toString();
-      expect(getEnvPort()).toBe(customPort);
+      vi.stubEnv("PORT", customPort.toString());
+      vi.resetModules();
+      const { getEnvPort: getEnvPortFresh } = await import("@/lib/env");
+      expect(getEnvPortFresh()).toBe(customPort);
     });
 
-    it("should throw error for invalid port number", () => {
-      process.env.PORT = "invalid";
-      expect(() => getEnvPort()).toThrow(
-        'Invalid PORT value "invalid": must be a non-negative integer',
-      );
+    it("should throw error for invalid port number", async () => {
+      const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
+        throw new Error("process.exit called");
+      }) as never);
+      vi.stubEnv("PORT", "invalid");
+      vi.resetModules();
+      await expect(import("@/lib/env")).rejects.toThrow("process.exit called");
+      expect(exitSpy).toHaveBeenCalledWith(1);
     });
 
-    it("should throw error for negative port number", () => {
-      process.env.PORT = "-1";
-      expect(() => getEnvPort()).toThrow('Invalid PORT value "-1": must be a non-negative integer');
+    it("should throw error for negative port number", async () => {
+      const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
+        throw new Error("process.exit called");
+      }) as never);
+      vi.stubEnv("PORT", "-1");
+      vi.resetModules();
+      await expect(import("@/lib/env")).rejects.toThrow("process.exit called");
+      expect(exitSpy).toHaveBeenCalledWith(1);
     });
   });
 
@@ -66,14 +77,18 @@ describe("CLI", () => {
       expect(() => validatePortConfiguration(3000)).not.toThrow();
     });
 
-    it("should not throw when PORT matches CLI port", () => {
-      process.env.PORT = "3000";
-      expect(() => validatePortConfiguration(3000)).not.toThrow();
+    it("should not throw when PORT matches CLI port", async () => {
+      vi.stubEnv("PORT", "3000");
+      vi.resetModules();
+      const { validatePortConfiguration: validatePortConfigurationFresh } = await import("./cli");
+      expect(() => validatePortConfigurationFresh(3000)).not.toThrow();
     });
 
-    it("should throw when PORT conflicts with CLI port", () => {
-      process.env.PORT = "3000";
-      expect(() => validatePortConfiguration(4000)).toThrow("Port conflict");
+    it("should throw when PORT conflicts with CLI port", async () => {
+      vi.stubEnv("PORT", "3000");
+      vi.resetModules();
+      const { validatePortConfiguration: validatePortConfigurationFresh } = await import("./cli");
+      expect(() => validatePortConfigurationFresh(4000)).toThrow("Port conflict");
     });
   });
 
@@ -526,11 +541,14 @@ describe("CLI", () => {
 
       it("should respect PORT environment variable", async () => {
         const customPort = 5115;
-        process.env.PORT = customPort.toString();
+        vi.stubEnv("PORT", customPort.toString());
+        vi.resetModules();
+        const { createCLI: createCLIFresh } = await import("./cli");
+        const cliWithCustomPort = createCLIFresh({ exitProcess: false });
 
         // First ingest some test data
         const ensrainbowOutputFile = join(TEST_FIXTURES_DIR, "test_ens_names_0.ensrainbow");
-        await cli.parse([
+        await cliWithCustomPort.parse([
           "ingest-ensrainbow",
           "--input-file",
           ensrainbowOutputFile,
@@ -539,7 +557,7 @@ describe("CLI", () => {
         ]);
 
         // Start server
-        const serverPromise = cli.parse(["serve", "--data-dir", testDataDir]);
+        const serverPromise = cliWithCustomPort.parse(["serve", "--data-dir", testDataDir]);
 
         // Give server time to start
         await new Promise((resolve) => setTimeout(resolve, 100));
@@ -587,9 +605,12 @@ describe("CLI", () => {
       });
 
       it("should throw on port conflict", async () => {
-        process.env.PORT = "5000";
+        vi.stubEnv("PORT", "5000");
+        vi.resetModules();
+        const { createCLI: createCLIFresh } = await import("./cli");
+        const cliWithPort = createCLIFresh({ exitProcess: false });
         await expect(
-          cli.parse(["serve", "--port", "4000", "--data-dir", testDataDir]),
+          cliWithPort.parse(["serve", "--port", "4000", "--data-dir", testDataDir]),
         ).rejects.toThrow("Port conflict");
       });
     });

apps/ensrainbow/src/cli.ts

@@ -1,3 +1,5 @@
+import config from "@/config";
+
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -14,13 +16,15 @@ import { ingestProtobufCommand } from "@/commands/ingest-protobuf-command";
 import { purgeCommand } from "@/commands/purge-command";
 import { serverCommand } from "@/commands/server-command";
 import { validateCommand } from "@/commands/validate-command";
-import { getDefaultDataSubDir, getEnvPort } from "@/lib/env";
+import { getDefaultDataDir } from "@/config/defaults";
+import { getEnvPort } from "@/lib/env";
 
 export function validatePortConfiguration(cliPort: number): void {
-  const envPort = process.env.PORT;
-  if (envPort !== undefined && cliPort !== getEnvPort()) {
+  // Only validate if PORT was explicitly set in the environment
+  // If PORT is not set, CLI port can override the default
+  if (process.env.PORT !== undefined && cliPort !== config.port) {
     throw new Error(
-      `Port conflict: Command line argument (${cliPort}) differs from PORT environment variable (${envPort}). ` +
+      `Port conflict: Command line argument (${cliPort}) differs from configured port (${config.port}). ` +
         `Please use only one method to specify the port.`,
     );
   }
@@ -89,7 +93,7 @@ export function createCLI(options: CLIOptions = {}) {
       //       .option("data-dir", {
       //         type: "string",
       //         description: "Directory to store LevelDB data",
-      //         default: getDefaultDataSubDir(),
+      //         default: getDefaultDataDir(),
       //       });
       //   },
       //   async (argv: ArgumentsCamelCase<IngestArgs>) => {
@@ -112,7 +116,7 @@ export function createCLI(options: CLIOptions = {}) {
             .option("data-dir", {
               type: "string",
               description: "Directory to store LevelDB data",
-              default: getDefaultDataSubDir(),
+              default: getDefaultDataDir(),
             });
         },
         async (argv: ArgumentsCamelCase<IngestProtobufArgs>) => {
@@ -135,7 +139,7 @@ export function createCLI(options: CLIOptions = {}) {
             .option("data-dir", {
               type: "string",
               description: "Directory containing LevelDB data",
-              default: getDefaultDataSubDir(),
+              default: getDefaultDataDir(),
             });
         },
         async (argv: ArgumentsCamelCase<ServeArgs>) => {
@@ -154,7 +158,7 @@ export function createCLI(options: CLIOptions = {}) {
             .option("data-dir", {
               type: "string",
               description: "Directory containing LevelDB data",
-              default: getDefaultDataSubDir(),
+              default: getDefaultDataDir(),
             })
             .option("lite", {
               type: "boolean",
@@ -177,7 +181,7 @@ export function createCLI(options: CLIOptions = {}) {
           return yargs.option("data-dir", {
             type: "string",
             description: "Directory containing LevelDB data",
-            default: getDefaultDataSubDir(),
+            default: getDefaultDataDir(),
           });
         },
         async (argv: ArgumentsCamelCase<PurgeArgs>) => {

apps/ensrainbow/src/config/config.schema.ts

@@ -0,0 +1,84 @@
+import { join } from "node:path";
+
+import { prettifyError, ZodError, z } from "zod/v4";
+
+import { makeFullyPinnedLabelSetSchema, PortSchema } from "@ensnode/ensnode-sdk/internal";
+
+import { ENSRAINBOW_DEFAULT_PORT, getDefaultDataDir } from "@/config/defaults";
+import type { ENSRainbowEnvironment } from "@/config/environment";
+import { invariant_dbSchemaVersionMatch } from "@/config/validations";
+import { logger } from "@/utils/logger";
+
+const DataDirSchema = z
+  .string()
+  .trim()
+  .min(1, {
+    error: "DATA_DIR must be a non-empty string.",
+  })
+  .transform((path: string) => {
+    // Resolve relative paths to absolute paths
+    if (path.startsWith("/")) {
+      return path;
+    }
+    return join(process.cwd(), path);
+  });
+
+const DbSchemaVersionSchema = z.coerce
+  .number({ error: "DB_SCHEMA_VERSION must be a number." })
+  .int({ error: "DB_SCHEMA_VERSION must be an integer." })
+  .optional();
+
+const LabelSetSchema = makeFullyPinnedLabelSetSchema("LABEL_SET");
+
+const ENSRainbowConfigSchema = z
+  .object({
+    port: PortSchema.default(ENSRAINBOW_DEFAULT_PORT),
+    dataDir: DataDirSchema.default(getDefaultDataDir()),
+    dbSchemaVersion: DbSchemaVersionSchema,
+    labelSet: LabelSetSchema.optional(),
+  })
+  /**
+   * Invariant enforcement
+   *
+   * We enforce invariants across multiple values parsed with `ENSRainbowConfigSchema`
+   * by calling `.check()` function with relevant invariant-enforcing logic.
+   * Each such function has access to config values that were already parsed.
+   */
+  .check(invariant_dbSchemaVersionMatch);
+
+export type ENSRainbowConfig = z.infer<typeof ENSRainbowConfigSchema>;
+
+/**
+ * Builds the ENSRainbow configuration object from an ENSRainbowEnvironment object.
+ *
+ * Validates and parses the complete environment configuration using ENSRainbowConfigSchema.
+ *
+ * @returns A validated ENSRainbowConfig object
+ * @throws Error with formatted validation messages if environment parsing fails
+ */
+export function buildConfigFromEnvironment(env: ENSRainbowEnvironment): ENSRainbowConfig {
+  try {
+    return ENSRainbowConfigSchema.parse({
+      port: env.PORT,
+      dataDir: env.DATA_DIR,
+      dbSchemaVersion: env.DB_SCHEMA_VERSION,
+      labelSet:
+        env.LABEL_SET_ID || env.LABEL_SET_VERSION
+          ? {
+              labelSetId: env.LABEL_SET_ID,
+              labelSetVersion: env.LABEL_SET_VERSION,
+            }
+          : undefined,
+    });
+  } catch (error) {
+    if (error instanceof ZodError) {
+      logger.error(`Failed to parse environment configuration: \n${prettifyError(error)}\n`);
+    } else if (error instanceof Error) {
+      logger.error(error, `Failed to build ENSRainbowConfig`);
+    } else {
+      logger.error(`Unknown Error`);
+    }
+
+    process.exit(1);
+  }
+}

apps/ensrainbow/src/config/defaults.ts

@@ -0,0 +1,5 @@
+import { join } from "node:path";
+
+export const ENSRAINBOW_DEFAULT_PORT = 3223;
+
+export const getDefaultDataDir = () => join(process.cwd(), "data");

apps/ensrainbow/src/config/environment.ts

@@ -0,0 +1,31 @@
+import type { LogLevelEnvironment, PortEnvironment } from "@ensnode/ensnode-sdk/internal";
+
+/**
+ * Represents the raw, unvalidated environment variables for the ENSRainbow application.
+ *
+ * Keys correspond to the environment variable names, and all values are optional strings, reflecting
+ * their state in `process.env`. This interface is intended to be the source type which then gets
+ * mapped/parsed into a structured configuration object like `ENSRainbowConfig`.
+ */
+export type ENSRainbowEnvironment = PortEnvironment &
+  LogLevelEnvironment & {
+    /**
+     * Directory path where the LevelDB database is stored.
+     */
+    DATA_DIR?: string;
+
+    /**
+     * Expected Database Schema Version.
+     */
+    DB_SCHEMA_VERSION?: string;
+
+    /**
+     * Expected Label Set ID.
+     */
+    LABEL_SET_ID?: string;
+
+    /**
+     * Expected Label Set Version.
+     */
+    LABEL_SET_VERSION?: string;
+  };

apps/ensrainbow/src/config/index.ts

@@ -0,0 +1,10 @@
+import { buildConfigFromEnvironment } from "./config.schema";
+import type { ENSRainbowEnvironment } from "./environment";
+
+export type { ENSRainbowConfig } from "./config.schema";
+export { buildConfigFromEnvironment } from "./config.schema";
+export { ENSRAINBOW_DEFAULT_PORT, getDefaultDataDir } from "./defaults";
+export type { ENSRainbowEnvironment } from "./environment";
+
+// build, validate, and export the ENSRainbowConfig from process.env
+export default buildConfigFromEnvironment(process.env as ENSRainbowEnvironment);

apps/ensrainbow/src/config/types.ts

@@ -0,0 +1 @@
+export type { ENSRainbowConfig } from "./config.schema";

apps/ensrainbow/src/config/validations.ts

@@ -0,0 +1,25 @@
+import type { z } from "zod/v4";
+
+import { DB_SCHEMA_VERSION } from "@/lib/database";
+
+import type { ENSRainbowConfig } from "./config.schema";
+
+/**
+ * Zod `.check()` function input.
+ */
+type ZodCheckFnInput<T> = z.core.ParsePayload<T>;
+
+/**
+ * Invariant: dbSchemaVersion must match the version expected by the code.
+ */
+export function invariant_dbSchemaVersionMatch(
+  ctx: ZodCheckFnInput<Pick<ENSRainbowConfig, "dbSchemaVersion">>,
+): void {
+  const { value: config } = ctx;
+
+  if (config.dbSchemaVersion !== undefined && config.dbSchemaVersion !== DB_SCHEMA_VERSION) {
+    throw new Error(
+      `DB_SCHEMA_VERSION mismatch! Expected version ${DB_SCHEMA_VERSION} from code, but found ${config.dbSchemaVersion} in environment variables.`,
+    );
+  }
+}

apps/ensrainbow/src/lib/env.ts

@@ -1,24 +1,8 @@
-import { join } from "node:path";
+import config from "@/config";
 
-import { parseNonNegativeInteger } from "@ensnode/ensnode-sdk";
-
-import { logger } from "@/utils/logger";
-
-export const getDefaultDataSubDir = () => join(process.cwd(), "data");
-
-export const DEFAULT_PORT = 3223;
+/**
+ * Gets the port from environment variables.
+ */
 export function getEnvPort(): number {
-  const envPort = process.env.PORT;
-  if (!envPort) {
-    return DEFAULT_PORT;
-  }
-
-  try {
-    const port = parseNonNegativeInteger(envPort);
-    return port;
-  } catch (_error: unknown) {
-    const errorMessage = `Invalid PORT value "${envPort}": must be a non-negative integer`;
-    logger.error(errorMessage);
-    throw new Error(errorMessage);
-  }
+  return config.port;
 }