Skip to content

duron.log module

Entry module-attribute 

Entry

Concrete log entry types used within Duron.

BaseEntry

Bases: TypedDict

id instance-attribute 

id

Identifier for this log entry, unique within the log.

labels instance-attribute 

labels

Arbitrary string labels associated with this log entry.

metadata instance-attribute 

metadata

Non-essential metadata associated with this log entry.

ts instance-attribute 

ts

Timestamp for this log entry, in microseconds since the Unix epoch.

LogStorage

Bases: Protocol

Protocol for persistent storage of operation logs.

The lease mechanism ensures exclusive access for appending entries, preventing concurrent writes from multiple processes.

acquire_lease async 

acquire_lease()

Acquire an exclusive lease for appending to the log.

Returns:

  • bytes –

    Opaque lease token to be used in append() and release_lease() calls.

Raises:

  • Exception –

    if lease cannot be acquired (e.g., already held by another process).

Note

Leases provide concurrency control to ensure only one invoke can append to a log at a time, preventing interleaved writes from multiple processes.

append async 

append(lease, entry)

Append a new entry to the log.

Parameters:

  • lease (bytes) –

    Valid lease token from acquire_lease().

  • entry (Entry) –

    Log entry to append (promise/create, promise/complete, stream/emit, etc).

Returns:

  • int –

    Log index of the appended entry.

Raises:

  • Exception –

    if lease is invalid or expired.

Note

Appends must be atomic and durable. The returned index must be monotonically increasing and consistent with stream() output.

release_lease async 

release_lease(lease)

Release a previously acquired lease.

Parameters:

  • lease (bytes) –

    Lease token returned by acquire_lease().

Note

Should be called when invoke completes or encounters an error. Implementations should be idempotent.

stream 

stream(start, /, *, live)

Stream log entries from storage.

Parameters:

  • start (int | None) –

    Starting log index (inclusive). If None, stream from beginning.

  • live (bool) –

    If True, continue streaming new entries as they are appended. If False, stop after reading existing entries.

Yields:

Note

Log indices are monotonically increasing but may have gaps. During replay phase, this is called with live=False to restore state. During live execution, this may be called with live=True to monitor logs.