Traffic bursts
Admission and concurrency budgets aim to absorb useful work while limiting queues, so a short burst does not become a long recovery period.
Architecture / Features
Turbnix Features
Turbnix is designed as a modern, lightweight, event-driven web server with adaptive resource control. Its focus is useful throughput, low overhead, and stable behavior under pressure.
The architecture below describes the project's design direction. Capabilities and operational guarantees depend on implementation and validation as the project matures.
The request path
Serving work. Observing pressure.
The event engine moves requests through the serving path. An adaptive controller uses lightweight measurements to influence how much work enters and runs concurrently.
Architecture / 01
Adaptive Event Engine
The adaptive design separates measurement from decision-making. Cheap per-worker metrics and counters are collected on the hot path; aggregation and decision logic run off the request and event-loop path. Signals can include CPU, RAM, active connections, queue depth, latency, and runtime saturation.
These signals inform admission control and concurrency limits so accepted work stays within available capacity. Fairness and overload protection guide how capacity is shared: a busy workload should not consume every opportunity to make progress. The goal is stable behavior under pressure without adding expensive control logic to each request.
Architecture / 02
Smart Cache
High-performance caching starts with keeping unrelated requests independent. The cache architecture uses granular locking to limit contention and per-key request coalescing, or single-flight behavior, so concurrent misses for the same key can share one fill operation.
Where cache policy allows, stale-serving can keep eligible responses available while a refresh runs. Combined with bounded refresh work, this approach aims to prevent cache stampedes from overwhelming the application. Cache eligibility, freshness, and invalidation remain policy decisions; dynamic or personalized responses must not be assumed safe to share.
Architecture / 03
PHP Runtime
The PHP-oriented process architecture is designed around supervised execution and controlled saturation. Bounded queues make waiting work explicit, while concurrency limits keep incoming traffic from creating unbounded demand for PHP workers or the services they depend on.
Process supervision includes crash detection, health checks, and restart with backoff. Failure isolation aims to contain a failing worker instead of allowing repeated failures to destabilize the whole service. Queue depth and runtime saturation feed resource decisions so admission can respond before waiting work consumes the remaining memory budget.
Architecture / 04
Reverse Proxy & Upstreams
The reverse-proxy design organizes upstreams into pools, with load balancing intended to distribute work across available capacity. Health-aware routing should avoid unhealthy destinations while connection reuse and efficient forwarding keep upstream overhead low as a design goal.
Retries need a budget, a deadline, and attention to whether repeating a request is safe. Limiting retry work helps prevent a struggling backend from receiving a retry storm on top of its original load. Pool limits and backpressure make backend capacity part of the serving decision, rather than treating every upstream as an unlimited resource.
Architecture / 05
HTTP/3 + TLS
Modern TLS handling and HTTP/3 over QUIC are architectural goals for Turbnix. The focus is on secure transport with deliberate budgets for connection state, handshake work, and protocol processing, alongside the needs of the HTTP serving path.
Transport efficiency must be evaluated under connection churn, packet loss, and sustained traffic, not inferred from protocol support alone. These goals do not establish production maturity or a fully released implementation. Availability and operational guidance will need to follow the implementation and its validation.
Architecture / 06
Graceful Reloads
The reload model uses immutable generations: a candidate generation is prepared without mutating the one currently serving traffic. Health-gated activation checks readiness before new connections are cut over, with listener continuity preserved where the platform and change allow it.
After cutover, the old generation drains existing work within a defined shutdown budget. Keeping activation and draining separate makes failures easier to reason about and provides a basis for rollback. Reload behavior under load must still be measured, including long-lived connections, drain timeouts, and any requests dropped during the transition.
Architecture / 07
Resource Efficiency
Low CPU and RAM use are design goals across the connection lifecycle. Bounded per-connection memory, efficient keep-alive handling, and explicit limits on buffered or queued work aim to keep idle connections inexpensive and busy connections predictable.
Time and resource budgets help protect capacity from slow or adversarial clients. For larger systems, NUMA and locality awareness guide worker and memory placement to reduce unnecessary cross-node traffic. These choices need workload-specific measurement: a smaller idle footprint is useful only if useful throughput and tail latency remain acceptable.
Architecture / 08
WordPress & Dynamic Workloads
Cached WordPress traffic and PHP-backed dynamic requests place different demands on a server. Turbnix focuses on efficient cache hits while bounding the uncached work that reaches PHP. Cache policy must distinguish shareable responses from personalized or otherwise ineligible content.
PHP saturation control, request coalescing, and bounded queues are intended to protect databases and other backends during bursts or cache misses. The important question is how the complete request path behaves when one dependency slows down. No measured WordPress RPS result is claimed here; cached and uncached behavior require separate evaluation.
Architecture / 09
Observability Without Hot-Path Cost
The observability goal is to keep expensive work off the critical request path, not to pretend measurement is free. Lightweight per-worker counters record essential activity; snapshots provide a bounded view of changing state without requiring each request to perform reporting or analysis.
Aggregation, export, and adaptive decisions belong outside the event-loop path. Sampling frequency and snapshot size need limits so monitoring remains useful under overload. Observability overhead itself is a measurement target, including the effect of instrumentation on CPU per request and tail latency.
Architecture / 10
wwwPanel Integration
wwwPanel is a separate lightweight control plane. The integration direction is deep operational coordination: transactional changes, health-gated activation, rollback, deployment controls, and resource-aware management that understands the state of the serving system.
The conceptual boundary keeps request serving in Turbnix and operational coordination in wwwPanel. Turbnix can conceptually operate independently from wwwPanel; the control plane is an integration, not the request-processing engine. This separation is intended to make deployment decisions explicit while keeping control-plane work out of the serving path.
Failure modes matter
Designed for pressure
Peak throughput is only one part of server behavior. These are the architectural responses Turbnix aims to validate when traffic and dependencies stop behaving ideally.
Backend saturation
Health signals, bounded PHP queues, and upstream limits help reduce new demand when a dependency cannot keep up.
Slow clients
Connection deadlines and bounded buffers aim to prevent slow reads or writes from holding an unbounded share of memory and capacity.
Connection churn
Efficient connection lifecycle handling and handshake budgets target repeated setup and teardown costs, not just steady keep-alive traffic.
Cache stampedes
Per-key single-flight fills and policy-controlled stale-serving aim to contain refresh work when many requests encounter the same expired item.
Reload-under-load
Health checks before activation, new-connection cutover, and bounded draining separate readiness from retirement of the old generation.
Benchmark philosophy
Measurement-first engineering
Turbnix uses measurement-first engineering. Useful throughput, resource cost, and tail behavior must be evaluated together, with reproducible workloads and clear hardware, configuration, and cache-state context.
Target measurements cover steady traffic, saturation, recovery, and long-running stability. Cached and uncached application paths need separate tests, and reloads need explicit accounting for interrupted work.
Measured benchmark results will be published as the implementation matures.
- RPS/core
- CPU/request
- RAM at large connection counts
- p50/p95/p99/p99.9 latency
- Cached WordPress throughput
- PHP queue depth
- Proxy overhead
- TLS handshakes/core
- HTTP/3 efficiency
- Overload recovery
- Reload-dropped requests
- Long soak tests
Explore the project
Follow the architecture as it develops
Explore the Turbnix web server repository or return to the project overview. Documentation is coming soon.