d-bis/smoa
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Backend, sync, infra, docs: ETag, API versioning, k8s, web scaffold, Android 16, domain stubs

Browse Source 
- Backend: ShallowEtagHeaderFilter for /api/v1/*, API-VERSIONING.md, README (tenant, CORS, Flyway, ETag)
- k8s: backend-deployment.yaml (Deployment, Service, Secret/ConfigMap)
- Web: scaffold with directory pull, 304 handling, touch-friendly UI
- Android 16: ANDROID-16-TARGET.md; BuildConfig STUN/signaling, SMOAApplication configures InfrastructureManager
- Domain: CertificateManager revocation stub, ReportService signReports, ZeroTrust/ThreatDetection minimal docs
- TODO.md and IMPLEMENTATION_STATUS.md updated; communications README for endpoint config

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
2026-02-10 20:37:01 -08:00
parent 97f75e144f
commit 5a8c26cf5d
101 changed files with 4923 additions and 103 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docs/reference/SMART-ROUTING-AND-QOS.md Normal file
View File

@@ -0,0 +1,68 @@
# Smart Routing, QoS, Lag Reduction, and System Stability
## Overview
SMOA implements **smart routing** and **QoS (Quality of Service)** for media (voice/video) to improve quality, reduce lag, manage infrastructure, and keep the system stable under poor conditions.
## Components
### Core (core/common)
| Component | Purpose |
|-----------|---------|
| **CircuitBreaker** | Per-endpoint failure handling: after N failures the circuit opens and calls fail fast until reset timeout. Used by InfrastructureManager for STUN/TURN/signaling. |
| **QoSPolicy / TrafficClass** | Traffic classification (VOICE, VIDEO, SIGNALING, DATA) and priority; policy caps (max concurrent sessions, max total send bitrate) for stability. |
| **ConnectivityManager** | Extended with `getActiveTransportType()` (WIFI, CELLULAR, VPN, ETHERNET) and `getCellularGeneration()` (4G LTE, 5G, 5G MW) for path selection. |
| **NetworkTransportType** | Enum for transport used by routing policy. |
| **CellularGeneration** | When on cellular: LTE_4G, NR_5G, NR_5G_MW (millimeter wave), UNKNOWN. Used to prefer 5G / 5G MW over 4G. |
### Communications (modules/communications)
| Component | Purpose |
|-----------|---------|
| **MediaRoutingPolicy** | Path preference: prefer low latency, prefer VPN when required, transport order, path failover, min bandwidth for video. |
| **NetworkPathSelector** | Selects best network path for media using ConnectivityManager, VPNManager, and MediaRoutingPolicy; exposes `SelectedPath` (transport, cellularGeneration when CELLULAR, recommendedForVideo). On cellular, ranks 4G LTE, 5G, and 5G MW per policy. |
| **InfrastructureManager** | Manages STUN/TURN/signaling endpoint lists; uses CircuitBreaker for health; `getHealthyStunUrls()`, `getHealthyTurnServers()`, `getHealthySignalingUrl()`; `buildWebRTCConfig()` for WebRTC with failover. |
| **ConnectionStabilityController** | Reconnection exponential backoff; degradation mode (NONE, AUDIO_ONLY, REDUCED_VIDEO); session count and bitrate caps from QoSPolicy. |
| **SmartRoutingService** | Orchestrates path selection, infra, stability, and adaptive codecs; exposes `RoutingState`, `getWebRTCConfig()`, `tryStartSession()`, `recordConnectionSuccess/Failure`, `updateFromConnectionQuality()`, `onConnectivityChanged()`. |
## QoS and Lag Reduction
- **Traffic classes**: Voice (highest), Video, Signaling, Data. Used for scheduling and prioritization hints.
- **Path selection**: Prefer Wi-Fi/VPN over cellular when policy says so; when on cellular, prefer 5G MW &gt; 5G &gt; 4G LTE (configurable via `cellularGenerationPreferenceOrder`). Avoid sending video when path is not recommended.
- **Adaptive codecs**: Connection-speed-aware codecs (see [MEDIA-CODECS-AND-P2M.md](MEDIA-CODECS-AND-P2M.md)) reduce bitrate on slow links, reducing buffering and lag.
- **Reconnection backoff**: Exponential backoff after connection failures to avoid hammering endpoints and reduce perceived instability.
- **Graceful degradation**: When connection tier is VERY_LOW (or policy says so), switch to AUDIO_ONLY to preserve voice and reduce load.
## Infrastructure Management
- **STUN/TURN/signaling**: Configure via `InfrastructureManager.setStunEndpoints()`, `setTurnEndpoints()`, `setSignalingEndpoints()`.
- **Health**: Each endpoint is protected by a circuit breaker; after a threshold of failures the endpoint is skipped until reset timeout.
- **Failover**: `getHealthyStunUrls()` / `getHealthyTurnServers()` / `getHealthySignalingUrl()` return only endpoints with closed circuits; WebRTC config is built from these for automatic failover.
## System Stability
- **Session cap**: `QoSPolicy.maxConcurrentSessions` limits concurrent media sessions; `SmartRoutingService.tryStartSession()` enforces it.
- **Bitrate cap**: `QoSPolicy.maxTotalSendBitrateBps` can be enforced by the app when sending (ConnectionStabilityController.isWithinBitrateCap()).
- **Circuit breakers**: Prevent cascading failures to unhealthy STUN/TURN/signaling servers.
- **Degradation**: AUDIO_ONLY and REDUCED_VIDEO reduce load when quality is poor.
## Integration
- **WebRTCManager**: Uses `SmartRoutingService.getWebRTCConfig()` for ICE/signaling config (healthy infra) and adaptive codec constraints.
- **VideoTransport** (meetings): Uses `SmartRoutingService.tryStartSession()` / `notifySessionEnded()`, `getRoutingState().recommendedForVideo` to decide audio-only vs video, and `recordConnectionSuccess/Failure()` for backoff.
- **Connectivity changes**: Call `SmartRoutingService.onConnectivityChanged()` when connectivity or VPN state changes so path selection and routing state are updated.
- **Quality updates**: When WebRTC stats (or network callback) provide new bandwidth/RTT/loss, update the connection quality monitor and call `SmartRoutingService.updateFromConnectionQuality()` to adapt codecs and degradation.
## Configuration
- **MediaRoutingPolicy**: Default prefers low latency and VPN when required; customize transport order, `cellularGenerationPreferenceOrder` (4G LTE, 5G, 5G MW), and `minBandwidthKbpsForVideo` per deployment. Cellular generation is derived from `TelephonyManager` (API 29+ for 5G NR; API 31+ for 5G MW when `OVERRIDE_NETWORK_TYPE_NR_ADVANCED` is reported).
- **QoSPolicy**: Set via `SmartRoutingService.setQoSPolicy()` (session cap, bitrate cap).
- **Circuit breaker**: Threshold and reset timeout are in InfrastructureManager (e.g. 3 failures, 60s reset); adjust as needed.
- **StabilityController**: `minBackoffMs`, `maxBackoffMs`, `backoffMultiplier` control reconnection backoff.
## Related
- [MEDIA-CODECS-AND-P2M.md](MEDIA-CODECS-AND-P2M.md) – Connection-speed-aware audio/video codecs and point-to-multipoint.
- Communications module: `modules/communications/domain/`.
- Core common: `core/common/` (CircuitBreaker, QoS, ConnectivityManager).