mirror of https://github.com/jmcorgan/fips.git synced 2026-07-22 07:48:26 +00:00

Files

Johnathan Corgan 56d39f223b Add ECN congestion signaling and transport congestion detection

Implement hop-by-hop ECN congestion signaling through the FMP layer,
transport-level congestion detection via kernel drop counters, and
chaos harness integration for end-to-end validation.

FMP/session ECN plumbing:

- Thread ce_flag parsed at link layer through dispatch_link_message,
  handle_session_datagram, handle_session_payload, and
  handle_encrypted_session_msg to session delivery
- Replace hardcoded false in session-layer record_recv() with actual
  ce_flag, activating ecn_ce_count tracking in session MMP

ECN congestion detection and CE relay:

- Add EcnConfig (node.ecn.*) with configurable loss_threshold (5%)
  and etx_threshold (3.0) for transit congestion detection
- Add send_encrypted_link_message_with_ce() that ORs FLAG_CE into FMP
  header flags; original method delegates with ce_flag=false
- Compute outgoing_ce = incoming_ce || local congestion on next-hop
  link, enabling hop-by-hop CE relay through transit nodes

IPv6 ECN-CE marking:

- Mark ECN-CE (0b11) in IPv6 Traffic Class on received DataPackets
  before TUN delivery when FMP CE flag is set
- Only marks ECN-capable packets (ECT(0)/ECT(1)); Not-ECT packets
  unchanged per RFC 3168

Transport congestion abstraction and UDP kernel drop detection:

- Add TransportCongestion struct to transport layer for transport-
  agnostic local congestion indicators
- Replace tokio::UdpSocket with AsyncFd<socket2::Socket> using
  libc::recvmsg() with ancillary data parsing
- Enable SO_RXQ_OVFL for kernel receive buffer drop counter on every
  packet, wiring up previously-stubbed UdpStats.kernel_drops
- Add TransportDropState for per-transport delta tracking with 1s
  tick sampling via sample_transport_congestion()
- Extend detect_congestion() with transport kernel drop check
  alongside MMP loss metrics

Congestion monitoring and control:

- Add CongestionStats (ce_forwarded, ce_received, congestion_detected,
  kernel_drop_events) to NodeStats with snapshot serialization
- Wire counters into forwarding path, session handler, and transport
  drop sampling with rate-limited warn logging (5s interval)
- Expose congestion data in show_routing control query and
  ecn_ce_count in show_mmp peer entries
- Add congestion counters to fipstop routing tab in two-column layout

Chaos harness integration:

- Add query_routing(), query_transports(), snapshot_all_congestion()
  to chaos control module
- Add congestion/kernel-drop log analysis in logs module
- Add congestion-stress scenario: 10-node tree, 1 Mbps bandwidth,
  5-10% netem loss, heavy iperf3 traffic
- Add IngressConfig for tc ingress policing with per-peer policer
  filters simulating upstream bandwidth bottlenecks
- Add iperf3 JSON result capture to traffic manager for throughput
  measurement across scenarios
- Add ECN A/B test scenarios (ecn-ab-on/off.yaml) with ingress
  policing and comparison script
- Enable TCP ECN negotiation (tcp_ecn=1 sysctl) in container
  entrypoint for end-to-end CE propagation

Tests:

- 10 ECN unit/integration tests: mark_ipv6_ecn_ce variants, CE relay
  chain (3-node propagation), EcnConfig serde roundtrip
- 3 transport drop congestion detection unit tests

Documentation:

- Update fips-mesh-layer.md: replace outdated CE Echo stub with full
  ECN Congestion Signaling section covering detection logic, CE relay,
  IPv6 marking, session tracking, and monitoring counters
- Update fips-configuration.md: add node.ecn.* parameter table and
  ecn block in complete reference YAML
- Update fips-transport-layer.md: add Congestion Reporting section
  with TransportCongestion struct, congestion() trait method, and
  per-transport status; document AsyncFd/recvmsg/SO_RXQ_OVFL in UDP
- Update chaos README: add congestion/ECN scenario docs, ingress
  traffic control, and iperf3 JSON capture sections
- Update README.md: add ECN to features list and "What works today";
  update transport and tooling entries

2026-03-05 17:05:57 +00:00

7.2 KiB

Raw Blame History

FIPS: Free Internetworking Peering System

A distributed, decentralized network routing protocol for mesh nodes connecting over arbitrary transports.

Status: Alpha (0.1.0)

FIPS is under active development. The protocol and APIs are not stable. Expect breaking changes. See Status & Roadmap below.

Overview

FIPS is a self-organizing mesh network that operates natively over a variety of physical and logical media — local area networks, Bluetooth, serial links, radio, or the existing internet as an overlay. Nodes generate their own identities, discover each other, and route traffic without any central authority or global topology knowledge.

FIPS uses Nostr keypairs (secp256k1/schnorr) as native node identities, making every Nostr user a potential network participant. Nodes address each other by npub, and the same cryptographic identity used in the Nostr ecosystem serves as both the routing address and the basis for end-to-end encrypted sessions across the mesh.

Features

Self-organizing mesh routing — spanning tree coordinates and bloom filter candidate selection, no global routing tables
Multi-transport — UDP/IP overlay today; designed for Ethernet, Bluetooth, serial, radio, and Tor
Noise encryption — hop-by-hop link encryption plus independent end-to-end session encryption
Nostr-native identity — secp256k1 keypairs as node addresses, no registration or central authority
IPv6 adaptation — TUN interface maps npubs to fd00::/8 addresses for unmodified IP applications
Metrics Measurement Protocol — per-link RTT, loss, jitter, and goodput measurement
ECN congestion signaling — hop-by-hop CE flag relay with RFC 3168 IPv6 marking, transport kernel drop detection
Operator visibility — fipsctl control socket interface for runtime inspection of peers, links, sessions, tree state, and metrics
Zero configuration — sensible defaults; a node can start with no config file, though peer addresses are needed to join a network

Quick Start

Requirements

Rust 1.85+ (edition 2024)
Linux (TUN interface requires CAP_NET_ADMIN or root)

Build

git clone https://github.com/jmcorgan/fips.git
cd fips
cargo build --release

Run

# Start with default search paths (see below):
sudo ./target/release/fips

# With an explicit configuration file:
sudo ./target/release/fips -c fips.yaml

Without -c, the node searches for fips.yaml in these locations (highest priority first, values from later files override earlier ones):

./fips.yaml (current directory)
~/.config/fips/fips.yaml (user config)
/etc/fips/fips.yaml (system)

If no config file is found, the node starts with defaults (ephemeral identity, default ports, no peers).

A minimal two-node setup (each node points at the other):

# node-a.yaml                          # node-b.yaml
node:                                  # node:
  identity:                            #   identity:
    nsec: "nsec1aaa..."                #     nsec: "nsec1bbb..."
transports:                            # transports:
  udp:                                 #   udp:
    bind_addr: "0.0.0.0:2121"          #     bind_addr: "0.0.0.0:2121"
peers:                                 # peers:
  - npub: "npub1bbb..."                #   - npub: "npub1aaa..."
    addresses:                         #     addresses:
      - transport: udp                 #       - transport: udp
        addr: "10.0.0.2:2121"          #         addr: "10.0.0.1:2121"

The nsec field accepts bech32 (nsec1...) or hex-encoded secret keys. Omit it entirely for an ephemeral identity that changes each restart.

See docs/design/fips-configuration.md for the full configuration reference.

Test Connectivity

FIPS includes a built-in DNS resolver (enabled by default, port 5354) that maps .fips names to fd00::/8 IPv6 addresses derived from each node's public key. Configure your system to send .fips queries to it.

With systemd-resolved:

sudo resolvectl dns fips0 127.0.0.1:5354
sudo resolvectl domain fips0 ~fips

Or manually in /etc/resolv.conf (routes all DNS through FIPS for .fips names only if your resolver supports conditional forwarding; otherwise this sets it as a general nameserver):

nameserver 127.0.0.1
options port:5354

Once DNS is configured, ping a peer by npub:

ping6 npub1bbb....fips

Any IPv6-capable application can reach FIPS nodes this way — ping6, ssh, curl, etc.

Inspect

While a node is running, use fipsctl to inspect its state:

fipsctl show status       # Node status overview
fipsctl show peers        # Authenticated peers
fipsctl show links        # Active links
fipsctl show tree         # Spanning tree state
fipsctl show sessions     # End-to-end sessions
fipsctl show bloom        # Bloom filter state
fipsctl show mmp          # MMP metrics summary
fipsctl show cache        # Coordinate cache stats
fipsctl show connections  # Pending handshake connections
fipsctl show transports   # Transport instances
fipsctl show routing      # Routing table summary

fipsctl communicates with the node via a Unix domain control socket (enabled by default). All queries are read-only. Use -s <path> to override the socket path.

Multi-node Testing

See testing/ for Docker-based integration test harnesses including static topology tests and stochastic chaos simulation.

Documentation

Protocol design documentation is in docs/design/, organized as a layered protocol specification. Start with fips-intro.md for the full protocol overview.

Project Structure

src/          Rust source (library + fips/fipsctl binaries)
docs/design/  Protocol design specifications
testing/      Docker-based integration test harnesses

Status & Roadmap

FIPS is at v0.1.0 (alpha). The core protocol works end-to-end over UDP/IP overlays but has not been tested beyond small meshes.

What works today

Spanning tree construction with greedy coordinate routing
Bloom filter discovery for finding nodes without global state
Noise IK (link layer) and Noise XK (session layer) encryption
IPv6 TUN adapter with DNS resolution of .fips names
Per-link metrics (RTT, loss, jitter, goodput)
ECN congestion signaling (hop-by-hop CE relay, IPv6 CE marking, kernel drop detection)
UDP, TCP, and Ethernet transports
Runtime inspection via fipsctl and fipstop
Docker-based integration and chaos testing

Near-term priorities

Peer discovery via Nostr relays (bootstrap without static peer lists)
Additional transports (Bluetooth, Tor)
Improved routing resilience under churn
Security audit of cryptographic protocols
CI pipeline and published crate

Longer-term

Mobile platform support
Bandwidth-aware routing and QoS
Protocol stability and versioned wire format

License

MIT — see LICENSE.

7.2 KiB Raw Blame History