Tracking: typed config — centralized validation, single source of defaults, no silent coercions

[erskingardner]

Root cause

Configuration correctness is enforced ad hoc, in three scattered ways, so misconfiguration fails silently at runtime instead of loudly at load:

1. Two sources of defaults: every field has a set_default(...) in base_config_builder() (src/config.rs:579-661) and a serde default_* fn — the serde ones are dead on the production load path, so the pairs can silently drift ([LOW] Config defaults are duplicated between base_config_builder set_default(...) and serde default_* fns (which are dead for the load path) — silent drift risk #171).
2. Free-form primitives for constrained values: logging.format/logging.level are Strings matched at runtime with silent fallthrough arms (src/main.rs init_logging), health.bind_address is an unparsed String, relay URLs are Vec<String> with validation only for the clearnet list, cache/concurrency sizes are plain usize.
3. Silent coercions far from load: zero/invalid values are "fixed" inside constructors where the operator can't see it — RateLimiter::new swaps max_entries = 0 for 100k (src/rate_limiter.rs:191), the dedup cache does the same (src/nostr/events.rs:511), event_processing_permits clamps (src/main.rs:166) while an oversized value panics in Semaphore::new.

Each member issue is one instance of "config that lies": a value the operator sets that either does nothing, does something else, or detonates later.

Refactor design

• Single source of defaults: drop the set_default ladder; serde default fns (backed by the existing DEFAULT_* consts) become the only place a default is written ([LOW] Config defaults are duplicated between base_config_builder set_default(...) and serde default_* fns (which are dead for the load path) — silent drift risk #171).
• Parse, don't validate — typed fields at load:
  • NonZeroUsize for max_rate_limit_cache_size / max_dedup_cache_size / max_tokens_per_event / max_concurrent_event_processing (with a sane upper bound for the semaphore), making the constructor coercions unrepresentable ([LOW] RateLimiter::new silently coerces max_entries = 0 to the 100,000 default instead of surfacing the misconfiguration #166, [LOW] server.max_tokens_per_event = 0 (and max_dedup_cache_size = 0) bypass ServerConfig::validate() — silent push outage / silent default swap #149, [LOW] max_concurrent_event_processing has no upper bound — an oversized value panics at startup in Semaphore::new #179).
  • enum LogFormat { Json, Pretty, Off } deserialized like the existing ApnsPayloadMode, removing both the silent fallthrough ([LOW] Invalid logging.format silently falls back to default formatter #142) and the undocumented "off" blackout arm ([LOW] logging.format = "off" silently disables ALL logging and ignores logging.level — an undocumented format value that causes a total log blackout #150) — silencing is level = "off", and an explicit format = "off" becomes a load error or documented behavior.
  • health.bind_address: SocketAddr ([LOW] health.bind_address is never validated at config load — a typo silently disables the health/readiness/metrics server while the process runs #167).
  • Relay URLs parsed into RelayUrl at load and normalized once; onion entries validated symmetrically with clearnet (scheme + .onion host) so a plaintext ws:// in relays.onion fails fast ([MEDIUM] Onion relay URLs bypass all URL validation — a plaintext ws:// entry in relays.onion defeats the wss-only TLS enforcement, and typo'd .onion URLs are silently dropped #122); inbox_relay_event_is_current compares normalized URLs and picks the newest event by created_at ([LOW] inbox_relay_event_is_current compares raw config strings and uses events.first(), causing spurious kind-10050 republishing and possibly skipping needed updates #124).
• Extend AppConfig::validate to every section, including cross-field checks: warn loudly on metrics.enabled && !health.enabled (structural fix — mounting /metrics independently — belongs to the health-server tracker) ([LOW] metrics.enabled = true with health.enabled = false silently produces an unreachable /metrics — collector runs with no endpoint to scrape it #196 rider).
• Key-file hygiene at load: on unix, reject or prominently warn when private_key_file mode grants group/other read, mirroring the 0600 guarantee the generate path already enforces ([LOW] Server private-key file is loaded with no permission check — a world/group-readable key file is accepted silently #146).
• Keep the private key out of the config crate's Value tree — resolve private_key/private_key_file through a dedicated Zeroizing path outside the builder ([LOW] Inline server.private_key leaves un-zeroized plaintext copies inside the config crate's value tree #156, acceptance test owned by the secret-hygiene tracker).

Members

• [LOW] Config defaults are duplicated between base_config_builder set_default(...) and serde default_* fns (which are dead for the load path) — silent drift risk #171 — single source of defaults
• [LOW] health.bind_address is never validated at config load — a typo silently disables the health/readiness/metrics server while the process runs #167 — parse health.bind_address as SocketAddr at load
• [LOW] RateLimiter::new silently coerces max_entries = 0 to the 100,000 default instead of surfacing the misconfiguration #166 — reject rate_limit.max_entries = 0 instead of silent 100k swap
• [LOW] server.max_tokens_per_event = 0 (and max_dedup_cache_size = 0) bypass ServerConfig::validate() — silent push outage / silent default swap #149 — reject max_tokens_per_event = 0 / max_dedup_cache_size = 0
• [LOW] max_concurrent_event_processing has no upper bound — an oversized value panics at startup in Semaphore::new #179 — upper-bound max_concurrent_event_processing (no Semaphore::new panic)
• [LOW] logging.format = "off" silently disables ALL logging and ignores logging.level — an undocumented format value that causes a total log blackout #150 — remove/reject the format = "off" log blackout
• [LOW] Invalid logging.format silently falls back to default formatter #142 — reject unknown logging.format values
• [MEDIUM] Onion relay URLs bypass all URL validation — a plaintext ws:// entry in relays.onion defeats the wss-only TLS enforcement, and typo'd .onion URLs are silently dropped #122 — validate onion relay URLs (scheme + .onion host)
• [LOW] inbox_relay_event_is_current compares raw config strings and uses events.first(), causing spurious kind-10050 republishing and possibly skipping needed updates #124 — normalized-URL comparison + newest-event selection for kind-10050 republish
• [LOW] Server private-key file is loaded with no permission check — a world/group-readable key file is accepted silently #146 — private-key file permission check at load
• [LOW] Inline server.private_key leaves un-zeroized plaintext copies inside the config crate's value tree #156 — (rider, tracked by secret-hygiene tracker) private key never enters the config Value tree

In-flight PRs

• PR fix: apply relay reconnect settings #208 (fixes [LOW] reconnect_interval_secs / max_reconnect_attempts config is never wired to the nostr-sdk client, so the documented reconnection settings have no effect #92, wire reconnect_interval_secs/max_reconnect_attempts to nostr-sdk): merge first — this tracker builds on it; [LOW] reconnect_interval_secs / max_reconnect_attempts config is never wired to the nostr-sdk client, so the documented reconnection settings have no effect #92 is the same "documented config that does nothing" class.
• PR fix: validate event processing concurrency cap #211 (fixes [LOW] max_concurrent_event_processing has no upper bound — an oversized value panics at startup in Semaphore::new #179, validate concurrency cap): merge first — this tracker absorbs it into the typed-field design.
• [LOW] reconnect_interval_secs / max_reconnect_attempts config is never wired to the nostr-sdk client, so the documented reconnection settings have no effect #92 — reconnect settings actually applied (point fix in flight)

Sequencing

Wave 1; fully parallel (config.rs + constructor signatures only). The rate-limit admission tracker consumes this tracker's typed NonZeroUsize configs, so it starts after this lands (soft dependency).

[erskingardner]

Completed: all member issues resolved via PR #231 (merged to master). See roadmap #222.

[erskingardner]

V2 follow-up tracker opened: #282. Keeping this V1 tracker closed; the new issue owns cross-field config invariants and enabled-state validation gaps left after the first wave.