Implement operation result pattern for Registrar Actions API

Author: tk-o

apps/ensapi/src/handlers/registrar-actions-api.ts

@@ -3,16 +3,16 @@ import z from "zod/v4";
 
 import {
   buildPageContext,
+  buildResultOkTimestamped,
+  buildResultServiceUnavailable,
   type Node,
   RECORDS_PER_PAGE_DEFAULT,
   RECORDS_PER_PAGE_MAX,
   type RegistrarActionsFilter,
   RegistrarActionsOrders,
-  RegistrarActionsResponseCodes,
-  type RegistrarActionsResponseError,
-  type RegistrarActionsResponseOk,
+  ResultCodes,
   registrarActionsFilter,
-  serializeRegistrarActionsResponse,
+  serializeNamedRegistrarActions,
 } from "@ensnode/ensnode-sdk";
 import {
   makeLowercaseAddressSchema,
@@ -26,6 +26,10 @@ import { validate } from "@/lib/handlers/validate";
 import { factory } from "@/lib/hono-factory";
 import { makeLogger } from "@/lib/logger";
 import { findRegistrarActions } from "@/lib/registrar-actions/find-registrar-actions";
+import {
+  resultCodeToHttpStatusCode,
+  resultIntoHttpResponse,
+} from "@/lib/result/result-into-http-response";
 import { registrarActionsApiMiddleware } from "@/middleware/registrar-actions.middleware";
 
 const app = factory.createApp();
@@ -161,45 +165,48 @@ app.get(
     summary: "Get Registrar Actions",
     description: "Returns all registrar actions with optional filtering and pagination",
     responses: {
-      200: {
+      [resultCodeToHttpStatusCode(ResultCodes.Ok)]: {
         description: "Successfully retrieved registrar actions",
       },
-      400: {
+      [resultCodeToHttpStatusCode(ResultCodes.InvalidRequest)]: {
         description: "Invalid query",
       },
-      500: {
-        description: "Internal server error",
+      [resultCodeToHttpStatusCode(ResultCodes.ServiceUnavailable)]: {
+        description: "Registrar Actions API is unavailable at the moment",
       },
     },
   }),
   validate("query", registrarActionsQuerySchema),
   async (c) => {
     try {
+      // Middleware ensures indexingStatus is available and not an Error
+      // This check is for TypeScript type safety
+      if (!c.var.indexingStatus || c.var.indexingStatus instanceof Error) {
+        throw new Error("Invariant violation: indexingStatus should be validated by middleware");
+      }
+
       const query = c.req.valid("query");
       const { registrarActions, pageContext } = await fetchRegistrarActions(undefined, query);
 
-      // respond with success response
-      return c.json(
-        serializeRegistrarActionsResponse({
-          responseCode: RegistrarActionsResponseCodes.Ok,
-          registrarActions,
+      // Get the accurateAsOf timestamp from the slowest chain indexing cursor
+      const accurateAsOf = c.var.indexingStatus.snapshot.slowestChainIndexingCursor;
+
+      const result = buildResultOkTimestamped(
+        {
+          registrarActions: serializeNamedRegistrarActions(registrarActions),
           pageContext,
-        } satisfies RegistrarActionsResponseOk),
+        },
+        accurateAsOf,
       );
+
+      return resultIntoHttpResponse(c, result);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : "Unknown error";
       logger.error(errorMessage);
 
-      // respond with 500 error response
-      return c.json(
-        serializeRegistrarActionsResponse({
-          responseCode: RegistrarActionsResponseCodes.Error,
-          error: {
-            message: `Registrar Actions API Response is unavailable`,
-          },
-        } satisfies RegistrarActionsResponseError),
-        500,
-      );
+      const result = buildResultServiceUnavailable("Registrar Actions API Response is unavailable");
+
+      return resultIntoHttpResponse(c, result);
     }
   },
 );
@@ -244,14 +251,14 @@ app.get(
     description:
       "Returns registrar actions filtered by parent node hash with optional additional filtering and pagination",
     responses: {
-      200: {
+      [resultCodeToHttpStatusCode(ResultCodes.Ok)]: {
         description: "Successfully retrieved registrar actions",
       },
-      400: {
-        description: "Invalid input",
+      [resultCodeToHttpStatusCode(ResultCodes.InvalidRequest)]: {
+        description: "Invalid query",
       },
-      500: {
-        description: "Internal server error",
+      [resultCodeToHttpStatusCode(ResultCodes.ServiceUnavailable)]: {
+        description: "Registrar Actions API is unavailable at the moment",
       },
     },
   }),
@@ -279,29 +286,22 @@ app.get(
       // Get the accurateAsOf timestamp from the slowest chain indexing cursor
       const accurateAsOf = c.var.indexingStatus.snapshot.slowestChainIndexingCursor;
 
-      // respond with success response
-      return c.json(
-        serializeRegistrarActionsResponse({
-          responseCode: RegistrarActionsResponseCodes.Ok,
-          registrarActions,
+      const result = buildResultOkTimestamped(
+        {
+          registrarActions: serializeNamedRegistrarActions(registrarActions),
           pageContext,
-          accurateAsOf,
-        } satisfies RegistrarActionsResponseOk),
+        },
+        accurateAsOf,
       );
+
+      return resultIntoHttpResponse(c, result);
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : "Unknown error";
       logger.error(errorMessage);
 
-      // respond with 500 error response
-      return c.json(
-        serializeRegistrarActionsResponse({
-          responseCode: RegistrarActionsResponseCodes.Error,
-          error: {
-            message: `Registrar Actions API Response is unavailable`,
-          },
-        } satisfies RegistrarActionsResponseError),
-        500,
-      );
+      const result = buildResultServiceUnavailable("Registrar Actions API Response is unavailable");
+
+      return resultIntoHttpResponse(c, result);
     }
   },
 );

apps/ensapi/src/lib/result/result-into-http-response.test.ts

@@ -10,11 +10,7 @@ import {
   ResultCodes,
 } from "@ensnode/ensnode-sdk";
 
-import {
-  type OpResultServer,
-  resultCodeToHttpStatusCode,
-  resultIntoHttpResponse,
-} from "./result-into-http-response";
+import { resultCodeToHttpStatusCode, resultIntoHttpResponse } from "./result-into-http-response";
 
 describe("resultCodeToHttpStatusCode", () => {
   it("should return 200 for ResultCodes.Ok", () => {
@@ -55,10 +51,7 @@ describe("resultIntoHttpResponse", () => {
       json: vi.fn().mockReturnValue(mockResponse),
     } as unknown as Context;
 
-    const result: OpResultServer<string> = {
-      resultCode: ResultCodes.Ok,
-      data: "test data",
-    };
+    const result = buildResultOk("test data");
 
     const response = resultIntoHttpResponse(mockContext, result);
 

apps/ensapi/src/lib/result/result-into-http-response.ts

@@ -1,13 +1,11 @@
 import type { Context } from "hono";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
 
-import { type AbstractResultOk, ResultCodes, type ResultServerError } from "@ensnode/ensnode-sdk";
-
-export type OpResultServerOk<TData> = AbstractResultOk<TData>;
-
-export type OpResultServer<TData = unknown> = OpResultServerOk<TData> | ResultServerError;
-
-export type OpResultServerResultCode = OpResultServer["resultCode"];
+import {
+  type OpResultServer,
+  type OpResultServerResultCode,
+  ResultCodes,
+} from "@ensnode/ensnode-sdk";
 
 /**
  * Get HTTP status code corresponding to the given operation result code.

apps/ensapi/src/middleware/registrar-actions.middleware.ts

@@ -1,13 +1,14 @@
 import config from "@/config";
 
 import {
-  RegistrarActionsResponseCodes,
+  buildResultInternalServerError,
+  buildResultServiceUnavailable,
   registrarActionsPrerequisites,
-  serializeRegistrarActionsResponse,
 } from "@ensnode/ensnode-sdk";
 
 import { factory } from "@/lib/hono-factory";
 import { makeLogger } from "@/lib/logger";
+import { resultIntoHttpResponse } from "@/lib/result/result-into-http-response";
 
 const logger = makeLogger("registrar-actions.middleware");
 
@@ -31,20 +32,20 @@ export const registrarActionsApiMiddleware = factory.createMiddleware(
   async function registrarActionsApiMiddleware(c, next) {
     // context must be set by the required middleware
     if (c.var.indexingStatus === undefined) {
-      throw new Error(`Invariant(registrar-actions.middleware): indexingStatusMiddleware required`);
+      return resultIntoHttpResponse(
+        c,
+        buildResultInternalServerError(
+          `Invariant(registrar-actions.middleware): indexingStatusMiddleware required.`,
+        ),
+      );
     }
 
     if (!registrarActionsPrerequisites.hasEnsIndexerConfigSupport(config.ensIndexerPublicConfig)) {
-      return c.json(
-        serializeRegistrarActionsResponse({
-          responseCode: RegistrarActionsResponseCodes.Error,
-          error: {
-            message: `Registrar Actions API is not available`,
-            details: `Connected ENSIndexer must have all following plugins active: ${registrarActionsPrerequisites.requiredPlugins.join(", ")}`,
-          },
-        }),
-        500,
-      );
+      const result = buildResultServiceUnavailable(`Registrar Actions API is not available`, {
+        details: `Connected ENSIndexer must have all following plugins active: ${registrarActionsPrerequisites.requiredPlugins.join(", ")}`,
+      });
+
+      return resultIntoHttpResponse(c, result);
     }
 
     if (c.var.indexingStatus instanceof Error) {
@@ -54,31 +55,24 @@ export const registrarActionsApiMiddleware = factory.createMiddleware(
         `Registrar Actions API requested but indexing status is not available in context.`,
       );
 
-      return c.json(
-        serializeRegistrarActionsResponse({
-          responseCode: RegistrarActionsResponseCodes.Error,
-          error: {
-            message: `Registrar Actions API is not available`,
-            details: `Indexing status is currently unavailable to this ENSApi instance.`,
-          },
-        }),
-        500,
-      );
+      const result = buildResultServiceUnavailable(`Registrar Actions API is not available`, {
+        details: `Indexing status is currently unavailable to this ENSApi instance.`,
+      });
+
+      return resultIntoHttpResponse(c, result);
     }
 
     const { omnichainSnapshot } = c.var.indexingStatus.snapshot;
 
-    if (!registrarActionsPrerequisites.hasIndexingStatusSupport(omnichainSnapshot.omnichainStatus))
-      return c.json(
-        serializeRegistrarActionsResponse({
-          responseCode: RegistrarActionsResponseCodes.Error,
-          error: {
-            message: `Registrar Actions API is not available`,
-            details: `The cached omnichain indexing status of the Connected ENSIndexer must be one of the following ${registrarActionsPrerequisites.supportedIndexingStatusIds.map((statusId) => `"${statusId}"`).join(", ")}.`,
-          },
-        }),
-        500,
-      );
+    if (
+      !registrarActionsPrerequisites.hasIndexingStatusSupport(omnichainSnapshot.omnichainStatus)
+    ) {
+      const result = buildResultServiceUnavailable(`Registrar Actions API is not available`, {
+        details: `The cached omnichain indexing status of the Connected ENSIndexer must be one of the following ${registrarActionsPrerequisites.supportedIndexingStatusIds.map((statusId) => `"${statusId}"`).join(", ")}.`,
+      });
+
+      return resultIntoHttpResponse(c, result);
+    }
 
     await next();
   },

packages/ensnode-sdk/src/api/registrar-actions/response.ts

@@ -1,6 +1,6 @@
 import type { InterpretedName } from "../../ens";
 import type { RegistrarAction } from "../../registrars";
-import type { UnixTimestamp } from "../../shared";
+import type { OpResultServer, UnixTimestamp } from "../../shared";
 import type { IndexingStatusResponseCodes } from "../indexing-status";
 import type { ErrorResponse } from "../shared/errors";
 import type { ResponsePageContext } from "../shared/pagination";
@@ -81,3 +81,16 @@ export interface RegistrarActionsResponseError {
  * at runtime.
  */
 export type RegistrarActionsResponse = RegistrarActionsResponseOk | RegistrarActionsResponseError;
+
+export interface RegistrarActionsResultOkData {
+  registrarActions: NamedRegistrarAction[];
+  paginationContext: ResponsePageContext;
+}
+
+/**
+ * Registrar Actions Result
+ *
+ * Use the `resultCode` field to determine the specific type interpretation
+ * at runtime.
+ */
+export type RegistrarActionsResult = OpResultServer<RegistrarActionsResultOkData>;

packages/ensnode-sdk/src/api/registrar-actions/serialize.ts

@@ -20,6 +20,12 @@ export function serializeNamedRegistrarAction({
   };
 }
 
+export function serializeNamedRegistrarActions(
+  actions: NamedRegistrarAction[],
+): SerializedNamedRegistrarAction[] {
+  return actions.map(serializeNamedRegistrarAction);
+}
+
 export function serializeRegistrarActionsResponse(
   response: RegistrarActionsResponse,
 ): SerializedRegistrarActionsResponse {

packages/ensnode-sdk/src/shared/result/result-base.ts

@@ -1,3 +1,4 @@
+import type { UnixTimestamp } from "../../shared";
 import type {
   ResultCode,
   ResultCodeClientError,
@@ -32,6 +33,26 @@ export interface AbstractResultOk<TDataType> extends AbstractResult<typeof Resul
   data: TDataType;
 }
 
+/**
+ * Abstract representation of a successful result with data guaranteed to be
+ * at least up to a certain timestamp.
+ */
+export interface AbstractResultOkTimestamped<TDataType> extends AbstractResultOk<TDataType> {
+  /**
+   * The minimum indexing cursor timestamp that the data is
+   * guaranteed to be accurate as of.
+   *
+   * Guarantees:
+   * - `data` is guaranteed to be at least up to `minIndexingCursor`, but
+   *   may be indexed with timestamps higher than `minIndexingCursor`.
+   *   - This guarantee may temporarily be violated during a chain reorg.
+   *     ENSNode automatically recovers from chain reorgs, but during one
+   *     the `minIndexingCursor` may theoretically be some seconds ahead of
+   *     the true state of indexed data.
+   */
+  minIndexingCursor: UnixTimestamp;
+}
+
 /**
  * Abstract representation of an error result.
  */