Interface ClusterManager

public interface ClusterManager
Manages the cluster of proxy instances.

The cluster manager tracks all online proxy instances, aggregates global state (player counts, server lists), and provides methods for cross-proxy coordination.

Cluster State

Each proxy maintains a local view of the cluster state, updated via heartbeat messages. The state is eventually consistent - there may be brief periods where proxies have slightly different views.

Local vs. Global

  • Local methods return data from this proxy instance only
  • Global methods aggregate data from all proxies in the cluster

  • Method Details

    • isClusterMode

      boolean isClusterMode()
      Check if clustering is enabled and connected.
      Returns:
      true if this proxy is part of an active cluster

    • getLocalProxyId

      @Nonnull String getLocalProxyId()
      Get this proxy's unique identifier.
      Returns:
      the local proxy ID

    • getLocalRegion

      @Nonnull String getLocalRegion()
      Get this proxy's region.
      Returns:
      the configured region (e.g., "eu-west")

    • getLocalProxyInfo

      @Nonnull ProxyInfo getLocalProxyInfo()
      Get information about this proxy instance.
      Returns:
      the local proxy info

    • getOnlineProxies

      @Nonnull Collection<ProxyInfo> getOnlineProxies()
      Get all online proxies in the cluster, including this one.
      Returns:
      an unmodifiable collection of proxy info

    • getProxy

      @Nonnull Optional<ProxyInfo> getProxy(@Nonnull String proxyId)
      Get a specific proxy by its ID.
      Parameters:
      proxyId - the proxy ID to look up
      Returns:
      the proxy info, or empty if not found/offline

    • getProxiesInRegion

      @Nonnull Collection<ProxyInfo> getProxiesInRegion(@Nonnull String region)
      Get all proxies in a specific region.
      Parameters:
      region - the region to filter by
      Returns:
      proxies in that region

    • getGlobalPlayerCount

      int getGlobalPlayerCount()
      Get the total number of players across all proxies.
      Returns:
      the global player count

    • getProxyCount

      int getProxyCount()
      Get the number of online proxy instances.
      Returns:
      the count of online proxies

    • findPlayerProxy

      @Nonnull Optional<String> findPlayerProxy(@Nonnull UUID playerUuid)
      Find which proxy a player is connected to.

      For async operations, prefer findPlayerProxyAsync(UUID).

      Parameters:
      playerUuid - the player's UUID
      Returns:
      the proxy ID, or empty if player is not online

    • findPlayerProxyAsync

      @Nonnull CompletableFuture<Optional<String>> findPlayerProxyAsync(@Nonnull UUID playerUuid)
      Find which proxy a player is connected to (async).

      This is the preferred method for cross-cluster lookups as it doesn't block while waiting for Redis responses.

      Parameters:
      playerUuid - the player's UUID
      Returns:
      a future completing with the proxy ID, or empty if not online

    • isPlayerOnline

      boolean isPlayerOnline(@Nonnull UUID playerUuid)
      Check if a player is online anywhere in the cluster.

      For async operations, prefer isPlayerOnlineAsync(UUID).

      Parameters:
      playerUuid - the player's UUID
      Returns:
      true if the player is connected to any proxy

    • isPlayerOnlineAsync

      @Nonnull CompletableFuture<Boolean> isPlayerOnlineAsync(@Nonnull UUID playerUuid)
      Check if a player is online anywhere in the cluster (async).

      This is the preferred method for cross-cluster lookups as it doesn't block while waiting for Redis responses.

      Parameters:
      playerUuid - the player's UUID
      Returns:
      a future completing with true if the player is online

    • getLeastLoadedProxy

      @Nonnull Optional<ProxyInfo> getLeastLoadedProxy(@Nonnull String region)
      Get the proxy with the lowest load in a specific region.

      Useful for load balancing new connections within a region. Use getLeastLoadedProxy() for any region.

      Parameters:
      region - the region to search (must not be null)
      Returns:
      the least loaded proxy in that region, or empty if none available

    • getLeastLoadedProxy

      @Nonnull Optional<ProxyInfo> getLeastLoadedProxy()
      Get the proxy with the lowest load across all regions.
      Returns:
      the least loaded proxy, or empty if none available