Class ReadRouter

java.lang.Object
com.loomcache.server.replication.ReadRouter
public class ReadRouter extends Object
Routes read requests to appropriate replicas based on consistency level.

Implements routing strategies: - STRONG: Token-bearing leader route via routeStrongRead() - BOUNDED_STALENESS: To least-lagging replica within threshold - EVENTUAL: Round-robin across active replicas - SESSION: Conservative leader routing until per-session replication progress is tracked

  • Constructor Details

    • ReadRouter

      public ReadRouter(String nodeId, String leaderId, int instanceNumber, ReadReplicaManager replicaManager)
      Initialize the ReadRouter.
      Parameters:
      nodeId - The local node identifier (leader)
      leaderId - The leader identifier (same as nodeId for now)
      instanceNumber - The instance number for logging
      replicaManager - The replica manager

  • Method Details

    • setReadIndexBarrier

      public void setReadIndexBarrier(Supplier<CompletableFuture<Long>> barrier)
      Set the legacy Raft readIndex barrier supplier. This hook is insufficient for STRONG routing because it cannot revalidate the actual read after the router returns. Use setStrongReadTokenProtocol(Supplier, LongPredicate) for linearizable STRONG reads.
      Parameters:
      barrier - supplier returning a future that completes when state machine has caught up under confirmed leadership

    • setStrongReadTokenProtocol

      public void setStrongReadTokenProtocol(Supplier<CompletableFuture<Long>> readTokenSupplier, LongPredicate readTokenValidator)
      Set the token protocol used for linearizable STRONG reads.
      Parameters:
      readTokenSupplier - supplier returning a future that completes with a read token
      readTokenValidator - validator used after the actual read before publishing

    • setBoundedStalenessThresholdMs

      public void setBoundedStalenessThresholdMs(long thresholdMs)
      Set the bounded staleness threshold in milliseconds.
      Parameters:
      thresholdMs - The threshold

    • setStrongReadBarrierTimeoutMs

      public void setStrongReadBarrierTimeoutMs(long timeoutMs)
      Set the maximum time a STRONG read will wait to acquire a linearizable read token.
      Parameters:
      timeoutMs - timeout in milliseconds, must be positive

    • routeRead

      public @Nullable String routeRead(ConsistencyLevel consistencyLevel, @Nullable String sessionId)
      Route a read request and get the target replica.
      Parameters:
      consistencyLevel - The desired consistency level
      sessionId - The session identifier (for SESSION consistency)
      Returns:
      The replica ID to read from for non-STRONG reads, or null on error. STRONG reads must use routeStrongRead() so the caller can revalidate before publishing.

    • routeStrongRead

      public @Nullable ReadRouter.StrongReadRoute routeStrongRead()
      Route a STRONG read to the leader and return a token that the caller must revalidate after executing the actual read.
      Returns:
      token-bearing leader route, or null when a linearizable route cannot be acquired

    • clearSession

      public void clearSession(String sessionId)
      Clear the session cache (e.g., on session expiration).
      Parameters:
      sessionId - The session to remove

    • getStats

      public ReadRouter.ReadRouterStats getStats()
      Get aggregated routing statistics.
      Returns:
      ReadRouterStats record