Documentation

A Linux-first web and application server written in Rust: fast, observable, secure and multi-tenant, with PHP, Node.js, Python and arbitrary upstreams as first-class runtimes.

All notable changes are recorded here. Format: Keep a Changelog.

Status: living document. Reflects the code as of milestone M9 (operations). The engineering contract is SCALWSNextGenWebServerClaudeCodeHandoff.docx; this file explains how the code realizes it and where it does not yet.

Significant decisions get an ADR in docs/adr/. Smaller ones are logged here with date and reason so they can be revisited.

Design ADRs: 0033 (control/data plane, reuseport), 0034 (PressureScore, classification), 0035 (lifecycle, drain, generations, recovery), 0036 (multi-instance state). Rollback point: pre-adaptive-runtime-2026-10-06.

Design: ADR-0033 … 0036 and docs/adaptive-runtime.md (architecture diagram, configuration reference). Rollback point: pre-adaptive-runtime-2026-10-06 (VERIFIED, docs/pre-adaptive-runtime-backup.md). Benchmarks: docs/benc

Design: ADR-0037. Applies to scalws-controller with listen: inherited (the default).

Design: ADR-0038. Applies to several instances under scalws-controller.

Design: ADR-0039 (transport plane), ADR-0040 (connection IDs), ADR-0041 (lifecycle). TCP (HTTP/1.1, HTTP/2) is unchanged: one shared accept queue per address (listen: inherited).

From the ScalWS apt repository (Ubuntu 24.04 or later, Debian 13 or later, amd64):

ScalWS Console is the web administration of a ScalWS host, shipped with ScalWS the way LiteSpeed WebAdmin ships with LiteSpeed Web Server: the same packages and release artifacts (scalwsd, scalws-controller, scalwsctl, s

ScalWS Console is part of the standard ScalWS distribution: the DEB/RPM packages built by scripts/package.sh contain /usr/bin/scalws-console and scalws-console.service, next to scalwsd, scalws-controller and scalwsctl.

The console never edits the active configuration in place. Every change is a transaction over the configuration file the controller reads (controller.config in controller.yaml), and the controller turns the file into a n

Roles are fixed sets of capabilities (cmd/scalws-console/src/rbac.rs). Every API handler names the capability it needs and checks it on the server; the browser only hides what the session cannot do. Sensitive actions als

/etc/scalws/console/credentials (packaged installs; <statedir>/credentials otherwise), mode 0600, one account per line:

Build: cmd/scalws-console at the commit that adds it; demo stack on the development VM (scripts/console-demo.sh): its own scalws-controller (state [private host path], listeners 127.0.0.1:28080/28443, metrics 39910+, CPU

Status: living document, revised at every milestone's security review. Scope today: M1 serving core (listeners, TLS, HTTP/1.1 + HTTP/2, routing, static files, reverse proxy, metrics endpoint, config reload) and M2 manage

Scoped standard run of the security-audit workflow over the new code: crates/scalws-h1, crates/scalws-http/src/h1server.rs (+ conn.rs dispatch), crates/scalws-core/src/upgrade.rs and the experimental upstream client (cra

Development VM (Ubuntu 24.04, Linux 6.8), commit 4f5c52f.

Dated reports. Those written before 2026-10-07 use the names of that time: the server was called SCB (scb-webd, scbctl, crates scb-, result rows labelled scb); it is now Scale Web Server (ScalWS): scalwsd, scalwsctl, sca

Reproducible, comparative HTTP benchmarks (handoff §14).

The authoritative single-instance reference for the Adaptive Runtime work: regression gates compare against these numbers with Adaptive Runtime disabled.

Machine and pinning as in 2026-10-10-xeon-bare-metal-pgo.md: 2× Xeon E5-2650 v2, server on four physical cores (CPUs 0-3), upstream and applications on 4-7, oha on socket 1; performance governor, turbo off. MODE=release:

First measurements away from the noisy VM: 2× Xeon E5-2650 v2 (Ivy Bridge EP, 8C/16T per socket, no AVX2), 121 GB, Ubuntu 26.04, kernel 7.0, performance governor, turbo off. Server on CPUs 0-3 (four physical cores of soc

ADR-0045. One scalwsd build (commit d7dcbf5, --features http3), run with server.upstreamclient: hyper (default) and experimental. Development VM: 4 server CPUs (0-3), upstreams on 4-5, load generator on 6-11. bench/multi

Overnight work (2026-10-08/09): Stage 1 (upstream path), Stage 2 (upstream telemetry), the open items, then this comparison. Host and method as in 2026-10-08-nginx-versions-real-apps.md: 8 vCPU EPYC 7642 VM, server on CP

The VM's throughput noise (CV 5–10 %) hides changes of a few percent, so user-space work per request was measured with callgrind: the server runs under valgrind --tool=callgrind, 500 warm-up requests, counters zeroed, 40

Follow-up to 2026-10-09-final-vs-nginx.md. Four areas were behind nginx 1.24–1.31.6 there: small static files (0.95–0.98×), 1 MiB files (0.95×), TLS + HTTP/2 (0.96–0.97×) and p99 tails (cache hits 9.2 ms vs 3.3–6.8 ms).

Host: development VM (8 vCPU EPYC 7642). 3 instances (CPUs 0-2), demux + controller on CPU 3, 4 × scalws-h3-probe (4 connections × 4 streams each, /hello.txt) on CPUs 4-7. bench/demux-profile.sh (perf + strace), bench/de

Host: development VM (8 vCPU EPYC 7642, Ubuntu 24.04). One binary (release, --features http3), two configurations: metrics.hosts: false (off, via bench/hosts-off-wrapper.sh, which adds the setting to the bench configurat

Host: development VM (8 vCPU EPYC 7642, Ubuntu 24.04). Server on CPUs 0-3, applications and upstreams on 4-5 (MariaDB pinned there too), oha on 6-7. MODE=release RUNS=3 FRESHSERVER=1 (3 × 30 s per scenario after 10 s war