V0.1.5

[GianIac]

This pull request implements v0.1.5, introducing dynamic peer candidate discovery to Numax while maintaining backward compatibility with static --peer deployments.

Prior to v0.1.5, clustering required knowing and configuring all remote peer addresses statically ($O(N^2)$ operational complexity). This release introduces the PeerDiscovery abstraction, candidate coordination in nx-core, discovery modes (mDNS, Bootstrap Gossip, DNS-SRV, and File Watch), and dynamic endpoint resolution without breaking authentication or transport boundaries.

Architectural Changes & Key Additions:

1. nx-core: Discovery Abstraction & Coordination (crates/nx-core/src/discovery/)

• PeerDiscovery Contract: Defines discover(), watch(), and announce() primitives with atomic snapshot-watch consistency.
• CandidateCoordinator & CandidateRegistry:
  • Aggregates candidates from multiple providers with deterministic ordering and deduplication.
  • Manages candidate source leases, contribution tracking, and clean removal when providers expire or disconnect.
  • Enforces DEFAULT_DISCOVERY_EVENT_CAPACITY and MAX_DISCOVERY_EVENT_CAPACITY limits across broadcast channels.
• Provider Implementations:
  • StaticDiscovery: Preserves backward compatibility with CLI/TOML --peer configurations.
  • MdnsDiscovery: Zero-configuration peer discovery for local networks over UDP multicast 5353.
  • BootstrapGossipDiscovery: Seed-based candidate exchange for bootstrap discovery.
  • DnsSrvDiscovery: Periodic DNS SRV record resolution with TTL-aware polling.
  • FileWatchDiscovery: File-system-based dynamic candidate updates for container orchestrators.

2. nx-net: Bootstrap Protocol & Configuration Validation (crates/nx-net/)

• Bootstrap Protocol: Implements BootstrapClient, BootstrapServer, and WireMessage::bootstrap_hello for exchanging peer candidates during bootstrap.
• Configuration Hardening:
  • Added InvalidConfig variant to NetError for descriptive configuration errors.
  • Introduced NodeConfig::validate() and Node::try_new() to validate peer limits, timeouts, and channel capacities before resource allocation.
  • Enforced strict canonicalization and validation for advertised listening endpoints.
• Cross-Platform Test Hardening: Adjusted TLS bootstrap rejection assertions to avoid OS-specific socket shutdown discrepancies on Windows.

3. nx-cli: Configuration & CLI Integration (crates/nx-cli/)

• Extended DiscoveryMode (static, bootstrap, mdns, dns-srv, file) in TOML and CLI flags:
  • --discovery-mode <MODE>
  • --advertised-endpoint <IP:PORT>
  • --cluster-id <ID>
  • --bootstrap-seed <IP:PORT>
• Precedence chain preserved: CLI flags > Environment variables (NX_*) > TOML config > Defaults.

4. Examples & Verification (examples/discovery_lan/)

• Added real three-daemon mDNS discovery demonstration on LAN (examples/discovery_lan/).
• Verifies zero-configuration mDNS discovery, GCounter CRDT synchronization, clean disconnect detection, durable identity restart, and missed-operation recovery without static --peer.

5. Documentation (docs/nx-site/)

• Added comprehensive design documentation: Peer Discovery Contract.
• Documented advertised endpoint resolution rules (--listen vs --advertised-endpoint, wildcard binds, and dynamic port allocation).
• Updated configuration references, CLI documentation, and roadmap progression.

---

Invariants & Safety Guarantees Preserved:

• Separation of Discovery and Authorization: Discovering an endpoint candidate does not grant authorization. TLS, mTLS, node identity verification, and handshake policies remain strictly enforced by nx-net.
• Deduplication & Convergence: Materialized CRDT state persistence, op-log replay, and deduplication logic in sync_manager remain intact.
• Resource Bounds: Candidate registries and event channels are bounded by max_candidates and MAX_DISCOVERY_EVENT_CAPACITY (4096) to prevent unbounded memory growth.
• Graceful Lifecycle: Long-running discovery tasks use AbortOnDropTask and explicit shutdown triggers for deterministic teardown.