# dista.checkpoint

> A module of Dista's API.

Where actor checkpoints live: objects under `DISTA_CHECKPOINT_URI`.

The URI is a local directory, a `file://` one, or anything objectstore
writes to, such as `s3://bucket/prefix`. A local directory only outlives the
worker that wrote it if the node that restarts the actor sees it too, so a
cluster needs a shared volume or object storage.

Each checkpoint is its own object, named for its actor and the number of
calls it covers, `<uri>/<actor ID in hex>/<calls>`, so a new one never
overwrites the one the head would restore from. The worker hosting the
actor deletes the ones before that one, those its predecessor left
included. A head that restarts restores each actor from its newest.

A checkpoint's bytes are, for each caller whose calls it includes, that
caller's number and the newest call's object ID, then the actor's state:
count u64, that many pairs of u64s, the state through the codec. Calls
resent after a head restart that it already includes aren't run again.

## Functions

### `checkpoint_uri`

```mojo
def checkpoint_uri() -> String
```

`DISTA_CHECKPOINT_URI`, without a trailing slash; raises if unset.

### `checkpoint_location`

```mojo
def checkpoint_location(actor: UInt64, calls: Int) -> String
```

Where actor `actor`'s checkpoint after `calls` calls lives.

### `newest_checkpoint`

```mojo
def newest_checkpoint(actor: UInt64) -> Int
```

The calls covered by actor `actor`'s newest checkpoint, or -1.

### `list_checkpoints`

```mojo
def list_checkpoints(actor: UInt64) -> List[Int]
```

The calls covered by each checkpoint actor `actor` has, in any order.

### `write_checkpoint`

```mojo
def write_checkpoint(location: String, data: Span[UInt8])
```

Writes a whole checkpoint, never part of one: after a head restart the newest is restored without anyone having said it was finished. An object store's put is whole already; a local file is written under a temporary name and renamed into place.

### `read_checkpoint`

```mojo
def read_checkpoint(location: String) -> List[UInt8]
```

### `delete_checkpoint`

```mojo
def delete_checkpoint(location: String)
```

Deletes a checkpoint nothing will restore from; a failure only leaves it behind.