Package com.btcvelocity.api.storage

Interface StorageService

public interface StorageService
Asynchronous storage service for persisting player data and proxy state to a durable backend (PostgreSQL).

All methods are non-blocking and return CompletableFutures. Callers should never block on the returned futures from a Netty event loop thread. Operations are dispatched to a dedicated thread pool so that database I/O never stalls the proxy's network threads.

Implementations must use parameterized queries to protect against SQL injection. Any exception encountered during a database operation completes the returned future exceptionally.

  • Method Details

    • upsertPlayer

      CompletableFuture<Void> upsertPlayer(PlayerData data)
      Inserts or updates the persisted record for the given player.

      If a row with the same UUID already exists, all columns are updated to the values in data. Otherwise a new row is inserted.

      Parameters:
      data - the player data to persist; must not be null
      Returns:
      a future that completes when the upsert is done, or completes exceptionally on database error

    • getPlayer

      CompletableFuture<Optional<PlayerData>> getPlayer(UUID uuid)
      Retrieves the persisted data for the player with the given UUID.
      Parameters:
      uuid - the player's unique identifier; must not be null
      Returns:
      a future that completes with an Optional containing the player data, or an empty optional if no row was found; completes exceptionally on database error

    • getPlayerByName

      CompletableFuture<Optional<PlayerData>> getPlayerByName(String username)
      Retrieves the persisted data for the player with the given username.

      The lookup is case-insensitive.

      Parameters:
      username - the player's username; must not be null
      Returns:
      a future that completes with an Optional containing the player data, or an empty optional if no row was found; completes exceptionally on database error

    • updateProxyHeartbeat

      CompletableFuture<Void> updateProxyHeartbeat(String proxyId, int playerCount, long uptimeSeconds)
      Updates the heartbeat row for the specified proxy, recording the current player count and uptime.

      If no row exists for the given proxyId, one is inserted.

      Parameters:
      proxyId - the proxy identifier; must not be null
      playerCount - the current number of players on the proxy
      uptimeSeconds - the proxy uptime in seconds
      Returns:
      a future that completes when the heartbeat is written, or completes exceptionally on database error

    • updatePlayerLastSeen

      CompletableFuture<Void> updatePlayerLastSeen(UUID uuid, String serverName, long lastSeen)
      Updates the last_seen timestamp and current server for the player with the given UUID.
      Parameters:
      uuid - the player's unique identifier; must not be null
      serverName - the name of the server the player is now on, or null to clear it
      lastSeen - the epoch millisecond timestamp to record
      Returns:
      a future that completes when the update is done, or completes exceptionally on database error