Runtime architecture

The runtime boundary is src/runtime.rs. It turns a validated Config into an immutable RuntimeSnapshot: router, pool states, parsed configuration, optional TLS snapshot, and monotonically increasing generation.

Load, publish, reload

RuntimeStore::from_path loads and validates TOML, builds generation 1, and starts health supervisors. Readers call load() and receive an Arc from ArcSwap, so an in-flight request retains one complete snapshot while a reload atomically publishes another. reload() and apply_config() serialize writers with a mutex, build/validate the candidate and start its health supervisor before swapping it; pool health is preserved by pool name. The old health supervisor is stopped only after publication.

On Unix, the child process uses reload_loop for SIGHUP. Invalid candidates log reload_rejected and leave the active snapshot untouched. TLS material follows the same candidate validation, but Pingora binds TLS listener settings when it constructs the service. A certificate activation therefore applies the runtime candidate and signals the supervisor, which validates then starts a replacement process with inherited listeners before draining the old child; failure restores the previous runtime configuration. See src/cli.rs and tests/reload.rs, tests/tls_listener.rs.

Control-plane synchronization

The control plane’s durable runtime_config record is the runtime-change source of truth. RuntimeConfigReloader persists a validated candidate before activation and restores the previous database value if activation fails. Writing the mounted TOML is a best-effort mirror: a read-only container mount does not reject a successfully persisted, live update.

Proxy-host records are not used directly by the proxy. On proxy_hosts.changed or cluster.catch_up, the reloader removes only reserved proxy-host-* routes/pools, resolves each enabled host upstream, materializes one round-robin TCP pool and / route per host, validates, and applies that snapshot. Operator-managed TOML routes/pools remain intact.

After either config/host refresh, the reloader refreshes WAF, IP-security, bot, host-auth, rate-limit (global and per-host), analytics-retention, and adaptive-tuning stores from the database. Keep a data-plane policy change on this path rather than mutating a request-time store ad hoc.