payjoin / rust-payjoin / 15273225656

83%

push

github

Add `SessionPersister` trait (#716)

`SessionPersister` is an alternative to `Persister` designed to persist
not just the initial state of a BIP78 type state machine, but the full
sequence of state transitions. Its explicit purpose is to allow sessions
to be replayed from their event history and to give applications the
ability to introspect their session’s progress (#336).

A `SessionPersister` is scoped to a specific BIP78 sender or receiver
session. Each session consists of discrete pieces of information
obtained during execution called session events. These session events
are stored via the `save_event` method. When an application resumes a
session, it loads these events into a replayer (not included in this
commit) to recover the latest session state. If the type state reaches
its terminal state or a fatal error occurs, the session is marked as
closed via `close()`.

Application developers should **not** interact directly with
`SessionPersister`. Instead, they interact indirectly by processing
state transition objects. These objects represent the possible outcomes
of attempting a state transition, and they must be processed for the
type state to advance or terminate.

There are six kinds of BIP78 state transition outcomes:

* A successful state transition that always progresses.
* A transition that may result in a **transient error**. In these cases,
the application should retry the session from its current state. These
errors originate outside of `rust-payjoin`. E.g an `ImplementationError`
triggered when executing an `InputsSeen` closure.
* A **fatal transition** that must close the session. These errors are
unrecoverable, requiring the fallback transaction to be broadcast. Fatal
transitions also include an event to be persisted for auditing purposes
and may also contain a transient error.
* Transitions that are either fatal or have no result (interpreted as
success). This is common for transitions handling responses to BIP78
subdirectory GET r... (continued)

582 of 597 new or added lines in 1 file covered. (97.49%)

6519 of 7710 relevant lines covered (84.55%)

600.75 hits per line