GitHub

event_journal

API reference for event_journal.

The journal of an event log (Effect's eventlog/EventJournal): the entries written locally or received from remotes, ordered by id, and how far each remote has seen them.

Entry ids are UUID version 7 bytes: 48 bits of milliseconds, then a 12-bit counter that keeps the ids of one process strictly ascending even when the clock stalls or moves back. make_memory keeps the journal in this process (sql_event_journal keeps it in a database). Effect's IndexedDB journal is browser-only and not ported.

Values

AttributeTypeDescription
EntryIdtype[EntryId]

An entry's id: UUID version 7 bytes.

RemoteIdtype[RemoteId]

A remote's id: UUID version 4 bytes.

StoreIdtype[StoreId]

The store of an identity an event log writes to ("default").

EntryIdSchemaS.Codec[EntryId, bytes]
RemoteIdSchemaS.Codec[RemoteId, bytes]
StoreIdSchemaS.Codec[StoreId, str]
ENTRY_ARRAY_CODECArraySchema[tuple[Entry, ...], Entry, bytes, Any, Any]

Entries as one frame each (Effect's Entry.arraySchemaBinary).

make_memoryEffect[EventJournalService]

A journal in this process (Effect's makeMemory).

layer_memoryLayer[EventJournal]

The EventJournal of make_memory.

Types

TypeDefinitionDescription
EntriesByIdtype EntriesById = Callable[[Sequence[EntryId]], Effect[list[Entry | None], EventJournalError]]

A journal's entries_by_id.

Compacttype Compact = Callable[[Sequence[RemoteEntry]], Effect[Sequence[Entry], EventJournalError]]
ReplayBatchtype ReplayBatch = Callable[[Sequence[EntryWithConflicts]], Effect[None, EventJournalError]]

Classes

Functions

make_remote_id_unsafe

make_remote_id_unsafe() -> RemoteId

A new random remote id (Effect's makeRemoteIdUnsafe).

Returns RemoteId

def make_remote_id_unsafe() -> RemoteId:
    """A new random remote id (Effect's ``makeRemoteIdUnsafe``)."""
    return RemoteId(uuid_v4_unsafe(format="bytes"))

now_millis

now_millis() -> int

The wall clock in milliseconds, which local entry ids follow (Effect's Date.now(); not the Clock service).

Returns int

def now_millis() -> int:
    """The wall clock in milliseconds, which local entry ids follow
    (Effect's ``Date.now()``; not the ``Clock`` service)."""
    return time.time_ns() // 1_000_000

latest_entry_id_floor

latest_entry_id_floor() -> int

The latest millisecond of an id local ids may follow, now.

Returns int

def latest_entry_id_floor() -> int:
    """The latest millisecond of an id local ids may follow, now."""
    return now_millis() + _MAX_CLOCK_SKEW_MILLIS

make_entry_id_unsafe

make_entry_id_unsafe(*, msecs=None) -> EntryId

A new entry id: the next local id, or with msecs a random id of that millisecond, truncated and clamped to the UUID v7 range (Effect's makeEntryIdUnsafe).

ParameterTypeDescription
msecsfloat | None = None

Returns EntryId

def make_entry_id_unsafe(*, msecs: float | None = None) -> EntryId:
    """A new entry id: the next local id, or with ``msecs`` a random id of
    that millisecond, truncated and clamped to the UUID v7 range (Effect's
    ``makeEntryIdUnsafe``)."""
    if msecs is not None:
        return EntryId(bytes(_uuid.v7_bytes(msecs, random_bytes_unsafe(16))))
    return _next_entry_id(_process_entry_ids, now_millis())

entry_id_millis

entry_id_millis(entry_id) -> int

The 48-bit millisecond timestamp of an entry id.

ParameterTypeDescription
entry_idbytes

Returns int

def entry_id_millis(entry_id: bytes) -> int:
    """The 48-bit millisecond timestamp of an entry id."""
    return int.from_bytes(entry_id[:6])

warn_if_ahead

warn_if_ahead(clock, ids) -> Effect[None]

Log a warning when the latest of ids is more than a day ahead of clock (Effect's warnIfAhead).

ParameterTypeDescription
clockClockService
idsIterable[EntryId]

Returns Effect[None]

def warn_if_ahead(clock: ClockService, ids: Iterable[EntryId]) -> Effect[None]:
    """Log a warning when the latest of ``ids`` is more than a day ahead of
    ``clock`` (Effect's ``warnIfAhead``)."""
    latest = _max_entry_id(ids)
    if latest is None:
        return succeed(None)
    ahead = entry_id_millis(latest) - now_millis_unsafe(clock)
    if ahead <= _MAX_CLOCK_SKEW_MILLIS:
        return succeed(None)
    return log_warning(
        f"Imported an entry id {round(ahead / 3_600_000)} hours ahead of the local clock"
    ).annotate_logs({"service": "EventJournal", "entryId": _uuid.stringify(latest)})

entry_order

entry_order(entry) -> bytes

The sort key of entries: their ids (Effect's Entry.Order).

ParameterTypeDescription
entryEntry

Returns bytes

def entry_order(entry: Entry) -> bytes:
    """The sort key of entries: their ids (Effect's ``Entry.Order``)."""
    return entry.id

make_entries

make_entries(entries, after) -> Effect[list[Entry], EventJournalError]

Entries for entries with fresh ids greater than the ids after and every local id so far (Effect's makeEntries).

ParameterTypeDescription
entriesSequence[EntryInput]
afterIterable[EntryId]

Returns Effect[list[Entry], EventJournalError]

def make_entries(
    entries: Sequence[EntryInput], after: Iterable[EntryId]
) -> Effect[list[Entry], EventJournalError]:
    """Entries for ``entries`` with fresh ids greater than the ids
    ``after`` and every local id so far (Effect's ``makeEntries``)."""

    def build() -> list[Entry]:
        sequence = _sequence_after(_local_floor(after, now_millis()))
        unchecked = S.new(Entry, disable_checks=True)
        return [
            unchecked(
                id=_next_entry_id(sequence, now_millis()),
                event=e.event,
                primary_key=e.primary_key,
                payload=e.payload,
            )
            for e in entries
        ]

    return try_(build, lambda cause: EventJournalError("writeMany", cause))

next_sequence_after

next_sequence_after(entries, next=0) -> int

The remote sequence following entries and next.

ParameterTypeDescription
entriesIterable[RemoteEntry]
nextint = 0

Returns int

def next_sequence_after(entries: Iterable[RemoteEntry], next: int = 0) -> int:
    """The remote sequence following ``entries`` and ``next``."""
    for remote_entry in entries:
        if remote_entry.remote_sequence >= next:
            next = remote_entry.remote_sequence + 1
    return next

advance_sequence

advance_sequence(next, acks, first_sequence=0) -> int

next moved past the acknowledged sequences that follow it without a gap, starting no lower than first_sequence.

ParameterTypeDescription
nextint
acksIterable[RemoteAck]
first_sequenceint = 0

Returns int

def advance_sequence(next: int, acks: Iterable[RemoteAck], first_sequence: int = 0) -> int:
    """``next`` moved past the acknowledged sequences that follow it
    without a gap, starting no lower than ``first_sequence``."""
    next = max(next, first_sequence)
    for sequence in sorted(ack.sequence for ack in acks):
        if sequence == next:
            next += 1
        elif sequence > next:
            break
    return next