API: Prometheus metrics, DB pool tuning, header/contract docs, health/ready split

.env.example

@@ -51,6 +51,25 @@ GRPC_API_DB_POOL_SIZE=10
 # against PgBouncer.
 GO_API_DB_POOL_SIZE=5
 
+# OPTIONAL  go-api  default: 0
+# Minimum pool connections kept open (issue #238). 0 matches pgxpool's own
+# default — raise it to pre-warm connections and cut cold-start latency.
+GO_API_DB_POOL_MIN_CONNS=0
+
+# OPTIONAL  go-api  default: 1800000 (30 min)
+# Maximum age of a pooled connection before it's recycled (issue #238). A
+# random jitter of 10% of this value is applied automatically so connections
+# don't all recycle at once.
+GO_API_DB_POOL_MAX_CONN_LIFETIME_MS=1800000
+
+# OPTIONAL  go-api  default: 300000 (5 min)
+# How long an idle pooled connection is kept before it's closed (issue #238).
+GO_API_DB_POOL_MAX_CONN_IDLE_TIME_MS=300000
+
+# OPTIONAL  go-api  default: 60000 (1 min)
+# How often idle pooled connections are health-checked (issue #238).
+GO_API_DB_POOL_HEALTH_CHECK_PERIOD_MS=60000
+
 # OPTIONAL  go-api
 # PgBouncer admin console connection, used by GET /v1/admin/db to read
 # SHOW POOLS / SHOW STATS. Connect to the virtual "pgbouncer" database.
@@ -151,8 +170,11 @@ RUST_LOG=info
 # Port serving /healthz and /readyz.
 HEALTH_PORT=8080
 
-# OPTIONAL  indexer  default: 30000 / 10000
-# Postgres per-statement and idle-in-transaction timeout bounds (ms).
+# OPTIONAL  indexer + go-api  default: 30000 / 10000
+# Postgres per-statement and idle-in-transaction timeout bounds (ms), applied
+# to every connection at connect time. Shared across both services (issue
+# #238) so they agree on how long a query or idle transaction may hold a
+# connection; bounded to [100, 3600000]ms, out-of-range values are clamped.
 DB_STATEMENT_TIMEOUT_MS=30000
 DB_IDLE_IN_TRANSACTION_TIMEOUT_MS=10000
 
@@ -287,6 +309,13 @@ RETENTION_SOROBAN_EVENTS_DAYS=0
 PPROF_ENABLED=false
 PPROF_ADDR=127.0.0.1:6060
 
+# OPTIONAL  go-api  default: 9091
+# Port the Go REST API serves its Prometheus /metrics endpoint on (issue #58),
+# separate from the public API port. This is a distinct process/port from the
+# Rust indexer's own METRICS_PORT (default 9090) documented above — same env
+# var name, different service.
+METRICS_PORT=9091
+
 # ---------------------------------------------------------------------------
 # Internal /internal/status auth (issue #316)
 # ---------------------------------------------------------------------------