ข้ามไปยังเนื้อหา
CephalonEngine

Cephalon.EventSourcing.Nats

เนื้อหานี้ยังไม่ได้แปลเป็นภาษาไทย แสดงเป็นภาษาอังกฤษแทน

Maturity: M1 · Ownership: provider-managed · Family: event-sourcing · See audit, matrix.

Cephalon.EventSourcing.Nats is the NATS JetStream KV event-store provider for Cephalon, implementing IEventStore against a NATS JetStream KV bucket using zero-padded keys for lexicographically safe ordering.

What it owns

Section titled “What it owns”
  • implements IEventStore backed by a NATS JetStream KV bucket
  • stores each domain event as a KV entry with key format {streamId}/{streamVersion:D20} — zero-padded 20-digit version numbers ensure lexicographic ordering matches numeric ordering, enabling correct key-sorted replay without separate index queries
  • enforces optimistic concurrency via a pre-append GetVersionAsync check and CreateAsync which throws NatsKVCreateException if the key already exists (caught and rethrown as EventStreamConcurrencyException)
  • creates or updates the KV bucket on first operation via CreateOrUpdateStoreAsync
  • reads streams by collecting all keys matching the {streamId}/ prefix with parsed version >= fromVersion, sorting lexicographically (which equals numeric order due to zero-padding), and fetching each entry
  • serializes event payloads with System.Text.Json
  • reconstructs domain events by resolving Type.GetType(AssemblyQualifiedName) and deserializing via JsonSerializer
  • NatsConnection does NOT connect on construction — connection is deferred to first use, so DI resolution does not require a live NATS server

Main surfaces

Section titled “Main surfaces”
  • NatsEventEntry.cs — plain-object representation of a single event stored as a KV entry
  • NatsEventStore.cs — IEventStore implementation
  • Hosting/NatsEventSourcingServiceCollectionExtensions.cs — AddCephalonNatsEventSourcing registration

How it fits

Section titled “How it fits”

Cephalon.EventSourcing.Nats plugs into the IEventStore contract owned by Cephalon.EventSourcing. Application code depends only on IEventStore — swapping providers requires only a registration change. NATS JetStream KV is a durable, ordered, replicated key-value store that fits the event-sourcing append-and-replay pattern cleanly.

Registration

Section titled “Registration”
services.AddCephalonNatsEventSourcing(
    url: "nats://localhost:4222",
    bucketName: "cephalon-events");

KV entry schema

Section titled “KV entry schema”
FieldNotes
Key{streamId}/{streamVersion:D20} — zero-padded version for lexicographic ordering
ValueJSON-serialized NatsEventEntry

NatsEventEntry payload fields:

FieldTypeNotes
StreamIdstringStream identifier
StreamVersionlongEvent version within the stream
EventTypestringAssembly-qualified CLR type name
PayloadstringJSON-serialized event body
OccurredAtUtcDateTimeUTC timestamp when the domain event occurred
AppendedAtUtcDateTimeUTC timestamp when the event was appended

Optimistic concurrency

Section titled “Optimistic concurrency”

AppendAsync reads the current stream version before appending events. If the actual version does not match expectedVersion, an EventStreamConcurrencyException is thrown before any events are written. For each event, CreateAsync is used — if the key already exists (concurrent writer raced ahead), NatsKVCreateException is caught and rethrown as EventStreamConcurrencyException with the re-read actual version.

Not shipped in this slice

Section titled “Not shipped in this slice”

This provider intentionally does not claim:

  • NATS JetStream streams (non-KV) for event publishing
  • event projections or read-model maintenance
  • snapshotting or stream archival
  • NATS consumer groups or competing consumers
  • change-data-capture or NATS monitoring integration
Section titled “Related docs”