HostProcessor Connection Logic

HostProcessor Connection Logic - Quick Reference

🎯 Decision Tree: Wire Processing

Incoming Wire from Beacon
├─ wire.id == installId? → SKIP (it's me)
├─ wire.type == Server or Client?
│  │
│  ├─ NodeManager has wire.id?
│  │  │
│  │  ├─ NO (New Peer) ────────────────────────┐
│  │  │                                         │
│  │  └─ YES (Known Peer)                       │
│  │     │                                      │
│  │     ├─ Session known?                      │
│  │     │  │                                   │
│  │     │  ├─ NO → NEW SESSION ────────┐      │
│  │     │  │                            │      │
│  │     │  └─ YES → DUPLICATE ──────┐   │      │
│  │                                  │   │      │
│  │                                  ▼   ▼      ▼
│  │                            [Duplicate] [Reconnect] [New Peer]
│  │
│  └─ Process accordingly
│
└─ Other type → LOG WARNING

📋 Scenarios & Actions

Scenario 1: New Peer Discovered

Condition: NodeManager returns NodeFlow.Error (doesn’t have this node ID)

Actions:

1. peerSessionManager.add(wire.id, wire.sessionId)
2. nodeManager.update(wire.toNode())  // Create stub
3. If wire.type == Server:
   └─ serverHandshakeProcess.trustServer(wire)
4. If wire.type == Client:
   └─ beaconManager.sendSignal(node)  // Advertise back

Example:

• Client starts for first time → Server discovers it → Server advertises back

---

Scenario 2: Known Peer, New Session (RESTART)

Condition: NodeManager has node, but session is NEW

Actions:

1. peerSessionManager.add(wire.id, wire.sessionId)  // Update session
2. nodeManager.update(wire.toNode())  // Update metadata
3. If wire.type == Server:
   ├─ serverHandshakeProcess.trustServer(wire)  // Re-establish
   └─ If I'm also Server:
      └─ beaconManager.sendSignal(node)  // Advertise back
4. If wire.type == Client:
   └─ beaconManager.sendSignal(node)  // Advertise

Example:

• Server crashes and restarts → Client receives new sessionId → Client re-establishes connection

---

Scenario 3: Known Peer, Same Session (DUPLICATE)

Condition: NodeManager has node AND session is KNOWN

Actions:

1. nodeManager.update(wire.toNode())  // Update metadata only
2. NO re-establishment (prevent loops)

Example:

• Server sends multiple beacons → Client ignores after first

---

🔄 Session Lifecycle

Server Starts
    ↓
Generates sessionId = UUID
    ↓
Broadcasts beacon with sessionId
    ↓
Client receives
    ↓
peerSessionManager.add(serverId, sessionId)
    ↓
[Server Running] ← Periodic beacons → [Client knows session]
    ↓
Server Crashes
    ↓
Client still has old sessionId in memory
    ↓
Server Restarts
    ↓
Generates NEW sessionId = UUID
    ↓
Broadcasts beacon with NEW sessionId
    ↓
Client receives
    ↓
isKnownSession(new sessionId) = FALSE
    ↓
Client detects RECONNECTION scenario
    ↓
peerSessionManager.add(serverId, NEW sessionId)  // Overwrites old
    ↓
Re-establish connection (trustServer, etc.)

---

🚦 Thread Safety Checkpoints

Step	Mutex Protection	Purpose
Beacon received	BeaconService.wireProcessingMutex	Prevent concurrent wire handling
Wire processing	HostProcessor.wireProcessingMutex	Serialize decision logic
Session check	PeerSessionManager.mutex	Safe map access
Session update	PeerSessionManager.mutex	Safe map modification
Node update	NodeManager.nodesMutex	Safe node map access

---

🎯 Type-Specific Logic

If Wire Type = Server

when {
    new peer -> {
        trustServer(wire)  // Download certs, nodes, open WebSocket
    }
    known peer, new session -> {
        trustServer(wire)  // RE-download everything
        if (I'm also a server) {
            sendSignal(node)  // Server-to-server discovery
        }
    }
    known peer, same session -> {
        update(wire.toNode())  // Metadata only
    }
}

If Wire Type = Client

when {
    new peer -> {
        sendSignal(node)  // Advertise myself to new client
    }
    known peer, new session -> {
        sendSignal(node)  // Re-advertise (client restarted)
    }
    known peer, same session -> {
        update(wire.toNode())  // Metadata only
    }
}

---

🔍 Debugging Checklist

If client doesn’t reconnect after server restart:

1. Check: Is new beacon being sent? (Server should auto-broadcast)
2. Check: Is client receiving wire? (Should log “received wire: Server from {id}”)
3. Check: Is session check working? (Should log “known session: false”)
4. Check: Is trustServer() being called? (Should log “Re-establishing connection”)
5. Check: Are there any exceptions? (Check error logs)

If getting duplicate connection attempts:

1. Check: BeaconService jobs map size (should be 1 per node.id)
2. Check: Is session being properly updated? (Old session should be overwritten)
3. Check: Are duplicate beacons hitting the “known session: true” path?

If session state corruption:

1. Check: All PeerSessionManager calls are suspend and use mutex
2. Check: No direct access to knownSessions map outside of mutex
3. Verify: LazyThreadSafetyMode.SYNCHRONIZED on all by inject()

---

📊 Expected Log Sequence

New Client Connects to Server

Server logs:

[INFO] emit: Client
[INFO] Starting beacon service for node {client-id}
[INFO] received wire: Client from {client-id}
[INFO] Discovered new Client. known session: false
[INFO] Beacon service started and initial signal sent

Client logs:

[INFO] emit: Server
[INFO] received wire: Server from {server-id}
[INFO] Discovered new Server. known session: false
[INFO] Re-establishing connection to server

Server Restarts (Client Already Running)

Server logs:

[INFO] emit: Server
[INFO] Starting beacon service for node {server-id}
[INFO] Beacon service started and initial signal sent

Client logs:

[INFO] received wire: Server from {server-id}
[INFO] Received wire from known Server. known session: false
[INFO] Known Server with NEW session - handling reconnection
[INFO] Re-establishing connection to restarted server {server-id}