Splitter: The Control Plane That Makes Shard Ownership Real
A deep dive into the Go service that uses Raft, leases, and region-aware placement to coordinate stateful microservices without split-brain.
- Splitter turns shard ownership into an explicit lease, which is why it can prevent split-brain instead of merely reducing it.
- Its domain model is doing real work here, because UNIT, GLOBAL, and REGIONAL are different governance problems, not just naming choices.
- Raft is not decorative plumbing in Splitter, it is the source of truth that makes leader transitions and stale-read avoidance part of the design.
- The project sits above consistent hashing and ad hoc leader election by combining placement, recovery, and observability into one control plane.
Why sharding breaks the moment ownership becomes stateful
Sharding looks simple until ownership has side effects. If two workers think they own the same shard, the result is not just duplicate work. It can be corrupted state, conflicting writes, or a split-brain system that keeps running long after the damage is done.
That is the problem Splitter is built to solve. It is not a routing library that hands out buckets and moves on. It is a control plane that decides who owns what, proves that decision, and keeps watching after the handoff.
| Approach | Ownership guarantee | Recovery behavior | Region awareness | Risk of split-brain | Best for |
|---|---|---|---|---|---|
| Consistent hashing | Probabilistic placement only | Rebalances by ring math | Usually no | High when work is stateful | Stateless traffic distribution |
| Best-effort leader election | One leader, weak shard semantics | Depends on client behavior | Sometimes | Medium to high | Simple coordination tasks |
| Manual shard assignment | Human enforced | Slow and error-prone | Possible, but brittle | Very high | Small systems and emergencies |
| Splitter | Exclusive lease-based ownership | Automatic reassignment and monitoring | Built in | Low when operated correctly | Stateful microservices and other authoritative work |
What Splitter actually coordinates
Splitter is a coordinator for stateful sharded services. The model is multi-tenant, so everything lives under a Tenant. Inside that, Domains define the unit of intent, and Shards are the concrete pieces of work that get owned, observed, and moved.
That structure matters because it is not just naming. The repository models services, domains, regions, and shard ranges as first-class concepts. In other words, placement is not an implementation detail. It is the product.
type Tenant struct {
Name string
}
type DomainType string
const (
UnitDomain DomainType = "UNIT"
GlobalDomain DomainType = "GLOBAL"
RegionalDomain DomainType = "REGIONAL"
)
type ShardingPolicy struct {
ShardCount int
UUIDRange string
}
Domains are the real unit of intent
The most revealing abstraction in Splitter is Domain. A UNIT domain is a single atomic slice of work. A GLOBAL domain spreads shards across the whole cluster. A REGIONAL domain pins ownership to a geographic boundary so work stays close to where it belongs.
That is a more mature model than generic sharding. It says the coordinator must understand not only how much work exists, but what kind of work it is and what constraints govern it.
The interesting trick: exclusive ownership by lease
This is the center of the design. Splitter does not trust a worker just because it wants a shard. It grants ownership through a lease, monitors that lease, and revokes or reassigns it when the system changes. The point is exclusivity, not convenience.
That distinction is what keeps the control plane honest. Consistent hashing can suggest where a shard should live. A lease can prove who actually owns it right now.
How Raft turns the control plane into a source of truth
Splitter uses Hashicorp Raft to persist mutations and keep the coordinator consistent. The finite state machine applies updates, deletes, and restores into an in-memory cache, then the read path waits behind a barrier so the leader does not serve stale state after a transition.
That is the subtle move that separates a serious control plane from a casual one. It is not enough to store state. The leader has to know it is caught up before it answers with authority.
1. Mutation enters the Raft log
2. FSM applies the change to cache
3. Snapshot captures durable state
4. Barrier waits for committed logs
5. Leader serves read only after catch-up
6. Worker renews lease against current truthWhy region-aware placement changes the game
Regional domains make Splitter useful beyond a single cluster room. If the work belongs near a geography, the control plane can pin it there. That is a latency story, but it is also an operational one, because locality is part of the contract.
This is where the repository stops looking like a clever sharding toolkit and starts looking like platform infrastructure. It knows that not all shards are equal, and not all failure domains should be treated the same way.
| Domain type | Placement rule | Operational meaning |
|---|---|---|
| UNIT | One atomic shard or work item | Simple authority for a single unit |
| GLOBAL | Shards spread across the cluster | Any worker can participate if leased |
| REGIONAL | Shards pinned to a region | Ownership respects locality and latency |
Fast activation is the kind of tradeoff only a control plane can expose
The repository includes a fast activation option that skips the recovery period and comes up sooner, at the cost of safety. That is not a casual flag. It is a sign the system is designed by people who understand the operational pressure of cold starts and failovers.
Good infrastructure does not hide the tradeoff. It makes the tradeoff explicit, so operators can choose the right failure mode for the moment they are in.
| Startup mode | What you gain | What you risk |
|---|---|---|
| Safe recovery | Correct state before serving | Slower activation |
| Fast activation | Quicker availability | Possible unsafe startup state |
Where Splitter fits in the landscape
Splitter does not replace every sharding tool. Consistent hashing is still fine for stateless distribution. Simple leader election is still fine for narrow coordination. Manual assignment is still useful in emergencies.
But Splitter solves a different class of problem. It exists when ownership itself is the product, when the system must decide who is allowed to touch a shard, and when that decision has to survive failover, region boundaries, and operator mistakes.
| System | Primary strength | Primary limitation |
|---|---|---|
| Consistent hashing | Low-friction placement | Weak ownership semantics |
| Ad hoc service discovery | Simple wiring | No durable shard contract |
| Homegrown election + local state | Quick to prototype | Hard to make safe at scale |
| Splitter | Exclusive, observable shard control | More moving parts by design |
What this repository signals about the team behind it
The codebase looks like real infrastructure, not a demo. Go, gRPC, Protobuf, Bazel, OpenTelemetry, Prometheus, and Raft all point to a team that cares about operability as much as algorithmic correctness.
The deeper signal is the model layer. Tenants, domains, shards, sessions, and regions are not bolted on later. They are the shape of the product. That usually means the project came from a painful internal need, then was polished enough to share.
