test: end-to-end integration harness (closes #28)

[eric-becker]

Summary

Adds a Docker Compose-based end-to-end integration harness that stands up real EMQX + floodgate + meshtasticd on an isolated bridge network and verifies floodgate's behavior end-to-end. Six cases (drop / zerohop / passthru / noop / custom-key passthru / meshtasticd round-trip), each asserting on both the subscriber's delivered payload and floodgate's /health stats. Available as a one-shot CI job (after smoke) and as a local ./scripts/run-integration.sh with --keep and --teardown modes.

What's in the stack

docker-compose.test.yaml (isolated bridge network floodgate-test-net):

• emqx — emqx/emqx:6.1.1, REST exposed to host on :18083 for the runner
• floodgate — built from local Dockerfile, /health exposed on host :18089 for the runner; uses tests/integration/config.yaml (drop_enabled: true, drop_portnums: [RANGE_TEST_APP], standard zerohop channels)
• exhook-init — alpine + curl + jq sidecar that waits for EMQX REST then idempotently registers the ExHook at http://floodgate:9000
• meshtasticd — ghcr.io/meshtastic/meshtasticd:latest, run with -s (SimRadio mode, no LoRa hardware) — matches upstream firmware's test_native.yml pattern
• meshtasticd-init — Python + meshtastic CLI sidecar that, after meshtasticd's TCP API on 4403 is up, sets moduleConfig.mqtt.{enabled,address,root,...} and sends one probe text message
• test-driver (under driver profile, runs only via compose run) — Python + paho-mqtt + meshtastic protobufs + cryptography. Crafts ServiceEnvelope packets, captures all msh/# deliveries, asserts on each case

MQTT 1883 and gRPC 9000 stay container-internal. Only /health and EMQX REST are mapped to the host (so the runner can probe readiness).

Six cases

Each case publishes a crafted (or organic, for case 6) Meshtastic packet and verifies BOTH the subscriber's captured bytes AND the /health stat counter. A behavior change with no stat increment, or a stat increment with no delivery effect, both fail the case loudly.

Case	What it crafts	Asserts
zerohop	TEXT_MESSAGE_APP on LongFast, default key, hop_limit=3	Delivered with hop_limit=0; stats.zerohop ↑
drop	RANGE_TEST_APP on LongFast, default key	NOT delivered to subscriber; stats.dropped ↑
passthru	TEXT_MESSAGE_APP on PrivateClear (not in zerohop list), default key	Delivered byte-identical, hop_limit=3; stats.passthru ↑
noop	TEXT_MESSAGE_APP on LongFast, default key, already hop_limit=0	Delivered byte-identical; stats.noop ↑
custom-key passthru	RANGE_TEST_APP on PrivateNet, custom AES key	Delivered byte-identical; stats.passthru ↑; stats.dropped did NOT increment (drop must not fire on unreadable portnum)
meshtasticd-roundtrip	observes organic meshtasticd traffic	At least one msh/.../e/... message with packet_id outside the crafted 0xAxxxxxxx range arrives within 60s

The crafted packets use a stable 0xAxxxxxxx packet_id namespace so they don't collide with meshtasticd's auto-generated IDs.

Runner

# One-shot — bring stack up, run cases, tear down, exit 0/non-zero
./scripts/run-integration.sh

# Ad-hoc poking — leave the stack running for inspection
./scripts/run-integration.sh --keep
#   floodgate /health: http://localhost:18089/health
#   EMQX dashboard:    http://localhost:18083  (admin / public)

# Tear down without running cases
./scripts/run-integration.sh --teardown

A new CI integration job runs the same script after smoke and dumps service logs on failure.

Verification constraint

Local end-to-end verification was not possible on the development host (k3s installs iptables FORWARD rules ahead of DOCKER-USER while the chain default is DROP, breaking inter-container traffic on Docker user-defined bridges). Each piece was verified individually — image builds clean, ruff lint passes, compose YAML parses, helper round-trip works in-image, every case is importable. CI on a clean GitHub Actions runner is the source of truth for the end-to-end run.

Test plan

• CI lint job passes (the new tests/integration/test-driver/run.py is in scope for ruff check src/ tests/)
• CI test job passes (tests/integration is now ignored from pytest)
• CI smoke job passes
• CI integration job passes — six PASS lines, exit 0
• CI manifests job passes
• After CI is green, run locally on a non-k3s host: ./scripts/run-integration.sh shows six PASS lines
• ./scripts/run-integration.sh --keep leaves the stack running with /health and EMQX dashboard reachable on the documented host ports
• ./scripts/run-integration.sh --teardown removes the stack and the floodgate-test-net network

Closes #28.

🤖 Generated with Claude Code