alknet/docs/architecture/decisions/030-static-dynamic-config-split.md

ADR-030: Static/Dynamic Configuration Split

Status

Accepted

Context

Alknet's configuration is loaded once at startup and never changes. This causes three specific failures:

1. No hot reload of authentication credentials. Adding or removing an authorized key requires restarting the server process. In head/worker deployments where keys are managed via a database, the process must be restarted every time a key is added, revoked, or rotated. This is operationally unacceptable.

2. No port forwarding access control. Any authenticated client can open a direct-tcpip channel to any destination. There is no policy governing which hosts, ports, or alknet control channels a client may access. A compromised key grants unrestricted network access through the tunnel.

3. No structured configuration beyond CLI flags. ADR-011 chose programmatic-first configuration for the alpha — correct at the time. But as alknet moves toward publishable releases, operators need config files for reproducible deployments, and the NAPI layer needs programmatic reload capability that ServeOptions doesn't currently support.

Not all configuration should be reloadable. Transport-level settings (listen address, TLS certificates, host key) require socket/TLS renegotiation to change at runtime — effectively a restart. Auth and forwarding policy can change atomically without disrupting existing connections.

Decision

Split configuration into StaticConfig and DynamicConfig.

StaticConfig

Immutable after startup. Constructed from ServeOptions (the builder pattern is preserved). Contains everything that affects socket binding, TLS handshakes, or SSH session negotiation:

• Transport mode, listen address
• TLS config (cert, key)
• iroh config (relay URL)
• Stealth mode flag
• Host key, host key algorithm
• Max auth attempts, max connections per IP
• Proxy config

Changing any of these requires a restart.

DynamicConfig

Hot-reloadable at runtime via ArcSwap<DynamicConfig>. Contains everything checked per-connection or per-channel:

• AuthPolicy — authorized keys, certificate authorities, token config
• ForwardingPolicy — allow/deny rules for channel targets (ADR-031)
• RateLimitConfig — rate limiting parameters

ArcSwap provides lock-free reads on the hot path (every auth_publickey() and every channel_open_direct_tcpip() call does an Arc dereference — zero cost compared to the current approach). Writes are atomic: store() swaps the pointer. Existing connections finish with their current config; new connections get the new config.

ConfigReloadHandle

pub struct ConfigReloadHandle {
    dynamic: Arc<ArcSwap<DynamicConfig>>,
}

impl ConfigReloadHandle {
    pub fn reload(&self, new_config: DynamicConfig) { ... }
}

The handle is obtained from Server::run() and passed to NAPI or the CLI.

ConfigService

The ConfigService wraps ArcSwap<DynamicConfig> reloads behind an irpc protocol (behind the irpc feature flag) for production deployments that use the service layer. For minimal deployments (CLI, single-node), direct ConfigReloadHandle::reload() is sufficient.

TOML Config File

An optional TOML config file covers static config plus initial auth/forwarding paths. This amends ADR-011 (does not supersede it) — the programmatic-first API remains primary. The config file is a convenience input format:

[server]
transport = "tls"
listen = "0.0.0.0:443"
stealth = false
max_connections_per_ip = 5
max_auth_attempts = 3

[server.tls]
cert = "/etc/alknet/tls/cert.pem"
key = "/etc/alknet/tls/key.pem"

[auth]
host_key = "/etc/alknet/ssh/host_key"

[forwarding]
default = "deny"

NAPI Reload API

interface AlknetServer {
  reloadAuth(auth: { authorizedKeys?: Buffer, certAuthority?: Buffer }): void;
  reloadForwarding(policy: ForwardingPolicyConfig): void;
  reloadAll(config: DynamicConfig): void;
}

The NAPI layer parses key data and constructs a new DynamicConfig, then calls ConfigReloadHandle::reload().

Client Configuration

Client configuration stays as ConnectOptions — no ArcSwap needed. Client config is almost entirely static (which server to connect to, which key to use).

Consequences

• Positive: Auth credentials and forwarding policy can be reloaded without restarting the server. Adding a key via reloadAuth() takes effect on the next connection attempt.
• Positive: ADR-011's programmatic-first intent is preserved. The TOML config file is an optional convenience layer, not a replacement for ServeOptions.
• Positive: ArcSwap provides zero-cost reads on the hot path. Every auth check and every channel open is a single Arc dereference.
• Positive: The ConfigService irpc protocol (behind feature flag) allows production deployments to integrate config reload into their service mesh without taking a direct dependency on DynamicConfig internals.
• Positive: Forwarding policy is now part of DynamicConfig — operators can restrict access per identity, per destination, per transport (ADR-031).
• Negative: Two config structs where there was one. The split is clean (transport vs. policy) but adds surface area.
• Negative: Config file introduces toml as a dependency in the CLI crate. This is acceptable for a CLI binary.

References

• research/configuration.md — Full analysis
• ADR-011 — Programmatic-first API (amended, not superseded)
• ADR-031 — Forwarding policy (part of DynamicConfig)
• ADR-029 — Identity as core type (DynamicConfig.auth uses IdentityProvider)
• integration-plan.md — Phase 1.1