Replace opaque VirtualNode with domain-typed connection addressing#123
Open
SamBarker wants to merge 3 commits into
Open
Replace opaque VirtualNode with domain-typed connection addressing#123SamBarker wants to merge 3 commits into
SamBarker wants to merge 3 commits into
Conversation
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>
Assisted-by: Claude claude-opus-4-6 <noreply@anthropic.com> Signed-off-by: Sam Barker <sam@quadrocket.co.uk>
SamBarker
commented
Jul 16, 2026
| 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`. |
Member
Author
There was a problem hiding this comment.
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Proposes a
ClientAddressingsealed interface to replace the opaqueVirtualNodemarker in the Router API (refining Proposal 070). The sealed hierarchy uses Kafka
domain types —
Bootstrapfor connections to the virtual cluster's bootstrap address,Brokerfor broker-specific connections — making the distinction compiler-checkableand self-documenting.
Also proposes:
clientAddressed()replacingOptional<VirtualNode> virtualNode()sendToRoute()collapsing theanyNode()+sendRequest()two-stepbrokerFor(int)replacingnodeForId(int)sendRequest(Broker, ...)overload alongside deprecatedsendRequest(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
VirtualNodeshould expose. This proposaladdresses both by replacing
VirtualNodewith a domain-typed sealed hierarchy.