mirror of
https://github.com/jmcorgan/fips.git
synced 2026-07-30 19:46:15 +00:00
Optional peer discovery and NAT hole-punching path gated behind a new
`nostr-discovery` cargo feature. Nodes publish signed overlay endpoint
adverts to public Nostr relays, consume peer adverts to populate
fallback dial addresses, and use STUN-assisted UDP hole punching with
NIP-59 gift-wrap offer/answer signaling to establish direct UDP paths
between NATed peers. Once a punched socket is up, it is handed into
the existing FIPS UDP transport and the standard Noise/FMP session
stack takes over unchanged.
The cargo feature is in the default feature set
(`default = ["nostr-discovery"]`) so stock builds include it; a
build that explicitly disables default features (or selects a
feature set without `nostr-discovery`) does not link the nostr /
nostr-sdk crates and does not emit a no-op poll in the tick loop.
Runtime behavior is independently gated by
`node.discovery.nostr.enabled`, which defaults to false; if the
config enables Nostr on a non-feature build, startup logs a
warning and continues without it.
== Cargo feature and dependencies
- New cargo feature `nostr-discovery = ["dep:nostr", "dep:nostr-sdk"]`.
Not in the default feature set.
- New optional Linux-only dependencies: `nostr 0.44` (features: std,
nip59) and `nostr-sdk 0.44`. Gift-wrap unwrap is hand-rolled in
`src/discovery/nostr/signal.rs` rather than relying on the SDK's
rumor-author check, which FIPS sidesteps by trusting `seal.pubkey`
exclusively.
== Wire format
Overlay advert event: `kind 37195`, parameterized replaceable
(NIP-01 application-defined replaceable range 30000-39999), with
`d = "fips-overlay-v1"`. The digits visually spell FIPS (7=F, 1=I,
9=P, 5=S); a relay survey confirmed the kind is unused.
Advert content carries the version tag, endpoint list
(`udp|tcp|tor` + addr), optional signal-relay and stun-server
metadata, and `issuedAt` / `expiresAt` timestamps. Endpoint
`addr: "nat"` is the sentinel that triggers traversal on the peer
side. NIP-40 `expiration` tag bounds staleness on permanent
shutdown. Lifecycle relies on parameterized-replaceable
supersession; the daemon does not emit NIP-09 kind-5 deletes —
strict relays (Damus, Primal) race delete-against-replace and can
silently drop the replacement.
Gift-wrapped signal event: `kind 21059`. Punch packets carry magic
values `PUNCH_MAGIC` / `PUNCH_ACK_MAGIC`, a sequence number, and a
16-byte session hash.
== Discovery surface
- `src/discovery.rs` (always compiled)
- `EstablishedTraversal`: bound UDP socket + selected remote +
peer npub + optional transport name/config tuning overrides.
- `BootstrapHandoffResult`: returned on successful handoff —
allocated transport id, local/remote addrs, peer NodeAddr,
session id.
- `src/discovery/nostr/` (`#![cfg(feature = "nostr-discovery")]`)
- `types.rs`: wire and control types described above. `ADVERT_KIND`
constant. `BootstrapError` enumerates failure modes (disabled,
missing advert, missing NAT endpoint, no usable relays, invalid
advert, invalid npub, signal timeout, punch timeout, replay,
STUN failure, protocol, nostr, io, serde, event-parse).
- `runtime.rs`: `NostrDiscovery` coordinator. Owns the shared
nostr-sdk `Client`, subscribes to advert + signal event kinds,
maintains a bounded advert cache and a bounded seen-sessions
replay set, drains `BootstrapEvent::{Established, Failed}` for
the node to consume, exposes `update_local_advert`,
`request_connect`, `advert_endpoints_for_peer`,
`cached_open_discovery_candidates`, and `shutdown`.
- `signal.rs`: NIP-59 gift-wrap encode/decode. Outbound wraps are
built against per-attempt ephemeral keys; inbound events are
unwrapped against the node identity.
- `stun.rs`: RFC 5389/8489 Binding Request client with
XOR-MAPPED-ADDRESS parsing for both IPv4 and IPv6; used only to
observe the initiator's own reflexive address against its
locally configured STUN list (peer-advertised STUN is
informational, never an egress target).
- `traversal.rs`: per-attempt candidate-pair punch planner.
Allocates a fresh `0.0.0.0:0` UDP socket per attempt, enumerates
LAN-private and ULA interface addresses alongside the STUN
reflexive address, schedules probe/ack exchanges at the
configured interval for the configured duration, and picks the
first candidate pair that authenticates end-to-end.
Strategy ordering is Reflexive↔Reflexive first, then LAN, then
Mixed. The STUN-observed pair is the only candidate that's reliable
across arbitrary network topologies; trying it first prevents the
planner from latching onto a misleading host-candidate path before
the reflexive path gets a chance. There is no catch-all
Local↔Local strategy: a previous design that paired every local
host candidate from one side with every local host candidate from
the other could declare success on a one-way reachable asymmetric
L3 path (corporate VPN, Tailscale subnet route, overlapping private
address space), only for the FMP handshake to stall because the
return path didn't match. The legitimate `Lan` strategy still pairs
candidates that share a subnet.
== Configuration surface
`node.discovery.nostr.*` (`NostrDiscoveryConfig`), all `serde(default)`
with `deny_unknown_fields`:
- `enabled` (default false), `advertise` (default true)
- `advert_relays`, `dm_relays`, `stun_servers`: defaults are
`wss://relay.damus.io`, `wss://nos.lol`, `wss://offchain.pub`
for both relay lists, and Google / Cloudflare / Twilio for STUN.
Operators are expected to override for production. Other
verified-working public relays for reference:
`nostr.bitcoiner.social`, `nostr-pub.wellorder.net`,
`nostr.oxtr.dev`, `nostr.mom`.
- `app` (default `"fips-overlay-v1"`), `signal_ttl_secs` (120)
- `policy`: `NostrDiscoveryPolicy::{Disabled, ConfiguredOnly (default),
Open}` — controls whether advert-derived endpoints are consumed
only for peers carrying `via_nostr = true`, or also for
non-configured peers within a budget cap.
- `share_local_candidates` (default false) — when false, the offer's
`local_addresses` list is empty and peers see only the reflexive
address. Enable per-node only for genuinely same-LAN deployments;
off-by-default eliminates the misleading-path failure mode for
the common case where peers are not on the same broadcast domain.
- `open_discovery_max_pending` (64) — caps queued open-discovery
retries; bounded by available outbound slots.
- `max_concurrent_incoming_offers` (16) — semaphore against offer
spam; excess offers are debug-logged and dropped.
- `advert_cache_max_entries` (2048) and `seen_sessions_max_entries`
(2048) — bound memory under ambient relay volume; overflow
evictions are debug-logged.
- `attempt_timeout_secs` (10), `replay_window_secs` (300)
- `punch_start_delay_ms` (2000), `punch_interval_ms` (200),
`punch_duration_ms` (10000)
- `advert_ttl_secs` (3600), `advert_refresh_secs` (1800)
Per-peer and per-transport flags:
- `PeerConfig.via_nostr: bool` — when true (and Nostr is enabled),
advert-derived addresses are appended as fallback dial candidates
after static addresses for that peer.
- `PeerConfig.addresses` is now `serde(default)` and may be empty
when `via_nostr: true`; validation requires at least one of the
two to be present per peer, and the error message names the
peer's npub.
- `UdpConfig.advertise_on_nostr: Option<bool>` and
`UdpConfig.public: Option<bool>` — UDP transports can be
advertised either as direct `host:port` (public = true) or as the
`addr: "nat"` sentinel that triggers rendezvous on the peer side.
- `TcpConfig.advertise_on_nostr` and `TorConfig.advertise_on_nostr`
— TCP and Tor onion endpoints can be advertised as directly
reachable.
- A reserved peer address `transport: udp, addr: "nat"` parses without
special-casing in YAML and routes through the bootstrap runtime.
Cross-field validation (`Config::validate`, called from `Node::new`
and `Node::with_identity`):
- Any transport with `advertise_on_nostr = true` requires
`node.discovery.nostr.enabled = true`.
- Any peer with `via_nostr = true` requires
`node.discovery.nostr.enabled = true`.
- A non-public UDP advert (`advertise_on_nostr = true`,
`public = false` — i.e. `udp:nat`) additionally requires at least
one `dm_relay` and at least one `stun_server`.
Surfaced as `ConfigError::Validation`.
== Node integration
`src/node/lifecycle.rs` is the main integration point.
- At node start (after transports are up, before TUN), if Nostr is
enabled and the feature is compiled in, `NostrDiscovery::start` is
invoked, the initial local overlay advert is built from the live
transport set and published, and the runtime handle is stored.
- The rx tick loop calls `poll_nostr_discovery` (feature-gated both
at method definition and call site), which refreshes the local
advert, drains bootstrap events, adopts established traversals,
schedules retries for failed traversals, and — under `policy:
open` — enqueues outbound retries for non-configured peers
visible in the advert cache, bounded by
`open_discovery_max_pending` and the remaining outbound slots.
- Outbound peer dialing is refactored to `try_peer_addresses`, which
first exhausts the static address list in priority order and only
then appends advert-derived fallback addresses; both lists run
through the same `attempt_peer_address_list` code path. The
`udp:nat` sentinel address triggers `NostrDiscovery::request_connect`
for the peer instead of a direct dial and returns `Ok(())`.
- `build_overlay_advert` walks operational transports, consults
per-instance `UdpConfig` / `TcpConfig` / `TorConfig` (matching by
optional transport instance name), and emits an `OverlayAdvert`
including `signalRelays` and `stunServers` when any UDP endpoint
is advertised as NAT.
- `adopt_established_traversal` is the bootstrap handoff API:
allocates a new `TransportId`, constructs a `UdpTransport` with
the user-supplied (or default) `UdpConfig`, calls the new
`adopt_socket_async` to reuse the punched socket verbatim,
registers the transport in the normal transport map, records it
in `bootstrap_transports`, and calls `initiate_connection` so the
normal handshake path runs. On failure, the transport is stopped
and removed cleanly and the set membership is rolled back.
- On clean shutdown, `NostrDiscovery::shutdown` is awaited so
background tasks stop before transports are torn down. (The
advert is not explicitly retracted; NIP-40 expiration plus the
next refresh from any live publisher supersedes it.)
New `Node` fields:
- `nostr_discovery: Option<Arc<NostrDiscovery>>` (feature-gated).
- `bootstrap_transports: HashSet<TransportId>` — per-peer UDP
transports adopted from NAT traversal, cleaned up via
`cleanup_bootstrap_transport_if_unused` whenever the link,
connection, peer, or pending-connect referencing them is removed.
Retry and error surface:
- `RetryState.expires_at_ms: Option<u64>` — optional absolute expiry
for a retry entry. `pump_retries` drops expired entries with an
info log. Used for open-discovery retries, which expire at two
times the advert TTL.
- New `NodeError::BootstrapHandoff(String)` returned from
`adopt_established_traversal` when the underlying transport
adoption fails or local address discovery fails.
- New `ConfigError::Validation(String)`.
- A small refactor extracts `Node::now_ms()` and reuses it across
lifecycle, rx-loop tick, and timeout bookkeeping.
== UDP transport
`src/transport/udp/`:
- `UdpRawSocket::adopt(std::net::UdpSocket, recv_buf, send_buf)`:
adopts an externally bound socket, makes it non-blocking, applies
the configured buffer sizes (warning if the kernel clamps), and
reports the resulting local address. Preserves the NAT mapping —
no rebind.
- `UdpTransport::adopt_socket_async(std::net::UdpSocket)`: the
`start_async` analogue for an already-bound socket, wiring the
async socket and recv task exactly as the fresh-bind path would.
- `Drop` impl for `UdpTransport`: if a transport is dropped while
still holding a recv task or socket (for example on error
teardown), aborts the task, clears the socket, and emits a debug
log so the cleanup is visible in tracing rather than silent.
== Logging and observability
Default `EnvFilter` demotes third-party relay-pool DEBUG output to
TRACE-only: `nostr_relay_pool`, `nostr_sdk`, and `nostr` are pinned
at INFO when our level is anything below TRACE, and at TRACE when
our level is TRACE — so the raw frames are still reachable when
explicitly asked for. RUST_LOG continues to override completely.
Concise one-line DEBUG events are emitted at the meaningful points
in the discovery / hole-punch sequence:
- `advert: published` (event id, relay count, endpoints, ttl)
- `advert: peer cached` (notify-loop ingress for non-self)
- `advert: resolved` (cache hit / relay fetch outcome)
- `traversal: initiator starting`
- `traversal: initiator STUN observed` (reflexive, local count)
- `traversal: offer sent` (session id, relay count, event id)
- `traversal: answer received` (accepted, reflexive, local)
- `traversal: initiator punch succeeded` (remote addr)
- `traversal: offer received` (responder side)
- `traversal: responder STUN observed`
- `traversal: answer sent`
- `traversal: responder punch succeeded`
Npubs are shortened to `npub1<4>..<4>` and event/session ids to
their first 8 hex characters.
Other operator-facing logs:
- `UdpTransport` adoption and drop paths log at info / debug.
- `adopt_established_traversal` logs at debug on entry and info on
successful return, tagged with peer npub, session id, transport
id, and both socket endpoints, so the bootstrap handoff is
traceable end-to-end alongside the `UdpTransport::drop` log.
- `cleanup_bootstrap_transport_if_unused` logs at debug when the
reference-count check drops an adopted transport.
- `connect_peer` tags its entry `debug!` with `peer_npub` so
downstream STUN, punch, and handshake logs for the same peer
correlate for operators.
- Advert-cache and seen-sessions overflow evictions log at debug so
mis-sized caps are visible under ambient relay volume.
- Gift-wrap unwrap failures on `SIGNAL_KIND` events log at trace
(hot path: fires for every unrelated signal event on the same
relay).
- Traversal-offer handler failures log at debug. Expected conditions
such as punch timeout on symmetric NAT are covered there; real
problems are reported upstream via `BootstrapEvent::Failed`.
- Inbound-offer rate-limit messages name the governing config field
(`max_concurrent_incoming_offers`) and state that the offer was
rate-limited rather than failing.
== Tests
- 18 new unit tests in `src/discovery/nostr/tests.rs` covering advert
encoding, signal envelope round-trip, STUN parsing, punch-packet
codec, and replay-window enforcement. Run under the
`nostr-discovery` feature.
- Config-validation tests in `src/config/mod.rs` covering the three
cross-field invariants and YAML parsing of the full
`node.discovery.nostr` block plus `peers[].via_nostr`, empty
`addresses` with `via_nostr: true`, and a `udp: nat` address.
- `src/node/tests/bootstrap.rs` integration tests that drive a
synthetic traversal (bound UDP socket pair + synthetic peer
identity) through `adopt_established_traversal` and assert the
Noise handshake completes over the adopted socket.
- Punch-planner tests assert reflexive-before-LAN ordering and that
same-LAN scenarios still include the LAN target in the plan.
- `testing/nat/` Docker NAT lab harness:
- Local `strfry` relay, local STUN responder, and one or two
router containers performing `iptables` NAT.
- Node LAN interfaces are provisioned with explicit `veth` pairs
injected into the node and router namespaces so every packet
traverses the router namespace (plain Docker bridges are not
used for the LAN).
- `cone` scenario: both peers behind full-cone-emulation NAT
(SNAT with source-port preservation, inbound DNAT back to the
single LAN host regardless of remote source); asserts UDP
traversal succeeds and link remote addresses are on the router
WAN subnet.
- `symmetric` scenario: `MASQUERADE --random-fully`; asserts UDP
traversal fails and TCP fallback converges over router-
published WAN addresses.
- `lan` scenario: both peers share a LAN subnet; asserts LAN
addresses are preferred over reflexive ones.
- Cleanup tears down all profile-gated services
(`--profile cone --profile symmetric --profile lan`) so no
orphan containers survive a run.
- `testing/scripts/build.sh` builds the Docker test image with
`--features "tui nostr-discovery"` by default so NAT-harness
binaries include bootstrap support.
== CI
- Linux release build and nextest unit-test job both use
`--features "gateway nostr-discovery"` so the feature-gated code
and its unit tests compile and run in CI.
- Three new integration matrix entries (`nat-cone`, `nat-symmetric`,
`nat-lan`) invoke `testing/nat/scripts/nat-test.sh`, collect
`docker compose logs` on failure, and always stop containers.
== Packaging and operations
- `packaging/common/fips.yaml` ships a fully commented
`node.discovery.nostr.*` block, plus documented
`advertise_on_nostr` / `public` examples under the UDP transport,
an `advertise_on_nostr` example under TCP, and a `via_nostr: true`
example under the static peer section with both a direct
`host:port` UDP address and a `udp: nat` fallback.
- `.github/workflows/package-openwrt.yml`: NIP-94 release event
publishes target the new default relay set.
== Documentation
- `README.md`: overlay discovery + NAT traversal moved from
"Near-term priorities" into "What works today".
- `docs/design/fips-intro.md`: rewrites the paragraphs that
previously described Nostr discovery and NAT traversal as future
work; describes the shipped mechanism and the feature gate.
- `docs/design/fips-transport-layer.md`: drops the "(future
direction)" qualifier from the Nostr Relay Discovery section,
expands with the `udp:nat` advertisement and bootstrap handoff
description, and updates the Current State callout.
- `docs/design/fips-mesh-layer.md`: notes that mid-session NAT
rebinding (roaming) and initial NAT traversal (Nostr path) are
distinct mechanisms.
- `docs/design/fips-configuration.md`: documents the full
`node.discovery.nostr.*` surface, including the three resource
caps and `share_local_candidates`.
- `docs/design/fips-nostr-discovery.md`: design and configuration
reference for the shipped mechanism, including the empty-
`addresses`-with-`via_nostr` shorthand.
- `docs/proposals/nostr-udp-hole-punch-protocol.md`: adds an
Implemented status callout, clarifies that the punch socket is
per-peer and per-attempt rather than shared with the application
listener, aligns field names with the shipped JSON
(`sessionId`, `issuedAt` / `expiresAt`, `reflexiveAddress`,
`localAddresses`, `stunServer`), sets the `d`-tag to
`fips-overlay-v1`, names the kind as 37195, and notes that
advertised STUN entries are informational.
- `docs/proposals/README.md`: adds a Status column and marks the
hole-punching proposal Implemented.
- `CHANGELOG.md`: Unreleased > Added entry covering the discovery
path, STUN/punch path, configuration surface, and Docker NAT lab.
Co-authored-by: Johnathan Corgan <johnathan@corganlabs.com>
457 lines
17 KiB
YAML
457 lines
17 KiB
YAML
name: CI
|
||
|
||
on:
|
||
push:
|
||
branches: ["**"]
|
||
pull_request:
|
||
workflow_dispatch:
|
||
inputs:
|
||
skip_integration:
|
||
description: "Skip integration tests"
|
||
type: boolean
|
||
default: false
|
||
|
||
permissions:
|
||
checks: write
|
||
contents: read
|
||
|
||
env:
|
||
CARGO_TERM_COLOR: always
|
||
RUST_BACKTRACE: 1
|
||
SOURCE_DATE_EPOCH: 0 # overridden per-step after checkout
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# Job 1 – Build matrix
|
||
#
|
||
# Builds on Linux x86_64, Linux aarch64, and macOS.
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
jobs:
|
||
fmt:
|
||
name: Format check
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
- uses: dtolnay/rust-toolchain@stable
|
||
with:
|
||
components: rustfmt
|
||
- run: cargo fmt --check
|
||
|
||
build:
|
||
name: Build (${{ matrix.os }})
|
||
runs-on: ${{ matrix.os }}
|
||
|
||
strategy:
|
||
fail-fast: false
|
||
matrix:
|
||
include:
|
||
- os: ubuntu-latest
|
||
- os: ubuntu-24.04-arm
|
||
- os: macos-latest
|
||
- os: windows-latest
|
||
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- name: Set SOURCE_DATE_EPOCH from git (Unix)
|
||
if: runner.os != 'Windows'
|
||
run: echo "SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)" >> "$GITHUB_ENV"
|
||
|
||
- name: Set SOURCE_DATE_EPOCH from git (Windows)
|
||
if: runner.os == 'Windows'
|
||
shell: pwsh
|
||
run: |
|
||
$epoch = git log -1 --format=%ct
|
||
echo "SOURCE_DATE_EPOCH=$epoch" >> $env:GITHUB_ENV
|
||
|
||
- name: Install system dependencies (Linux only)
|
||
if: runner.os == 'Linux'
|
||
run: sudo apt-get update && sudo apt-get install -y libdbus-1-dev
|
||
|
||
- name: Install Rust toolchain
|
||
uses: dtolnay/rust-toolchain@stable
|
||
|
||
- name: Cache Cargo registry + build
|
||
uses: actions/cache@v4
|
||
with:
|
||
path: |
|
||
~/.cargo/registry
|
||
~/.cargo/git
|
||
target
|
||
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
|
||
restore-keys: |
|
||
${{ runner.os }}-cargo-
|
||
|
||
- name: Build
|
||
run: cargo build --release
|
||
|
||
- name: SHA-256 hashes (Linux)
|
||
if: runner.os == 'Linux'
|
||
run: sha256sum target/release/fips target/release/fipsctl target/release/fipstop target/release/fips-gateway
|
||
|
||
- name: SHA-256 hashes (macOS)
|
||
if: runner.os == 'macOS'
|
||
run: shasum -a 256 target/release/fips target/release/fipsctl target/release/fipstop
|
||
|
||
- name: SHA-256 hashes (Windows)
|
||
if: runner.os == 'Windows'
|
||
shell: pwsh
|
||
run: Get-FileHash target\release\fips.exe, target\release\fipsctl.exe, target\release\fipstop.exe -Algorithm SHA256
|
||
|
||
# Upload the Linux binary so integration jobs can use it without rebuilding
|
||
- name: Upload Linux binary
|
||
if: matrix.os == 'ubuntu-latest'
|
||
uses: actions/upload-artifact@v4
|
||
with:
|
||
name: fips-linux
|
||
path: |
|
||
target/release/fips
|
||
target/release/fipsctl
|
||
target/release/fipstop
|
||
target/release/fips-gateway
|
||
retention-days: 1
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# Job 2 – Unit tests
|
||
#
|
||
# Runs `cargo test` on Linux. Gated on the build matrix completing so we
|
||
# don't waste runner time if compilation is broken.
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
test:
|
||
name: Unit tests
|
||
runs-on: ubuntu-latest
|
||
needs: [build]
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- name: Set SOURCE_DATE_EPOCH from git
|
||
run: echo "SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)" >> "$GITHUB_ENV"
|
||
|
||
- name: Install system dependencies
|
||
run: sudo apt-get update && sudo apt-get install -y libdbus-1-dev
|
||
|
||
- name: Install Rust toolchain
|
||
uses: dtolnay/rust-toolchain@stable
|
||
|
||
- name: Cache Cargo registry + build
|
||
uses: actions/cache@v4
|
||
with:
|
||
path: |
|
||
~/.cargo/registry
|
||
~/.cargo/git
|
||
target
|
||
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
|
||
restore-keys: |
|
||
${{ runner.os }}-cargo-
|
||
|
||
- name: Install cargo-nextest
|
||
uses: taiki-e/install-action@nextest
|
||
|
||
- name: Run unit tests
|
||
run: cargo nextest run --all --profile ci
|
||
|
||
- name: Publish test report (Checks tab)
|
||
uses: dorny/test-reporter@v2
|
||
if: always()
|
||
with:
|
||
name: Unit Tests
|
||
path: target/nextest/ci/junit.xml
|
||
reporter: java-junit
|
||
fail-on-error: false
|
||
|
||
- name: Publish test report (run summary)
|
||
uses: mikepenz/action-junit-report@v4
|
||
if: always()
|
||
with:
|
||
report_paths: target/nextest/ci/junit.xml
|
||
check_name: Unit Tests Summary
|
||
fail_on_failure: false
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# Job 2b – Unit tests (macOS)
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
test-macos:
|
||
name: Unit tests (macOS)
|
||
runs-on: macos-latest
|
||
needs: [build]
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- name: Set SOURCE_DATE_EPOCH from git
|
||
run: echo "SOURCE_DATE_EPOCH=$(git log -1 --format=%ct)" >> "$GITHUB_ENV"
|
||
|
||
- name: Install Rust toolchain
|
||
uses: dtolnay/rust-toolchain@stable
|
||
|
||
- name: Cache Cargo registry + build
|
||
uses: actions/cache@v4
|
||
with:
|
||
path: |
|
||
~/.cargo/registry
|
||
~/.cargo/git
|
||
target
|
||
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
|
||
restore-keys: |
|
||
${{ runner.os }}-cargo-
|
||
|
||
- name: Install cargo-nextest
|
||
uses: taiki-e/install-action@nextest
|
||
|
||
- name: Run unit tests
|
||
run: cargo nextest run --all --profile ci
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# Job 2c – Unit tests (Windows)
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
test-windows:
|
||
name: Unit tests (Windows)
|
||
runs-on: windows-latest
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
- name: Install Rust toolchain
|
||
uses: dtolnay/rust-toolchain@stable
|
||
|
||
- name: Cache Cargo registry + build
|
||
uses: actions/cache@v4
|
||
with:
|
||
path: |
|
||
~/.cargo/registry
|
||
~/.cargo/git
|
||
target
|
||
key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
|
||
restore-keys: |
|
||
${{ runner.os }}-cargo-
|
||
|
||
- name: Install cargo-nextest
|
||
uses: taiki-e/install-action@nextest
|
||
|
||
- name: Run unit tests
|
||
run: cargo nextest run --all --profile ci
|
||
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
# Job 3 – Integration tests (static mesh + chaos simulation)
|
||
#
|
||
# Runs only when both build and test succeed. Each topology / scenario is a
|
||
# separate matrix entry so they run in parallel.
|
||
#
|
||
# All harnesses share a single Docker image (fips-test:latest) built once
|
||
# in the setup step from testing/docker/.
|
||
# ─────────────────────────────────────────────────────────────────────────────
|
||
integration:
|
||
name: Integration (${{ matrix.suite }})
|
||
runs-on: ubuntu-latest
|
||
needs: [build, test]
|
||
if: ${{ !inputs.skip_integration }}
|
||
|
||
strategy:
|
||
fail-fast: false
|
||
matrix:
|
||
include:
|
||
# ── Static mesh topologies ─────────────────────────────────────────
|
||
- suite: static-mesh
|
||
type: static
|
||
topology: mesh
|
||
- suite: static-chain
|
||
type: static
|
||
topology: chain
|
||
# ── Rekey integration test ──────────────────────────────────────────
|
||
- suite: rekey
|
||
type: rekey
|
||
topology: rekey
|
||
- suite: acl-allowlist
|
||
type: acl-allowlist
|
||
# ── Chaos / stochastic scenarios ───────────────────────────────────
|
||
- suite: chaos-smoke-10
|
||
type: chaos
|
||
scenario: smoke-10
|
||
- suite: churn-mixed-10
|
||
type: chaos
|
||
scenario: churn-mixed
|
||
chaos_flags: "--nodes 10 --duration 120"
|
||
- suite: ethernet-mesh
|
||
type: chaos
|
||
scenario: ethernet-mesh
|
||
- suite: ethernet-only
|
||
type: chaos
|
||
scenario: ethernet-only
|
||
- suite: tcp-mesh
|
||
type: chaos
|
||
scenario: tcp-mesh
|
||
- suite: bottleneck-parent
|
||
type: chaos
|
||
scenario: bottleneck-parent
|
||
- suite: cost-avoidance
|
||
type: chaos
|
||
scenario: cost-avoidance
|
||
- suite: cost-reeval
|
||
type: chaos
|
||
scenario: cost-reeval
|
||
- suite: cost-stability
|
||
type: chaos
|
||
scenario: cost-stability
|
||
- suite: depth-vs-cost
|
||
type: chaos
|
||
scenario: depth-vs-cost
|
||
- suite: mixed-technology
|
||
type: chaos
|
||
scenario: mixed-technology
|
||
- suite: congestion-stress
|
||
type: chaos
|
||
scenario: congestion-stress
|
||
# ── Sidecar deployment ──────────────────────────────────────────
|
||
- suite: sidecar
|
||
type: sidecar
|
||
# ── NAT traversal lab (Nostr/STUN UDP hole punch) ───────────────
|
||
- suite: nat-cone
|
||
type: nat
|
||
scenario: cone
|
||
- suite: nat-symmetric
|
||
type: nat
|
||
scenario: symmetric
|
||
- suite: nat-lan
|
||
type: nat
|
||
scenario: lan
|
||
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
|
||
# Fetch the pre-built Linux binary from job 1
|
||
- name: Download Linux binary
|
||
uses: actions/download-artifact@v4
|
||
with:
|
||
name: fips-linux
|
||
path: _bin
|
||
|
||
# Install binaries to unified docker context and build shared image
|
||
- name: Install binaries and build Docker image
|
||
run: |
|
||
chmod +x _bin/fips _bin/fipsctl
|
||
[ -f _bin/fipstop ] && chmod +x _bin/fipstop || true
|
||
[ -f _bin/fips-gateway ] && chmod +x _bin/fips-gateway || true
|
||
cp _bin/fips testing/docker/fips
|
||
cp _bin/fipsctl testing/docker/fipsctl
|
||
[ -f _bin/fipstop ] && cp _bin/fipstop testing/docker/fipstop || true
|
||
[ -f _bin/fips-gateway ] && cp _bin/fips-gateway testing/docker/fips-gateway || true
|
||
docker build -t fips-test:latest testing/docker
|
||
docker build -t fips-test-app:latest -f testing/docker/Dockerfile.app testing/docker
|
||
|
||
# ── Static topology ────────────────────────────────────────────────────
|
||
- name: Generate configs (static)
|
||
if: matrix.type == 'static'
|
||
run: bash testing/static/scripts/generate-configs.sh ${{ matrix.topology }}
|
||
|
||
- name: Start containers (static)
|
||
if: matrix.type == 'static'
|
||
run: |
|
||
docker compose -f testing/static/docker-compose.yml \
|
||
--profile ${{ matrix.topology }} up -d
|
||
|
||
- name: Run ping test (static)
|
||
if: matrix.type == 'static'
|
||
run: bash testing/static/scripts/ping-test.sh ${{ matrix.topology }}
|
||
|
||
- name: Collect logs on failure (static)
|
||
if: matrix.type == 'static' && failure()
|
||
run: |
|
||
docker compose -f testing/static/docker-compose.yml \
|
||
--profile ${{ matrix.topology }} logs --no-color
|
||
|
||
- name: Stop containers (static)
|
||
if: matrix.type == 'static' && always()
|
||
run: |
|
||
docker compose -f testing/static/docker-compose.yml \
|
||
--profile ${{ matrix.topology }} down --volumes --remove-orphans
|
||
|
||
# ── Rekey integration test ──────────────────────────────────────────────
|
||
- name: Generate and inject configs (rekey)
|
||
if: matrix.type == 'rekey'
|
||
run: |
|
||
bash testing/static/scripts/generate-configs.sh rekey
|
||
bash testing/static/scripts/rekey-test.sh inject-config
|
||
|
||
- name: Start containers (rekey)
|
||
if: matrix.type == 'rekey'
|
||
run: |
|
||
docker compose -f testing/static/docker-compose.yml \
|
||
--profile rekey up -d
|
||
|
||
- name: Run rekey test
|
||
if: matrix.type == 'rekey'
|
||
run: bash testing/static/scripts/rekey-test.sh
|
||
|
||
- name: Collect logs on failure (rekey)
|
||
if: matrix.type == 'rekey' && failure()
|
||
run: |
|
||
docker compose -f testing/static/docker-compose.yml \
|
||
--profile rekey logs --no-color
|
||
|
||
- name: Stop containers (rekey)
|
||
if: matrix.type == 'rekey' && always()
|
||
run: |
|
||
docker compose -f testing/static/docker-compose.yml \
|
||
--profile rekey down --volumes --remove-orphans
|
||
|
||
# ── ACL allowlist integration test ─────────────────────────────────────
|
||
- name: Run ACL allowlist integration test
|
||
if: matrix.type == 'acl-allowlist'
|
||
run: bash testing/acl-allowlist/test.sh --skip-build --keep-up
|
||
|
||
- name: Collect logs on failure (acl-allowlist)
|
||
if: matrix.type == 'acl-allowlist' && failure()
|
||
run: |
|
||
docker compose -f testing/acl-allowlist/docker-compose.yml logs --no-color
|
||
|
||
- name: Stop containers (acl-allowlist)
|
||
if: matrix.type == 'acl-allowlist' && always()
|
||
run: |
|
||
docker compose -f testing/acl-allowlist/docker-compose.yml down --volumes --remove-orphans
|
||
|
||
# ── Chaos simulation ───────────────────────────────────────────────────
|
||
- name: Install Python deps (chaos)
|
||
if: matrix.type == 'chaos'
|
||
run: pip3 install --quiet pyyaml jinja2
|
||
|
||
- name: Run chaos scenario
|
||
if: matrix.type == 'chaos'
|
||
run: bash testing/chaos/scripts/chaos.sh ${{ matrix.scenario }} ${{ matrix.chaos_flags }}
|
||
|
||
- name: Upload sim results on failure (chaos)
|
||
if: matrix.type == 'chaos' && failure()
|
||
uses: actions/upload-artifact@v4
|
||
with:
|
||
name: sim-results-${{ matrix.scenario }}
|
||
path: testing/chaos/sim-results/
|
||
retention-days: 7
|
||
|
||
# ── Sidecar deployment ──────────────────────────────────────────────
|
||
- name: Run sidecar integration test
|
||
if: matrix.type == 'sidecar'
|
||
run: bash testing/sidecar/scripts/test-sidecar.sh --skip-build
|
||
|
||
- name: Collect logs on failure (sidecar)
|
||
if: matrix.type == 'sidecar' && failure()
|
||
run: |
|
||
for node in a b c; do
|
||
echo "--- sidecar-${node} logs ---"
|
||
docker logs "sidecar-${node}-fips-1" 2>&1 || true
|
||
echo ""
|
||
done
|
||
|
||
# ── NAT traversal lab ───────────────────────────────────────────────
|
||
- name: Run NAT lab scenario
|
||
if: matrix.type == 'nat'
|
||
run: bash testing/nat/scripts/nat-test.sh ${{ matrix.scenario }}
|
||
|
||
- name: Collect logs on failure (nat)
|
||
if: matrix.type == 'nat' && failure()
|
||
run: |
|
||
docker compose -f testing/nat/docker-compose.yml \
|
||
--profile ${{ matrix.scenario }} logs --no-color
|
||
|
||
- name: Stop containers (nat)
|
||
if: matrix.type == 'nat' && always()
|
||
run: |
|
||
docker compose -f testing/nat/docker-compose.yml \
|
||
--profile cone --profile symmetric --profile lan \
|
||
down --volumes --remove-orphans
|