Add registry decorators for deadlines and service-keyed circuit breakers by suresh-prakash · Pull Request #94 · hypertrace/java-grpc-utils

suresh-prakash · 2026-10-28T06:13:32Z

Summary

Add InterceptingChannelRegistry so an already-built GrpcChannelRegistry can carry one client interceptor, and TimeoutChannelRegistry so grpc.client.timeout applies a default deadline when a call has none.
Add a service-keyed circuit breaker: CircuitBreakerInterceptorFactory.forService and CircuitBreakerChannelRegistry.wrap. The breaker name is the protobuf service name. failureStatusCodes defaults to DEADLINE_EXCEEDED, UNAVAILABLE, and RESOURCE_EXHAUSTED.
Leave the existing request-keyed interceptor unchanged. Callers compose the timeout and circuit-breaker decorators themselves.

Test plan

./gradlew -Pversion=0.13.23 :grpc-client-utils:test :grpc-circuitbreaker-utils:test
Confirm an absent or disabled config returns the original registry
Confirm an enabled service opens on the configured failure statuses and rejects with RESOURCE_EXHAUSTED before the downstream call
Confirm a quoted dotted service name parses, and an unknown status name fails startup

Made with Cursor

Co-authored-by: Cursor <cursoragent@cursor.com>

…gistry. Co-authored-by: Cursor <cursoragent@cursor.com>

github-actions · 2026-10-28T06:16:24Z

Test Results

132 tests +33 132 ✅ +33 23s ⏱️ ±0s
22 suites + 5 0 💤 ± 0
22 files + 5 0 ❌ ± 0

Results for commit 68ee8a5. ± Comparison against base commit 48511e9.

♻️ This comment has been updated with latest results.

suresh-prakash · 2026-10-29T06:23:55Z

gitignore "docs/superpowers".

suresh-prakash · 2026-10-29T06:25:21Z

+
+  private CircuitBreakerChannelRegistry() {}
+
+  public static GrpcChannelRegistry wrap(GrpcChannelRegistry registry, Config config) {


Prefer to use final wherever feasible (to avoid errors like accidentally assigning a local variable instead of the field). Let's use that throughout this PR.

suresh-prakash · 2026-10-29T06:25:56Z

+
+  static final String CIRCUIT_BREAKER_CONFIG = "circuit.breaker.config";
+
+  private CircuitBreakerChannelRegistry() {}


Nit: Can also use lombok?

suresh-prakash · 2026-10-29T06:34:57Z

+    for (String serviceName : config.root().keySet()) {
+      if (CircuitBreakerConfigParser.ENABLED.equals(serviceName)
+          || CircuitBreakerConfigParser.DEFAULT_THRESHOLDS.equals(serviceName)) {
+        continue;


Would be helpful to have "debug" logs at these early exist points so it can come handy for debugging.

suresh-prakash · 2026-10-29T06:36:42Z

+            .map(Status.Code::name)
+            .collect(Collectors.joining(", "));
+    return ConfigFactory.parseString(
+        "failureRateThreshold = "


Would be better if these configs were built more first-class instead of string concatenation. It's okay if that's not possible.

Maybe, once we have the first-class model, the defaults can be specified directly in the model.

suresh-prakash · 2026-10-29T06:47:12Z

+        Objects.requireNonNull(registry), Objects.requireNonNull(interceptor));
+  }
+
+  @Delegate(excludes = ForAddress.class)


Do we need the excludes specifically? Or, can lombok automatically skip methods that are explicitly overridden?

suresh-prakash · 2026-10-29T06:47:21Z

+  }
+
+  private static final class InterceptedManagedChannel extends ManagedChannel {
+    @Delegate(excludes = InterceptedCall.class)


suresh-prakash · 2026-10-29T06:53:25Z

+
+    Config timeoutConfig = config.getConfig(TIMEOUT_PATH);
+    if (!timeoutConfig.hasPath(ENABLED_KEY) || !timeoutConfig.getBoolean(ENABLED_KEY)) {
+      return registry;


Add a debug log at all early exist points, especially since the would be invoked just once per restart.

suresh-prakash · 2026-10-29T06:53:43Z

+    return InterceptingChannelRegistry.wrap(registry, new DefaultTimeoutClientInterceptor(timeout));
+  }
+
+  private TimeoutChannelRegistry() {}


Nit: Can be replaced with Lombok?

suresh-prakash · 2026-10-29T06:54:12Z


 .idea
+
+.superpowers/


docs/superpowers can also be ignored.

Parse service breakers into CircuitBreakerThresholds instead of rebuilding defaults as HOCON, and log when a decorator is skipped or a call is rejected. Lombok still excludes forAddress because that method is inherited, not overridden. Co-authored-by: Cursor <cursoragent@cursor.com>

suresh-prakash · 2026-10-29T07:04:48Z

+
+  static final String CIRCUIT_BREAKER_CONFIG = CircuitBreakerConfigParser.CIRCUIT_BREAKER_CONFIG;
+
+  public static GrpcChannelRegistry wrap(final GrpcChannelRegistry registry, final Config config) {


Why not take in the first-class object here instead of typesafe?

suresh-prakash · 2026-10-29T07:07:01Z

+    return new ServiceCircuitBreakerInterceptor(Map.of(), Map.of());
+  }
+
+  // Resilience4j records onError as a success when recordException returns false.


This comment seems off place still.

Callers can install the breaker from CircuitBreakerThresholds without passing Typesafe Config. Parameters in the new code are final, and a breaker logs when it changes state. Co-authored-by: Cursor <cursoragent@cursor.com>

aaron-steinfeld · 2026-11-02T15:35:24Z

question: Could we clarify why the registry is wrapped (TimeoutChannelRegistry.wrap, CircuitBreakerChannelRegistry.wrap) rather than adding the interceptor through the registry's existing config?

The goal makes sense: opt in via config, and apply a circuit breaker (and a default timeout) to all outgoing calls in the Kafka Streams apps. As the registry is currently structured, GrpcRegistryConfig.defaultInterceptors is applied to every channel it builds, so the app would construct the registry once with the interceptor:

GrpcChannelRegistry registry =
    new GrpcChannelRegistry(
        GrpcRegistryConfig.builder()
            .defaultInterceptor(CircuitBreakerInterceptorFactory.forService(config))
            .build());

forService (added in this PR) already returns a plain ClientInterceptor and is a no-op when circuit.breaker.config is absent or disabled, so opt-in by config is preserved without needing to wrap the registry.

What does wrapping give us over that? For example:

Is the registry constructed somewhere the apps can't pass a GrpcRegistryConfig (a shared framework or bootstrap)?
Does the layering of timeout and breaker need to be controlled by the caller beyond interceptor order?
Is there something else I'm missing?

Knowing the constraint will help us decide whether wrapping is the right shape or whether a config-based route covers it.

🤖 Drafted with Claude Code

suresh-prakash and others added 7 commits October 23, 2026 15:26

Plan registry decorators for deadlines and service circuit breakers.

d2bcd3b

Co-authored-by: Cursor <cursoragent@cursor.com>

Record the worktree Gradle version required for dependency locking.

e099cfd

Co-authored-by: Cursor <cursoragent@cursor.com>

Add a channel-registry decorator that installs one client interceptor.

01e657e

Co-authored-by: Cursor <cursoragent@cursor.com>

Apply a configured default deadline to every channel from a registry.

fef7b20

Co-authored-by: Cursor <cursoragent@cursor.com>

Parse the gRPC statuses that count as circuit-breaker failures.

8e081c8

Co-authored-by: Cursor <cursoragent@cursor.com>

Add a service-keyed gRPC circuit breaker interceptor.

a5cdb78

Co-authored-by: Cursor <cursoragent@cursor.com>

Install the service-keyed circuit breaker from an existing channel re…

f8a3844

…gistry. Co-authored-by: Cursor <cursoragent@cursor.com>

suresh-prakash commented Oct 29, 2026

View reviewed changes

Let registry wrap take service thresholds directly.

68ee8a5

Callers can install the breaker from CircuitBreakerThresholds without passing Typesafe Config. Parameters in the new code are final, and a breaker logs when it changes state. Co-authored-by: Cursor <cursoragent@cursor.com>

suresh-prakash marked this pull request as ready for review November 2, 2026 08:28

suresh-prakash requested a review from a team as a code owner November 2, 2026 08:28


		private CircuitBreakerChannelRegistry() {}

		public static GrpcChannelRegistry wrap(GrpcChannelRegistry registry, Config config) {


		static final String CIRCUIT_BREAKER_CONFIG = "circuit.breaker.config";

		private CircuitBreakerChannelRegistry() {}


		static final String CIRCUIT_BREAKER_CONFIG = CircuitBreakerConfigParser.CIRCUIT_BREAKER_CONFIG;

		public static GrpcChannelRegistry wrap(final GrpcChannelRegistry registry, final Config config) {


		.idea

		.superpowers/

Conversation

suresh-prakash commented Oct 28, 2026

Summary

Test plan

Uh oh!

github-actions Bot commented Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test Results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aaron-steinfeld commented Nov 2, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Oct 28, 2026 •

edited

Loading