cadrumo.adapters.persistence.operations.lease module

Durable filesystem owner leases for supervised operations.

class OperationLeaseStorage(*, storage_root)[source]

Bases: JournalRepositoryBase[_OperationLeaseRecord]

Shared operation-journal-root lease storage and lock authority.

The journal adapter uses the non-locking current-lease read only while it already holds this same repository lock. Lease transitions acquire that lock here, preventing a nested acquisition around journal commits.

Parameters:

storage_root (Path)

path_for(operation_id)[source]

Keep one lease record beside journals, using the supplied conflict-scope key.

Return type:

Path

Parameters:

operation_id (str)

ensure_root()[source]

Materialize the canonical secure journal root before locking it.

Return type:

None

refuse_retired_operation_path(*, scope_ref, operation_id)[source]

Refuse a superseded operation-keyed path without opening its bytes.

Return type:

None

Parameters:

  • scope_ref (OperationConflictScopeReference)

  • operation_id (OperationId)

current_unlocked(scope_ref)[source]

Load the scope’s exact lease state while the caller owns lock_target.

Return type:

OperationOwnerLease | None

Parameters:

scope_ref (OperationConflictScopeReference)

replace_unlocked(scope_ref, operation_id, lease, *, observed_at)[source]

Atomically replace one lease state while the caller owns the lock.

Return type:

None

Parameters:
require_live_exact_unlocked(*, scope_ref, operation_id, lease, observed_at)[source]

Refuse a journal writer without the exact live scope-and-operation lease.

Return type:

None

Parameters:
class OperationLeaseFilesystemRepository(*, storage_root)[source]

Bases: OperationLeaseRepository

Caller-clocked durable owner-lease port over the operation journal root.

Each transition runs its lock wait and file access on a worker thread, so the awaiting event loop is never parked on lease contention or disk.

Parameters:

storage_root (Path)

async inspect(scope_ref, operation_id, *, observed_at)[source]

Return absent, active, or expired durable lease state at observed_at.

Return type:

OperationLeaseObservation

Parameters:

  • scope_ref (OperationConflictScopeReference)

  • operation_id (OperationId)

  • observed_at (datetime)

async acquire(candidate, *, observed_at)[source]

Acquire only an absent lease; live and expired predecessors remain unchanged.

Return type:

OperationLeaseResult

Parameters:
async compare_and_swap(predecessor, successor, *, observed_at)[source]

Renew an exact live owner or take over an exact expired owner.

Return type:

OperationLeaseResult

Parameters:
async release(predecessor, *, observed_at)[source]

Release only the exact current lease and persist its absent successor.

Return type:

OperationLeaseResult

Parameters: