mikael-lovqvists-claude-agent/video-setup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update discovery behaviour — targeted unicast replies, not multicast

Browse Source 
Document that immediate re-announcements go directly to the triggering peer
(unicast) rather than to the multicast group, and explain the two conditions
that trigger a reply: new peer and restarted peer (site_id change).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
mikael-lovqvists-claude-agent
2026-03-30 04:35:28 +00:00
parent a5198e84d2
commit f3a6be0701
2 changed files with 9 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/cli/discovery_cli.md
View File

@@ -1,6 +1,6 @@
# discovery_cli
A development tool for testing the UDP multicast discovery layer. Announces a node on the local network and prints peers as they appear and disappear.
A development tool for testing the discovery layer. Announces a node on the local network via UDP multicast and prints peers as they appear and disappear.
---

10
docs/discovery.md
View File

@@ -43,12 +43,18 @@ A node may set multiple bits — a relay that also archives sets both `RELAY` an
### Behaviour
- Nodes send announcements periodically (e.g. every 5 s) and immediately on startup
- Nodes send announcements periodically (e.g. every 5 s) and immediately on startup via multicast
- No daemon — the node process itself sends and listens; no background service required
- On receiving an announcement, the control plane records the peer (address, port, name, function) and can initiate a transport connection if needed
- On receiving an announcement the control plane records the peer (address, port, name, function) and can initiate a transport connection if needed
- A node going silent for a configured number of announcement intervals is considered offline
- Announcements are informational only — the hub validates identity at connection time
#### Targeted replies
Multicast is only used for the periodic keep-alive broadcast. When a node receives an announcement from a peer it does not yet know, or detects that a known peer has restarted (its `site_id` changed for the same address and port), it sends an **immediate unicast reply** directly back to that peer's IP address. This ensures the new or restarted peer learns about this node quickly without waiting up to `interval_ms`, while avoiding a multicast blast that would unnecessarily wake every other node on the subnet.
Steady-state keepalive packets from already-known peers do not trigger any reply.
### No Avahi/Bonjour Dependency
The system does not link against, depend on, or interact with Avahi or Bonjour. It opens a raw UDP multicast socket directly, which requires only standard POSIX socket APIs. This keeps the runtime dependency footprint minimal and the behaviour predictable.