Skip to content

refactor(ensapi): apply operation result pattern #1545

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tk-o wants to merge 40 commits into
base: feat/ensnode-result-type
Choose a base branch
from
Open

refactor(ensapi): apply operation result pattern #1545

Show file tree
Hide file tree
Changes from 20 commits
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
e80b9f4
Implement operation result pattern in ENSApi error handlers
tk-o Jan 18, 2026
56aa797
Implement operation result pattern for ENSApi /amirealtime endpoint
tk-o Jan 18, 2026
902d556
Implement operation result pattern for Registrar Actions API
tk-o Jan 18, 2026
412e722
Apply PR feedback from AI agents
tk-o Jan 19, 2026
02fbeb3
Add `buildRouteResponsesDescription` function for ensuring comprehens…
tk-o Jan 19, 2026
ac5bb11
Handle "unhandled result code" while generating HTTP response from a …
tk-o Jan 19, 2026
1cd4b10
Improve code style in Registrar Actions API
tk-o Jan 19, 2026
a649edd
Fix typos
tk-o Jan 19, 2026
d6575b5
Fix type casting
tk-o Jan 19, 2026
1246ce7
Include InvalidRequest result code in docs
tk-o Jan 19, 2026
2d86cc2
Apply PR feedback: use concrete Result OK types
tk-o Jan 20, 2026
6565097
feat(ensnode-sdk): introduce `InsufficientIndexingProgress` result code
tk-o Jan 21, 2026
159d210
feat(ensapi): update OpenAPI route descriptions
tk-o Jan 21, 2026
fe3ffcc
feat(ensadmin): update `StatefulFetchRegistrarActionsNotReady` type
tk-o Jan 21, 2026
8ea9155
fix(ensnode-sdk): workaround for zod schema imports
tk-o Jan 21, 2026
229d8d8
fix(ensnode-sdk): introduce `getSufficientIndexingProgressChainCursor…
tk-o Jan 22, 2026
35fa0b7
fix(ensnode-sdk): dependency import issue
tk-o Jan 22, 2026
50b5e18
Apply PR feedback from AI agents
tk-o Jan 22, 2026
f5d75f7
Apply PR feedback from AI agents
tk-o Jan 22, 2026
d4261da
Apply PR feedback from self-review
tk-o Jan 22, 2026
59f3700
Apply PR feedback from AI agents
tk-o Jan 22, 2026
9b46b51
refactor: split Zod schemas for OpenAPI spec
tk-o Jan 23, 2026
3c4b632
docs: update Zod schemas to include field descriptions for OpenAPI sp…
tk-o Jan 23, 2026
13d5336
Update Result type
tk-o Jan 27, 2026
ad74cb7
Update `api` module in ENSNode SDK
tk-o Jan 27, 2026
8526bfd
Introduce `IndexingStatusForSupportedApiResult` to ENSNode SDK
tk-o Jan 27, 2026
a01108d
Define OpenAPI responses in separate files
tk-o Jan 27, 2026
b64544c
Change how indexing status is fetched by ENSApi route handlers
tk-o Jan 27, 2026
aef406a
Update API docs
tk-o Jan 27, 2026
4f1302e
Align ENSAdmin with updated ENSNode SDK types
tk-o Jan 27, 2026
6395275
Fix unit tests
tk-o Jan 27, 2026
5768d6b
Update data model for `ResultInsufficientIndexingProgressData`
tk-o Jan 27, 2026
a4cb033
Introduce API Hanlder Prerequisites Validation
tk-o Jan 28, 2026
860d697
Move test objects into "mocks" file
tk-o Jan 28, 2026
42c6d24
Support multi-version Registrar Actions API
tk-o Jan 28, 2026
0cb64fd
Refactor Registrar Actions API
tk-o Jan 28, 2026
bf40907
Add relevat test coverage for function
tk-o Jan 28, 2026
3cb3cf6
Update V1 handler path prefix
tk-o Jan 28, 2026
3e58e07
Fix Zod schemas for parsing result error objects
tk-o Jan 28, 2026
1b33cad
Minor cleanup
tk-o Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion apps/ensadmin/src/app/mock/registrar-actions/mocks.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import {
Duration,
InterpretedName,
NamedRegistrarAction,
OmnichainIndexingStatusIds,
registrarActionsPrerequisites,
} from "@ensnode/ensnode-sdk";

Expand Down Expand Up @@ -248,7 +249,7 @@ export const variants: Map<StatefulFetchStatusId, StatefulFetchRegistrarActions>
StatefulFetchStatusIds.NotReady,
{
fetchStatus: StatefulFetchStatusIds.NotReady,
supportedIndexingStatusIds: registrarActionsPrerequisites.supportedIndexingStatusIds,
supportedIndexingStatusId: OmnichainIndexingStatusIds.Following,
} satisfies StatefulFetchRegistrarActionsNotReady,
],
[
Expand Down
17 changes: 5 additions & 12 deletions apps/ensadmin/src/components/registrar-actions/display-registrar-actions-panel.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -153,19 +153,12 @@ export function DisplayRegistrarActionsPanel({
<CardContent className="max-sm:p-3 max-sm:pt-0 flex flex-col gap-4">
<p>The Registrar Actions API on the connected ENSNode instance is not available yet.</p>
<p>
The Registrar Actions API will be available once the omnichain indexing status reaches
one of the following:
The Registrar Actions API will be available once the omnichain indexing status becomes{" "}
<Badge variant="secondary">
{formatOmnichainIndexingStatus(registrarActions.supportedIndexingStatusId)}
Copy link
Member

@lightwalker-eth lightwalker-eth Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm worried that our client-code is interpreting this value as a strict enum, rather than as an arbitrary string.

It's super important we put a high priority on these distinctions.

Copy link
Contributor Author

@tk-o tk-o Jan 27, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you please expand on that note?

Looking at formatOmnichainIndexingStatus function definition:

export function formatOmnichainIndexingStatus(status: OmnichainIndexingStatusId): string {
  const [, formattedStatus] = status.split("-");

  return formattedStatus;
}

Did you mean its input parameter type should be string, like so?

export function formatOmnichainIndexingStatus(status: string): string {
  const [, formattedStatus] = status.split("-");

  return formattedStatus;
}

Copy link
Member

@lightwalker-eth lightwalker-eth Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@tk-o Your question here is about UI-level concerns. However the main idea I'm trying to flag here is about data-model level concerns in relation to change management.

Here's a principle that should influence all our work: avoid breaking changes to our APIs (as soon as we can achieve the first "stable" API release).

Therefore, we must work hard now to design the first "stable" API release so that we can avoid breaking changes as we continue iterating in the future!

For any enum, we must thoughtfully consider future change management:

  1. Are we ready to commit to NEVER introducing a new value to this enum without it being a breaking change requiring a new incremented /vX/... in the API route?
  2. Or do we want the flexibility to introduce a new value to this enum without it being a breaking change?

Use of option 1 should be VERY selective and deliberate. It should never be an accidental oversight.

Use of option 2 requires that we explicitly prepare clients for gracefully handling new enum values that they won't recognize because they come from a future server version.

Do you have any questions on the above?

What do you recommend for this OmnichainIndexingStatusId enum? Should it use option 1 or option 2? Why is that your recommendation?

Copy link
Contributor Author

@tk-o tk-o Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lightwalker-eth Yes, it's likely some enums will have to be extended to cover new cases. This may lead to situation where client-side code does not recognize a newly added enum variant included in server response.

I would go ahead with option 1.

As I proposed during our last team call, I think the client should be able to pick which version of the API response schema (i.e. v1, v2, etc.) it expects. This would leave no room for unnoticed breaking changes. The change management would rely on a migration process. This is the option 1 you mentioned above.

For example:

  1. The client app has been using the v1 data model provided by ENSNodeClientV1 instance.
  2. Now the client app needs to use the v2 data model.
    • The client app has to migrate from using ENSNodeClientV1 instance to the ENSNodeClientV2 instance.

As for option 2, if we wanted to use it just for enums, we would need to make the client app to handle the "unrecognized" enum variants. In other words, the client app would have to know which variants of the given enum are "recognized", so all other variants could be considered "unrecognized".

If we went down this way, we would have to wrap all enum values in some data wrapper type to allow expressing a generic "unrecognized" variant, so the client app could handle it accordingly.

</Badge>
.
</p>

<ul>
{registrarActions.supportedIndexingStatusIds.map((supportedStatusId) => (
<li className="inline" key={supportedStatusId}>
<Badge variant="secondary">
{formatOmnichainIndexingStatus(supportedStatusId)}
</Badge>{" "}
</li>
))}
</ul>
</CardContent>
<CardFooter className="gap-6">
<Button asChild>
Expand Down
6 changes: 4 additions & 2 deletions apps/ensadmin/src/components/registrar-actions/types.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
import { NamedRegistrarAction, OmnichainIndexingStatusId } from "@ensnode/ensnode-sdk";
import { NamedRegistrarAction, OmnichainIndexingStatusIds } from "@ensnode/ensnode-sdk";

export const StatefulFetchStatusIds = {
/**
Expand Down Expand Up @@ -61,7 +61,9 @@ export interface StatefulFetchRegistrarActionsUnsupported {
*/
export interface StatefulFetchRegistrarActionsNotReady {
fetchStatus: typeof StatefulFetchStatusIds.NotReady;
supportedIndexingStatusIds: ReadonlyArray<OmnichainIndexingStatusId>;
supportedIndexingStatusId:
| typeof OmnichainIndexingStatusIds.Completed
| typeof OmnichainIndexingStatusIds.Following;
Copy link
Contributor Author

@tk-o tk-o Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There can be just one supported indexing status at a time.

Copy link
Member

@lightwalker-eth lightwalker-eth Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest to define a new type in the indexing status file for the idea of an "indexing status end state" that would be a type union of completed and following.

We should document how these are "end states" because once indexing reaches one of these statuses, it will continue in that status forever.

Then you can reference that newly defined type union here and anywhere else where it is relevant.

}

/**
Expand Down
13 changes: 9 additions & 4 deletions apps/ensadmin/src/components/registrar-actions/use-stateful-fetch-registrar-actions.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { useENSNodeConfig, useRegistrarActions } from "@ensnode/ensnode-react";
import {
getChainIndexingConfigTypeId,
IndexingStatusResponseCodes,
RegistrarActionsOrders,
RegistrarActionsResponseCodes,
Expand Down Expand Up @@ -27,7 +28,7 @@ const {
hasEnsIndexerConfigSupport,
hasIndexingStatusSupport,
requiredPlugins,
supportedIndexingStatusIds,
getSupportedIndexingStatus,
} = registrarActionsPrerequisites;

/**
Copy link
Member

@lightwalker-eth lightwalker-eth Jan 23, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A key goal of our work here is to fully remove the need for the whole "use stateful registrar actions" concept.

We should just have a "use registrar actions" that makes a single stateless API request. The client can then appropriately handle errors associated with insufficient indexing status or a config that won't support the API request.

Copy link
Contributor Author

@tk-o tk-o Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree on the goal, but this PR is not aiming to update the client code. It will be done in a follow-up PR to reduce the PR scope.

Expand All @@ -51,10 +52,12 @@ export function useStatefulRegistrarActions({
) {
const { ensIndexerPublicConfig } = ensNodeConfigQuery.data;
const { omnichainSnapshot } = indexingStatusQuery.data.realtimeProjection.snapshot;
const chains = Array.from(omnichainSnapshot.chains.values());
const configTypeId = getChainIndexingConfigTypeId(chains);

isRegistrarActionsApiSupported =
hasEnsIndexerConfigSupport(ensIndexerPublicConfig) &&
hasIndexingStatusSupport(omnichainSnapshot.omnichainStatus);
hasIndexingStatusSupport(configTypeId, omnichainSnapshot.omnichainStatus);
}

// Note: ENSNode Registrar Actions API is available only in certain cases.
Expand Down Expand Up @@ -101,12 +104,14 @@ export function useStatefulRegistrarActions({
}

const { omnichainSnapshot } = indexingStatusQuery.data.realtimeProjection.snapshot;
const chains = Array.from(omnichainSnapshot.chains.values());
const configTypeId = getChainIndexingConfigTypeId(chains);

// fetching is temporarily not possible due to indexing status being not advanced enough
if (!hasIndexingStatusSupport(omnichainSnapshot.omnichainStatus)) {
if (!hasIndexingStatusSupport(configTypeId, omnichainSnapshot.omnichainStatus)) {
Copy link
Contributor Author

@tk-o tk-o Jan 22, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Checking indexing status support now requires providing the chains configuration type ID.

return {
fetchStatus: StatefulFetchStatusIds.NotReady,
supportedIndexingStatusIds,
supportedIndexingStatusId: getSupportedIndexingStatus(configTypeId),
} satisfies StatefulFetchRegistrarActionsNotReady;
}

Expand Down
124 changes: 88 additions & 36 deletions apps/ensapi/src/handlers/amirealtime-api.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,13 @@
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

import {
buildAmIRealtimeResultOk,
ChainIndexingConfigTypeIds,
ChainIndexingStatusIds,
type ChainIndexingStatusSnapshotFollowing,
type CrossChainIndexingStatusSnapshot,
createRealtimeIndexingStatusProjection,
OmnichainIndexingStatusIds,
type UnixTimestamp,
} from "@ensnode/ensnode-sdk";

Expand All @@ -25,15 +30,42 @@ describe("amirealtime-api", () => {
slowestChainIndexingCursor,
}: {
now: UnixTimestamp;
slowestChainIndexingCursor?: UnixTimestamp;
slowestChainIndexingCursor: UnixTimestamp;
}) => {
indexingStatusMiddlewareMock.mockImplementation(async (c, next) => {
const indexingStatus = {
slowestChainIndexingCursor: slowestChainIndexingCursor ?? now - 10,
omnichainSnapshot: {
omnichainStatus: OmnichainIndexingStatusIds.Following,
omnichainIndexingCursor: slowestChainIndexingCursor,
chains: new Map([
[
1,
{
chainStatus: ChainIndexingStatusIds.Following,
latestIndexedBlock: {
timestamp: now - 10,
number: 150,
},
latestKnownBlock: {
timestamp: now,
number: 151,
},
config: {
configType: ChainIndexingConfigTypeIds.Indefinite,
startBlock: {
number: 100,
timestamp: now - 1000,
},
},
} satisfies ChainIndexingStatusSnapshotFollowing,
],
]),
} as CrossChainIndexingStatusSnapshot["omnichainSnapshot"],
snapshotTime: now,
slowestChainIndexingCursor,
} satisfies Pick<
CrossChainIndexingStatusSnapshot,
"slowestChainIndexingCursor" | "snapshotTime"
"omnichainSnapshot" | "slowestChainIndexingCursor" | "snapshotTime"
> as CrossChainIndexingStatusSnapshot;

const realtimeProjection = createRealtimeIndexingStatusProjection(indexingStatus, now);
Expand Down Expand Up @@ -61,17 +93,21 @@ describe("amirealtime-api", () => {
describe("request", () => {
it("should accept valid maxWorstCaseDistance query param", async () => {
// Arrange: set `indexingStatus` context var
arrangeMockedIndexingStatusMiddleware({ now });
arrangeMockedIndexingStatusMiddleware({ now, slowestChainIndexingCursor: now - 10 });

// Act
const response = await app.request("http://localhost/amirealtime?maxWorstCaseDistance=300");
const responseJson = await response.json();

// Assert
expect(response.status).toBe(200);
expect(responseJson).toMatchObject({
maxWorstCaseDistance: 300,
});
expect(responseJson).toStrictEqual(
buildAmIRealtimeResultOk({
maxWorstCaseDistance: 300,
worstCaseDistance: 10,
slowestChainIndexingCursor: now - 10,
}),
);
});

it("should accept valid maxWorstCaseDistance query param (set to `0`)", async () => {
Expand All @@ -84,44 +120,56 @@ describe("amirealtime-api", () => {

// Assert
expect(response.status).toBe(200);
expect(responseJson).toMatchObject({
maxWorstCaseDistance: 0,
});
expect(responseJson).toStrictEqual(
buildAmIRealtimeResultOk({
maxWorstCaseDistance: 0,
worstCaseDistance: 0,
slowestChainIndexingCursor: now,
}),
);
});

it("should use default maxWorstCaseDistance when unset", async () => {
// Arrange: set `indexingStatus` context var
arrangeMockedIndexingStatusMiddleware({ now });
arrangeMockedIndexingStatusMiddleware({ now, slowestChainIndexingCursor: now - 10 });

// Act
const response = await app.request("http://localhost/amirealtime?maxWorstCaseDistance");
const responseJson = await response.json();

// Assert
expect(response.status).toBe(200);
expect(responseJson).toMatchObject({
maxWorstCaseDistance: AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE,
});
expect(responseJson).toStrictEqual(
buildAmIRealtimeResultOk({
maxWorstCaseDistance: AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE,
worstCaseDistance: 10,
slowestChainIndexingCursor: now - 10,
}),
);
});

it("should use default maxWorstCaseDistance when not provided", async () => {
// Arrange: set `indexingStatus` context var
arrangeMockedIndexingStatusMiddleware({ now });
arrangeMockedIndexingStatusMiddleware({ now, slowestChainIndexingCursor: now - 10 });

// Act
const response = await app.request("http://localhost/amirealtime");
const responseJson = await response.json();

// Assert
expect(response.status).toBe(200);
expect(responseJson).toMatchObject({
maxWorstCaseDistance: AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE,
});
expect(responseJson).toStrictEqual(
buildAmIRealtimeResultOk({
maxWorstCaseDistance: AMIREALTIME_DEFAULT_MAX_WORST_CASE_DISTANCE,
worstCaseDistance: 10,
slowestChainIndexingCursor: now - 10,
}),
);
});

it("should reject invalid maxWorstCaseDistance (negative number)", async () => {
// Arrange: set `indexingStatus` context var
arrangeMockedIndexingStatusMiddleware({ now });
arrangeMockedIndexingStatusMiddleware({ now, slowestChainIndexingCursor: now - 10 });

// Act
const response = await app.request("http://localhost/amirealtime?maxWorstCaseDistance=-1");
Expand All @@ -135,7 +183,7 @@ describe("amirealtime-api", () => {

it("should reject invalid maxWorstCaseDistance (not a number)", async () => {
// Arrange: set `indexingStatus` context var
arrangeMockedIndexingStatusMiddleware({ now });
arrangeMockedIndexingStatusMiddleware({ now, slowestChainIndexingCursor: now - 10 });

// Act
const response = await app.request(
Expand All @@ -161,11 +209,13 @@ describe("amirealtime-api", () => {

// Assert
expect(response.status).toBe(200);
expect(responseJson).toMatchObject({
maxWorstCaseDistance: 10,
slowestChainIndexingCursor: 1766123720,
worstCaseDistance: 9,
});
expect(responseJson).toStrictEqual(
buildAmIRealtimeResultOk({
maxWorstCaseDistance: 10,
slowestChainIndexingCursor: now - 9,
worstCaseDistance: 9,
}),
);
});

it("should return 200 when worstCaseDistance equals maxWorstCaseDistance", async () => {
Expand All @@ -178,11 +228,13 @@ describe("amirealtime-api", () => {

// Assert
expect(response.status).toBe(200);
expect(responseJson).toMatchObject({
maxWorstCaseDistance: 10,
slowestChainIndexingCursor: 1766123719,
worstCaseDistance: 10,
});
expect(responseJson).toStrictEqual(
buildAmIRealtimeResultOk({
maxWorstCaseDistance: 10,
slowestChainIndexingCursor: 1766123719,
worstCaseDistance: 10,
}),
);
});

it("should return 503 when worstCaseDistance exceeds maxWorstCaseDistance", async () => {
Expand All @@ -195,13 +247,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"));
Expand All @@ -215,9 +267,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./,
);
});
});
Expand Down
Loading
Loading