suaveplan/packages/networking/network/network-plugin-intra-relay/README.md

@suaveplan/network-plugin-intra-relay - Intra-mesh peer-to-peer relay: RelayDiscovery (topology-driven candidate set with leaf exclusion), RelaySelector (5 strategies — LowestLatency / HighestReliability / FewestHops / TierOptimized / LoadBalanced), RelayConnectionManager (pending → active → degraded → closed FSM), RelayMessageEnvelope (hop-count + visited-nodes wrapper), LoopPrevention, RelayPerformanceMonitor, RelaySecurityManager (peer authentication, ed25519 signature validation, per-peer + global token-bucket rate limiting), and IntraRelayPlugin facade.

Summary

Intra-mesh peer-to-peer relay for the Suaveplan network. When direct WebRTC fails (symmetric NAT, restrictive firewall), IntraRelayPlugin routes the message through an intermediate peer in the same mesh. RelayDiscovery builds a candidate set from peer:connected bus events and explicitly excludes leaf-tier peers (which lack forwarding capacity); RelaySelector picks the optimal relay using one of five strategies (lowest-latency, highest-reliability, fewest-hops, tier-optimized, load-balanced) with a deterministic peer-id tiebreak; RelayConnectionManager runs a pending → active → degraded → closed finite-state machine per (sourceId, targetId) pair and auto-closes paths after a configurable idle timeout; RelayMessageEnvelope wraps the original MessageEnvelope with relayPath / hopCount / maxHops / visitedNodes; LoopPrevention drops envelopes that exceed maxHops (default 8) or whose visitedNodes already contain the current peer, emitting relay:loop-detected for observability; RelayPerformanceMonitor samples per-path RTT and emits relay:degraded / relay:recovered when quality crosses configurable thresholds; RelaySecurityManager (optional, opt-in via IntraRelayPluginConfig.security) enforces a trusted-peer allowlist, validates ed25519 signatures over canonical bytes, and applies per-peer + global token-bucket rate limits to prevent DoS. Wrapped in a single IntraRelayPlugin satisfying the NetworkPlugin lifecycle.

Documentation tree

• connection — (no submodules)
  • relay-connection-manager — (no submodules)
• discovery — (no submodules)
  • relay-discovery — (no submodules)
• envelope — (no submodules)
  • relay-envelope — (no submodules)
• loop — (no submodules)
  • loop-prevention — (no submodules)
• monitor — (no submodules)
  • relay-performance-monitor — (no submodules)
• plugin — (no submodules)
  • intra-relay-plugin — (no submodules)
• security — (no submodules)
  • relay-security-manager — (no submodules)
• selector — (no submodules)
  • relay-selector — (no submodules)
• error-codes — Frozen NET_INTRA_RELAY error registry for @suaveplan/network-plugin-intra-relay. Every failure path the relay subsy…

- [relay-connection-manager](./src/connection/relay-connection-manager.md) — _(no submodules)_- [discovery](./src/discovery/relay-discovery.md) — _(no submodules)_- [relay-discovery](./src/discovery/relay-discovery.md) — _(no submodules)_- [envelope](./src/envelope/relay-envelope.md) — _(no submodules)_- [relay-envelope](./src/envelope/relay-envelope.md) — _(no submodules)_- [loop](./src/loop/loop-prevention.md) — _(no submodules)_- [loop-prevention](./src/loop/loop-prevention.md) — _(no submodules)_- [monitor](./src/monitor/relay-performance-monitor.md) — _(no submodules)_- [relay-performance-monitor](./src/monitor/relay-performance-monitor.md) — _(no submodules)_- [plugin](./src/plugin/intra-relay-plugin.md) — _(no submodules)_- [intra-relay-plugin](./src/plugin/intra-relay-plugin.md) — _(no submodules)_- [security](./src/security/relay-security-manager.md) — _(no submodules)_- [relay-security-manager](./src/security/relay-security-manager.md) — _(no submodules)_- [selector](./src/selector/relay-selector.md) — _(no submodules)_- [relay-selector](./src/selector/relay-selector.md) — _(no submodules)_- [error-codes](./src/error-codes.md) — Frozen `NET_INTRA_RELAY` error registry for `@suaveplan/network-plugin-intra-relay`. Every failure path the relay subsy…

• relay-connection-manager — (no submodules)- discovery — (no submodules)- relay-discovery — (no submodules)- envelope — (no submodules)- relay-envelope — (no submodules)- loop — (no submodules)- loop-prevention — (no submodules)- monitor — (no submodules)- relay-performance-monitor — (no submodules)- plugin — (no submodules)- intra-relay-plugin — (no submodules)- security — (no submodules)- relay-security-manager — (no submodules)- selector — (no submodules)- relay-selector — (no submodules)- error-codes — Frozen NET_INTRA_RELAY error registry for @suaveplan/network-plugin-intra-relay. Every failure path the relay subsy…
• relay-connection-manager — (no submodules)- discovery — (no submodules)- relay-discovery — (no submodules)- envelope — (no submodules)- relay-envelope — (no submodules)- loop — (no submodules)- loop-prevention — (no submodules)- monitor — (no submodules)- relay-performance-monitor — (no submodules)- plugin — (no submodules)- intra-relay-plugin — (no submodules)- security — (no submodules)- relay-security-manager — (no submodules)- selector — (no submodules)- relay-selector — (no submodules)- error-codes — Frozen NET_INTRA_RELAY error registry for @suaveplan/network-plugin-intra-relay. Every failure path the relay subsy…
• relay-connection-manager — (no submodules)- discovery — (no submodules) - relay-discovery — (no submodules)- envelope — (no submodules) - relay-envelope — (no submodules)- loop — (no submodules) - loop-prevention — (no submodules)- monitor — (no submodules) - relay-performance-monitor — (no submodules)- plugin — (no submodules) - intra-relay-plugin — (no submodules)- security — (no submodules) - relay-security-manager — (no submodules)- selector — (no submodules) - relay-selector — (no submodules)- error-codes — Frozen NET_INTRA_RELAY error registry for @suaveplan/network-plugin-intra-relay. Every failure path the relay subsy…

Modules

• Connection
• Discovery
• Envelope
• Error codes
• Loop prevention
• Performance monitor
• Plugin facade
• Security manager
• Selector
• Types — relay
• Types — security