fitz

Fitz is a container-friendly application broker that exposes seven communication and state primitives through one active broker process and one route model per storage namespace.

Each storage namespace has one active writer. Independent workloads can use separate deployments and namespaces.

What Fitz Provides

Fitz combines streams, queues, live fanout, RPC, KV, leases, and schedules behind one broker process. Each domain has its own persistence, disconnect, and restart semantics.

Domain	Use it for	Durability model
Notice	live fanout to connected subscribers	ephemeral
Stream	durable append and replay of committed history	durable according to write mode
KV	current authoritative state	durable on commit according to write mode
Queue	work delivery with reservation and redelivery	best-effort persistence; crash loss is possible
RPC	live request and response dispatch to registered workers	ephemeral
Lease	single-broker ownership coordination	ephemeral
Schedule	durable future timing intent	durable definitions and pending fire claims

Durable paths use Midge-backed persistence. Local storage writes to disk. Blob/object-backed storage uses a local cache plus provider storage, so durable state that has reached the configured cloud durability barrier can outlive and be recovered by a replacement broker process. A storage writer lease ensures only one process at a time owns a storage namespace. Each domain's contract and selected write policy determine which commits are durable.

Deployment Tradeoffs

Each storage namespace has one active writer. A replacement process can recover persisted state after it acquires the storage lease. An ungraceful failure may delay that handoff while the lease expires. Clients reconnect and rebuild ephemeral session state.

Assign independent workloads or partitions to separate Fitz deployments, each with its own storage namespace and local cache. Application routing owns that assignment; Fitz does not automatically shard one logical broker across processes. RouteFamily remains an isolation boundary within a deployment, not a cross-process shard selector.

Fitz does not form a multi-node consensus cluster or provide a clustered high-availability mode. Process replacement can interrupt traffic; it does not provide:

• zero-downtime or transparent failover during process replacement
• session recovery after disconnect
• exactly-once delivery
• durable live subscription recovery
• durable RPC pending work
• crash-safe lease ownership

Sessions are ephemeral. Disconnect creates a new session, and clients must rebuild subscriptions, workers, leases, transactions, and Stream resume positions explicitly.

Quick Start

Run an anonymous local broker:

docker run --rm \
  -p 4090:4090 \
  -p 4091:4091 \
  -p 9090:9090 \
  -e FITZ_AUTH_REQUIRED=false \
  -e FITZ_STORAGE_MODE=local \
  -e FITZ_STORAGE_PATH=/data \
  ghcr.io/cntryl/fitz:latest

For a reproducible deployment, use an immutable SemVer image published by the repository release process.

Check readiness:

curl http://localhost:4090/healthz

For repository-local development:

docker compose up --build

The compose file starts an authenticated broker on 4090/4091 and an anonymous broker on 4190/4191. These defaults are for local development: ports are loopback-bound, the admin surface is local, and the authenticated broker uses the shared HS256 dev secret dev-test-secret.

Provider-specific development profiles use the Sqrzl storage emulator:

docker compose -f compose.s3.yml up --build       # S3-compatible emulator
docker compose -f compose.azure.yml up --build    # Azure Blob emulator
docker compose -f compose.gcs.yml up --build      # GCS emulator

Each profile starts local brokers and a provider-compatible storage emulator. See the compose files for ports and credentials.

Runtime Surfaces

• HTTP root and admin UI: http://localhost:4090/
• WebSocket data plane: ws://localhost:4090/ws
• TCP data plane: localhost:4091
• Probes: /livez, /targetz, /startupz, /healthz, /readyz
• Prometheus metrics: http://localhost:9090/metrics on the dedicated unauthenticated listener
• Authenticated structured metrics: /api/v1/{family}/metrics (wildcard admins use /api/v1/all/metrics)

Deployment Configuration

Use these references to configure and operate a Fitz process:

• Storage: docs/operations/cloud-setup.md
• Operator guide: docs/operations/operator-guide.md
• Auth and browser perimeter: docs/operations/auth-browser-deployment.md
• Probes and metrics: docs/operations/observability.md
• Operations runbook: docs/operations/operations-runbook.md
• Environment variables: docs/user-guides/vars.md

Important defaults:

• FITZ_AUTH_REQUIRED defaults to true.
• FITZ_ROUTE_FAMILIES defaults to 1; configure a contiguous allowlist such as 1,2,3 before serving multiple isolated families.
• FITZ_STORAGE_MODE accepts memory, local, or cloud.
• Queue is for regenerable or loss-tolerant work. Accepted enqueues and ACKs can be lost before background persistence completes, so an enqueue response is not a durable commit.
• FITZ_STORAGE_CLOUD_DURABILITY accepts background or strict for broker-selected durable cloud writes.

Documentation

Use docs/README.md as the documentation index.

Start here:

• docs/user-guides/overview.md
• docs/user-guides/quick-start.md
• docs/user-guides/api-guide.md
• docs/development/domain-boundaries-spec.md
• docs/clients/client-spec.md