{"id":50720340,"url":"https://github.com/cntryl/fitz","last_synced_at":"2026-06-09T23:30:19.708Z","repository":{"id":359978694,"uuid":"1088804134","full_name":"cntryl/fitz","owner":"cntryl","description":"Unified broker for KV, queue, notice, RPC, lease, stream, and schedule messaging patterns.","archived":false,"fork":false,"pushed_at":"2026-06-08T16:38:52.000Z","size":7141,"stargazers_count":2,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-08T18:24:21.001Z","etag":null,"topics":["event-driven","key-value-store","message-broker","pubsub","queue","rpc","rust","scheduler","stream-processing","tcp","websocket"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cntryl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap/admin-troubleshooting-roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-03T13:33:45.000Z","updated_at":"2026-06-08T16:40:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cntryl/fitz","commit_stats":null,"previous_names":["cntryl/fitz"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/cntryl/fitz","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cntryl%2Ffitz","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cntryl%2Ffitz/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cntryl%2Ffitz/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cntryl%2Ffitz/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cntryl","download_url":"https://codeload.github.com/cntryl/fitz/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cntryl%2Ffitz/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34130641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["event-driven","key-value-store","message-broker","pubsub","queue","rpc","rust","scheduler","stream-processing","tcp","websocket"],"created_at":"2026-06-09T23:30:18.552Z","updated_at":"2026-06-09T23:30:19.700Z","avatar_url":"https://github.com/cntryl.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fitz\n\nFitz is a broker project for teams that need one place to handle common application messaging patterns.\n\n## What Problem Fitz Solves\n\nMany systems end up running separate tools for:\n\n- request response traffic\n- queue workloads\n- event fanout\n- stream style delivery\n- key value coordination data\n\nThat increases operational overhead, client complexity, and integration drift across services.\n\nFitz is intended to provide a single broker surface for these patterns so teams can start with one deployment model and one client contract.\n\n## What Fitz Should Be\n\nFitz should be:\n\n- simple to start locally and in containers\n- explicit about durability and failure behavior\n- predictable to operate with health probes and metrics\n- practical to adopt from multiple client languages\n\nIt currently exposes HTTP and WebSocket on 4090, TCP framed traffic on 4091, and domain surfaces for KV, queue, notice, RPC, lease, stream, and schedule.\n\nCurrent status: early prototype.\n\n## Quick Start\n\n### Option 1: Docker Run\n\n1. Start Fitz from GHCR with auth disabled for local onboarding:\n\n\t\tdocker run --rm -p 4090:4090 -p 4091:4091 -e FITZ_AUTH_REQUIRED=false -e RUST_LOG=info,fitz=trace ghcr.io/cntryl/fitz:latest\n\n2. Verify basic health from another terminal:\n\n\t\tcurl http://localhost:4090/healthz\n\nExpected result: HTTP 200 with a small JSON status response.\n\n### Option 2: Docker Compose\n\nThe repository includes [compose.yml](compose.yml) with two services:\n\n- fitz-auth: auth required on 4090 and 4091\n- fitz-anon: auth disabled on 4190 and 4191\n\nThe compose file also configures admin auth for the local UI and admin API. Use these credentials when signing in:\n\n- Username: `admin`\n- Password: `pwd123`\n\nRun both:\n\n\t\tdocker compose up --build\n\nIf you want to use published images only, use a compose file that sets `image: ghcr.io/cntryl/fitz:latest` and removes `build`.\n\nQuick checks:\n\n\t\tcurl http://localhost:4090/healthz\n\t\tcurl http://localhost:4190/healthz\n\nStop:\n\n\t\tdocker compose down\n\n### Option 3: Cloud Storage With Peas\n\n[compose.cloud.yml](compose.cloud.yml) starts the same two Fitz brokers against the Peas emulator. This compose file is local-emulator-only and defaults to the S3-compatible Peas front door:\n\n\t\tdocker compose -f compose.cloud.yml up --build\n\nPeas provider flips stay in a compose-only environment variable:\n\n\t\tFITZ_PEAS_PROVIDER=peas-azure docker compose -f compose.cloud.yml up --build\n\t\tFITZ_PEAS_PROVIDER=peas-gcs docker compose -f compose.cloud.yml up --build\n\nPeas uses `http://peas:9000` inside compose and publishes `http://127.0.0.1:9000` for local host tests. The default namespace is `fitz`, with access key `admin` and secret `easy-peasy`. Real cloud providers use explicit `FITZ_STORAGE_MODE=cloud` plus `FITZ_STORAGE_PROVIDER=...` runtime env instead of this Peas compose file.\n\n### Minimal Compose Example\n\nIf you want a single local service, this is the smallest useful compose file:\n\n\t\tservices:\n\t\t\tfitz:\n\t\t\t\timage: ghcr.io/cntryl/fitz:latest\n\t\t\t\tports:\n\t\t\t\t\t- \"4090:4090\"\n\t\t\t\t\t- \"4091:4091\"\n\t\t\t\tenvironment:\n\t\t\t\t\tFITZ_AUTH_REQUIRED: \"false\"\n\t\t\t\t\tFITZ_STORAGE_MODE: \"local\"\n\t\t\t\t\tFITZ_STORAGE_PATH: \"/data\"\n\t\t\t\t\tRUST_LOG: \"info,fitz=trace\"\n\n## Endpoints\n\n- HTTP root and static UI: http://localhost:4090/\n- WebSocket endpoint: ws://localhost:4090/ws\n- TCP endpoint: localhost:4091\n- Health probes: /healthz, /readyz, /startupz\n- Metrics: /metrics\n\n## Configuration Notes\n\n- FITZ_AUTH_REQUIRED defaults to true.\n- FITZ_ROUTE_FAMILIES defaults to `1`. Configure a non-empty contiguous list starting at `1`, such as `1,2,3`, before startup.\n- FITZ_STORAGE_MODE can be set to `memory`, `local`, or `cloud`.\n- FITZ_STORAGE_PATH is only for local disk storage and defaults to `./.fitz`.\n- FITZ_STORAGE_MEMTABLE_BYTES optionally sets Midge's runtime memtable size and flush threshold in bytes. Lower values make SST flushes happen sooner for diagnostics and constrained environments.\n- Cloud storage requires FITZ_STORAGE_PROVIDER plus provider-specific values. Supported providers are `peas-s3`, `peas-azure`, `peas-gcs`, `aws-s3`, `s3-compatible`, `minio`, `wasabi`, `oci-s3`, `azure-blob`, and `gcs`.\n- Cloud storage uses FITZ_STORAGE_CACHE_PATH for its local cache and defaults to `./.fitz-cloud-cache`; it does not read FITZ_STORAGE_PATH.\n- FITZ_STORAGE_CLOUD_DURABILITY can be `background` or `strict`; any other value is rejected. `background` keeps provider upload asynchronous; `strict` waits for provider acknowledgement for broker-selected durable cloud writes and request-level sync writes.\n- Authenticated JWTs resolve to a route family server-side. Keep `FITZ_ROUTE_FAMILIES=1,2,...` as the provisioned allowlist, set `FITZ_ROUTE_FAMILY_MAP=tid-value=1,other=2`, and use `FITZ_ROUTE_FAMILY_CLAIM` to choose the identity claim (`tid` by default, `org_id` is recommended for Auth0 Organizations).\n- `FITZ_AUTH_CUSTOM_CLAIM` can point at a namespaced JWT object containing only `permissions`, for example `https://example.com/fitz`.\n- `FITZ_AUTH_ROLE_CLAIM` defaults to `roles` and is only used when that claim's array values are already direct Fitz permissions or recognized coarse scopes.\n- Permission normalization is fixed: configured custom permission claim, top-level `permissions`, configured role claim array, `scp`, then `scope`.\n- Provider setup is claim-driven: Auth0 uses `org_id` plus top-level `permissions`; Entra delegated uses `tid` plus `scp`; Entra app-only uses `tid` plus `roles`; Cognito uses `custom:tenant_id` or `sub` plus `scope`; Okta uses an exact custom or namespaced identity claim plus `scope`, a configured custom permissions claim, or a configured role claim array.\n- FITZ_MIN_MEMORY_BYTES defaults to `134217728` and rejects smaller Linux cgroup memory limits during startup. Set it higher for production headroom, or set it to `0` only when intentionally bypassing the preflight for experiments.\n\n## Documentation\n\n- Full docs index: [docs/README.md](docs/README.md)\n- Architectural laws: [docs/development/architectural-laws.md](docs/development/architectural-laws.md)\n- Client protocol spec: [docs/clients/client-spec.md](docs/clients/client-spec.md)\n- User onboarding guides: [docs/user-guides](docs/user-guides)\n- Auth0 setup: [docs/user-guides/auth0.md](docs/user-guides/auth0.md)\n- Operations guides: [docs/operations](docs/operations)\n- Local perf loop runner: [docs/development/perf-loop.md](docs/development/perf-loop.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcntryl%2Ffitz","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcntryl%2Ffitz","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcntryl%2Ffitz/lists"}