Felix 0.2.0
Released 2026-09-07. The full history is in CHANGELOG.md.
Durable streams. A stream registered with durable: true now persists every
record before acknowledging it, replays it after a restart, and lets a
subscriber resume from an exact offset.
No wire-protocol break. felix-wire VERSION remains 1. The new
capabilities are negotiated flag bits, so a 0.1.1 client and a 0.2.0 broker
still interoperate: they agree on the original flag set. Negotiating
capabilities instead of bumping a version is what makes this work.
Durable storage is opt-in and off by default. Nothing persists unless the
broker is started with FELIX_DURABLE_STORAGE_DIR and the stream is
registered durable. The on-disk format is version 2; there is no version 1 to
migrate from, because durable storage did not exist in 0.1.1.
Clustering is not in this release. It contains broker membership plumbing (brokers can register, heartbeat, and appear in a control-plane listing), but nothing routes across brokers. A client still talks to one broker and gets exactly what it got in 0.1.1. See Known limitations below.
- Durable single-node log. A log-structured segment store behind the broker:
records are never rewritten, a torn tail is repaired on startup while interior
corruption refuses to start, and indexes are derived rather than trusted.
Group commit means one device flush serves many appends. Configured with
FELIX_DURABLE_STORAGE_DIR,FELIX_DURABLE_SEGMENT_BYTES, and the fsync policy (none,periodic,on_commit). (#173, #174) - Resumable subscriptions over the wire.
Subscribecarries an optionalstart:latest(the default, and what every older client sends),earliest, or an exact offset. Every delivered event carries its offset. History read from disk joins live delivery with no gap and no duplicate. Asking for an offset retention has discarded is a typed error, not a silent restart at the tail. (#197) - Retention on durable logs.
FELIX_DURABLE_RETENTION_BYTESandFELIX_DURABLE_RETENTION_SECONDSbound a stream’s growth by deleting the oldest sealed segments. Unset means unbounded, which remains the default. (#203) - Capability negotiation for stream authentication. A client offers
Auth.client_flagsand the broker answersAuthOk.server_flags. A peer that predates negotiation exchanges a plainOk, and the only safe reading of that silence is the original flag set. (#170) - Binary publish acknowledgements, so an acked publish no longer pays for a JSON round trip. (#167)
- Broker cluster membership (control plane only, see Known limitations):
a Node resource model, membership persisted in both stores with an ordered
changefeed, heartbeat and liveness expiry, broker-side registration and
graceful deregistration, an operator listing at
GET /v1/nodes, and Prometheus metrics for the fleet. (#218, #219, #220, #221, #222, #223) - Documentation site migrated from MkDocs to Astro Starlight, with the durable segment format, storage performance, and delivery semantics written up. (#165, #166, #169, #174)
- Demos for lossy and lossless state settlement and for slow-consumer isolation. (#163)
- Lossless publishing was not lossless end to end. (#171)
- The backlog-to-live handoff dropped records. Reading history before registering a subscriber loses any publish landing in between; the handoff is now ordered so it cannot. (#191)
- A failed rollover is now terminal. A rollover fails on a failed fsync or a failed file creation, and both mean the log can no longer honour what it has already acknowledged. It rejects further appends rather than continuing quietly. (#196)
- An inline rollover no longer parks every Tokio worker. The segment set is behind a synchronous lock; held across a rollover’s device flushes it stalled everything else on the runtime. It also stopped appends being rejected outright under rollover contention: six runs in twenty became zero in twenty. (#217)
- Record header checksums (format v2), plus cancellation, startup, and hydration defects found in review. (#178)
- MTU black-hole collapse on Linux, where a path MTU below the probed size silently destroyed throughput. Acked publishes are now pipelined. (#200, #202)
- Durability, ordering, and recovery defects from successive reviews of the durable log. (#176, #179, #180)
- Cursor identity is pinned to disk offsets, and the broker proves its catalog seeded before reporting ready. (#180)
Changed
Section titled “Changed”- An fsync was cut from the rollover path. A freshly created and therefore
empty index file was being flushed. Median p999 on the default inline path
improved from 5.12ms to 3.98ms (−22%), and max from 61.8ms to 47.0ms (−24%).
Background rollover was added alongside it and ships disabled, because it
measured worse:
F_FULLFSYNCdoes not overlap with concurrent writes, so moving a rollover’s flushes off the append lock stops confining them rather than hiding them. (#192) - Performance is now measured on a Linux 16 vCPU VM in addition to macOS, since the two platforms’ fsync semantics differ enough to invert a result. (#201)
Dependencies
Section titled “Dependencies”opentelemetry0.31.0 → 0.32.0,opentelemetry-otlp0.31.1 → 0.32.0,opentelemetry_sdk0.31.0 → 0.32.1,tracing-opentelemetry0.32.1 → 0.33.0. These four are version-locked to each other and have to move together.sqlx0.8.6 → 0.9.0. ItsSqlSafeStrbound meanssqlx::querynow takes only&'static str, so dynamic statements needAssertSqlSafeand a reason.base640.22 → 0.23,bytes1.11 → 1.12,dashmap6.1 → 6.2,uuid1.21 → 1.24,socket20.6.2 → 0.6.5,rcgen0.14.7 → 0.14.9,metrics0.24.3 → 0.24.6,serde_json1.0.149 → 1.0.151.h2→ 0.4.16 for RUSTSEC-2026-0258.
Known limitations
Section titled “Known limitations”- No clustering. The membership endpoints added here are a registry. No traffic crosses a broker, brokers do not talk to each other, and there is no sharding, replication, or failover. Placement lands in M3, cross-broker forwarding in M4.
- The membership endpoints are not authenticated. Registration, heartbeat, drain, and deregister accept any caller that can reach them; only the operator read endpoints require a token. Safe on a trusted network, not on an open one. Tracked in #126.
- At-most-once delivery. Slow subscribers drop under the default policy. Durable streams make the record recoverable (a subscriber can resume from an offset), but nothing redelivers automatically.
- Single-region, single control-plane instance.
Upgrading from 0.1.1
Section titled “Upgrading from 0.1.1”No code changes are required, and no configuration becomes mandatory. Every addition above is opt-in.
- 0.1.1 clients work against a 0.2.0 broker unchanged. Capabilities are negotiated, so an older client simply does not offer the new flags.
- Durable storage stays off until
FELIX_DURABLE_STORAGE_DIRis set. Setting it is not sufficient on its own: a stream must also be registereddurable: true. - If you do enable durable storage, decide the fsync policy deliberately.
periodic(the default) bounds loss to one interval;on_commitloses nothing acknowledged and costs milliseconds per publish. segment_size_bytesis a latency knob as well as a recovery knob. Below a few MiB, tail latency is dominated by rollover flushes. Prefer the 256 MiB default unless restart time is really the binding constraint, and measure the tail if you change it.
