Skip to content

Conversation

@cryptodev-2s
Copy link
Contributor

Explanation

Tests with RPC failover required triple-nested withMockedCommunications blocks, creating excessive indentation and reducing readability. Test helpers also used 20+ instances of any types.

Solution

  • Added mockedEndpoints array option to withNetworkClient - eliminates nested blocks
  • Replaced any types with proper types (Json, unknown, generics)
  • Reduced test indentation from 3 levels to 1 level

Before

await withMockedCommunications({ ... }, async (primaryComms) => {
  await withMockedCommunications({ ... }, async (failoverComms) => {
    await withNetworkClient({ ... }, async ({ ... }) => {
      // test logic
    });
  });
});

After

await withNetworkClient({
  mockedEndpoints: [
    { providerType: networkClientType },
    { providerType: 'custom', customRpcUrl: failoverEndpointUrl },
  ],
}, async ({ comms }) => {
  const [primaryComms, failoverComms] = comms;
  // test logic
});

References

Checklist

  • I've updated the test suite for new or updated code as appropriate
  • I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
  • I've communicated my changes to consumers by updating changelogs for packages I've changed
  • I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

In a future commit we will introduce changes to `network-controller` so
that it will keep track of the status of each network as requests are
made. These updates to `createServicePolicy` assist with that.

See the changelog for a list of changes to the `ServicePolicy` API.

Besides the changes listed there, the tests for `createServicePolicy`
have been refactored slightly so that it is easier to maintain in the
future.
In a future commit we will introduce changes to `network-controller` so
that it will keep track of the status of each network as requests are
made. This commit paves the way for this to happen by redefining the
existing RPC endpoint-related events that NetworkController produces.

Currently, when requests are made through the network clients that
NetworkController exposes, three events are published:

- `NetworkController:rpcEndpointDegraded`
  - Published when enough successive retriable errors are encountered
    while making a request to an RPC endpoint that the maximum number of
    retries is reached.
- `NetworkController:rpcEndpointUnavailable`
  - Published when enough successive errors are encountered while making
    a request to an RPC endpoint that the underlying circuit breaks.
- `NetworkController:rpcEndpointRequestRetried`
  - Published when a request is retried (mainly used for testing).

It's important to note that in the context of the RPC failover feature,
an "RPC endpoint" can actually encompass multiple URLs, so the above
events actually fire for any URL.

While these events are useful for reporting metrics on RPC endpoints, in
order to effectively be able to update the status of a network, we need
events that are less granular and are guaranteed not to fire multiple
times in a row. We also need a new event.

Now the list of events looks like this:

- `NetworkController:rpcEndpointInstanceDegraded`
  - The same as `NetworkController:rpcEndpointDegraded` before.
- `NetworkController:rpcEndpointInstanceUnavailable`
  - The same as `NetworkController:rpcEndpointInstanceDegraded` before.
- `NetworkController:rpcEndpointInstanceRetried`
  - Renamed from `NetworkController:rpcEndpointRequestRetried`.
- `NetworkController:rpcEndpointDegraded`
  - Similar to `NetworkController:rpcEndpointInstanceDegraded`, but
    won't be published again if the RPC endpoint is already in a
    degraded state.
- `NetworkController:rpcEndpointUnavailable`
  - Published when all of the circuits underlying all of the URLs for an
    RPC endpoint have broken (none of the URLs are available). Won't be
    published again if the RPC endpoint is already in an unavailable
    state.
- `NetworkController:rpcEndpointAvailable`
  - A new event. Published the first time a successful request is made
    to one of the URLs for an RPC endpoint, or following a degraded or
    unavailable status.
mcmire and others added 11 commits November 21, 2025 12:53
- Simplify RPC service configuration creation using map
- Update CHANGELOG with corrected event payload documentation
- Fix test descriptions for clarity
- Remove unused RpcServiceConfiguration type
…nstant

Replace the magic number 5 with a well-documented constant that explains
how the number of attempts needed to break both circuits in an RPC service
chain is calculated. This makes the test intent clearer and the calculation
explicit.

- Add DEFAULT_REQUEST_ATTEMPTS constant
- Add DEFAULT_RPC_SERVICE_ATTEMPTS_UNTIL_BREAK constant
- Add DEFAULT_RPC_CHAIN_ATTEMPTS_UNTIL_BREAK constant with documentation
- Replace all occurrences of magic number 5 with the constant
Revert test description to original wording
Organize tests into two clear groups to make it easier to understand
which tests are testing failover functionality vs single-endpoint behavior.
Tests within each group maintain their original order for easier review.
Add comprehensive documentation for the getError function that extracts
errors from Cockatiel's FailureReason type in circuit breaker event handlers.
Documents both possible shapes of the FailureReason object.
- Add mockedEndpoints array to withNetworkClient to eliminate triple nesting
- Replace 20 any types with proper types (Json, unknown, generics)
- Reduce indentation from 3 levels to 1 in failover tests
@cryptodev-2s cryptodev-2s force-pushed the refactor/flatten-network-client-test-helpers branch from 67c255c to a626807 Compare November 25, 2025 22:45
@cryptodev-2s cryptodev-2s force-pushed the update-network-controller-rpc-endpoint-events branch from 81a987c to 2c35648 Compare November 25, 2025 23:00
Base automatically changed from update-network-controller-rpc-endpoint-events to main November 27, 2025 14:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants