{"id":36400014,"url":"https://github.com/macprog-guy/axum-conf-rs","last_synced_at":"2026-01-11T16:03:21.009Z","repository":{"id":331352188,"uuid":"1124933254","full_name":"macprog-guy/axum-conf-rs","owner":"macprog-guy","description":"Batteries included Rust services using tokio, axum and optionally postgres using configuration files.","archived":false,"fork":false,"pushed_at":"2026-01-05T13:27:18.000Z","size":606,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-06T20:36:40.631Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/macprog-guy.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":"audit.toml","citation":null,"codeowners":null,"security":"docs/security-audit.md","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":"2025-12-29T21:49:48.000Z","updated_at":"2026-01-05T13:27:17.000Z","dependencies_parsed_at":"2026-01-07T13:04:56.266Z","dependency_job_id":null,"html_url":"https://github.com/macprog-guy/axum-conf-rs","commit_stats":null,"previous_names":["macprog-guy/axum-conf-rs"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/macprog-guy/axum-conf-rs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macprog-guy%2Faxum-conf-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macprog-guy%2Faxum-conf-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macprog-guy%2Faxum-conf-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macprog-guy%2Faxum-conf-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/macprog-guy","download_url":"https://codeload.github.com/macprog-guy/axum-conf-rs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/macprog-guy%2Faxum-conf-rs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28312260,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T14:58:17.114Z","status":"ssl_error","status_checked_at":"2026-01-11T14:55:53.580Z","response_time":60,"last_error":"SSL_read: 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-01-11T16:03:20.942Z","updated_at":"2026-01-11T16:03:20.994Z","avatar_url":"https://github.com/macprog-guy.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# axum-conf\n\n[![codecov](https://codecov.io/gh/emethot/axum-conf/graph/badge.svg)](https://codecov.io/gh/emethot/axum-conf)\n[![Crates.io](https://img.shields.io/crates/v/axum-conf.svg)](https://crates.io/crates/axum-conf)\n[![Documentation](https://docs.rs/axum-conf/badge.svg)](https://docs.rs/axum-conf)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Production-ready web services with Axum — batteries included.**\n\nBuild Kubernetes-native Rust services without the boilerplate. axum-conf gives you health probes, metrics, security headers, rate limiting, and more — all configured through simple TOML.\n\n```\n                              axum-conf\n    ┌─────────────────────────────────────────────────────────┐\n    │                                                         │\n    │  ┌─────────────┐   ┌──────────────┐   ┌─────────────┐   │\n    │  │   Config    │──▶│ FluentRouter │──▶│  Middleware │   │\n    │  │   (TOML)    │   │   Builder    │   │    Stack    │   │\n    │  └─────────────┘   └──────────────┘   └─────────────┘   │\n    │                           │                             │\n    │                           ▼                             │\n    │  ┌─────────────────────────────────────────────────┐    │\n    │  │              Production-Ready Server            │    │\n    │  │  • Health probes  • Metrics  • Security headers │    │\n    │  │  • Rate limiting  • CORS     • Graceful shutdown│    │\n    │  └─────────────────────────────────────────────────┘    │\n    │                                                         │\n    └─────────────────────────────────────────────────────────┘\n```\n\n## Why axum-conf?\n\n- **Zero boilerplate**: Get liveness probes, Prometheus metrics, and security headers without writing middleware\n- **Kubernetes-native**: Built for container deployments with proper health checks and graceful shutdown\n- **Configuration-driven**: Change behavior through TOML files, not code changes\n\n## Quick Start\n\n**1. Add to Cargo.toml:**\n```toml\n[dependencies]\naxum-conf = \"0.3\"\naxum = \"0.8\"\ntokio = { version = \"1\", features = [\"full\"] }\n```\n\n**2. Create `config/dev.toml`:**\n```toml\n[http]\nbind_port = 3000\nmax_payload_size_bytes = \"1MiB\"\n```\n\n**3. Write `src/main.rs`:**\n```rust\nuse axum::{Router, routing::get};\nuse axum_conf::{Config, Result, FluentRouter};\n\nasync fn hello() -\u003e \u0026'static str {\n    \"Hello, World!\"\n}\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c()\u003e {\n    let config = Config::default();\n    config.setup_tracing();\n\n    FluentRouter::without_state(config)?\n        .route(\"/\", get(hello))\n        .setup_middleware()\n        .await?\n        .start()\n        .await\n}\n```\n\n**4. Run:**\n```bash\nRUST_ENV=dev cargo run\n```\n\n**5. Test it:**\n```bash\ncurl http://localhost:3000/        # Your handler\ncurl http://localhost:3000/live    # Liveness probe\ncurl http://localhost:3000/ready   # Readiness probe\ncurl http://localhost:3000/metrics # Prometheus metrics\n```\n\n## What You Get\n\n| Feature | What it does | Default |\n|---------|--------------|---------|\n| **Health probes** | `/live` and `/ready` endpoints for Kubernetes | Enabled |\n| **Prometheus metrics** | Request counts, latencies at `/metrics` | Enabled |\n| **Request logging** | Structured logs with UUIDv7 correlation IDs | Enabled |\n| **Rate limiting** | Per-IP request throttling | 100 req/sec |\n| **Security headers** | X-Frame-Options, X-Content-Type-Options | Enabled |\n| **Panic recovery** | Catches panics, returns 500, keeps running | Enabled |\n| **Graceful shutdown** | Handles SIGTERM, drains connections | 30s timeout |\n| **Compression** | gzip, brotli, deflate, zstd | Available |\n\n## Cargo Features\n\nEnable optional capabilities by category:\n\n### Core Features\n\n| Feature | What it adds |\n|---------|--------------|\n| `postgres` | PostgreSQL connection pooling with sqlx |\n| `keycloak` | OIDC/JWT authentication via Keycloak |\n| `basic-auth` | HTTP Basic Auth and API key authentication |\n| `session` | Cookie-based session management |\n| `opentelemetry` | Distributed tracing with OTLP export |\n| `rustls` | TLS support (auto-enabled by `postgres`) |\n| `circuit-breaker` | Per-target circuit breaker for external services |\n| `openapi` | OpenAPI spec generation via utoipa |\n\n### Middleware Features\n\n| Feature | What it adds |\n|---------|--------------|\n| `metrics` | Prometheus metrics at `/metrics` |\n| `rate-limiting` | Per-IP request throttling |\n| `security-headers` | Security headers (X-Frame-Options, etc.) |\n| `deduplication` | Request deduplication by request ID |\n| `compression` | gzip/brotli/deflate/zstd compression |\n| `cors` | CORS handling |\n| `api-versioning` | API version extraction (path/header/query) |\n| `concurrency-limit` | Max concurrent request limiting |\n| `path-normalization` | Trailing slash normalization |\n| `sensitive-headers` | Authorization header redaction in logs |\n| `payload-limit` | Request body size limits |\n\n### Feature Groups\n\n| Group | Includes |\n|-------|----------|\n| `production` | metrics, rate-limiting, security-headers, compression, cors |\n| `full` | All features |\n\n```toml\n# Example: Production setup with PostgreSQL\naxum-conf = { version = \"0.3\", features = [\"production\", \"postgres\"] }\n```\n\n### Feature Compatibility\n\nMost features work together, with one important exception:\n\n| Feature | Compatible With | Notes |\n|---------|----------------|-------|\n| `keycloak` | All except `basic-auth` | Automatically enables `session` |\n| `basic-auth` | All except `keycloak` | Cannot be used with OIDC |\n| `postgres` | All features | Independent database layer |\n| `session` | All features | Required by `keycloak` |\n| `opentelemetry` | All features | Independent tracing layer |\n\n**Important:** `keycloak` and `basic-auth` are mutually exclusive. Choose one authentication method per application.\n\n## Examples\n\nRun the examples to see axum-conf in action:\n\n```bash\n# Basic hello world\ncargo run --example hello_world\n\n# Application state management\ncargo run --example with_state\n\n# JSON REST API\ncargo run --example json_api\n\n# Middleware configuration (requires features)\ncargo run --example with_middleware --features \"cors,compression,rate-limiting\"\n```\n\n## Configuration Example\n\n```toml\n# config/prod.toml\n[http]\nbind_addr = \"0.0.0.0\"\nbind_port = 8080\nmax_payload_size_bytes = \"32KiB\"\nrequest_timeout = \"30s\"\nmax_requests_per_sec = 1000\n\n[http.cors]\nallowed_origins = [\"https://app.example.com\"]\nallowed_methods = [\"GET\", \"POST\", \"PUT\", \"DELETE\"]\n\n[database]\nurl = \"{{ DATABASE_URL }}\"\nmax_pool_size = 10\n\n[logging]\nformat = \"json\"\n```\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Getting Started](docs/getting-started.md) | Build your first service step-by-step |\n| [Architecture](docs/architecture.md) | How axum-conf works under the hood |\n| **Configuration** | |\n| [Overview](docs/configuration/overview.md) | Configuration methods and philosophy |\n| [TOML Reference](docs/configuration/toml-reference.md) | Complete configuration schema |\n| [Environment Variables](docs/configuration/environment-vars.md) | Using `{{ VAR }}` substitution |\n| **Features** | |\n| [PostgreSQL](docs/features/postgres.md) | Database integration guide |\n| [Keycloak/OIDC](docs/features/keycloak.md) | Authentication setup |\n| [OpenTelemetry](docs/features/opentelemetry.md) | Distributed tracing |\n| [Basic Auth](docs/features/basic-auth.md) | Simple authentication |\n| [Sessions](docs/features/sessions.md) | Session management |\n| [Circuit Breaker](docs/features/circuit-breaker.md) | External service resilience |\n| [OpenAPI](docs/features/openapi.md) | API documentation generation |\n| [Deduplication](docs/features/deduplication.md) | Request deduplication |\n| [TLS/rustls](docs/features/rustls.md) | TLS configuration |\n| **Middleware** | |\n| [Overview](docs/middleware/overview.md) | Middleware stack architecture |\n| [Features](docs/middleware/features.md) | API versioning, limits, normalization |\n| [Security](docs/middleware/security.md) | Rate limiting, CORS, headers |\n| [Observability](docs/middleware/observability.md) | Logging, metrics, tracing |\n| [Performance](docs/middleware/performance.md) | Compression, timeouts, limits |\n| **Kubernetes** | |\n| [Health Checks](docs/kubernetes/health-checks.md) | Liveness and readiness probes |\n| [Graceful Shutdown](docs/kubernetes/graceful-shutdown.md) | Proper pod termination |\n| [Deployment](docs/kubernetes/deployment.md) | Complete K8s manifests |\n| **Reference** | |\n| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |\n| [API Docs](https://docs.rs/axum-conf) | Rustdoc API reference |\n\n## Minimal Kubernetes Deployment\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: my-service\nspec:\n  template:\n    spec:\n      containers:\n      - name: app\n        image: my-service:latest\n        ports:\n        - containerPort: 8080\n        env:\n        - name: RUST_ENV\n          value: \"prod\"\n        livenessProbe:\n          httpGet:\n            path: /live\n            port: 8080\n        readinessProbe:\n          httpGet:\n            path: /ready\n            port: 8080\n      terminationGracePeriodSeconds: 35\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacprog-guy%2Faxum-conf-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmacprog-guy%2Faxum-conf-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmacprog-guy%2Faxum-conf-rs/lists"}