Skip to content

Replace opaque VirtualNode with domain-typed connection addressing#123

Open
SamBarker wants to merge 3 commits into
kroxylicious:mainfrom
SamBarker:router-context-endpoint-type
Open

Replace opaque VirtualNode with domain-typed connection addressing#123
SamBarker wants to merge 3 commits into
kroxylicious:mainfrom
SamBarker:router-context-endpoint-type

Conversation

@SamBarker

@SamBarker SamBarker commented Jul 16, 2026

Copy link
Copy Markdown
Member

Summary

Proposes a ClientAddressing sealed interface to replace the opaque VirtualNode
marker in the Router API (refining Proposal 070). The sealed hierarchy uses Kafka
domain types — Bootstrap for connections to the virtual cluster's bootstrap address,
Broker for broker-specific connections — making the distinction compiler-checkable
and self-documenting.

Also proposes:

  • clientAddressed() replacing Optional<VirtualNode> virtualNode()
  • sendToRoute() collapsing the anyNode() + sendRequest() two-step
  • brokerFor(int) replacing nodeForId(int)
  • sendRequest(Broker, ...) overload alongside deprecated sendRequest(VirtualNode, ...)

All deprecated methods receive default implementations that delegate to their
replacements — no runtime breaks during the migration window.

Context

The bootstrap/broker distinction surfaced independently from two directions:
the port-binding separation work (#4147) arrived at a sealed two-case type
from the networking layer, and review of the dynamic routing PR (#4307,
discussion)
raised the question of what state VirtualNode should expose. This proposal
addresses both by replacing VirtualNode with a domain-typed sealed hierarchy.

Introduces a ClientAddressing sealed interface with Bootstrap and Broker
subtypes to replace the opaque VirtualNode marker in the Router API.
This makes the bootstrap/broker distinction compiler-checkable and uses
Kafka domain terms. VirtualNode is deprecated, not removed, to allow a
migration window.

Assisted-by: Claude claude-opus-4-6 <noreply@anthropic.com>
Signed-off-by: Sam Barker <sam@quadrocket.co.uk>
Assisted-by: Claude claude-opus-4-6 <noreply@anthropic.com>
Signed-off-by: Sam Barker <sam@quadrocket.co.uk>
@SamBarker
SamBarker requested a review from a team as a code owner July 16, 2026 02:23
Assisted-by: Claude claude-opus-4-6 <noreply@anthropic.com>
Signed-off-by: Sam Barker <sam@quadrocket.co.uk>
accommodate a speculative future type. Second, the flat hierarchy is strictly simpler and
does not foreclose the two-level design: if `Controller` is needed later, a unifying
`VirtualNode` interface can be introduced alongside it without breaking existing code
that uses `Broker`.

@SamBarker SamBarker Jul 16, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

Is Controller as a future peer subtype well-served by the flat hierarchy, or does the two-level hierarchy (rejected here) better justify itself despite Controller being hypothetical? The motivation for Controller is the proxy standing between members of the Kafka cluster — not just between clients and brokers. The flat design doesn't foreclose the two-level option later, but reviewers with a view on whether the proxy will need to mediate controller connections may have a stronger opinion on whether that extensibility point is worth pre-building.

@SamBarker SamBarker changed the title docs: propose ClientAddressing sealed interface for RouterContext Replace opaque VirtualNode with domain-typed connection addressing Jul 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant