{"id":45436872,"url":"https://github.com/faiscadev/fila","last_synced_at":"2026-04-01T17:48:32.707Z","repository":{"id":337746678,"uuid":"1155042149","full_name":"faiscadev/fila","owner":"faiscadev","description":"A message broker where fair scheduling and per-key throttling are first-class primitives.","archived":false,"fork":false,"pushed_at":"2026-03-03T20:29:50.000Z","size":1732,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T00:30:21.699Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/faiscadev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-11T03:54:01.000Z","updated_at":"2026-03-03T20:28:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/faiscadev/fila","commit_stats":null,"previous_names":["faiscadev/fila"],"tags_count":20,"template":false,"template_full_name":null,"purl":"pkg:github/faiscadev/fila","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faiscadev%2Ffila","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faiscadev%2Ffila/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faiscadev%2Ffila/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faiscadev%2Ffila/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/faiscadev","download_url":"https://codeload.github.com/faiscadev/fila/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faiscadev%2Ffila/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30236260,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T23:09:55.450Z","status":"ssl_error","status_checked_at":"2026-03-07T23:00:57.737Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-02-22T03:14:16.395Z","updated_at":"2026-04-01T17:48:32.699Z","avatar_url":"https://github.com/faiscadev.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fila\n\nA message broker that makes fair scheduling and per-key throttling first-class primitives.\n\n\u003e **Status:** Under active development. Not production-ready.\n\n## The problem\n\nEvery existing broker delivers messages in FIFO order. When multiple tenants, customers, or workload types share a queue, a single noisy producer can starve everyone else. Rate limiting is pushed to the consumer — which means the consumer has to fetch a message, check the limit, and re-enqueue it. That wastes work and adds latency.\n\nFila moves scheduling decisions into the broker:\n\n- **Deficit Round Robin (DRR) fair scheduling** — each fairness key gets its fair share of delivery bandwidth. No tenant starves another.\n- **Token bucket throttling** — per-key rate limits enforced at the broker, before delivery. Consumers only receive messages that are ready to process.\n- **Lua rules engine** — `on_enqueue` and `on_failure` hooks let you define scheduling policy (assign fairness keys, set weights, decide retry vs. dead-letter) in user-supplied Lua scripts.\n- **Zero wasted work** — consumers never receive a message they can't act on.\n\n## Quickstart\n\n### Option 1: Docker\n\n```sh\ndocker run -p 5555:5555 ghcr.io/faiscadev/fila:dev\n```\n\n### Option 2: Install script\n\n```sh\n# Download, inspect, then run:\ncurl -fsSL https://raw.githubusercontent.com/faiscadev/fila/main/install.sh -o install.sh\nless install.sh\nbash install.sh\nfila-server\n```\n\n### Option 3: Cargo\n\n```sh\ncargo install fila-server fila-cli\nfila-server\n```\n\n### Try it out\n\nOnce the broker is running on `localhost:5555`:\n\n```sh\n# Create a queue\nfila queue create orders\n\n# Enqueue a message (via any gRPC client — grpcurl shown here)\ngrpcurl -plaintext -d '{\n  \"queue\": \"orders\",\n  \"headers\": {\"tenant\": \"acme\"},\n  \"payload\": \"aGVsbG8=\"\n}' localhost:5555 fila.v1.FilaService/Enqueue\n\n# Check queue stats\nfila queue inspect orders\n```\n\n### Fair scheduling demo (under 5 minutes)\n\nCreate a queue with a Lua hook that assigns fairness keys from headers:\n\n```sh\nfila queue create fair-demo \\\n  --on-enqueue 'function on_enqueue(msg)\n    return { fairness_key = msg.headers[\"tenant\"] or \"default\" }\n  end'\n```\n\nEnqueue messages from two tenants — one sends 100x more than the other:\n\n```sh\n# Noisy tenant: 100 messages\nfor i in $(seq 1 100); do\n  grpcurl -plaintext -d \"{\\\"queue\\\":\\\"fair-demo\\\",\\\"headers\\\":{\\\"tenant\\\":\\\"noisy\\\"},\\\"payload\\\":\\\"$(echo -n msg-$i | base64)\\\"}\" \\\n    localhost:5555 fila.v1.FilaService/Enqueue\ndone\n\n# Quiet tenant: 5 messages\nfor i in $(seq 1 5); do\n  grpcurl -plaintext -d \"{\\\"queue\\\":\\\"fair-demo\\\",\\\"headers\\\":{\\\"tenant\\\":\\\"quiet\\\"},\\\"payload\\\":\\\"$(echo -n msg-$i | base64)\\\"}\" \\\n    localhost:5555 fila.v1.FilaService/Enqueue\ndone\n```\n\nNow consume. Fila's DRR scheduler interleaves delivery — the quiet tenant's messages aren't stuck behind all 100 of the noisy tenant's:\n\n```sh\nfila queue inspect fair-demo\n```\n\n## Key concepts\n\n| Concept | What it does |\n|---------|-------------|\n| **Fairness groups** | Messages are grouped by a `fairness_key`. The DRR scheduler gives each group its fair share of delivery bandwidth. |\n| **Throttling** | Token bucket rate limiters keyed by `throttle_keys`. The broker holds messages until tokens are available. |\n| **Lua hooks** | `on_enqueue` assigns fairness keys, weights, and throttle keys. `on_failure` decides retry vs. dead-letter. |\n| **Dead letter queue** | Messages that exhaust retries are moved to a `\u003cqueue\u003e.dlq` queue. Use `fila redrive` to move them back. |\n| **Runtime config** | Key-value pairs readable from Lua via `fila.get(key)`. Change behavior without restarting the broker. |\n| **Visibility timeout** | Consumed messages are \"leased\" for a configurable duration. If not acked, they're re-delivered. |\n\nSee [docs/concepts.md](docs/concepts.md) for a deep dive, [docs/tutorials.md](docs/tutorials.md) for guided walkthroughs, and [docs/lua-patterns.md](docs/lua-patterns.md) for copy-paste Lua scripts.\n\n## Performance\n\nSub-millisecond p50 enqueue-to-consume latency. DRR fair scheduling adds no measurable overhead vs FIFO. The benchmark suite includes self-benchmarks and competitive comparisons against Kafka, RabbitMQ, and NATS. See [docs/benchmarks.md](docs/benchmarks.md) for full results.\n\n## Client SDKs\n\n| Language | Package | Repository |\n|----------|---------|------------|\n| Rust | `fila-sdk` | [crates/fila-sdk](crates/fila-sdk) |\n| Go | `github.com/faiscadev/fila-go` | [faiscadev/fila-go](https://github.com/faiscadev/fila-go) |\n| Python | `fila` | [faiscadev/fila-python](https://github.com/faiscadev/fila-python) |\n| JavaScript | `@anthropic/fila` | [faiscadev/fila-js](https://github.com/faiscadev/fila-js) |\n| Ruby | `fila` | [faiscadev/fila-ruby](https://github.com/faiscadev/fila-ruby) |\n| Java | `dev.fila:fila-client` | [faiscadev/fila-java](https://github.com/faiscadev/fila-java) |\n\n## CLI\n\nThe `fila` CLI manages queues, configuration, and dead-letter redrives:\n\n```\nfila queue create \u003cname\u003e       Create a queue\nfila queue delete \u003cname\u003e       Delete a queue\nfila queue list                List all queues\nfila queue inspect \u003cname\u003e      Show queue stats and per-key breakdown\n\nfila config set \u003ckey\u003e \u003cvalue\u003e  Set a runtime config key\nfila config get \u003ckey\u003e          Get a runtime config value\nfila config list [--prefix p]  List all config entries\n\nfila redrive \u003cdlq\u003e --count N   Move messages from DLQ back to source queue\n```\n\nUse `--addr` to connect to a non-default broker address (default: `http://localhost:5555`).\n\n## Configuration\n\nFila reads `fila.toml` from the current directory or `/etc/fila/fila.toml`. All settings have sensible defaults — the broker runs with zero configuration.\n\n```toml\n[server]\nlisten_addr = \"0.0.0.0:5555\"\n\n[scheduler]\nquantum = 1000            # DRR quantum per fairness key\n\n[lua]\ndefault_timeout_ms = 10   # script execution timeout\ncircuit_breaker_threshold = 3\n\n[telemetry]\notlp_endpoint = \"http://localhost:4317\"  # optional\n```\n\nSee [docs/configuration.md](docs/configuration.md) for all options.\n\n## API\n\nFila exposes two gRPC services on the same port:\n\n**Hot path** (`fila.v1.FilaService`) — for producers and consumers:\n- `Enqueue` — add a message to a queue\n- `Consume` — server-streaming delivery of messages\n- `Ack` — acknowledge successful processing\n- `Nack` — reject a message (triggers `on_failure` hook)\n\n**Admin** (`fila.v1.FilaAdmin`) — for operators and the CLI:\n- `CreateQueue`, `DeleteQueue`, `ListQueues`\n- `SetConfig`, `GetConfig`, `ListConfig`\n- `GetStats` — queue depth, in-flight, per-key fairness stats\n- `Redrive` — move messages from DLQ back to source\n\nSee [docs/api-reference.md](docs/api-reference.md) for the full reference, and [docs/compatibility.md](docs/compatibility.md) for the versioning and compatibility policy.\n\n## Architecture\n\nFila uses a single-threaded scheduler core with multi-threaded I/O (inspired by Redis). The scheduler loop processes commands from a channel, making scheduling decisions without locks. gRPC handlers and consumer delivery run on tokio's thread pool and communicate with the scheduler through bounded channels.\n\nData is persisted in RocksDB with crash recovery on startup — no messages are lost.\n\n## Building from source\n\n### Prerequisites\n\n- Rust 1.75+ (stable)\n- `protoc` (protobuf compiler)\n- System libraries for RocksDB (usually installed automatically; on some systems you may need `libclang` and `cmake`)\n\n```sh\ncargo build\ncargo nextest run   # or: cargo test\n```\n\n## License\n\n[AGPLv3](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaiscadev%2Ffila","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaiscadev%2Ffila","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaiscadev%2Ffila/lists"}