nexusguard/Nexus-Guard-Suite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

docs: update transport fallback chain with smart reconnection

Browse Source
This commit is contained in:
datadunia
2026-07-04 13:10:40 +07:00
parent c204f75978
commit 1124cd8159
1 changed files with 16 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+16 -9
View File
@@ -73,10 +73,12 @@ NexusGuard SD-WAN Suite: Enterprise Zero-Trust SD-WAN with WireGuard tunneling,
``` ```
### Transport Fallback Chain (Agent → Server) ### Transport Fallback Chain (Agent → Server)
1. gRPC via HTTPS domain (TLS) → `italy-twenty.gl.at.ply.gg:443` 1. gRPC via HTTPS domain (TLS) → `api-nexus.datadunia.com:443`
2. gRPC via WireGuard IP (insecure, tunnel-encrypted) → `10.172.21.1:8080` 2. gRPC via WireGuard IP (insecure, tunnel-encrypted) → `10.172.21.1:8080`
3. HTTP heartbeat (fallback) → `serverURL/api/v1/heartbeat` 3. HTTP heartbeat (fallback) → `serverURL/api/v1/heartbeat`
**Smart reconnection:** If gRPC was never connected (HTTPS blocked by Cloudflare), agent skips HTTPS on reconnect and only tries WG IP. If gRPC was connected before, agent tries last successful transport first.
### Heartbeat = PRIMARY Channel ### Heartbeat = PRIMARY Channel
Always runs. Handles: Always runs. Handles:
- Health check (30s interval) - Health check (30s interval)
@@ -84,12 +86,16 @@ Always runs. Handles:
- Handshake monitoring (rebuilds tunnel if lastHandshake > 120s) - Handshake monitoring (rebuilds tunnel if lastHandshake > 120s)
- Recovery after failure (wasFailing → OnRecovered → full rebuild) - Recovery after failure (wasFailing → OnRecovered → full rebuild)
### gRPC = BONUS Channel ### gRPC = REAL-TIME Channel (when connected)
Best-effort. Handles: Handles with **zero delay**:
- Real-time commands: Suspend, Resume, ConfigUpdate, Reconnect, Disconnect - **ConfigUpdate** → immediate tunnel rebuild (no heartbeat wait)
- Suspend / Resume → immediate tunnel stop/rebuild
- Reconnect / Disconnect → immediate action
- StatusReport from agent (tunnel_up, lastHandshake, state) - StatusReport from agent (tunnel_up, lastHandshake, state)
- Ping/Pong keepalive (20s) - Ping/Pong keepalive (20s)
When gRPC disconnects → falls back to HTTP heartbeat (30s delay for config sync).
### gRPC Port Multiplexing ### gRPC Port Multiplexing
HTTP + gRPC share port 8080 via `cmux`: HTTP + gRPC share port 8080 via `cmux`:
- Server: `cmux.New(lis)` → match gRPC by `content-type` header, match HTTP by `Any()` - Server: `cmux.New(lis)` → match gRPC by `content-type` header, match HTTP by `Any()`
@@ -108,11 +114,12 @@ HTTP + gRPC share port 8080 via `cmux`:
2. Start tunnel (memory-injected, no disk files) 2. Start tunnel (memory-injected, no disk files)
3. Start heartbeat (always, primary channel) 3. Start heartbeat (always, primary channel)
4. Start gRPC (if ServerWGIP available, bonus channel) 4. Start gRPC (if ServerWGIP available, bonus channel)
5. On heartbeat config change → rebuild tunnel 5. On gRPC ConfigUpdate → immediate tunnel rebuild (no delay)
6. On heartbeat stale handshake → rebuild tunnel 6. On heartbeat config change → rebuild tunnel (30s delay, HTTP fallback)
7. On heartbeat failure+recovery → rebuild tunnel 7. On heartbeat stale handshake → rebuild tunnel
8. On gRPC suspend → stop tunnel, heartbeat continues 8. On heartbeat failure+recovery → rebuild tunnel
9. On gRPC resume → rebuild tunnel from server config 9. On gRPC suspend → stop tunnel, heartbeat continues
10. On gRPC resume → rebuild tunnel from server config
### Protobuf Messages ### Protobuf Messages
- **Agent → Server**: HelloMessage, HeartbeatAck, StatusReport, PingMessage - **Agent → Server**: HelloMessage, HeartbeatAck, StatusReport, PingMessage