feat(ensrainbow): enhance entrypoint command with eager public config and mismatch handling (#2037)

Author: djstrong

.changeset/ensrainbow-eager-public-config.md

@@ -0,0 +1,11 @@
+---
+"ensrainbow": minor
+---
+
+ENSRainbow's `GET /v1/config` is now available immediately at startup, removing the cold-start gap that previously forced downstream services (e.g. ENSIndexer) to wait for the entire database download/validation before they could read public config (issue #2020).
+
+- The entrypoint command now builds the `EnsRainbowPublicConfig` in-memory from its CLI/env arguments (`LABEL_SET_ID`, `LABEL_SET_VERSION`) before the HTTP server starts accepting requests, so `/v1/config` returns `200` from the first request.
+- After the background bootstrap finishes, ENSRainbow verifies that the on-disk database's stored label set (`labelSetId` and `highestLabelSetVersion`) matches the configured one. On mismatch it logs a helpful error naming both the expected and actual label sets, refuses to serve, and terminates with exit code `1`.
+- `/ready` continues to gate on full database readiness (`200` only after the database has been attached and the env-vs-DB validation has passed).
+- `/v1/heal/{labelhash}` and `/v1/labels/count` continue to return `503 Service Unavailable` while the database is still bootstrapping.
+- `/health` is unchanged and still returns `200` as soon as the HTTP server is listening.

apps/ensindexer/src/lib/public-config-builder/public-config-builder.test.ts

@@ -230,49 +230,9 @@ describe("PublicConfigBuilder", () => {
       expect(result).toBe(customConfig);
       expect(result.isSubgraphCompatible).toBe(false);
     });
-
-    it("awaits readiness before fetching ENSRainbow config", async () => {
-      const callOrder: string[] = [];
-      const ensRainbowClientMock = {
-        config: vi.fn().mockImplementation(async () => {
-          callOrder.push("config");
-          return mockEnsRainbowConfig;
-        }),
-      } as unknown as EnsRainbow.ApiClient;
-      const waitForReady = vi.fn().mockImplementation(async () => {
-        callOrder.push("wait");
-      });
-
-      setupStandardMocks();
-      const mockPublicConfig = createMockPublicConfig();
-      vi.mocked(validateEnsIndexerPublicConfig).mockReturnValue(mockPublicConfig);
-
-      const builder = new PublicConfigBuilder(ensRainbowClientMock, waitForReady);
-      const result = await builder.getPublicConfig();
-
-      expect(waitForReady).toHaveBeenCalledTimes(1);
-      expect(ensRainbowClientMock.config).toHaveBeenCalledTimes(1);
-      expect(callOrder).toEqual(["wait", "config"]);
-      expect(result).toBe(mockPublicConfig);
-    });
   });
 
   describe("getPublicConfig() - error handling", () => {
-    it("throws when readiness check fails and does not call config()", async () => {
-      const readinessError = new Error("ENSRainbow not ready");
-      const ensRainbowClientMock = {
-        config: vi.fn(),
-      } as unknown as EnsRainbow.ApiClient;
-      const waitForReady = vi.fn().mockRejectedValue(readinessError);
-
-      const builder = new PublicConfigBuilder(ensRainbowClientMock, waitForReady);
-
-      await expect(builder.getPublicConfig()).rejects.toThrow(readinessError);
-      expect(waitForReady).toHaveBeenCalledTimes(1);
-      expect(ensRainbowClientMock.config).not.toHaveBeenCalled();
-      expect(validateEnsIndexerPublicConfig).not.toHaveBeenCalled();
-    });
-
     it("throws when ENSRainbow client config() fails", async () => {
       // Arrange
       const ensRainbowError = new Error("ENSRainbow service unavailable");

apps/ensindexer/src/lib/public-config-builder/public-config-builder.ts

@@ -19,15 +19,6 @@ export class PublicConfigBuilder {
    */
   private ensRainbowClient: EnsRainbow.ApiClient;
 
-  /**
-   * One-time async readiness hook awaited before the first
-   * `ensRainbowClient.config()` invocation, so callers don't race ENSRainbow's
-   * background bootstrap. Defaults to a no-op for callers that don't need to
-   * gate on readiness (e.g. tests or environments where ENSRainbow is already
-   * known to be ready).
-   */
-  private waitForEnsRainbowReady: () => Promise<void>;
-
   /**
    * Immutable ENSIndexer Public Config
    *
@@ -38,15 +29,9 @@ export class PublicConfigBuilder {
 
   /**
    * @param ensRainbowClient ENSRainbow Client instance used to fetch ENSRainbow Public Config
-   * @param waitForEnsRainbowReady One-time async readiness hook awaited before the first
-   *        `ensRainbowClient.config()` invocation. Defaults to a no-op.
    */
-  constructor(
-    ensRainbowClient: EnsRainbow.ApiClient,
-    waitForEnsRainbowReady: () => Promise<void> = async () => {},
-  ) {
+  constructor(ensRainbowClient: EnsRainbow.ApiClient) {
     this.ensRainbowClient = ensRainbowClient;
-    this.waitForEnsRainbowReady = waitForEnsRainbowReady;
   }
 
   /**
@@ -62,8 +47,6 @@ export class PublicConfigBuilder {
    */
   async getPublicConfig(): Promise<EnsIndexerPublicConfig> {
     if (typeof this.immutablePublicConfig === "undefined") {
-      await this.waitForEnsRainbowReady();
-
       const [versionInfo, ensRainbowPublicConfig] = await Promise.all([
         this.getEnsIndexerVersionInfo(),
         // TODO: remove dependency on ENSRainbow by dropping `ensRainbowPublicConfig` from `EnsIndexerPublicConfig`.

apps/ensindexer/src/lib/public-config-builder/singleton.ts

@@ -1,7 +1,4 @@
-import { ensRainbowClient, waitForEnsRainbowToBeReady } from "@/lib/ensrainbow/singleton";
+import { ensRainbowClient } from "@/lib/ensrainbow/singleton";
 import { PublicConfigBuilder } from "@/lib/public-config-builder/public-config-builder";
 
-export const publicConfigBuilder = new PublicConfigBuilder(
-  ensRainbowClient,
-  waitForEnsRainbowToBeReady,
-);
+export const publicConfigBuilder = new PublicConfigBuilder(ensRainbowClient);

apps/ensrainbow/src/commands/entrypoint-command.test.ts

@@ -109,6 +109,14 @@ describe("entrypointCommand (existing DB on disk)", () => {
     expect(healthRes.status).toBe(200);
     const healthData = (await healthRes.json()) as EnsRainbow.HealthResponse;
     expect(healthData).toEqual({ status: "ok" });
+
+    // /v1/config from CLI/env before bootstrap completes.
+    const earlyConfigRes = await fetch(`${endpoint}/v1/config`);
+    expect(earlyConfigRes.status).toBe(200);
+    const earlyConfigData = (await earlyConfigRes.json()) as EnsRainbow.ENSRainbowPublicConfig;
+    expect(earlyConfigData.serverLabelSet.labelSetId).toBe(labelSetId);
+    expect(earlyConfigData.serverLabelSet.highestLabelSetVersion).toBe(labelSetVersion);
+
     await handle.bootstrapComplete;
 
     const readyRes = await fetch(`${endpoint}/ready`);
@@ -130,6 +138,74 @@ describe("entrypointCommand (existing DB on disk)", () => {
   });
 });
 
+describe("entrypointCommand (env-vs-DB label-set mismatch)", () => {
+  // DB path uses configured id/version; contents claim a different label set -> mismatch after attach.
+  const configuredLabelSetId = buildLabelSetId("entrypoint-mismatch-test");
+  const configuredLabelSetVersion = buildLabelSetVersion(0);
+  const dbLabelSetId = buildLabelSetId("different-labelset");
+  const dbLabelSetVersion = buildLabelSetVersion(1);
+  const port = 3228;
+  const endpoint = `http://localhost:${port}`;
+
+  let testDataDir: string;
+  let handle: EntrypointCommandHandle | undefined;
+
+  beforeEach(async () => {
+    testDataDir = await mkdtemp(join(tmpdir(), "ensrainbow-test-entrypoint-mismatch-"));
+    const dbSubdir = join(testDataDir, `data-${configuredLabelSetId}_${configuredLabelSetVersion}`);
+    const markerFile = join(testDataDir, DB_READY_MARKER_FILENAME);
+
+    const db = await ENSRainbowDB.create(dbSubdir);
+    await db.setPrecalculatedRainbowRecordCount(0);
+    await db.markIngestionFinished();
+    await db.setLabelSetId(dbLabelSetId);
+    await db.setHighestLabelSetVersion(dbLabelSetVersion);
+    await db.close();
+
+    await writeFile(markerFile, "");
+  });
+
+  afterEach(async () => {
+    if (handle) {
+      await handle.close().catch(() => {});
+      handle = undefined;
+    }
+    await rm(testDataDir, { recursive: true, force: true });
+  });
+
+  it("invokes the exit hook with code 1 and does not flip /ready to 200", async () => {
+    const exit = vi.fn((code: number): never => {
+      throw new Error(`test exit hook (${code})`);
+    });
+
+    handle = await entrypointCommand({
+      port,
+      dataDir: testDataDir as AbsolutePath,
+      dbSchemaVersion: DB_SCHEMA_VERSION as DbSchemaVersion,
+      labelSetId: configuredLabelSetId,
+      labelSetVersion: configuredLabelSetVersion,
+      registerSignalHandlers: false,
+      exit,
+    });
+
+    // Still CLI/env public config; bootstrap fails before publishing db-backed state.
+    const configRes = await fetch(`${endpoint}/v1/config`);
+    expect(configRes.status).toBe(200);
+    const configData = (await configRes.json()) as EnsRainbow.ENSRainbowPublicConfig;
+    expect(configData.serverLabelSet.labelSetId).toBe(configuredLabelSetId);
+    expect(configData.serverLabelSet.highestLabelSetVersion).toBe(configuredLabelSetVersion);
+
+    await handle.bootstrapComplete;
+
+    expect(exit).toHaveBeenCalledTimes(1);
+    expect(exit).toHaveBeenCalledWith(1);
+
+    // /ready must NOT flip to 200 on mismatch - the cachedDbConfig is never set.
+    const readyRes = await fetch(`${endpoint}/ready`);
+    expect(readyRes.status).toBe(503);
+  });
+});
+
 describe("entrypointCommand (signal handlers)", () => {
   const labelSetId = buildLabelSetId("entrypoint-signal-test");
   const labelSetVersion = buildLabelSetVersion(0);

apps/ensrainbow/src/commands/entrypoint-command.ts

@@ -6,10 +6,10 @@ import { fileURLToPath } from "node:url";
 
 import { serve } from "@hono/node-server";
 
+import type { EnsRainbowServerLabelSet } from "@ensnode/ensnode-sdk";
 import { stringifyConfig } from "@ensnode/ensnode-sdk/internal";
-import type { EnsRainbow } from "@ensnode/ensrainbow-sdk";
 
-import { buildEnsRainbowPublicConfig } from "@/config/public";
+import { buildEnsRainbowPublicConfigFromLabelSet } from "@/config/public";
 import type { AbsolutePath, DbConfig, DbSchemaVersion } from "@/config/types";
 import { createApi } from "@/lib/api";
 import { ENSRainbowDB } from "@/lib/database";
@@ -50,6 +50,16 @@ export interface EntrypointCommandOptions {
    * Tests should pass `false` to avoid leaking handlers across cases.
    */
   registerSignalHandlers?: boolean;
+  /**
+   * Hook used to terminate the process on fatal bootstrap errors (download failure or
+   * env-vs-DB label-set mismatch). Defaults to `process.exit`. Implementations must not
+   * return normally (same contract as `process.exit`). If a custom hook returns anyway,
+   * {@link entrypointCommand} calls `process.exit(code)` as a fallback so the process
+   * cannot keep serving after a fatal bootstrap error. Tests should throw from the hook
+   * (caught internally) instead of returning, so the test runner is not killed by that
+   * fallback.
+   */
+  exit?: (code: number) => never;
 }
 
 /**
@@ -58,7 +68,8 @@ export interface EntrypointCommandOptions {
 export interface EntrypointCommandHandle {
   /**
    * Resolves when bootstrap finishes or is aborted by shutdown.
-   * Never rejects: non-abort failures terminate the process via `process.exit(1)`.
+   * Never rejects: non-abort failures terminate the process via `options.exit(1)`
+   * (defaults to `process.exit(1)`).
    */
   readonly bootstrapComplete: Promise<void>;
   close(): Promise<void>;
@@ -87,13 +98,15 @@ export async function entrypointCommand(
 
   const ensRainbowServer = ENSRainbowServer.createPending();
 
-  let cachedPublicConfig: EnsRainbow.ENSRainbowPublicConfig | null = null;
+  // Public config from CLI/env so `/v1/config` works before attach; validated against DB after bootstrap.
+  const argsServerLabelSet: EnsRainbowServerLabelSet = {
+    labelSetId: options.labelSetId,
+    highestLabelSetVersion: options.labelSetVersion,
+  };
+  const inMemoryPublicConfig = buildEnsRainbowPublicConfigFromLabelSet(argsServerLabelSet);
+
   let cachedDbConfig: DbConfig | null = null;
-  const app = createApi(
-    ensRainbowServer,
-    () => cachedPublicConfig,
-    () => cachedDbConfig,
-  );
+  const app = createApi(ensRainbowServer, inMemoryPublicConfig, () => cachedDbConfig);
 
   const httpServer = serve({
     fetch: app.fetch,
@@ -172,13 +185,54 @@ export async function entrypointCommand(
     process.once("SIGINT", signalHandler);
   }
 
+  const exit = options.exit ?? ((code: number) => process.exit(code));
+  let exitRequested = false;
+  const requestExit = (code: number) => {
+    exitRequested = true;
+    let exitHookThrew = false;
+    try {
+      exit(code);
+    } catch (_error) {
+      exitHookThrew = true;
+      // Tests may throw from a custom exit hook to short-circuit control flow.
+      // Swallow to avoid this surfacing as a bootstrap failure.
+    }
+    if (!exitHookThrew) {
+      // TypeScript cannot enforce `never` at runtime; a buggy hook could return and leave
+      // HTTP up after resolvePromise() + fatal bootstrap — force termination.
+      logger.error(
+        new Error("ENSRainbow exit hook returned without terminating the process"),
+        "Exit hook violated non-returning contract; calling process.exit as fallback",
+      );
+      process.exit(code);
+    }
+  };
+
   const bootstrapComplete = new Promise<void>((resolvePromise) => {
     // Defer bootstrap so the HTTP server starts accepting requests first.
     setTimeout(() => {
       runDbBootstrap(options, ensRainbowServer, bootstrapAborter.signal)
-        .then(({ publicConfig, dbConfig }) => {
+        .then((dbConfig) => {
+          if (
+            dbConfig.serverLabelSet.labelSetId !== argsServerLabelSet.labelSetId ||
+            dbConfig.serverLabelSet.highestLabelSetVersion !==
+              argsServerLabelSet.highestLabelSetVersion
+          ) {
+            logger.error(
+              `ENSRainbow database label set ` +
+                `${dbConfig.serverLabelSet.labelSetId}@${dbConfig.serverLabelSet.highestLabelSetVersion} ` +
+                `does not match the configured ` +
+                `LABEL_SET_ID=${argsServerLabelSet.labelSetId} / ` +
+                `LABEL_SET_VERSION=${argsServerLabelSet.highestLabelSetVersion}. ` +
+                `Refusing to serve a misconfigured database; please reconcile the env/CLI ` +
+                `arguments with the database in the data directory and restart.`,
+            );
+            resolvePromise();
+            requestExit(1);
+            return;
+          }
+
           cachedDbConfig = dbConfig;
-          cachedPublicConfig = publicConfig;
           logger.info(
             "ENSRainbow database bootstrap complete. Service is ready to serve heal requests.",
           );
@@ -190,8 +244,13 @@ export async function entrypointCommand(
             resolvePromise();
             return;
           }
+          if (exitRequested) {
+            resolvePromise();
+            return;
+          }
           logger.error(error, "ENSRainbow database bootstrap failed - exiting");
-          process.exit(1);
+          resolvePromise();
+          requestExit(1);
         })
         .finally(() => {
           signalBootstrapSettled();
@@ -206,13 +265,13 @@ export async function entrypointCommand(
  * Idempotent DB bootstrap pipeline.
  *
  * If marker + DB are present, reuse them; otherwise download + extract.
- * Returns the public config and DB config for the attached DB.
+ * Returns the {@link DbConfig} read from the attached DB.
  */
 async function runDbBootstrap(
   options: EntrypointCommandOptions,
   ensRainbowServer: ENSRainbowServer,
   signal: AbortSignal,
-): Promise<{ publicConfig: EnsRainbow.ENSRainbowPublicConfig; dbConfig: DbConfig }> {
+): Promise<DbConfig> {
   const { dataDir, dbSchemaVersion, labelSetId, labelSetVersion } = options;
   const downloadTempDir = options.downloadTempDir ?? join(dataDir, ".download-temp");
   const markerFile = join(dataDir, DB_READY_MARKER_FILENAME);
@@ -233,8 +292,7 @@ async function runDbBootstrap(
       throwIfAborted(signal);
       await ensRainbowServer.attachDb(existingDb);
       existingDbAttached = true;
-      const dbConfig = await buildDbConfig(ensRainbowServer);
-      return { publicConfig: buildEnsRainbowPublicConfig(dbConfig), dbConfig };
+      return await buildDbConfig(ensRainbowServer);
     } catch (error) {
       // Always release any opened DB handle/lock first, even when aborting. This prevents
       // a leaked LevelDB lock when SIGTERM races a non-abort failure (e.g. attachDb throws
@@ -296,8 +354,7 @@ async function runDbBootstrap(
     // Write marker only after a successful attach.
     await writeFile(markerFile, "");
 
-    const dbConfig = await buildDbConfig(ensRainbowServer);
-    return { publicConfig: buildEnsRainbowPublicConfig(dbConfig), dbConfig };
+    return await buildDbConfig(ensRainbowServer);
   } catch (error) {
     if (!dbAttached) {
       await safeClose(db);