Package com.tnsai.reliability

Class S3CheckpointStore

java.lang.Object

com.tnsai.reliability.S3CheckpointStore

All Implemented Interfaces:

CheckpointStore

public final class S3CheckpointStore
extends Object
implements CheckpointStore

S3-backed CheckpointStore (TNS-312). Use this when checkpoints need to outlive a single host — agent fleet distributed across many processes / containers / regions, where a run starting in one place may be resumed in another.

Object layout

One JSON object per checkpoint at s3://<bucket>/<keyPrefix><runId>/<stepIndex>.json. The shape matches FilesystemCheckpointStore's envelope: runId, stepIndex, capturedAt, stateBase64, metadata, previousCheckpointId.

Atomic writes

S3 PutObject is atomic — readers either see the previous good version or the new one, never a torn write. No tmp/rename dance like the filesystem store needs.

Concurrency

The S3Client is thread-safe; this store delegates directly so concurrent save(com.tnsai.reliability.Checkpoint) / latest(java.lang.String) from many threads is fine.

Run id sanitisation

Run ids are S3 object-key components — must not contain / (would change the directory layout) or be empty. The store rejects those at the entry point.

Optional dependency

software.amazon.awssdk:s3 is declared <optional>true</optional> on tnsai-core; consumers that don't use this store don't pay for the SDK. Loading this class without the SDK on the classpath is a hard NoClassDefFoundError, by design.

Since:

0.10.0 (TNS-312)

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEFAULT_KEY_PREFIX	Default key prefix; objects land under this folder in the bucket.

Constructor Summary

Constructors

Constructor	Description
S3CheckpointStore(software.amazon.awssdk.services.s3.S3Client s3, String bucket)
S3CheckpointStore(software.amazon.awssdk.services.s3.S3Client s3, String bucket, String keyPrefix)

Method Summary

Modifier and Type	Method	Description
List<Checkpoint>	history(String runId)
Optional<Checkpoint>	latest(String runId)
void	save(Checkpoint cp)	Persist a checkpoint.
void	truncate(String runId, Instant before)	Drop every checkpoint for runId captured strictly before before.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

DEFAULT_KEY_PREFIX

public static final String DEFAULT_KEY_PREFIX

Default key prefix; objects land under this folder in the bucket.

See Also:

• Constant Field Values

Constructor Details

S3CheckpointStore

public S3CheckpointStore(software.amazon.awssdk.services.s3.S3Client s3,
 String bucket)

S3CheckpointStore

public S3CheckpointStore(software.amazon.awssdk.services.s3.S3Client s3,
 String bucket,
 String keyPrefix)

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