refactor(ensapi): apply operation result pattern

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

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import {
+  buildResultOk,
   type CrossChainIndexingStatusSnapshot,
   createRealtimeIndexingStatusProjection,
   type UnixTimestamp,
@@ -69,9 +70,11 @@ describe("amirealtime-api", () => {
 
         // Assert
         expect(response.status).toBe(200);
-        expect(responseJson).toMatchObject({
-          maxWorstCaseDistance: 300,
-        });
+        expect(responseJson).toMatchObject(
+          buildResultOk({
+            maxWorstCaseDistance: 300,
+          }),
+        );
       });
 
       it("should accept valid maxWorstCaseDistance query param (set to `0`)", async () => {
@@ -84,9 +87,11 @@ describe("amirealtime-api", () => {
 
         // Assert
         expect(response.status).toBe(200);
-        expect(responseJson).toMatchObject({
-          maxWorstCaseDistance: 0,
-        });
+        expect(responseJson).toMatchObject(
+          buildResultOk({
+            maxWorstCaseDistance: 0,
+          }),
+        );
       });
 
       it("should use default maxWorstCaseDistance when unset", async () => {
@@ -99,9 +104,11 @@ describe("amirealtime-api", () => {
 
         // Assert
         expect(response.status).toBe(200);
-        expect(responseJson).toMatchObject({
-          maxWorstCaseDistance: AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE,
-        });
+        expect(responseJson).toMatchObject(
+          buildResultOk({
+            maxWorstCaseDistance: AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE,
+          }),
+        );
       });
 
       it("should use default maxWorstCaseDistance when not provided", async () => {
@@ -114,9 +121,11 @@ describe("amirealtime-api", () => {
 
         // Assert
         expect(response.status).toBe(200);
-        expect(responseJson).toMatchObject({
-          maxWorstCaseDistance: AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE,
-        });
+        expect(responseJson).toMatchObject(
+          buildResultOk({
+            maxWorstCaseDistance: AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE,
+          }),
+        );
       });
 
       it("should reject invalid maxWorstCaseDistance (negative number)", async () => {
@@ -161,11 +170,13 @@ describe("amirealtime-api", () => {
 
         // Assert
         expect(response.status).toBe(200);
-        expect(responseJson).toMatchObject({
-          maxWorstCaseDistance: 10,
-          slowestChainIndexingCursor: 1766123720,
-          worstCaseDistance: 9,
-        });
+        expect(responseJson).toStrictEqual(
+          buildResultOk({
+            maxWorstCaseDistance: 10,
+            slowestChainIndexingCursor: 1766123720,
+            worstCaseDistance: 9,
+          }),
+        );
       });
 
       it("should return 200 when worstCaseDistance equals maxWorstCaseDistance", async () => {
@@ -178,11 +189,13 @@ describe("amirealtime-api", () => {
 
         // Assert
         expect(response.status).toBe(200);
-        expect(responseJson).toMatchObject({
-          maxWorstCaseDistance: 10,
-          slowestChainIndexingCursor: 1766123719,
-          worstCaseDistance: 10,
-        });
+        expect(responseJson).toStrictEqual(
+          buildResultOk({
+            maxWorstCaseDistance: 10,
+            slowestChainIndexingCursor: 1766123719,
+            worstCaseDistance: 10,
+          }),
+        );
       });
 
       it("should return 503 when worstCaseDistance exceeds maxWorstCaseDistance", async () => {
@@ -195,13 +208,13 @@ describe("amirealtime-api", () => {
 
         // Assert
         expect(response.status).toBe(503);
-        expect(responseJson).toHaveProperty("message");
-        expect(responseJson.message).toMatch(
+        expect(responseJson).toHaveProperty("errorMessage");
+        expect(responseJson.errorMessage).toMatch(
           /Indexing Status 'worstCaseDistance' must be below or equal to the requested 'maxWorstCaseDistance'; worstCaseDistance = 11; maxWorstCaseDistance = 10/,
         );
       });
 
-      it("should return 500 when indexing status has not been resolved", async () => {
+      it("should return 503 when indexing status has not been resolved", async () => {
         // Arrange: set `indexingStatus` context var
         indexingStatusMiddlewareMock.mockImplementation(async (c, next) => {
           c.set("indexingStatus", new Error("Network error"));
@@ -215,9 +228,9 @@ describe("amirealtime-api", () => {
 
         // Assert
         expect(response.status).toBe(503);
-        expect(responseJson).toHaveProperty("message");
-        expect(responseJson.message).toMatch(
-          /Indexing Status has to be resolved successfully before 'maxWorstCaseDistance' can be applied./,
+        expect(responseJson).toHaveProperty("errorMessage");
+        expect(responseJson.errorMessage).toMatch(
+          /Indexing Status must be resolved successfully before 'maxWorstCaseDistance' can be applied./,
         );
       });
     });

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

@@ -2,13 +2,21 @@ import { minutesToSeconds } from "date-fns";
 import { describeRoute } from "hono-openapi";
 import z from "zod/v4";
 
-import type { Duration } from "@ensnode/ensnode-sdk";
+import {
+  type AmIRealtimeResult,
+  buildResultInternalServerError,
+  buildResultOk,
+  buildResultServiceUnavailable,
+  type Duration,
+  ResultCodes,
+} from "@ensnode/ensnode-sdk";
 import { makeDurationSchema } from "@ensnode/ensnode-sdk/internal";
 
-import { errorResponse } from "@/lib/handlers/error-response";
 import { params } from "@/lib/handlers/params.schema";
+import { buildRouteResponsesDescription } from "@/lib/handlers/route-responses-description";
 import { validate } from "@/lib/handlers/validate";
 import { factory } from "@/lib/hono-factory";
+import { resultIntoHttpResponse } from "@/lib/result/result-into-http-response";
 
 const app = factory.createApp();
 
@@ -24,16 +32,22 @@ app.get(
     summary: "Check indexing progress",
     description:
       "Checks if the indexing progress is guaranteed to be within a requested worst-case distance of realtime",
-    responses: {
-      200: {
+    responses: buildRouteResponsesDescription<AmIRealtimeResult>({
+      [ResultCodes.Ok]: {
         description:
           "Indexing progress is guaranteed to be within the requested distance of realtime",
       },
-      503: {
+      [ResultCodes.InvalidRequest]: {
+        description: "Invalid request parameters",
+      },
+      [ResultCodes.InternalServerError]: {
+        description: "Indexing progress cannot be determined due to an internal server error",
+      },
+      [ResultCodes.ServiceUnavailable]: {
         description:
           "Indexing progress is not guaranteed to be within the requested distance of realtime or indexing status unavailable",
       },
-    },
+    }),
   }),
   validate(
     "query",
@@ -46,41 +60,46 @@ app.get(
     }),
   ),
   async (c) => {
-    // context must be set by the required middleware
+    // Invariant: Indexing Status must be available in application context
     if (c.var.indexingStatus === undefined) {
-      throw new Error(`Invariant(amirealtime-api): indexingStatusMiddleware required.`);
+      const result = buildResultInternalServerError(
+        `Invariant(amirealtime-api): Indexing Status must be available in application context.`,
+      );
+
+      return resultIntoHttpResponse(c, result);
     }
 
-    // return 503 response error with details on prerequisite being unavailable
+    // Invariant: Indexing Status must be resolved successfully before 'maxWorstCaseDistance' can be applied
     if (c.var.indexingStatus instanceof Error) {
-      return errorResponse(
-        c,
-        `Invariant(amirealtime-api): Indexing Status has to be resolved successfully before 'maxWorstCaseDistance' can be applied.`,
-        503,
+      const result = buildResultServiceUnavailable(
+        `Invariant(amirealtime-api): Indexing Status must be resolved successfully before 'maxWorstCaseDistance' can be applied.`,
       );
+
+      return resultIntoHttpResponse(c, result);
     }
 
     const { maxWorstCaseDistance } = c.req.valid("query");
     const { worstCaseDistance, snapshot } = c.var.indexingStatus;
     const { slowestChainIndexingCursor } = snapshot;
 
-    // return 503 response error with details on
-    // requested `maxWorstCaseDistance` vs. actual `worstCaseDistance`
+    // Case: worst-case distance exceeds requested maximum
     if (worstCaseDistance > maxWorstCaseDistance) {
-      return errorResponse(
-        c,
+      const result = buildResultServiceUnavailable(
         `Indexing Status 'worstCaseDistance' must be below or equal to the requested 'maxWorstCaseDistance'; worstCaseDistance = ${worstCaseDistance}; maxWorstCaseDistance = ${maxWorstCaseDistance}`,
-        503,
       );
+
+      return resultIntoHttpResponse(c, result);
     }
 
-    // return 200 response OK with current details on `maxWorstCaseDistance`,
-    // `slowestChainIndexingCursor`, and `worstCaseDistance`
-    return c.json({
-      maxWorstCaseDistance,
-      slowestChainIndexingCursor,
-      worstCaseDistance,
-    });
+    // Case: worst-case distance is within requested maximum
+    return resultIntoHttpResponse(
+      c,
+      buildResultOk({
+        maxWorstCaseDistance,
+        slowestChainIndexingCursor,
+        worstCaseDistance,
+      }),
+    );
   },
 );