Optimize DB pooling, add monitoring; enhance escrow disputes & support docs (#240)

Author: amanosiadnan-cmyk

SUPPORT.md

@@ -0,0 +1,21 @@
+# Support Setup
+
+This document contains a minimal, repo-tracked plan to set up customer support infrastructure.
+
+Goals:
+- Ticketing: integrate Zendesk/Intercom
+- In-app help center: docs and FAQ
+- Support email: support@example.com (placeholder)
+- Basic SLA and escalation templates
+
+Checklist:
+- [ ] Provision Zendesk or Intercom workspace
+- [ ] Configure email routing to support@example.com
+- [ ] Create knowledge base and import `docs/FAQ.md`
+- [ ] Add in-app help center links (frontend changes required)
+- [ ] Train support team and document SLAs
+- [ ] Add basic analytics and alerting for ticket volume
+
+Notes:
+- This file is a starting point and does not perform any automated provisioning.
+- For operational deployment, runbook steps should be executed by the platform team.

backend/src/config.rs

@@ -33,12 +33,36 @@ pub struct DatabaseConfig {
     pub url: String,
     #[serde(default = "default_database_pool_size")]
     pub max_pool_size: usize,
+    #[serde(default = "default_database_min_pool_size")]
+    pub min_pool_size: usize,
+    #[serde(default = "default_pool_resize_threshold_high")]
+    pub resize_threshold_high: f64,
+    #[serde(default = "default_pool_resize_threshold_low")]
+    pub resize_threshold_low: f64,
+    #[serde(default = "default_pool_resize_step")]
+    pub pool_resize_step: usize,
 }
 
 fn default_database_pool_size() -> usize {
     16
 }
 
+fn default_database_min_pool_size() -> usize {
+    4
+}
+
+fn default_pool_resize_threshold_high() -> f64 {
+    75.0
+}
+
+fn default_pool_resize_threshold_low() -> f64 {
+    25.0
+}
+
+fn default_pool_resize_step() -> usize {
+    2
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ServerConfig {
     pub port: u16,
@@ -216,6 +240,10 @@ impl Default for Config {
             database: DatabaseConfig {
                 url: "postgres://localhost/BLINKS".to_string(),
                 max_pool_size: 16,
+                min_pool_size: 4,
+                resize_threshold_high: 75.0,
+                resize_threshold_low: 25.0,
+                pool_resize_step: 2,
             },
             server: ServerConfig { port: 3000 },
             jwt: JwtConfig {

backend/src/db.rs

@@ -1,6 +1,10 @@
 use deadpool_postgres::{Manager, ManagerConfig, Pool, RecyclingMethod, Runtime};
 use std::str::FromStr;
 use tokio_postgres::NoTls;
+use tokio::time::{sleep, Duration};
+use crate::service::MetricsService;
+use std::sync::Arc;
+use std::cmp;
 
 pub type DbPool = Pool;
 
@@ -38,6 +42,104 @@ pub async fn run_migrations(database_url: &str) -> Result<(), Box<dyn std::error
     Ok(())
 }
 
+/// Start a background task that monitors database connections and updates metrics.
+///
+/// - `database_url`: Postgres connection string used for monitoring queries.
+/// - `configured_max_size`: the configured pool max size from configuration.
+/// - `check_interval_secs`: how often to poll Postgres for connection counts.
+///
+/// Returns a JoinHandle for the spawned task. The task will run until cancelled.
+pub fn start_db_pool_monitoring(
+    database_url: String,
+    configured_max_size: usize,
+    check_interval_secs: u64,
+) -> tokio::task::JoinHandle<()> {
+    tokio::spawn(async move {
+        loop {
+            match tokio_postgres::Config::from_str(&database_url)
+                .and_then(|cfg| cfg.connect(NoTls))
+            {
+                Ok((client, connection)) => {
+                    // detach connection handling
+                    tokio::spawn(async move {
+                        if let Err(e) = connection.await {
+                            tracing::warn!(error = %e, "Postgres monitor connection error");
+                        }
+                    });
+
+                    // Query active connections for this database
+                    match client
+                        .query_one(
+                            "SELECT count(*) FROM pg_stat_activity WHERE datname = current_database()",
+                            &[],
+                        )
+                        .await
+                    {
+                        Ok(row) => {
+                            let active: i64 = row.get(0);
+                            let active_usize = cmp::min(active as usize, 1_000_000);
+                            MetricsService::update_db_pool_status(configured_max_size, active_usize);
+                        }
+                        Err(e) => tracing::warn!(error = %e, "Failed to query pg_stat_activity"),
+                    }
+
+                    let _ = client.close().await;
+                }
+                Err(e) => tracing::error!(error = %e, "Failed to connect to Postgres for monitoring"),
+            }
+
+            sleep(Duration::from_secs(check_interval_secs)).await;
+        }
+    })
+}
+
+/// Health check for database connectivity.
+pub async fn health_check_db(database_url: &str) -> bool {
+    match tokio_postgres::Config::from_str(database_url)
+        .and_then(|cfg| cfg.connect(NoTls))
+        .await
+    {
+        Ok((mut client, connection)) => {
+            // drive connection
+            tokio::spawn(async move {
+                let _ = connection.await;
+            });
+
+            let res = client.query_one("SELECT 1", &[]).await.is_ok();
+            let _ = client.close().await;
+            res
+        }
+        Err(_) => false,
+    }
+}
+
+/// Recommend a new pool size based on current utilization and configuration.
+/// This function does not mutate or rebuild the pool; it only suggests a size.
+pub fn recommend_pool_size(
+    current_max: usize,
+    active_connections: usize,
+    min_pool_size: usize,
+    resize_step: usize,
+    high_threshold: f64,
+    low_threshold: f64,
+) -> usize {
+    if current_max == 0 {
+        return current_max;
+    }
+
+    let utilization = (active_connections as f64 / current_max as f64) * 100.0;
+
+    if utilization >= high_threshold {
+        // scale up
+        current_max.saturating_add(resize_step)
+    } else if utilization <= low_threshold && current_max > min_pool_size {
+        // scale down but not below min
+        current_max.saturating_sub(resize_step).max(min_pool_size)
+    } else {
+        current_max
+    }
+}
+
 /// Reset migrations for testing purposes
 /// This drops all tables, types, and the migration history to allow re-running migrations
 /// WARNING: Only use this in test environments! This will destroy all data in the database.

backend/src/http/metrics.rs

@@ -61,8 +61,11 @@ pub async fn prometheus_metrics() -> impl IntoResponse {
 /// - errorRate: number (percentage)
 pub async fn json_metrics(State(services): State<Arc<ServiceContainer>>) -> Json<MetricsResponse> {
     // Update database pool metrics
-    let db_pool_size = services.db_pool.status().size;
-    MetricsService::update_db_pool_metrics(db_pool_size);
+    let status = services.db_pool.status();
+    let db_pool_size = status.size;
+    // active connections = size - available (deadpool status exposes `available`)
+    let active_connections = db_pool_size.saturating_sub(status.available);
+    MetricsService::update_db_pool_status(db_pool_size, active_connections);
 
     let detailed = MetricsService::get_detailed_metrics();
 

backend/src/service/metrics_service.rs

@@ -62,6 +62,20 @@ lazy_static! {
     )
     .expect("Can't create db_pool_connections metric");
 
+    /// Database pool max size gauge
+    pub static ref DB_POOL_MAX_SIZE: Gauge = register_gauge!(
+        "db_pool_max_size",
+        "Configured maximum size of the database connection pool"
+    )
+    .expect("Can't create db_pool_max_size metric");
+
+    /// Database pool utilization percentage (0.0 - 100.0)
+    pub static ref DB_POOL_UTILIZATION: Gauge = register_gauge!(
+        "db_pool_utilization_percent",
+        "Current database pool utilization as a percentage"
+    )
+    .expect("Can't create db_pool_utilization_percent metric");
+
     pub static ref CACHE_EVENTS_TOTAL: CounterVec = register_counter_vec!(
         "cache_events_total",
         "Total cache events by operation and outcome",
@@ -422,7 +436,22 @@ pub struct AlertPayload {
 
     /// Update database pool metrics
     pub fn update_db_pool_metrics(active_connections: usize) {
+        // Backwards-compatible: treat argument as pool size when no active count available
+        DB_POOL_CONNECTIONS.set(active_connections as f64);
+        DB_POOL_MAX_SIZE.set(active_connections as f64);
+        DB_POOL_UTILIZATION.set(100.0);
+    }
+
+    /// Update DB pool status with both configured max size and active connections
+    pub fn update_db_pool_status(pool_max_size: usize, active_connections: usize) {
+        DB_POOL_MAX_SIZE.set(pool_max_size as f64);
         DB_POOL_CONNECTIONS.set(active_connections as f64);
+        let utilization = if pool_max_size == 0 {
+            0.0
+        } else {
+            (active_connections as f64 / pool_max_size as f64) * 100.0
+        };
+        DB_POOL_UTILIZATION.set(utilization);
     }
 
     pub fn record_cache_event(operation: &str, outcome: &str) {