Module lag 

Replica Lag-Aware Routing Module

This module provides lag-aware query routing for HeliosProxy, ensuring queries are routed to replicas that meet freshness requirements.

Features

• Continuous lag monitoring via WAL position tracking
• Read-your-writes consistency guarantees
• Configurable lag thresholds per sync mode
• Integration with routing hints (/*helios:lag=X*/)

Architecture

Query + Lag Hint
      │
      ▼
┌─────────────────┐
│  LagAwareRouter │──────► LagMonitor
│                 │        (node lag data)
│  - Extract hint │
│  - Check RYW    │──────► RYWTracker
│  - Filter nodes │        (session LSNs)
└─────────────────┘
      │
      ▼
  Eligible Nodes

Example

use heliosdb::proxy::lag::{LagMonitor, LagAwareRouter, LagRoutingConfig};

let config = LagRoutingConfig::default();
let monitor = LagMonitor::new(config.poll_interval);
let router = LagAwareRouter::new(monitor, config);

// Route with freshness requirement
let decision = router.route(query, session_id, Some(Duration::from_millis(100)));

Re-exports

pub use config::LagCalculation;

pub use config::LagRoutingConfig;

pub use config::SyncModeLagConfig;

pub use metrics::LagMetrics;

pub use metrics::LagStatsSnapshot;

pub use metrics::NodeLagStats;

pub use monitor::LagInfo;

pub use monitor::LagMonitor;

pub use monitor::LagTrend;

pub use monitor::NodeLagData;

pub use router::LagAwareRouter;

pub use router::LagRoutingDecision;

pub use router::LagRoutingReason;

pub use ryw::ReadYourWritesTracker;

pub use ryw::RywSession;

pub use ryw::WorkflowConsistency;

pub use ryw::WorkflowTracker;

Modules

config

Lag routing configuration types

metrics

Lag Routing Metrics

monitor

Lag Monitor - Continuous replication lag tracking

router

Lag-Aware Router - Route queries based on freshness requirements

ryw

Read-Your-Writes (RYW) Consistency Tracker

Enums

SyncMode

SyncMode enum for replica synchronization classification