Concord.Txn (Concord v3.0.1)

Atomic multi-key transactions for Concord.

A transaction is a one-shot, atomic operation that:

Evaluates compare predicates against pre-transaction state
If all hold (AND), executes the success branch
Otherwise, executes the failure branch
Returns {:ok, %Result{}} — never {:error, ...} for compare failures

Transaction Spec

%{
  compare: [compare()],
  success: [operation()],
  failure: [operation()]
}

Examples

# Atomic create-if-absent
Concord.Txn.commit(%{
  compare: [{:exists, "/key", :==, false}],
  success: [{:put, "/key", value, %{}}],
  failure: [{:get, {:key, "/key"}, %{}}]
})

# Conditional update with revision check
Concord.Txn.commit(%{
  compare: [{:mod_revision, "/key", :==, 1842}],
  success: [{:put, "/key", new_value, %{prev_kv: true}}],
  failure: [{:get, {:key, "/key"}, %{}}]
})

Summary

Functions

commit(spec, opts \\ [])

Commits a transaction spec atomically.

resolve(idempotency_key, opts \\ [])

Resolves the result of a transaction submitted with an idempotency key.

Functions

commit(spec, opts \\ [])

@spec commit(
  map(),
  keyword()
) :: {:ok, Concord.Txn.Result.t()} | {:error, term()}

Commits a transaction spec atomically.

Options

:idempotency_key — string key for safe retry (optional)
:timeout — operation timeout in ms (default: 5000)

Returns

{:ok, %Result{succeeded: true, ...}} — success branch ran
{:ok, %Result{succeeded: false, ...}} — failure branch ran (not an error)
{:error, {:invalid_txn, reason}} — spec validation failed
{:error, reason} — cluster error (:no_leader, :timeout, etc.)

resolve(idempotency_key, opts \\ [])

@spec resolve(
  binary(),
  keyword()
) :: {:ok, Concord.Txn.Result.t()} | {:error, term()}

Resolves the result of a transaction submitted with an idempotency key.

This is useful after a client timeout, when the transaction may have committed even though the caller did not receive its result.

Returns {:error, :not_found} when the key has no retained transaction result.