Package com.tnsai.reliability

Class FilesystemCheckpointStore

java.lang.Object
com.tnsai.reliability.FilesystemCheckpointStore
All Implemented Interfaces:
CheckpointStore
public final class FilesystemCheckpointStore extends Object implements CheckpointStore
Filesystem-backed CheckpointStore (TNS-299). Persists each checkpoint as a JSON file under <root>/<runId>/<stepIndex>.json.

Why JSON

Debuggability beats raw bytes/sec for almost every long-running run the framework supports. Operators can less a checkpoint file to see exactly what state was captured, which step it sat at, and what metadata the orchestrator attached. Binary serialization is a follow-up for hot paths that demand it.

Durability

save(com.tnsai.reliability.Checkpoint) writes to a sibling .tmp file, fsyncs the file descriptor, and then atomically renames it over the final path. A crash mid-write leaves the previous good entry intact rather than a truncated file.

Run id sanitization

Run ids must be path-safe. The store rejects ids containing /, \, .., or null bytes — these would let a malicious id escape the configured root directory. Use UUIDs or URL-safe slugs.
Since:
0.10.0 (TNS-299)

  • Constructor Details

    • FilesystemCheckpointStore

      public FilesystemCheckpointStore(Path root)

  • Method Details

    • save

      public void save(Checkpoint cp)
      Description copied from interface: CheckpointStore
      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.
      Specified by:
      save in interface CheckpointStore

    • latest

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

    • history

      public List<Checkpoint> history(String runId)
      Specified by:
      history in interface CheckpointStore
      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

      public void truncate(String runId, Instant before)
      Description copied from interface: CheckpointStore
      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.
      Specified by:
      truncate in interface CheckpointStore