Interface SnapshotService

All Known Implementing Classes:
GrpcSnapshotService
public interface SnapshotService
Project Tachyon Interface SnapshotService

The core service responsible for managing player data backups (snapshots) and restorations.

This service acts as the bridge between the Spigot server and the Quarkus backend via gRPC. It handles the creation of point-in-time backups (both full profiles and specific components) and provides the necessary methods to fetch and decode snapshot histories for administrative reviews.

Since:
1.0.0-SNAPSHOT
Version:
1.0
Author:
Jimmy (vSKAH) - 17/04/2026

  • Method Details

    • takeDatabaseSnapshot

      CompletableFuture<Void> takeDatabaseSnapshot(@NotNull @NotNull String playerUniqueId, @NotNull @NotNull String reason, @NotNull @NotNull SnapshotTriggerType triggerType)
      Triggers an asynchronous backup of a player's entire profile based on the current database state.

      Important Warning: This method snapshots the data exactly as it currently exists in the backend database, not the live data present in the Spigot server's memory. If the player has "dirty" components that have not yet been flushed to the backend (via saveProfile() or saveComponent()), those unsaved changes will not be included in this snapshot.

      This creates a snapshot with FULL granularity. Because it serializes every piece of data currently attached to the player's database document, it should be used for major events (e.g., player bans, manual admin backups, or major scheduled saves).

      Parameters:
      playerUniqueId - The UUID of the player whose profile is being snapshotted.
      reason - The human-readable reason for this snapshot (e.g., "Suspected duplication").
      triggerType - The system or user action that triggered this backup (e.g., MANUAL, SPIGOT_TASK).
      Returns:
      A CompletableFuture that completes when the backend has successfully saved the full snapshot.

    • takeComponentSnapshot

      <T extends tech.skworks.tachyon.libs.com.google.protobuf.Message> CompletableFuture<Void> takeComponentSnapshot(@NotNull @NotNull String playerUniqueId, @NotNull @NotNull String reason, @NotNull @NotNull SnapshotTriggerType triggerType, @NotNull T component)
      Triggers an asynchronous backup of a single, specific Protobuf component for a player.

      This creates a snapshot with SPECIFIC_COMPONENT granularity in the database. It is highly optimized, sending only the compressed raw bytes (Zstd) of the targeted component over the network. Ideal for frequent, highly targeted backups (e.g., saving an inventory right after a trade).

      Type Parameters:
      T - The specific type of the Protobuf message.
      Parameters:
      playerUniqueId - The UUID of the player associated with the data.
      reason - The human-readable reason for this specific snapshot.
      triggerType - The system or user action that triggered this backup.
      component - The specific Protobuf message instance containing the data to backup.
      Returns:
      A CompletableFuture that completes when the backend has successfully saved the specific snapshot.

    • toggleSnapshotLocking

      CompletableFuture<ToggleLockSnapshotResponse> toggleSnapshotLocking(@NotNull @NotNull String snapshotId, @NotNull @NotNull String executorUniqueId)
      Asynchronously toggles the lock status of a specific snapshot.

      A locked snapshot is protected from being automatically purged or archived by scheduled maintenance tasks (such as the S3 Archiver job). This method inverses the current lock state (locks an unlocked snapshot, or unlocks a locked one).

      Parameters:
      snapshotId - The unique identifier (ObjectId hex string) of the target snapshot. Must not be null.
      executorUniqueId - The unique identifier (e.g., UUID) of the administrator or system executing this action. Must not be null.
      Returns:
      A CompletableFuture that, when successfully completed, yields a ToggleLockSnapshotResponse containing the newly applied lock status.

    • getSnapshots

      CompletableFuture<ListSnapshotsResponse> getSnapshots(@NotNull @NotNull String playerUniqueId)
      Retrieves the metadata history of all snapshots associated with a specific player.

      This method does not download the actual heavy data payloads. It only fetches the lightweight metadata (IDs, timestamps, reasons, granularity) used to populate the administrative Snapshot GUI lists.

      Parameters:
      playerUniqueId - The UUID of the player whose snapshot history is being requested.
      Returns:
      A CompletableFuture containing the response with the list of snapshot metadata.

    • decodeSnapshot

      CompletableFuture<DecodeSnapshotResponse> decodeSnapshot(@NotNull @NotNull String snapshotId)
      Fetches and decodes the actual data payload of a specific snapshot from the backend.

      Whether the snapshot is FULL (JSON parsed) or SPECIFIC_COMPONENT (Raw Binary), the backend will process it and return a standardized response containing the decoded Protobuf components wrapped in Any objects, ready to be processed by the ComponentRegistry.

      Parameters:
      snapshotId - The unique MongoDB ObjectId string of the snapshot to retrieve.
      Returns:
      A CompletableFuture containing the decoded snapshot data payload.