Chief of State (CoS) is an open-source clustered persistence tool for building event-sourced applications. CoS supports CQRS and event-sourcing through simple, language-agnostic interfaces via gRPC or HTTP/JSON, and it lets you describe your schema with Protobuf. Under the hood, CoS leverages Apache Pekko to scale out and deliver performant, reliable persistence.
Chief of State was built with these principles:
- Wire format should be the same as persistence
- Scaling should not require re-architecture
- Developers shouldn't face race conditions or database locks
- Rules should be enforced with interfaces
- Event sourcing is valuable but challenging to implement
- An ideal event-sourcing datastore would offer random access by key, streaming, and atomic writes
Chief of State was created in 2020 at Namely based on the principles above.
If your company is still using the Namely version and wants to migrate to this fork, you must be at least on namely v0.9.2-rc.1. See the documentation for setup instructions.
From version v2.4.11 onward, Chief of State has been fully migrated from Akka to Apache Pekko. Projects on versions before that cannot be upgraded to the latest releases due to the lack of a migration kit at this time.
- Journal & Snapshot — Serialization using Google Protocol Buffer message format
- Clustering — Preconfigured clustering and domain entity sharding with the split-brain-resolver algorithm
- Caching — Automatic caching and entity Passivation
- Storage — Automatic configuration of PostgreSQL storage on boot
- Observability — OpenTelemetry integration for tracing and metrics
- Compaction — Journal compaction support
- Kubernetes — Direct integration to form a cluster using the Kubernetes API
- Subscriptions — Real-time events streaming without interacting with the Journal Store
- Read Side Management — Via the CLI tool:
- Skip offset per shard and across the whole CoS cluster
- Pause, resume, and restart read sides per shard or cluster-wide
- List read sides' offsets per shard and across the cluster
Chief of State has been used in production by notable companies since 2020.
You implement two handler interfaces (gRPC or HTTP): a write handler to process commands and events, and optionally many read handlers that react to state changes by consuming events from the write handler.
The main entry point is the Service. You interact with Chief of State via:
ProcessCommand— Send commands to be processed by the Write HandlerGetState— Retrieve the current state of a persistent entity
You describe state mutations by implementing two RPCs in the WriteSideHandlerService:
HandleCommand— Accepts a command and the prior state, returns an event. For example, givenUpdateUserEmailand aUser, it might returnUserEmailUpdated.HandleEvent— Accepts an event and the prior state, returns the new state. For example, givenUserEmailUpdatedand aUser, it returns a newUserinstance with the email updated.
In response to state mutations, CoS sends changes to many ReadSideHandlerService implementations. CoS guarantees at-least-once delivery of events and resulting state to each read side, in the order they were persisted.
Read side handlers can:
- Write state changes to a data store (e.g., Elasticsearch)
- Publish changes to Kafka topics
- Send notifications to users in response to specific events
Join the discussion and ask Chief of State–related questions:
Contributions are welcome!
The project adheres to Semantic Versioning and Conventional Commits. If you see an issue you'd like to fix, the best way is to submit a pull request. To test your changes locally:
# Install Earthly CLI (macOS)
brew install earthly/earthly/earthly
# Build the Docker image
earthly +build-image
# Run tests
earthly -P --no-output +test-localTip: See the Earthly docs for installation on Linux and Windows.
Chief of State is free and will remain so, with no paid license requirement.