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 # 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 ### 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 - 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 - 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 - 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 ### 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. 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.