Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 32 additions & 8 deletions docs/src/content/docs/durable/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,15 @@ implement the `Store` interface out of tree.
- **Deterministic replay.** A recovered instance is byte-identical to one that
never crashed, because recovery replays the recorded driving events and
nondeterministic results rather than re-executing their sources.
- **Exactly-once effects.** A domain effect is applied exactly once over the
- **Exactly-once effects.** A domain effect from a step (not an initial entry, which is at-least-once, or a parent transition an actor drives, which is not dispatched) is applied exactly once over the
instance's lifetime (the live run plus any number of recoveries), even though
the replay loop is at-least-once. Each effect carries a deterministic
`EffectID` and is deduplicated through the `Store`'s dispatch set.
the replay loop is at-least-once. The exception is a crash or failed mark after the
handler returned, or a handoff between owners, where it can apply twice, so keep
handlers idempotent on `EffectInstance` plus the `EffectID`. Each effect carries a
deterministic `EffectID` and is deduplicated through the `Store`'s dispatch set.
The handler needs a `Store` that implements `DispatchStore`, as `MemStore` and
`FileStore` do: with any other `Store`, `Start`, `Recover` and the stateless
`Runner.Fire` refuse the configuration with `ErrEffectDispatch`.
- **Durability across restart.** Every `Fire` step is write-ahead appended to the
`Store` before it is acknowledged, so a crash after a successful `Fire` never
loses the step. Periodic checkpoints bound the tail that recovery replays.
Expand Down Expand Up @@ -74,7 +79,7 @@ the first time, and replayed verbatim on recovery:
| **Clock** (timers) | `WithRunnerClock` | `JournalClockRead`, replayed so timers fire at the same recorded instants, wall-clock-independent; armed deadlines survive checkpoint compaction |
| **Invoked services** | `WithServiceRegistry` + `Handle.RunService` | `JournalServiceResult`; a recorded result replays through the kernel's settle seam without re-running the service, and an unrecorded one (a context canceled during the service or its settle, a crash, or a failed `Append` whose write didn't land) runs again when the host calls `RunService` |
| **Child-machine actors** | `WithActorPalette` + `Handle.DeliverToActor` | `JournalActorMessage`; recovery re-fires a recorded parent transition; a settled or stopped actor doesn't re-run; a running `InvokeActor` actor restarts from its initial state on any `Recover`, and a `Spawn` actor doesn't return |
| **Domain effects** | `WithEffectHandler` | dispatch set, applied exactly once via deterministic `EffectID` dedup |
| **Domain effects** | `WithEffectHandler` | dispatch set, a step's effects applied exactly once via deterministic `EffectID` dedup, with the exceptions under Exactly-once effects |

Use `WithCheckpointEvery(n)` to tune how often a full snapshot is written: a
shorter interval bounds recovery replay, a longer one cuts checkpoint cost.
Expand Down Expand Up @@ -153,15 +158,34 @@ failed the Handle returns `ErrHandleFailed` saying it was recorded; `Recover` se
its effects. To move a healthy Handle's instance to a new Handle, stop calling the old one
and let its calls return first: a step can start after `Drain` returns. `Recover` a new
Handle with the same options to continue, unless the cause is `ErrFenced`: then a newer
owner holds the instance, so stop.
owner holds the instance, so stop. `Recover` retries an unapplied effect, and returns
`ErrEffectDispatch` while the handler still fails.

## A note on serialized payloads

Events, service done-data, actor done-data, and actor messages are recorded as their
JSON form. A parent reducer that type-asserts a non-JSON Go type from `AssignCtx.Event`
observes the JSON-decoded shape on a replayed `onDone`. A `WithEventData` payload is
decoded from its JSON form live as well as on replay, so a reducer gets the same value
both ways. `WithEventDataDecoder` decodes it as the type the caller passed, chosen per
observes the JSON-decoded shape of actor done-data on a replayed `onDone`. A service's
result is decoded from its JSON form live as well as on replay, so a reducer gets the same
value both ways. When `WithEventDataDecoder` covers the invocation's `onDone` event, the
result arrives as the decoder's type, for example `durable.DecodeAs[User]`. Otherwise it
arrives in JSON's generic form: a struct as a map and an integer as a `float64`, which
loses precision above 2^53. A decoder that fails, or that returns a type other than the
one the service returned, parks the result: `RunService` returns `ErrEventDataEncoding`
and no `onDone` or `onError` reducer runs, but the journal records the result as the
service returned it, and the Handle stays healthy. The service stays in flight and never
runs again. The decoder is part of the Runner's options, so the Handle that parked the
result never sees a fix: `Recover` with the fixed decoder, then call `RunService`, and it
settles the parked result. Until then `RunService` keeps returning
`ErrEventDataEncoding`. A checkpoint keeps a parked result, and a `Fire` that leaves the
state that declares the service discards it; a timer that leaves it doesn't yet, since
`Tick` doesn't stop the service. A service error stays message-only, an error with the same message, which `errors.Is` no
longer matches. Register the decoder before you record results: replay decodes the journal
with the recovering Runner's decoder, so a decoder added or changed after results were
recorded changes what replay hands the reducer, and one that can't decode a settled result
fails `Recover` and `StateAt` with `ErrEventDataEncoding`; a parked one doesn't fail them. A
`WithEventData` payload is decoded from its JSON form live as well as on replay, so a
reducer gets the same value both ways. `WithEventDataDecoder` decodes it as the type the caller passed, chosen per
event, for example `durable.DecodeAs[Order]`. Without one, a payload decodes as JSON's own
form, so `Handle.Fire` refuses a struct or an integer rather than hand the reducer a map
or a `float64`. An error stays an error with the same message, with any invalid UTF-8
Expand Down
Loading