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#
| Attribute | Type | Description |
|---|---|---|
EntryId | type[EntryId] | An entry's id: UUID version 7 bytes. |
RemoteId | type[RemoteId] | A remote's id: UUID version 4 bytes. |
StoreId | type[StoreId] | The store of an identity an event log writes to ( |
EntryIdSchema | S.Codec[EntryId, bytes] | |
RemoteIdSchema | S.Codec[RemoteId, bytes] | |
StoreIdSchema | S.Codec[StoreId, str] | |
ENTRY_ARRAY_CODEC | ArraySchema[tuple[Entry, ...], Entry, bytes, Any, Any] | Entries as one frame each (Effect's |
make_memory | Effect[EventJournalService] | A journal in this process (Effect's |
layer_memory | Layer[EventJournal] | The |
Types#
| Type | Definition | Description |
|---|---|---|
EntriesById | type EntriesById = Callable[[Sequence[EntryId]], Effect[list[Entry | None], EventJournalError]] | A journal's |
Compact | type Compact = Callable[[Sequence[RemoteEntry]], Effect[Sequence[Entry], EventJournalError]] | |
ReplayBatch | type ReplayBatch = Callable[[Sequence[EntryWithConflicts]], Effect[None, EventJournalError]] |
Classes#
Functions#
make_remote_id_unsafe#
make_remote_id_unsafe() -> RemoteIdA 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() -> intThe 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_000latest_entry_id_floor#
latest_entry_id_floor() -> intThe 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_MILLISmake_entry_id_unsafe#
make_entry_id_unsafe(*, msecs=None) -> EntryIdA 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).
| Parameter | Type | Description |
|---|---|---|
msecs | float | 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) -> intThe 48-bit millisecond timestamp of an entry id.
| Parameter | Type | Description |
|---|---|---|
entry_id | bytes |
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).
| Parameter | Type | Description |
|---|---|---|
clock | ClockService | |
ids | Iterable[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) -> bytesThe sort key of entries: their ids (Effect's Entry.Order).
| Parameter | Type | Description |
|---|---|---|
entry | Entry |
Returns bytes
def entry_order(entry: Entry) -> bytes:
"""The sort key of entries: their ids (Effect's ``Entry.Order``)."""
return entry.idmake_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).
| Parameter | Type | Description |
|---|---|---|
entries | Sequence[EntryInput] | |
after | Iterable[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) -> intThe remote sequence following entries and next.
| Parameter | Type | Description |
|---|---|---|
entries | Iterable[RemoteEntry] | |
next | int = 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 nextadvance_sequence#
advance_sequence(next, acks, first_sequence=0) -> intnext moved past the acknowledged sequences that follow it
without a gap, starting no lower than first_sequence.
| Parameter | Type | Description |
|---|---|---|
next | int | |
acks | Iterable[RemoteAck] | |
first_sequence | int = 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