Build ENSRainbow config

.changeset/young-carrots-cheer.md

@@ -0,0 +1,6 @@
+---
+"ensrainbow": patch
+"@ensnode/ensrainbow-sdk": patch
+---
+
+Adds `/v1/config` endpoint to ENSRainbow API returning public configuration (version, label set, records count) and deprecates `/v1/version` endpoint. The new endpoint provides comprehensive service discovery capabilities for clients.

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,9 +4,9 @@ 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 { createCLI, validatePortConfiguration } from "./cli";
+import { createCLI } from "./cli";
 
 // Path to test fixtures
 const TEST_FIXTURES_DIR = join(__dirname, "..", "test", "fixtures");
@@ -37,43 +37,86 @@ describe("CLI", () => {
     await rm(tempDir, { recursive: true, force: true });
   });
 
-  describe("getEnvPort", () => {
-    it("should return DEFAULT_PORT when PORT is not set", () => {
-      expect(getEnvPort()).toBe(DEFAULT_PORT);
-    });
+  describe("port configuration", () => {
+    it("should allow CLI port to override PORT env var", async () => {
+      // Mock serverCommand so we only test argument resolution here
+      vi.resetModules();
+      const serverCommandMock = vi.fn().mockResolvedValue(undefined);
+      vi.doMock("@/commands/server-command", () => ({
+        serverCommand: serverCommandMock,
+      }));
 
-    it("should return port from environment variable", () => {
-      const customPort = 4000;
-      process.env.PORT = customPort.toString();
-      expect(getEnvPort()).toBe(customPort);
-    });
+      // Simulate PORT being set in the environment
+      vi.stubEnv("PORT", "3000");
+
+      const { createCLI: createCLIFresh } = await import("./cli");
+      const cliWithPort = createCLIFresh({ exitProcess: false });
 
-    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',
-      );
+      // CLI port should override env PORT
+      await cliWithPort.parse(["serve", "--port", "4000", "--data-dir", testDataDir]);
+
+      expect(serverCommandMock).toHaveBeenCalledWith(expect.objectContaining({ port: 4000 }));
+
+      // Restore real implementation for subsequent tests
+      vi.doUnmock("@/commands/server-command");
     });
 
-    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 reject port less than 1", async () => {
+      // Validation happens during argument parsing, before command handler is called
+      try {
+        await cli.parse(["serve", "--port", "0", "--data-dir", testDataDir]);
+        expect.fail("Expected error to be thrown");
+      } catch (error) {
+        expect(error).toBeDefined();
+        expect(String(error)).toContain("Invalid port");
+      }
     });
-  });
 
-  describe("validatePortConfiguration", () => {
-    it("should not throw when PORT env var is not set", () => {
-      expect(() => validatePortConfiguration(3000)).not.toThrow();
+    it("should reject negative port", async () => {
+      // Validation happens during argument parsing, before command handler is called
+      try {
+        await cli.parse(["serve", "--port", "-1", "--data-dir", testDataDir]);
+        expect.fail("Expected error to be thrown");
+      } catch (error) {
+        expect(error).toBeDefined();
+        expect(String(error)).toContain("Invalid port");
+      }
     });
 
-    it("should not throw when PORT matches CLI port", () => {
-      process.env.PORT = "3000";
-      expect(() => validatePortConfiguration(3000)).not.toThrow();
+    it("should reject port greater than 65535", async () => {
+      // Validation happens during argument parsing, before command handler is called
+      try {
+        await cli.parse(["serve", "--port", "65536", "--data-dir", testDataDir]);
+        expect.fail("Expected error to be thrown");
+      } catch (error) {
+        expect(error).toBeDefined();
+        expect(String(error)).toContain("Invalid port");
+      }
     });
 
-    it("should throw when PORT conflicts with CLI port", () => {
-      process.env.PORT = "3000";
-      expect(() => validatePortConfiguration(4000)).toThrow("Port conflict");
+    it("should accept valid port numbers", async () => {
+      // Mock serverCommand so we only test argument resolution here
+      vi.resetModules();
+      const serverCommandMock = vi.fn().mockResolvedValue(undefined);
+      vi.doMock("@/commands/server-command", () => ({
+        serverCommand: serverCommandMock,
+      }));
+
+      const { createCLI: createCLIFresh } = await import("./cli");
+      const cliWithPort = createCLIFresh({ exitProcess: false });
+
+      // Test valid ports
+      await cliWithPort.parse(["serve", "--port", "1", "--data-dir", testDataDir]);
+      expect(serverCommandMock).toHaveBeenCalledWith(expect.objectContaining({ port: 1 }));
+
+      await cliWithPort.parse(["serve", "--port", "65535", "--data-dir", testDataDir]);
+      expect(serverCommandMock).toHaveBeenCalledWith(expect.objectContaining({ port: 65535 }));
+
+      await cliWithPort.parse(["serve", "--port", "3223", "--data-dir", testDataDir]);
+      expect(serverCommandMock).toHaveBeenCalledWith(expect.objectContaining({ port: 3223 }));
+
+      // Restore real implementation for subsequent tests
+      vi.doUnmock("@/commands/server-command");
     });
   });
 
@@ -512,8 +555,8 @@ describe("CLI", () => {
           testDataDir,
         ]);
 
-        // Give server time to start
-        await new Promise((resolve) => setTimeout(resolve, 100));
+        // Give server time to start (DB open + validation can take a bit)
+        await new Promise((resolve) => setTimeout(resolve, 500));
 
         // Make a request to health endpoint
         const response = await fetch(`http://localhost:${customPort}/health`);
@@ -524,13 +567,40 @@ describe("CLI", () => {
         await serverPromise;
       });
 
+      it("should use the default port when PORT env var is not set", async () => {
+        // Mock serverCommand so we don't actually start a server or touch the DB here
+        vi.resetModules();
+        const serverCommandMock = vi.fn().mockResolvedValue(undefined);
+        vi.doMock("@/commands/server-command", () => ({
+          serverCommand: serverCommandMock,
+        }));
+
+        // PORT is cleared in beforeEach; no CLI --port is provided
+        const { createCLI: createCLIFresh } = await import("./cli");
+        const cliWithDefaultPort = createCLIFresh({ exitProcess: false });
+
+        // Invoke serve without specifying --port
+        await cliWithDefaultPort.parse(["serve", "--data-dir", testDataDir]);
+
+        // Assert that serverCommand was called with the default port
+        expect(serverCommandMock).toHaveBeenCalledWith(
+          expect.objectContaining({ port: ENSRAINBOW_DEFAULT_PORT }),
+        );
+
+        // Restore real implementation for subsequent tests
+        vi.doUnmock("@/commands/server-command");
+      });
+
       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,10 +609,10 @@ 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));
+        // Give server time to start (DB open + validation can take a bit)
+        await new Promise((resolve) => setTimeout(resolve, 500));
 
         // Make a request to health endpoint
         const response = await fetch(`http://localhost:${customPort}/health`);
@@ -586,11 +656,41 @@ describe("CLI", () => {
         await serverPromise;
       });
 
-      it("should throw on port conflict", async () => {
-        process.env.PORT = "5000";
-        await expect(
-          cli.parse(["serve", "--port", "4000", "--data-dir", testDataDir]),
-        ).rejects.toThrow("Port conflict");
+      it("should allow CLI port to override PORT env var", async () => {
+        vi.stubEnv("PORT", "5000");
+        vi.resetModules();
+        const { createCLI: createCLIFresh } = await import("./cli");
+        const cliWithPort = createCLIFresh({ exitProcess: false });
+
+        // First ingest data
+        const ensrainbowOutputFile = join(TEST_FIXTURES_DIR, "test_ens_names_0.ensrainbow");
+        await cliWithPort.parse([
+          "ingest-ensrainbow",
+          "--input-file",
+          ensrainbowOutputFile,
+          "--data-dir",
+          testDataDir,
+        ]);
+
+        // CLI port should override env PORT without error
+        const serverPromise = cliWithPort.parse([
+          "serve",
+          "--port",
+          "4000",
+          "--data-dir",
+          testDataDir,
+        ]);
+
+        // Give server time to start (DB open + validation can take a bit)
+        await new Promise((resolve) => setTimeout(resolve, 500));
+
+        // Verify server is running on the CLI port (not env port)
+        const response = await fetch("http://localhost:4000/health");
+        expect(response.status).toBe(200);
+
+        // Cleanup - send SIGINT to stop server
+        process.emit("SIGINT", "SIGINT");
+        await serverPromise;
       });
     });
 

apps/ensrainbow/src/cli.ts

@@ -1,3 +1,5 @@
+import config from "@/config";
+
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -6,6 +8,7 @@ import { hideBin } from "yargs/helpers";
 import yargs from "yargs/yargs";
 
 import { buildLabelSetId, type LabelSetId } from "@ensnode/ensnode-sdk";
+import { PortSchemaBase } from "@ensnode/ensnode-sdk/internal";
 
 import { convertCommand } from "@/commands/convert-command-sql";
 import { convertCsvCommand } from "@/commands/convert-csv-command";
@@ -14,17 +17,6 @@ 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";
-
-export function validatePortConfiguration(cliPort: number): void {
-  const envPort = process.env.PORT;
-  if (envPort !== undefined && cliPort !== getEnvPort()) {
-    throw new Error(
-      `Port conflict: Command line argument (${cliPort}) differs from PORT environment variable (${envPort}). ` +
-        `Please use only one method to specify the port.`,
-    );
-  }
-}
 
 // interface IngestArgs {
 //   "input-file": string;
@@ -36,6 +28,11 @@ interface IngestProtobufArgs {
   "data-dir": string;
 }
 
+/**
+ * Arguments for the 'serve' command.
+ *
+ * Note: CLI arguments take precedence over environment variables.
+ */
 interface ServeArgs {
   port: number;
   "data-dir": string;
@@ -89,7 +86,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 +109,7 @@ export function createCLI(options: CLIOptions = {}) {
             .option("data-dir", {
               type: "string",
               description: "Directory to store LevelDB data",
-              default: getDefaultDataSubDir(),
+              default: config.dataDir,
             });
         },
         async (argv: ArgumentsCamelCase<IngestProtobufArgs>) => {
@@ -129,17 +126,24 @@ export function createCLI(options: CLIOptions = {}) {
           return yargs
             .option("port", {
               type: "number",
-              description: "Port to listen on",
-              default: getEnvPort(),
+              description: "Port to listen on (overrides PORT env var if both are set)",
+              default: config.port,
+              coerce: (port: number) => {
+                const result = PortSchemaBase.safeParse(port);
+                if (!result.success) {
+                  const firstError = result.error.issues[0];
+                  throw new Error(`Invalid port: ${firstError?.message ?? "invalid port number"}`);
+                }
+                return result.data;
+              },
             })
             .option("data-dir", {
               type: "string",
               description: "Directory containing LevelDB data",
-              default: getDefaultDataSubDir(),
+              default: config.dataDir,
             });
         },
         async (argv: ArgumentsCamelCase<ServeArgs>) => {
-          validatePortConfiguration(argv.port);
           await serverCommand({
             port: argv.port,
             dataDir: argv["data-dir"],
@@ -154,7 +158,7 @@ export function createCLI(options: CLIOptions = {}) {
             .option("data-dir", {
               type: "string",
               description: "Directory containing LevelDB data",
-              default: getDefaultDataSubDir(),
+              default: config.dataDir,
             })
             .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: config.dataDir,
           });
         },
         async (argv: ArgumentsCamelCase<PurgeArgs>) => {