60 lines
2.6 KiB
Markdown
60 lines
2.6 KiB
Markdown
# Quickstart: Network Ports
|
|
|
|
Prerequisites and the build are in [001's
|
|
quickstart](../001-service-and-clients/quickstart.md#prerequisites), 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.
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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`.
|