Package io.kroxylicious.proxy.internal.routing

Interface NodeIdMapping

All Known Implementing Classes:
BijectiveNodeIdMapping, IdentityNodeIdMapping
public sealed interface NodeIdMapping permits BijectiveNodeIdMapping, IdentityNodeIdMapping
Maps between target-cluster node IDs and the virtual node IDs presented to clients. Implementations must be thread-safe.

Negative node IDs — the Kafka protocol uses negative node IDs as sentinels with defined semantics, for example -1 means "no leader", "unknown controller", or "no coordinator available". These values must pass through the mapping unchanged; translating them would corrupt the protocol. Implementations must therefore return any negative input unmodified from both toVirtual(java.lang.String, int) and fromVirtual(String, int).

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    NodeIdMapping.RouteAndNode
    A route name and target-cluster node ID pair.

  • Method Summary

    Modifier and Type
    Method
    Description
    NodeIdMapping.RouteAndNode
    fromVirtual(int virtualNodeId)
    Translates a virtual node ID back to its route and target-cluster node ID.
    int
    fromVirtual(String route, int virtualNodeId)
    Translates a virtual node ID back to its target-cluster node ID, given the route.
    int
    toVirtual(String route, int targetNodeId)
    Translates a target-cluster node ID to a virtual node ID.

  • Method Details

    • toVirtual

      int toVirtual(String route, int targetNodeId)
      Translates a target-cluster node ID to a virtual node ID.

      Negative values (Kafka protocol sentinels such as -1 "no leader") are returned unchanged and must not be fed into the translation formula.

      Parameters:
      route - the route name
      targetNodeId - the node ID on the target cluster
      Returns:
      the virtual node ID, or targetNodeId unchanged if negative

    • fromVirtual

      int fromVirtual(String route, int virtualNodeId)
      Translates a virtual node ID back to its target-cluster node ID, given the route. The route is always supplied by the router via RouterContext.sendRequest(io.kroxylicious.proxy.topology.VirtualNode, org.apache.kafka.common.message.RequestHeaderData, org.apache.kafka.common.protocol.ApiMessage).

      As with toVirtual(java.lang.String, int), negative values are returned unchanged.

      Parameters:
      route - the route name
      virtualNodeId - the virtual node ID
      Returns:
      the target-cluster node ID, or virtualNodeId unchanged if negative

    • fromVirtual

      NodeIdMapping.RouteAndNode fromVirtual(int virtualNodeId)
      Translates a virtual node ID back to its route and target-cluster node ID. Only works for dedicated (one-to-one) mappings where the route can be recovered from the virtual node ID alone.

      Behaviour is undefined for negative inputs; proxy port node IDs are always non-negative and this method is never called with a sentinel value.

      Parameters:
      virtualNodeId - the virtual node ID
      Returns:
      the route name and target node ID