midi-harbor/specs/005-network-ports/quickstart.md

Quickstart: Network Ports

Prerequisites and the build are in 001's quickstart, with the automated equivalent of each scenario.

---

Scenario 2 — Network session self-heals (US3 · SC-003, SC-004, SC-005, SC-011)

The headline capability. Requires a second machine.

midi-harbor session create "Studio"
midi-harbor session discover                # expect: the peer machine listed by advertised name
midi-harbor session connect Studio <peer>
midi-harbor status                          # expect: Connected

Interoperability check (SC-011): with the peer running Apple's Network MIDI rather than Midi Harbor, confirm discovery and connection work with no manual configuration on either side.

Now induce each failure in turn, and after each one run midi-harbor status and confirm MIDI resumes flowing with no user action:

Failure	How to induce	Expected recovery
Network interruption	Unplug the cable or disable Wi-Fi for 30 s	Reconnects within 10 s of restoration (SC-003)
Sleep / wake	Sleep the machine, wake it	Reconnects within 15 s of wake (SC-004)
Peer restart	Reboot the other machine	Keeps retrying, reconnects when the peer returns
Wi-Fi roam	Move between access points so the address changes	Re-establishes at the new address

Time each recovery from the history, not a stopwatch. Leave midi-harbor events --follow running on both machines while inducing each failure: the TIME column gives the moment the session was lost and the moment it connected again. For sleep, measure from the system_resumed event.

Stuck-note check (SC-005): hold a chord down on the sending side, cut the network mid-chord, restore it. No note may be left sounding on the receiving side after recovery.

Packet-loss check (SC-006) — this is what the recovery journal is for:

# Linux, on the sending machine:
sudo tc qdisc add dev <iface> root netem loss 5%
# ...play notes and move controllers for 60 seconds...
sudo tc qdisc del dev <iface> root netem

Pass criteria: no note left sounding, and controller values at the receiver match the sender within 1 second of the loss ending. Confirm the journal did the work:

midi-harbor status --json | jq '.detail[] | select(.kind == "network") | {name, lost, recovered}'

recovered must be non-zero. If it is zero while lost is non-zero, the journal is not functioning regardless of what the audible result seemed to be.

Soak test (SC-007): leave the session carrying traffic for 24 hours. Expect zero unrecovered disconnections in midi-harbor events.