Skip to content
valkyothPublic

Repository files navigation

Rust edge gateway for websites, applications, caching, and load balancing.
Modular builds. Rootless containers. Explicit security and operational controls.


Fluxheim overview

Fluxheim

Fluxheim is a modular Rust webserver and edge gateway. Serve static websites and PHP applications, reverse-proxy services, cache responses, balance traffic, automate certificates, and inspect your deployment through logs, metrics and traces.

Download a release · Read the guides · Browse configurations

Features

These tables describe this source checkout. For a deployed release, use its tagged documentation and release notes. A check means implemented, not enabled in every binary or container. Choose the appropriate build features or packaged profile; runtime configuration still controls what is enabled. Read each guide's limitations before relying on a feature. The coverage ledger tracks outstanding corrections and qualification; a table entry is not release approval.

Server And Routing

Feature Supported Documentation
Static files, MIME types, index pages and GET/HEAD ✅ Static serving and publication limits
Static conditional requests, single byte ranges and directory listings Limited Current semantics and directory URL gaps
Virtual hosts, wildcard hosts, default site and strict host matching ✅ Vhosts
Static, proxy and redirect routes; method filters ✅ HTTP routing
Opt-in regex routes, capture variables and path rewrites ✅ Rewrites and current capture limits
HTTP-to-HTTPS redirects ✅ Listeners and redirects
Reverse proxy with HTTP/1.1 and HTTP/2 origins ✅ Connections, deadlines and gateway pages
HTTP/1.1 WebSocket upgrades Limited Configuration and open authorization/handshake limits
gRPC route filtering and H2 transport primitives Limited Trailer and streaming gaps; not general gRPC pass-through
gzip, Zstandard and Brotli response compression Limited Configuration, negotiation gaps and CPU limits
Request header forwarding and mutation Limited Request headers and identity limitations
Response headers, browser policy and redirect/cookie rewriting Limited Response headers and current limits
CORS origin allowlists and local preflights Limited CORS and current inheritance/wildcard limits
External authorization subrequests Limited Authorization and current security limits
Opt-in traffic mirroring Limited Sampling and current projection limits
PROXY protocol receive/send Limited HTTP support and HTTPS trust-policy blocker
TCP stream proxying, upstream TLS and connection limits Limited TCP streams and current boundaries
DNS-style UDP forwarding and one-way syslog forwarding Beta UDP setup, limits and restrictions

Access And TLS

Feature Supported Documentation
Trusted-proxy-aware IP allow/deny rules Limited Access policy and mapped-CIDR limitation
GeoIP country and ASN allow/deny rules ✅ GeoIP
Rate limits, delay mode and concurrency limits Limited Admission, queues and current lifetime/table limits
rustls or OpenSSL TLS backends ✅ HTTPS and TLS
Client certificates, fingerprint rules and upstream mTLS ✅ Fingerprint authorization, client authentication and proxy TLS
FIPS-capable backend build paths Conditional Required provider and deployment evidence
ACME issuance and renewal: HTTP-01, EAB and ARI Limited: scheduling and recovery corrections pending Certificates, ACME and current limits
External HTTP-01 challenge forwarding ✅ Challenge forwarding
Privacy build profile ✅ Privacy boundaries

FIPS-capable builds are not a claim that Fluxheim or every deployment is certified. GeoIP describes database-derived network information, not proof of a person's location or identity.

Cache

Feature Supported Documentation
Vhost and route-scoped proxy caching ✅ Caching
Bounded memory cache ✅ Memory caching
Disk cache, storage-bin backend and memory/disk tiers ✅ Persistent caching
Encrypted disk cache with local keys or OpenBao Transit ✅ Cache encryption
Local static-file memory caching ✅ Static cache
Range caching and fixed-slice composition ✅ Range and slice limits
Peer-assisted fill (variant restrictions apply) ✅ Peer fill and safety limits
Origin-fill concurrency protection ✅ Origin protection
Cache locks, revalidation, stale serving and hit/miss diagnostics ✅ Cache configuration
Warming, protected purge, status and object/key inspection ✅ Cache operations

Load Balancing

Feature Supported Documentation
Weighted round-robin, least-connections, least-sessions and power-of-two ✅ Load balancing
Hash, consistent hash, bounded-load hash, Maglev and Ketama ✅ Algorithms and boundaries
Priority groups, locality, backup, drain and disabled members ✅ Pool configuration
In-flight caps, bounded queues and slow start ✅ Pool configuration
Active TCP/TLS, HTTP, gRPC, exec and database health checks ✅ Health checks
Passive transport/status failure ejection and circuit state ✅ Health policy
Bounded retries and shared pool retry budgets ✅ Retry policy
Weighted least-time selection and passive header-latency thresholds ✅ Latency measurement
DNS, file and HTTP backend discovery ✅ Discovery
Source-IP, header, request-cookie and managed-cookie affinity ✅ Persistence
Runtime member controls, backend-set updates and pool status ✅ Operations
Optional local restart-persistent runtime state ✅ State and restrictions

Persistence and runtime overrides are not an active-active cluster state service. Managed-cookie signing keys remain process-local, and runtime weight overrides do not apply to every selector. Native HTTP retry and latency policies have explicit replay and measurement boundaries.

PHP And Extensions

Feature Supported Documentation
PHP/FastCGI with externally managed pools ✅ PHP deployment
Managed PHP-FPM: static, dynamic and ondemand pools Unix only Managed PHP-FPM
Front-controller routing and mixed static/PHP sites Documented routing limits PHP routing
PHP request-body replay and application recipes Collected ingress; documented memory limits PHP runtime
PHP container images with application extensions ✅ PHP images and prerequisites
Sandboxed Wasm access, headers, routing and cache policy hooks ✅ Wasm
Opt-in proxy ABI and WASI compatibility surfaces Preview Compatibility boundaries

PHP is a separate runtime, not embedded in Fluxheim. Windows supports external FastCGI over TCP and rejects managed PHP-FPM. Wasm is an explicit build/profile choice; it is not syntax-compatible iRules, Lua or VCL execution.

Operations And Visibility

Feature Supported Documentation
Structured text/JSON logging, bounded queues and typed event fields ✅ Logging and disclosure boundaries
Native access completion and configurable access fields Limited Current fields and unused options
Protected log files and rotation ✅ File lifecycle
Request IDs and distributed trace correlation ✅ Correlation and tracing
Per-vhost and module trace annotations Limited: native enrichment pending Current span fields
Prometheus metrics with bounded labels ✅ Metrics
Metrics bearer-token authentication Limited: Unix private-file enforcement pending Credential permissions and rotation
OTLP metric and trace export, retry and recovery ✅ OTLP export
Grafana/Prometheus/Jaeger and SigNoz integration examples and dashboards ✅ Collector integrations
Exporter-health dashboard panels Limited: direct scrape required Signal-path limitations
Prometheus operational alert examples Limited: persistent log-worker alert pending Rules and boundaries
Authenticated admin operations and owner-only Unix operations socket ✅ Admin API and roles
Configurable operations-socket group mode and Unix control-token leaf enforcement Limited Current limitations and safe settings
Read-only operational status and restricted observer credentials ✅ Operational status API
Verified configuration snapshots, reload and explicit rollback ✅ Snapshots
Automatic recovery identity and overlapping validation Limited Current recovery boundaries
Configuration loading, split files and validation Limited Composition rules and diagnostics
CLI validation and standalone configuration tester Limited: mode and profile checks Commands and validation
Foreground service, process settings and graceful drain Limited Active settings, shutdown and current limits
Inherited listeners and externally supervised blue/green deployment ✅ Upgrade requirements and systemd restart distinctions

Audit queue admission does not guarantee durable audit storage. The admin API has specific supported operations, not complete server management; see the management API boundary. JSON escaping and typed event restrictions do not provide general secret redaction for arbitrary legacy or dependency log messages.

Packaging And Deployment

Feature Supported Documentation
Linux x86_64 and ARM64 portable packages ✅ Portable releases
macOS Apple Silicon portable packages Unsigned macOS
Windows x86_64 native packages Unsigned Windows packages
Focused full, Wasm, cache, proxy, load-balancer, PHP and config-tester profiles ✅ Package selection and compiled capabilities
Rootless Wolfi, Alpine, Debian and SUSE containers ✅ Build and Podman
Container OS/PHP refreshes independent of Fluxheim releases ✅ Runtime refresh
RPM packages and hardened systemd services ✅ systemd deployment

SUSE PHP uses BCI; other SUSE profiles use Micro. Windows ARM64 and Intel macOS are not supported release targets. HTTP/3 is deferred; production UDP/GSLB, a WAF and a full management UI are not implemented. Plans are tracked in the roadmap, not implied by these tables.

Quick Start

Build with the repository's pinned Rust toolchain, validate the example, then start the server from the repository root. This example serves an included static page; it needs no database, PHP pool or upstream application:

cargo build --locked
cargo run --locked -- --validate-config --config examples/configuration/single.toml
cargo run --locked -- --config examples/configuration/single.toml

From another terminal:

curl -H 'Host: configuration.example.test' http://127.0.0.1:8080/

Expected body: configuration-single-ok. Stop with Ctrl+C. Port 8080 must be free; this is a loopback HTTP demonstration, not a public TLS deployment.

For your own static site, replace the host names and root in this configuration:

[server]
listen = ["127.0.0.1:8080"]
default_vhost = "site"

[[vhosts]]
name = "site"
hosts = ["example.test", "www.example.test"]

[vhosts.web]
root = "/srv/sites/example/public"
index_files = ["index.html"]
deny_dotfiles = true
cache_control = "public, max-age=60"

The directory must exist and be readable by the service user. This example binds locally; public deployment also needs appropriate listeners, network/firewall rules and TLS. See vhost setup and production readiness.

Documentation

Development And Security

Run local checks and select live tests:

scripts/checks.sh
scripts/test_starter.py --list

Use scripts/release_checks.sh for release qualification. The collector gate checks stored signals and dashboards against running collector products; skipped external services are not release evidence.

Fluxheim uses a locked dependency graph, CI, CodeQL, RustSec advisory checks, dependency/license policy and native/container smoke tests. Checksums and repeat builds do not by themselves prove independent build provenance. Read supply-chain policy for the trust model and SECURITY.md for vulnerability reporting.

License

Fluxheim is distributed under the European Union Public Licence v1.2.

Releases

Sponsor this project

Packages

Used by

Contributors

Languages