Glossary

Glossary

Terms as they are used in this codebase. Where a word has a general meaning in the CQRS/event-sourcing world, the definition below is the Evento-specific one.

---

Architecture

RECQ — Reactive, Event-driven Commands and Queries. The architecture pattern Evento implements. See recq-patterns.

Bundle — An application unit hosting one or more domain components, connected to the server over TCP. The deployable unit of an Evento system.

Server / broker — The central process all bundles connect to. Owns the bundle registry, event store, routing and performance store. Bundles never talk directly to each other.

Context — A named scope restricting which events a component consumes; set with setComponentContexts(Class<?>, String...).

---

Components

Annotation	What it is
@Aggregate	The write model. Handles commands, emits events, rebuilds state by event sourcing
@Projector	Builds a read model by consuming events
@Saga	A long-running process, with persistent state, found per event by association
@Observer	Reacts to events with at-least-once delivery plus dedupe
@Projection	Serves queries against a read model
@Service	Handles commands without an aggregate
@Invoker	Entry point for application code invoking the system

Handler	Role
@AggregateCommandHandler	Decides: takes a command plus state, returns an event. init = true creates the aggregate
@EventSourcingHandler	Applies: takes an event plus state, returns/mutates the new state
@CommandHandler	Service-level command handling
@EventHandler	Consumes an event. executor = "name" opts into parallel consumption; retry = n sets retries
@SagaEventHandler	Consumes an event into saga state; associationProperty locates the instance
@QueryHandler	Answers a query, returning Single.of(...) or Multiple.of(...)
@InvocationHandler	Invoker entry point

---

Wire and transport

Frame — A parsed Message plus the retained raw wire bytes. Retaining the bytes is what makes zero-copy forwarding possible.

payloadType — The String the broker routes on. The server never deserializes the payload itself.

Chunking — Transparent splitting of a large message into CHUNK frames keyed by a stream UUID, reassembled on the far side. Means there is no message size limit; maxFrameLength bounds per-chunk memory only.

Zero-copy forwarding — Relaying Request / Response via sendRaw(byte[]) without re-encoding CBOR on the broker hop.

DEGRADED — A connection state meaning the Netty write buffer passed its high-water mark. Advisory only: canSend() is still true, because the socket is alive.

Supersede — When a bundle reconnects, its new session replaces the old one in ConnectionRegistry. The old session's disconnect must then be ignored, or it wipes the new session's handlers.

Correlation id — The UUID tying a Response to its Request. Retrying with the same correlation id is what makes exactly-once possible.

---

Consumers

Consumer — Anything that reads the event stream and advances a checkpoint: a projector, saga or observer.

Checkpoint — The persisted position of a consumer in the event stream, with an optimistic version for concurrency control.

CheckpointMode — ON_START (default) persists the dispatch frontier; WATERMARK persists the highest contiguous completed sequence, restoring at-least-once at the cost of replaying the in-flight window after a crash.

Consumer executor — A named, bounded execution resource enabling parallel consumption. The name is a capacity budget shared bundle-wide.

Dispatch frontier — The furthest event handed to an executor. Under ON_START this is what the checkpoint records — which is why the crash-loss window is the set of running tasks.

In-flight window — Events submitted but not yet completed. Lost on a hard kill under ON_START; replayed under WATERMARK.

Lane — One serialised slot in a partitioned executor. Events sharing an aggregate id pin to one lane, giving per-aggregate ordering with cross-aggregate parallelism.

LockHandle — The AutoCloseable handle from ConsumerLock. Pins one pooled JDBC connection for its whole lifetime — the origin of the pool-sizing rule.

Dead-letter queue (DLQ) — Per-consumer store of events that exhausted their retries, with a retry flag. evento_v2_dead_event.

Dedupe store — Observer-side duplicate suppression with sweep windows. evento_v2_dedupe.

---

Capacity

Congestion collapse — Throughput falling rather than plateauing past capacity, because expired work is never cancelled and retries sustain it. Recognisable by idle CPU alongside collapsing throughput.

Growth-first queue — A queue that refuses an offer while the pool can still grow, so the executor reaches max before it queues. A stock ThreadPoolExecutor does the reverse.

Saturated — Pool at max and queue full. The counter evento.server.bus.executor.saturated only moves in this state, which is what makes it the alerting signal.

Indeterminate — The correct reading of a RequestTimeoutException: the caller stopped waiting, so the work may or may not have been applied. Not a failure.

---

Project conventions

SPI — Service Provider Interface: a seam you may implement. The five consumer SPIs are the main ones.

OCP dispatcher map — Map<Class<? extends Message>, Handler>, used instead of switch chains so that adding a message type never edits existing dispatch code.

Sealed hierarchy — Message and BusEvent. Extending permits forces every switch in the codebase to handle the new case. Load-bearing, not stylistic.

Tests at the boundary — Integration tests use real TCP transports, not mocks.

---

See also

Architecture Overview · Getting Started · Home