Felix 0.3.0
Released 2026-09-15. The full history is in CHANGELOG.md.
The composed-semantics release. A cache stopped being something you can only poll: you can subscribe to a key, join with current state already in hand, and fold deltas into durable sums. These compose because each one is a reading of the same log. A consumer group now survives failover whole: the dead-letter list travels with the shard along with the cursor.
No wire-protocol break. felix-wire VERSION remains 1. Every new
capability is a negotiated feature bit (FEATURE_CACHE_WATCH,
FEATURE_CACHE_WATCH_RETAINED, FEATURE_COUNTERS). A 0.2.0 client and a
0.3.0 broker interoperate byte-for-byte on everything they both know, and a
client never sends a request the broker did not advertise. The internal
broker-to-broker protocol grew six message kinds (16–21), which is how that
protocol evolves; an older peer answers an unknown kind with a typed refusal
rather than a misparse.
- Keyed cache watch (#348).
cache_watchsubscribes to one key or key prefix; every applied write is delivered in the shard’s write order with its log offset, deletes included as tombstoned changes. Resume by offset replays from the cache’s log and joins live delivery with no gap and no duplicate, which is tested under concurrent writes at join time. An offset compaction has collapsed is answered with a marked snapshot of current values (resnapshot), never a silent gap. A watch that falls behind is ended loudly withcache_watch_laggednaming the first missed offset (filtered offsets are sparse, so a drop could never be read from an offset jump), and re-watching from that offset is gapless. - Retained delivery on a watch (#349). Ask for
retainedand receive each matching key’s current value first, at the offset of the write that produced it, then live changes: join a presence roster and hold it immediately, no polling.retained_countmakes “your state is now complete” an explicit moment, and joining an empty key a definite zero instead of a silence. Survives failover: a promoted replica serves the retained value from its rebuilt index, at the original offset. - Counters (#350).
counter_addappends a signed delta and answers with the sum including it, so one round trip increments and tells you where you stand. Scoped and routed exactly like cache keys, stored beside the cache (a counter and a cache value sharing a key are unrelated). The sum survives restart, compaction (which collapses applied deltas into a checkpoint without renumbering the log), and leader failover, where the promoted replica folds the true sum from its shipped log and keeps counting. At-least-once: a retried add after a lost acknowledgement double-counts; the decision and its failure mode are recorded indocs/projections.md. - The dead-letter list replicates with its shard (#362). Group state now fails over whole: a promoted leader resumes each group where it had reached and lists what it had given up on, and an operator’s redrive works there. Before this, promotion silently forgot exactly the records an operator had been told to look at. Entries recorded under the earlier on-disk layout are still listed and discardable.
- Client API:
watch_cache/watch_cache_retained(typedLaggedandresnapshotsurfaces),counter_add/counter_get, each feature-gated on the broker’s advertisement before anything is sent.
- A publish forwarded between brokers now lands on the shard it was routed for (#356).
- Control-plane readiness is proven against a database that can fail (#358), and the rolling-restart and Raft-chaos test harnesses retry a dead connection against a re-probed rotation instead of a stale snapshot (#359, #364), which is the load-balancer behaviour they model.
Known limitations
Section titled “Known limitations”- A prefix watch reads one shard; watching a whole multi-shard cache means one watch per shard, with no client helper yet.
- Counters carry no dedupe identity, so retried adds can double-count, and a cache watch does not see counter changes.
- A cache still declares no consistency level: its writes carry the
Leaderguarantee, notQuorum.
The status table (https://gabloe.github.io/felix/getting-started/what-felix-is-for/) remains the per-capability source of truth.
