saga/storage/conformance

Checks a storage adapter against the saga/storage contract.

Use this module from an adapter’s own tests; it needs no test framework. run gives each scenario a fresh fixture and fresh execution ids, and checks atomic creation, unchanged data after refused writes, claims as values (any holder may commit; a rebuilt claim with another token is refused), revision and generation checks, cancellation races, release, that a live owner keeps its claim, that a lost owner’s claim ends within owner_loss_within, the unfinished listing, and that a saga/durable drive whose runner is killed frees the execution at once for the next drive, which resumes from the checkpoint. One fixture may serve several executions, as a database pool does. The memory, file and PostgreSQL adapters pass the same checks.

A pass covers the storage protocol from one VM; it does not certify cross-node fencing, media durability or power-loss behavior.

import gleam/time/duration
import saga/storage/conformance

let result =
  conformance.run(
    fn() {
      let assert Ok(store) = memory.start()
      Ok(conformance.fixture(memory.storage(store), cleanup: fn() {
        memory.stop(store)
      }))
    },
    timeout: duration.seconds(5),
    owner_loss_within: duration.milliseconds(500),
  )

owner_loss_within is the adapter’s declared window for noticing that an owner is gone: near zero for the memory adapter, which watches the claiming process, and the lease duration for a lease-based adapter.

pub type Failure {
  SetupFailed(String)
  UnexpectedResult(check: String)
  AdapterCrashed(String)
  TimedOut
  InvalidTimeout
}

pub opaque type Fixture

pub fn fixture(
  storage: storage.Storage,
  cleanup cleanup: fn() -> Nil,
) -> Fixture

pub fn run(
  fresh: fn() -> Result(Fixture, String),
  timeout timeout: duration.Duration,
  owner_loss_within owner_loss_within: duration.Duration,
) -> Result(Nil, Failure)