spi/me.ahoo.wow.spi.log

Package-level declarations

Types

class AggregateTail @InternalWowApi constructor(val streams: List<EventStreamRecord>, val earlier: List<CommittedRequest>)

What EventLog.readTail reads of one aggregate in one round trip: its streams from a version on, in version order, and the request keys of its streams before that version, the latest first (earlier).

AppendOutcome

@WowSpi

sealed interface AppendOutcome

How an append ended. Every expected result is a value; only a defect is an exception.

CommittedRequest

class CommittedRequest @InternalWowApi constructor(val version: Int, val requestId: String, val commandType: String)

The request key of one committed stream: the aggregate's version it committed, its requestId and its commandType, the command's fingerprint. The kernel builds an aggregate's recent requests from these.

EventLog

@WowSpi

interface EventLog

The log of one bounded context: the only place a fact is written (axiom A1).

EventRecord

class EventRecord @InternalWowApi constructor(val name: String, val revision: Int, val payload: String)

One event as the log stores it: its type name (context.aggregate.event, not a class name), the revision of its schema, and its serialized payload.

EventStreamRecord

class EventStreamRecord @InternalWowApi constructor(val ref: AggregateRef, val version: Int, val commandId: String, val requestId: String, val commandType: String, val commitTime: Long, val events: List<EventRecord>, val scope: Scope, val causation: Causation? = null, val headers: Map<String, String> = emptyMap(), val operator: Operator? = null, val access: Map<String, Any?>? = null, val accessVersion: Int? = if (access == null) null else version)

The events one command produced, committed together by one append: the unit of fact (documentation/designs/08-data-protocols.md §4).

LogEntry

class LogEntry @InternalWowApi constructor(val position: LogPosition, val stream: EventStreamRecord, val transport: ByteArray? = null)

A committed event stream at its position in the log, with the transport section appended with it, if any. Only EventLog.tail and EventLog.readEntries return entries: the transport serves the subscriptions and signals that read the log, never the domain.

LogPosition

data class LogPosition(val partition: Int, val sequence: Long)

A position in the log: a partition and a sequence within it, in the order commits became visible.

Partitioner

object Partitioner

Assigns an aggregate to a partition. The hash is part of the storage format: it is fixed across JVMs, processes and versions (64-bit over context.aggregate/tenant/id, never String.hashCode), so every node and every release agrees, and changing it means repartitioning the log.

PartitionLineage

class PartitionLineage

Where a log partition comes from: the metadata format 1 reserves for the online splits of 10.x, so that they are an additive change. Each backend stores it with the partition's counter, writes ROOT for every partition a log is created with, and reads it back with EventLog.lineage; nothing acts on it yet.

SnapshotTail

class SnapshotTail @InternalWowApi constructor(val snapshot: SnapshotRecord?, val tail: AggregateTail)

What SnapshotTailReader.readWithSnapshot reads of one aggregate: its snapshot, null when it has none, and the tail after it, every stream of the aggregate when there is no snapshot.

SnapshotTailReader

@WowSpi

fun interface SnapshotTailReader

An optional capability of a store that holds a context's log and its snapshots in one database: reading an aggregate's snapshot and the tail after it in one round trip (me.ahoo.wow.spi.store.Store.snapshotTails). The runtime gives it to the kernel for the aggregate types whose log and primary snapshots are on that one store; the others are read the way every log can: the snapshot, then the tail (readSnapshotTailApart).

TailPacer

@WowSpi

class TailPacer(partitions: Int, val interval: Duration, val maxInterval: Duration)

How often a tail polls: every interval while it finds entries, backing off when it finds none, each empty poll doubling the wait up to maxInterval. A commit this log made in the partition wakes its tails at once, so an idle partition's next entry is not held up by the backoff on the node that appends it; entries other nodes append are read within maxInterval.

TailPolling

@WowSpi

class TailPolling(val interval: Duration, val maxInterval: Duration)

How often the tails of a polled log poll: every interval while they find entries, backing off up to maxInterval while they find none (wow.log.poll-interval, wow.log.max-poll-interval).

Transport

class Transport @InternalWowApi constructor(val wait: WaitContext? = null, val reservations: List<ReservationKey> = emptyList(), val trace: Map<String, String> = emptyMap(), val releases: List<ReservationKey> = emptyList())

What an append carries for delivery, not as fact (§4): domain code and queries never see it, and a migration or a replay drops it. The runtime appends it encoded (TransportCodec), and a backend stores those bytes apart from the stream (its own column or field), never reading them.

TransportCodec

@InternalWowApi

object TransportCodec

The one form of a Transport: the runtime encodes it once, the log stores the bytes as they are, and the Kafka envelope and the cluster channel embed the same JSON object.

VersionPages

@InternalWowApi

object VersionPages

How a backend reads an aggregate's streams by version (EventLog.read, EventLog.readEntries): a page of at most SIZE streams at a time, by the version key, each page emitted before the next is read. A read then holds one page, whatever the aggregate's history: a replay from version 1 of an aggregate of hundreds of thousands of streams, which held them all, holds 512. Each page is a call of its own, so a long read holds no connection between pages; a read within one page is one call, as before.

Functions

notAppendedAfter

fun notAppendedAfter(failed: EventStreamRecord, outcome: AppendOutcome): AppendOutcome.Conflict

The outcome of a stream that came after failed, of the same aggregate, in one EventLog.appendAll, when failed did not commit (outcome): not appended, a conflict at the version outcome leaves the aggregate at, the conflict's own when outcome is one, else the version before failed's.

readSnapshotTailApart

@InternalWowApi

suspend fun EventLog.readSnapshotTailApart(ref: AggregateRef, snapshots: SnapshotStore, earlier: Int): SnapshotTail

ref's snapshot in snapshots and the tail after it, read apart: SnapshotStore.load, then EventLog.readTail from the snapshot's version, or every stream of ref (a replay) and no earlier keys when there is no snapshot.

requireChains

fun requireChains(streams: List<Pair<EventStreamRecord, ByteArray?>>)

Checks what EventLog.appendAll takes of one aggregate: its streams in consecutive versions, in order. A backend that commits a group in one write relies on it to commit them as a prefix.