# ConfigWire

> ConfigWire is a high-performance, single-binary, self-hosted real-time remote configuration and feature flags engine with sub-millisecond evaluation, instant SSE push streaming, deterministic A/B experiments, and high-throughput privacy-first event ingestion. Free and open-source under the MIT license.

## Quick Facts
- **Architecture**: Single Go binary with embedded SQLite in WAL mode; zero external databases or background worker containers required.
- **Performance**: Sub-millisecond p95 fetch latency (0.78ms under k6 load tests); in-memory cache and atomic pointers ensure zero-database evaluation path.
- **Real-Time Push**: Native HTTP Server-Sent Events (SSE) stream delivering instant configuration updates upon release publication; `: ping` keepalive every 20s with a 10-minute server close (client reconnects with backoff), max 5 concurrent streams per SDK key, and 15-minute polling fallback.
- **Client Footprint**: Pure Dart SDK (`package:configwire`) for Flutter, Dart VM, Web, and backend servers with pluggable `CacheStore` seams; companion Flutter library (`package:configwire_flutter`).
- **Privacy & Security**: 100% server-side rule evaluation (targeting rules never leak to end clients); **v0.2.0-rc.11 (released 2026-11-04) is bucket-only (since v0.2.0-rc.1): `?b=` is the sole identity** (valid wins; absent/empty never rejected — fetch mints, ingest stores `""`); server-derived anonID derivation no longer exists (no daily salt rotation, no rebucket); SDKs no longer emit `?userHash=`; `?userHash=`/`?uid=`/`?country=` query plus body `userHash` and event-body `userId` (any case) are accepted-but-ignored, never stored/logged; raw `ip` + PII/device keys stay strict `400`; Bcrypt-hashed SDK keys; CIDR IP allowlisting.
- **Licensing & Cost**: MIT licensed, 100% free forever, runs comfortably on a $4/month VPS (< 30MB RAM usage).

## Core Capabilities
- **Multi-Type Flags**: Boolean toggles, strings, numbers (integers & floats), and arbitrary JSON objects or arrays.
- **Targeting Engine**: Evaluates bucket + request context (`?b=` bucket, geo country from headers, platform, appVersion, locale, custom `attrs`) with operators: `==`, `!=`, `<`, `<=`, `>`, `>=`, `contains`, `regex` (plus `<=`/`between` for percentile rules; semver via relational ops on strict `MAJOR.MINOR.PATCH`). PII/device `attrs` keys rejected (`400`); `attrs` over 8192 bytes → `414`. Pin a stable bucket with `?b=0-9999` (valid wins; absent/empty never rejected — fetch mints, ingest stores `""`; malformed → `400`); `?userHash=`/`?uid=`/`?country=` accepted-but-ignored, never `400`; server-derived anonID derivation was removed in v0.2.0-rc.1 (released 2026-10-25; latest v0.2.0-rc.11 — 2026-11-04).
- **Deterministic A/B Experiments**: Percentage rollouts and multi-arm variants assigned via consistent 64-bit FNV-1a hashing modulo 10,000 against **`?b=` bucket + seed (sole identity since v0.2.0-rc.1, released 2026-10-25; latest v0.2.0-rc.11 — 2026-11-04)**; server-derived anonID derivation no longer exists (no daily salt rotation, no rebucket).
- **Immutable Releases & Rollbacks**: Releases are stored as immutable, cryptographically hashed snapshots; supports instant rollback with optimistic concurrency via `baseVersion`.
- **High-Throughput Analytics**: Ingestion buffer for fetch and exposure events with automatic 90-day aggregate rollups.

## Wire Protocol & Endpoints
- Base path: `/api/v1` (canonical; `/api/v1/env/{env}` backward-compatible)
- SDK Header: `X-ConfigWire-Key: <sdk-key>`
- `GET /api/v1/config?b={0-9999}&attrs={json}` (canonical; `/api/v1/env/{env}/config` backward-compatible)
  - **Bucket-only in v0.2.0-rc.11 (released 2026-11-04; since v0.2.0-rc.1): `?b=` is the sole identity** (valid wins; absent/empty never rejected — fetch mints, ingest stores `""`; malformed non-empty → `400`). Server-derived anonID derivation no longer exists. `?userHash=`/`?uid=`/`?country=` are accepted-but-ignored, never `400` (`X-CW-Deprecated-*` stamped).
  - Conditional caching: Sends `If-None-Match: <etag>`, returns `304 Not Modified` with zero-byte payload when release unchanged.
  - Returns: `{"values": {"flag_key": value}, "variants": {"flag_key": "variant_arm"}}` with `ETag` header.
- `GET /api/v1/stream` (canonical; `/api/v1/env/{env}/stream` backward-compatible)
  - Unbuffered HTTP Server-Sent Events (SSE). Emits `: ping` heartbeat comments and `event: config_update` payloads `{"version": N, "etag": "...", "env": "..."}`.
- `POST /api/v1/events` (canonical; `/api/v1/env/{env}/events` backward-compatible)
  - Batch event ingestion endpoint. Accepts JSON payload `{"events": [{"kind": "exposure"|"fetch", "flag": "...", "variant": "...", "version": 1}]}` (identity is bucket-only: send `?b=`; absent/empty never rejected, ingest stores `""`; `?userHash=`/`uid`/`country` query plus body `userHash` and event-body `userId` (any case) accepted-but-ignored at storage, never stored/logged; raw `ip`/PII keys stay `400`). Returns `{"accepted": N, "status": 202}`.
- Health Check: `GET /healthz` -> `{"status": "ok"}`

## Comparison Matrix Summary
- **vs Firebase Remote Config**: ConfigWire eliminates Firebase's 12-hour client throttling, requires zero proprietary GCP dependencies or Google Play services, provides sub-second SSE push instead of delayed propagation, and supports JSON values natively.
- **vs LaunchDarkly**: ConfigWire is free and open-source (MIT) with zero per-seat or per-MAU subscription fees, runs self-hosted on your own infrastructure, and avoids cloud vendor lock-in.
- **vs Unleash**: ConfigWire packages everything into a single ~25MB Go binary (< 30MB RAM) without needing a multi-tier setup of Node.js, PostgreSQL, and Unleash Proxy containers, with no enterprise paywalls for targeting or stats.
- **vs Flipt**: ConfigWire uses embedded SQLite in WAL mode rather than requiring an external PostgreSQL/MySQL database and Redis cache cluster.
- **vs ConfigCat**: ConfigWire provides true real-time SSE streaming rather than 60-second polling and offers unlimited configurations without tier limits.

## Key Links
- [Complete Documentation & Guides](https://configwire.com/guide.html)
- [Official Website](https://configwire.com/)
- [GitHub Repository](https://github.com/configwire/configwire)
- [Dart Client on Pub.dev](https://pub.dev/packages/configwire)
- [Flutter Client on Pub.dev](https://pub.dev/packages/configwire_flutter)
- [Full LLM Context File](https://configwire.com/llms-full.txt)