feat(pool): jitter for server_lifetime

[frangz]

Closes #962.

Summary

Adds server_lifetime_jitter (milliseconds) at the general, database, and user config levels. When non-zero, each backend connection samples a per-connection offset uniformly from [-jitter, +jitter] once at creation time, so its effective lifetime is fixed at birth and the comparison sites in the pool use that effective value instead of the bare server_lifetime.

This breaks the synchronized retirement of cohorts that opened together (e.g. during a traffic ramp), which otherwise produces a periodic reconnect wave at every server_lifetime interval — visible as a clean N-minute latency stripe in client metrics. See #962 for context and prior art.

Default is 0 (no jitter), preserving existing behavior.

Implementation

Config (pgdog-config)

• general.rs: new server_lifetime_jitter: u64 with default 0, _Default:_ annotation, and docs URL placeholder per pgdog-config/CONTRIBUTING.md. Env override PGDOG_SERVER_LIFETIME_JITTER.
• database.rs, users.rs: server_lifetime_jitter: Option<u64> overrides, mirroring the existing server_lifetime precedence.
• url.rs: query-param parsing for the database-level override.

Pool config (pgdog-stats, pgdog/src/backend/pool/config.rs)

• New Config::max_age_jitter: Duration (default Duration::ZERO). Resolved User → Database → General, same chain as server_lifetime.

Per-connection sampling (pgdog/src/backend/pool/monitor.rs)

• After a successful Server::connect, sample once via rand::rng().random_range(-jitter..=+jitter) and store on the connection. Skipped (and free) when jitter is 0.

Effective lifetime (pgdog/src/backend/server.rs)

• Server::set_max_age_offset_ms(i64) and Server::effective_max_age(base) -> Duration. Saturates at zero on negative overflow; returns base unchanged for offset 0.

Comparison sites (pgdog/src/backend/pool/inner.rs)

• close_old and maybe_check_in now compare server.age(now) against server.effective_max_age(self.config.max_age).

Behavioral details (matches the issue's contract)

• Sampled once at connection creation, not on every check, so each connection's lifetime is deterministic from its birth time.
• Additive (uniform [-jitter, +jitter]) so the average effective lifetime stays at server_lifetime, not skewed shorter.
• Process-global RNG (non-cryptographic).

Tests

10 new tests, all passing locally:

• pgdog-config: URL parsing of server_lifetime_jitter.
• pgdog::backend::pool::config: precedence chain (general → database → user), default-zero, and the existing precedence test extended.
• pgdog::backend::server: effective_max_age for default / positive / negative / negative-saturating cases.

Existing pool/server tests (27 in pool::inner, full pgdog-config suite) continue to pass.

cargo fmt applied; no new clippy warnings introduced at the touched call sites.

Docs

The /// doc comments reference https://docs.pgdog.dev/configuration/pgdog.toml/{general,databases}/#server_lifetime_jitter per pgdog-config/CONTRIBUTING.md. Happy to follow up with a docs PR (or update those URLs) once you tell me where the new headings should land.

[CLAassistant]

All committers have signed the CLA.

[codecov]

Codecov Report

❌ Patch coverage is 98.38710% with 2 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
pgdog/src/backend/server.rs	97.18%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[levkk]

Just a minor stylistic change, otherwise this is great!

[levkk]

nit: starting from here, let's propagate it as Duration so we are sure not to confuse units - I've done this before, even when the name of the variable is *_ms, it's easy to forget.

[levkk]

Nice!

If you'd like to follow up with docs, you can just add the setting description here: https://github.com/pgdogdev/docs/blob/main/docs/configuration/pgdog.toml/general.md#server_lifetime

I'm going to let the CI finish and merge.

🙏