Package com.tnsai.reliability

Interface CheckpointStore

All Known Implementing Classes:
FilesystemCheckpointStore, InMemoryCheckpointStore, RedisCheckpointStore, S3CheckpointStore, SqliteCheckpointStore
public interface CheckpointStore
SPI for persisting Checkpoints across the lifetime of a long-running run (TNS-299).

Implementations range from local-only (FilesystemCheckpointStore, SqliteCheckpointStore) to distributed (S3CheckpointStore follow-up). The contract is intentionally narrow so any KV / blob / SQL store can adapt: append on save(com.tnsai.reliability.Checkpoint), retrieve the latest by run id, walk the chain via history(java.lang.String), and prune via truncate(java.lang.String, java.time.Instant).

Concurrency

Implementations MUST be safe to call concurrently. A run may save a checkpoint on its own thread while a separate inspector thread reads latest(java.lang.String) for an operator dashboard.

Durability

save(com.tnsai.reliability.Checkpoint) must not return until the checkpoint is persisted such that a process crash immediately afterwards can recover it. In-memory stores satisfy this trivially (single process); filesystem stores must fsync their writes before returning; SQL stores must commit the transaction.
Since:
0.10.0 (TNS-299)

  • Method Details

    • save

      void save(Checkpoint cp)
      Persist a checkpoint. Returns when the entry is durable — see "Durability" in the type-level javadoc. Overwrites any prior checkpoint with the same (runId, stepIndex) pair so a step that retries can replace its earlier snapshot.
      Throws:
      NullPointerException - if cp is null

    • latest

      Optional<Checkpoint> latest(String runId)
      Returns:
      the highest-stepIndex checkpoint known for runId, or empty when the store has none.

    • history

      List<Checkpoint> history(String runId)
      Returns:
      all checkpoints for runId, ordered by ascending stepIndex. Empty list when no checkpoints exist. Implementations may impose a soft cap when histories grow unbounded; document the cap in their javadoc when they do.

    • truncate

      void truncate(String runId, Instant before)
      Drop every checkpoint for runId captured strictly before before. Leaves the latest entry if it falls on or after the cutoff so resume continues to work. Used by retention jobs; not on the run's hot path.