Home

Felix

Engineering documentation for Felix, generated from the docs/ directory in the repository.

This is not the user-facing documentation. For getting started, client guides, deployment and configuration reference, see the published site: https://gabloe.github.io/felix/. This wiki covers the engineering design and investigation notes behind the code — the audience is someone reading or changing the implementation, not someone using it.

Every page here is generated from a file in docs/ and says so at the bottom, with a link to that file. The file in the repo is the source of truth. If this page and the repo disagree, the repo is right, and this page is due for a refresh.

Architecture & Design

What Felix is and how its pieces fit together.

• Broker-internal forwarding protocol
• Felix Architecture
• Felix Wire Protocol (v1)
• Felix semantics
• Felix – Comprehensive Design Document

Storage & Replication

The append-only log, its on-disk format, and how records reach a majority.

• Durable Storage
• Durable Storage Performance
• Felix Durable Segment Format (v2)
• One core log, many semantics
• Plan: group-commit the cache write path
• Shard replication and leader failover
• The cache is a projection over the log

Control Plane & Cluster

Placement, Raft-backed metadata, and the harness used to test cluster behavior locally.

• A formal model of one shard
• Control Plane + RAFT Plan (Draft)
• Metadata Raft
• Subscribe routing: redirect, not proxy
• The Postgres the control plane requires
• The local cluster harness

Clients & Configuration

Talking to a broker or a cluster, and the knobs each side exposes.

• Auth Design: OIDC Exchange + Felix Tokens
• Broker Config Examples
• Client Config
• Running a client against a cluster

Security

Bootstrap, RBAC, and the internal-surface threat model.

• Bootstrap security
• Panic and abort audit — broker data path
• RBAC Model (Control Plane)
• Soak and resource-leak report — broker
• Threat model: the broker-internal surface

Performance Investigations

Session-by-session records of what was measured, ruled out, and found.

• Real-network performance suite
• Sharding investigation: keyed publishes, io_uring, and a ceiling that would not move
• The 0.4.0 performance matrix
• Throughput investigation: why Felix is slower than raw QUIC

Explorations & History

Spikes, demo write-ups, and the original MVP plan.

• A Kafka wire shim: what it would take, and what it would buy
• Felix Demos
• Felix MVP To-Do List