refactor: rename all instances of maxRealtimeDistance to maxWorstCaseDistance (namehash#1415)

Author: tk-o

apps/ensapi/src/handlers/amirealtime-api.test.ts

@@ -9,7 +9,7 @@ import {
 import { factory } from "@/lib/hono-factory";
 import * as middleware from "@/middleware/indexing-status.middleware";
 
-import amIRealtimeApi, { AMIREALTIME_DEFAULT_MAX_REALTIME_DISTANCE } from "./amirealtime-api"; // adjust import path as needed
+import amIRealtimeApi, { AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE } from "./amirealtime-api"; // adjust import path as needed
 
 vi.mock("@/middleware/indexing-status.middleware", () => ({
   indexingStatusMiddleware: vi.fn(),
@@ -59,52 +59,52 @@ describe("amirealtime-api", () => {
 
   describe("GET /amirealtime", () => {
     describe("request", () => {
-      it("should accept valid maxRealtimeDistance query param", async () => {
+      it("should accept valid maxWorstCaseDistance query param", async () => {
         // Arrange: set `indexingStatus` context var
         arrangeMockedIndexingStatusMiddleware({ now });
 
         // Act
-        const response = await app.request("http://localhost/amirealtime?maxRealtimeDistance=300");
+        const response = await app.request("http://localhost/amirealtime?maxWorstCaseDistance=300");
         const responseJson = await response.json();
 
         // Assert
         expect(response.status).toBe(200);
         expect(responseJson).toMatchObject({
-          maxRealtimeDistance: 300,
+          maxWorstCaseDistance: 300,
         });
       });
 
-      it("should accept valid maxRealtimeDistance query param (set to `0`)", async () => {
+      it("should accept valid maxWorstCaseDistance query param (set to `0`)", async () => {
         // Arrange: set `indexingStatus` context var
         arrangeMockedIndexingStatusMiddleware({ now, slowestChainIndexingCursor: now });
 
         // Act
-        const response = await app.request("http://localhost/amirealtime?maxRealtimeDistance=0");
+        const response = await app.request("http://localhost/amirealtime?maxWorstCaseDistance=0");
         const responseJson = await response.json();
 
         // Assert
         expect(response.status).toBe(200);
         expect(responseJson).toMatchObject({
-          maxRealtimeDistance: 0,
+          maxWorstCaseDistance: 0,
         });
       });
 
-      it("should use default maxRealtimeDistance when unset", async () => {
+      it("should use default maxWorstCaseDistance when unset", async () => {
         // Arrange: set `indexingStatus` context var
         arrangeMockedIndexingStatusMiddleware({ now });
 
         // Act
-        const response = await app.request("http://localhost/amirealtime?maxRealtimeDistance");
+        const response = await app.request("http://localhost/amirealtime?maxWorstCaseDistance");
         const responseJson = await response.json();
 
         // Assert
         expect(response.status).toBe(200);
         expect(responseJson).toMatchObject({
-          maxRealtimeDistance: AMIREALTIME_DEFAULT_MAX_REALTIME_DISTANCE,
+          maxWorstCaseDistance: AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE,
         });
       });
 
-      it("should use default maxRealtimeDistance when not provided", async () => {
+      it("should use default maxWorstCaseDistance when not provided", async () => {
         // Arrange: set `indexingStatus` context var
         arrangeMockedIndexingStatusMiddleware({ now });
 
@@ -115,89 +115,89 @@ describe("amirealtime-api", () => {
         // Assert
         expect(response.status).toBe(200);
         expect(responseJson).toMatchObject({
-          maxRealtimeDistance: AMIREALTIME_DEFAULT_MAX_REALTIME_DISTANCE,
+          maxWorstCaseDistance: AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE,
         });
       });
 
-      it("should reject invalid maxRealtimeDistance (negative number)", async () => {
+      it("should reject invalid maxWorstCaseDistance (negative number)", async () => {
         // Arrange: set `indexingStatus` context var
         arrangeMockedIndexingStatusMiddleware({ now });
 
         // Act
-        const response = await app.request("http://localhost/amirealtime?maxRealtimeDistance=-1");
+        const response = await app.request("http://localhost/amirealtime?maxWorstCaseDistance=-1");
 
         // Assert
         expect(response.status).toBe(400);
         await expect(response.text()).resolves.toMatch(
-          /maxRealtimeDistance query param must be a non-negative integer/,
+          /maxWorstCaseDistance query param must be a non-negative integer/,
         );
       });
 
-      it("should reject invalid maxRealtimeDistance (not a number)", async () => {
+      it("should reject invalid maxWorstCaseDistance (not a number)", async () => {
         // Arrange: set `indexingStatus` context var
         arrangeMockedIndexingStatusMiddleware({ now });
 
         // Act
         const response = await app.request(
-          "http://localhost/amirealtime?maxRealtimeDistance=invalid",
+          "http://localhost/amirealtime?maxWorstCaseDistance=invalid",
         );
 
         // Assert
         expect(response.status).toBe(400);
         await expect(response.text()).resolves.toMatch(
-          /maxRealtimeDistance query param must be a number/,
+          /maxWorstCaseDistance query param must be a number/,
         );
       });
     });
 
     describe("response", () => {
-      it("should return 200 when worstCaseDistance is below maxRealtimeDistance", async () => {
+      it("should return 200 when worstCaseDistance is below maxWorstCaseDistance", async () => {
         // Arrange: set `indexingStatus` context var
         arrangeMockedIndexingStatusMiddleware({ now, slowestChainIndexingCursor: now - 9 });
 
         // Act
-        const response = await app.request("http://localhost/amirealtime?maxRealtimeDistance=10");
+        const response = await app.request("http://localhost/amirealtime?maxWorstCaseDistance=10");
         const responseJson = await response.json();
 
         // Assert
         expect(response.status).toBe(200);
         expect(responseJson).toMatchObject({
-          maxRealtimeDistance: 10,
+          maxWorstCaseDistance: 10,
           slowestChainIndexingCursor: 1766123720,
           worstCaseDistance: 9,
         });
       });
 
-      it("should return 200 when worstCaseDistance equals maxRealtimeDistance", async () => {
+      it("should return 200 when worstCaseDistance equals maxWorstCaseDistance", async () => {
         // Arrange: set `indexingStatus` context var
         arrangeMockedIndexingStatusMiddleware({ now, slowestChainIndexingCursor: now - 10 });
 
         // Act
-        const response = await app.request("http://localhost/amirealtime?maxRealtimeDistance=10");
+        const response = await app.request("http://localhost/amirealtime?maxWorstCaseDistance=10");
         const responseJson = await response.json();
 
         // Assert
         expect(response.status).toBe(200);
         expect(responseJson).toMatchObject({
-          maxRealtimeDistance: 10,
+          maxWorstCaseDistance: 10,
           slowestChainIndexingCursor: 1766123719,
           worstCaseDistance: 10,
         });
       });
 
-      it("should return 503 when worstCaseDistance exceeds maxRealtimeDistance", async () => {
+      it("should return 503 when worstCaseDistance exceeds maxWorstCaseDistance", async () => {
         // Arrange: set `indexingStatus` context var
         arrangeMockedIndexingStatusMiddleware({ now, slowestChainIndexingCursor: now - 11 });
 
         // Act
-        const response = await app.request("http://localhost/amirealtime?maxRealtimeDistance=10");
+        const response = await app.request("http://localhost/amirealtime?maxWorstCaseDistance=10");
         const responseJson = await response.json();
 
         // Assert
         expect(response.status).toBe(503);
         expect(responseJson).toHaveProperty("message");
         expect(responseJson.message).toMatch(
-          /Indexing Status 'worstCaseDistance' must be below or equal to the requested 'maxRealtimeDistance'; worstCaseDistance = 11; maxRealtimeDistance = 10/,
+          /Indexing Status 'worstCaseDistance' must be below or equal to the requested 'maxWorstCaseDistance'; worstCaseDistance = 11; maxWorstCaseDistance = 10/,
         );
       });
 
@@ -210,14 +210,14 @@ describe("amirealtime-api", () => {
         });
 
         // Act
-        const response = await app.request("http://localhost/amirealtime?maxRealtimeDistance=10");
+        const response = await app.request("http://localhost/amirealtime?maxWorstCaseDistance=10");
         const responseJson = await response.json();
 
         // Assert
-        expect(response.status).toBe(500);
+        expect(response.status).toBe(503);
         expect(responseJson).toHaveProperty("message");
         expect(responseJson.message).toMatch(
-          /Indexing Status has to be resolved successfully before 'maxRealtimeDistance' can be applied./,
+          /Indexing Status has to be resolved successfully before 'maxWorstCaseDistance' can be applied./,
         );
       });
     });

apps/ensapi/src/handlers/amirealtime-api.ts

@@ -11,52 +11,54 @@ import { factory } from "@/lib/hono-factory";
 
 const app = factory.createApp();
 
-// Set default `maxRealtimeDistance` for `GET /amirealtime` endpoint to one minute.
-export const AMIREALTIME_DEFAULT_MAX_REALTIME_DISTANCE: Duration = minutesToSeconds(1);
+// Set default `maxWorstCaseDistance` for `GET /amirealtime` endpoint to one minute.
+export const AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE: Duration = minutesToSeconds(1);
 
 // allow performance monitoring clients to read HTTP Status for the provided
-// `maxRealtimeDistance` param
+// `maxWorstCaseDistance` param
 app.get(
   "/",
   validate(
     "query",
     z.object({
-      maxRealtimeDistance: params.queryParam
+      maxWorstCaseDistance: params.queryParam
         .optional()
-        .default(AMIREALTIME_DEFAULT_MAX_REALTIME_DISTANCE)
-        .pipe(makeDurationSchema("maxRealtimeDistance query param")),
+        .default(AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE)
+        .pipe(makeDurationSchema("maxWorstCaseDistance query param")),
     }),
   ),
   async (c) => {
     // context must be set by the required middleware
     if (c.var.indexingStatus === undefined) {
-      throw new Error(`Invariant(amirealtime): indexingStatusMiddleware required.`);
+      throw new Error(`Invariant(amirealtime-api): indexingStatusMiddleware required.`);
     }
 
+    // return 503 response error with details on prerequisite being unavailable
     if (c.var.indexingStatus instanceof Error) {
       return errorResponse(
         c,
-        `Invariant(amirealtime): Indexing Status has to be resolved successfully before 'maxRealtimeDistance' can be applied.`,
+        `Invariant(amirealtime-api): Indexing Status has to be resolved successfully before 'maxWorstCaseDistance' can be applied.`,
+        503,
       );
     }
 
-    const { maxRealtimeDistance } = c.req.valid("query");
+    const { maxWorstCaseDistance } = c.req.valid("query");
     const { worstCaseDistance, snapshot } = c.var.indexingStatus;
     const { slowestChainIndexingCursor } = snapshot;
 
     // return 503 response error with details on
-    // requested `maxRealtimeDistance` vs. actual `worstCaseDistance`
-    if (worstCaseDistance > maxRealtimeDistance) {
+    // requested `maxWorstCaseDistance` vs. actual `worstCaseDistance`
+    if (worstCaseDistance > maxWorstCaseDistance) {
       return errorResponse(
         c,
-        `Indexing Status 'worstCaseDistance' must be below or equal to the requested 'maxRealtimeDistance'; worstCaseDistance = ${worstCaseDistance}; maxRealtimeDistance = ${maxRealtimeDistance}`,
+        `Indexing Status 'worstCaseDistance' must be below or equal to the requested 'maxWorstCaseDistance'; worstCaseDistance = ${worstCaseDistance}; maxWorstCaseDistance = ${maxWorstCaseDistance}`,
         503,
       );
     }
 
-    // return 200 response OK with current details on `maxRealtimeDistance`,
+    // return 200 response OK with current details on `maxWorstCaseDistance`,
     // `slowestChainIndexingCursor`, and `worstCaseDistance`
-    return c.json({ maxRealtimeDistance, slowestChainIndexingCursor, worstCaseDistance });
+    return c.json({ maxWorstCaseDistance, slowestChainIndexingCursor, worstCaseDistance });
   },
 );
 

apps/ensapi/src/handlers/ensnode-api.ts

@@ -35,7 +35,7 @@ app.get("/indexing-status", async (c) => {
       serializeIndexingStatusResponse({
         responseCode: IndexingStatusResponseCodes.Error,
       } satisfies IndexingStatusResponseError),
-      500,
+      503,
     );
   }
 

apps/ensapi/src/middleware/is-realtime.middleware.ts

@@ -8,7 +8,7 @@ import { makeLogger } from "@/lib/logger";
  */
 export type IsRealtimeMiddlewareVariables = { isRealtime: boolean };
 
-export const makeIsRealtimeMiddleware = (scope: string, maxRealtimeDistance: Duration) => {
+export const makeIsRealtimeMiddleware = (scope: string, maxWorstCaseDistance: Duration) => {
   const logger = makeLogger(scope);
 
   let hasLoggedIndexingStatusError = false;
@@ -24,7 +24,7 @@ export const makeIsRealtimeMiddleware = (scope: string, maxRealtimeDistance: Dur
       // no indexing status available in context
       if (!hasLoggedIndexingStatusError) {
         logger.warn(
-          `ENSIndexer is NOT guaranteed to be within ${maxRealtimeDistance} seconds of realtime. Current indexing status has not been successfully fetched by this ENSApi instance yet and is therefore unknown to this ENSApi instance because: ${c.var.indexingStatus.message}.`,
+          `ENSIndexer is NOT guaranteed to be within ${maxWorstCaseDistance} seconds of realtime. Current indexing status has not been successfully fetched by this ENSApi instance yet and is therefore unknown to this ENSApi instance because: ${c.var.indexingStatus.message}.`,
         );
 
         hasLoggedIndexingStatusError = true;
@@ -35,16 +35,16 @@ export const makeIsRealtimeMiddleware = (scope: string, maxRealtimeDistance: Dur
     }
 
     // determine if we're within the max worst-case distance to qualify as "realtime".
-    const isRealtime = c.var.indexingStatus.worstCaseDistance <= maxRealtimeDistance;
+    const isRealtime = c.var.indexingStatus.worstCaseDistance <= maxWorstCaseDistance;
 
     if (lastLoggedIsRealtime !== isRealtime) {
       if (isRealtime) {
         logger.info(
-          `ENSIndexer is guaranteed to be within ${maxRealtimeDistance} seconds of realtime.`,
+          `ENSIndexer is guaranteed to be within ${maxWorstCaseDistance} seconds of realtime`,
         );
       } else {
         logger.warn(
-          `ENSIndexer is NOT guaranteed to be within ${maxRealtimeDistance} seconds of realtime. (Worst Case distance: ${c.var.indexingStatus.worstCaseDistance} seconds > ${maxRealtimeDistance} seconds).`,
+          `ENSIndexer is NOT guaranteed to be within ${maxWorstCaseDistance} seconds of realtime. (Worst Case distance: ${c.var.indexingStatus.worstCaseDistance} seconds > ${maxWorstCaseDistance} seconds).`,
         );
       }
 

docs/ensnode.io/src/content/docs/docs/usage/api.mdx

@@ -216,17 +216,18 @@ This allows your client to programmatically determine whether the ENSNode
 instance is sufficiently synchronized for your use case before proceeding with
 operations that depend on the latest onchain data.
 
-#### Verification endpoint
+#### Simplified Monitoring API
 
-For improved developer experience, you may want to use `GET /amirealtime`
-endpoint, which supports an optional `maxRealtimeDistance` parameter.
+For simplified monitoring, you may want to use `GET /amirealtime` endpoint,
+which supports an optional `maxWorstCaseDistance` parameter (for which default
+value is `AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE`).
 
-The `maxRealtimeDistance` parameter accepts a duration value in seconds,
-representing the max allowed distance from the current "tip" of all indexed chains.
+The `maxWorstCaseDistance` parameter accepts a duration value in seconds,
+representing the max worst case distance from the current "tip" of all indexed chains.
 When you include this parameter it influences the HTTP response code as follows:
 
-- **Success (200 OK)**: The latest indexed block of each chain is within the requested distance from realtime.
-- **Service Unavailable (503)**: The latest indexed block of each chain is NOT within the requested distance from realtime.
+- **Success (200 OK)**: The latest indexed block of each chain is guaranteed within the requested distance from realtime.
+- **Service Unavailable (503)**: The latest indexed block of each chain is NOT guaranteed within the requested distance from realtime.
 
 
 ## Registrar Actions API

packages/ensnode-sdk/README.md

@@ -169,14 +169,10 @@ console.log(config);
 
 #### Indexing Status API
 
-##### `indexingStatus(options)`
+##### `indexingStatus()`
 
 Fetches the ENSNode's multichain indexing status.
 
-- `options`: (optional) additional options
-  - `maxRealtimeDistance`: (optional) The max allowed distance in seconds between the latest indexed block of the slowest indexed chain and the current time. Setting this parameter influences the HTTP response code:
-    - Success (200 OK): The latest indexed block of each chain is within the requested distance from realtime
-    - Service Unavailable (503): The latest indexed block of each chain is NOT within the requested distance from realtime
 - Returns: `IndexingStatusResponse` - The indexing status data for all indexed chains
 - Throws: Error if the request fails or the ENSNode API returns an error response
 
@@ -185,11 +181,6 @@ Fetches the ENSNode's multichain indexing status.
 const status = await client.indexingStatus();
 console.log(status);
 // Returns indexing status for all indexed chains
-
-// Check if omnichain indexing is within 60 seconds of realtime
-const status = await client.indexingStatus({ maxRealtimeDistance: 60 });
-console.log(status);
-// Returns indexing status, throws if not within 60 seconds of realtime
 ```
 
 ### Configuration