midi-harbor/specs/001-service-and-clients/spec.md

Feature Specification: Midi Harbor — Service and Clients

Created: 2026-09-20

Status: Implemented

Split 2026-09-27: This was the whole of Midi Harbor's first specification. Each capability now has a spec of its own, from 002-configuration to 010-graphical-interface, holding its user story, requirements, success criteria, research and tasks under their original numbers; the index says which spec holds each. This one keeps the service, the command line, the daemon contract, the architecture and the original input.

Input: User description: "Midi Harbor: a cross-platform (macOS + Linux) MIDI connectivity manager. It manages three kinds of MIDI endpoint from one place: (1) virtual MIDI ports — the IAC-driver equivalent — that let apps on the same computer talk to each other over MIDI; (2) RTP-MIDI network sessions that let computers exchange MIDI over a LAN, discovered via mDNS/Bonjour and interoperable with Apple Network MIDI, rtpMIDI on Windows, and rtpmidid on Linux; (3) Bluetooth LE MIDI links, both connecting out to BLE MIDI peripherals (keyboards, controllers) and advertising this computer as a BLE MIDI peripheral. The defining value is connection resilience: unlike the built-in macOS support, connections must self-heal — automatically reconnecting after network changes, sleep/wake, device unplug, peer restart, and Wi-Fi roaming — and must recover MIDI state so no notes are left stuck. Users configure named virtual ports that persist across reboots, define routes between any two endpoints, see live connection health and traffic, and get a clear reason when something genuinely cannot connect. A headless daemon runs at login and owns all connections; a libcosmic GUI and a CLI are clients of it."

Amended 2026-09-20: Ship as a single executable rather than separate daemon and GUI binaries. The background service is a subcommand of that executable. The graphical interface is optional and can be excluded at build time, leaving a fully functional headless command-line build. The executable sets up its own launchd (macOS) or systemd (Linux) per-user service.

Amended 2026-09-20 (2): Physical MIDI hardware attached to the computer (USB and DIN interfaces, controllers, keyboards) is a first-class endpoint kind alongside virtual ports, network sessions, and Bluetooth devices. This enables the repeater use case: take a physical device and carry it over the network or over Bluetooth to another machine.

User Scenarios & Testing (mandatory)

User Story 2 - One binary: headless service, CLI, and optional GUI (Priority: P1)

A user installs a single Midi Harbor executable. Running it with no arguments opens the graphical interface; running midi-harbor service install registers it as a user service that starts at login and keeps running. On a headless machine — a rack computer, a stage box, a Raspberry Pi with no desktop — the same executable is built without the graphical interface and driven entirely from the command line, with the same configuration and the same self-healing behaviour.

Why this priority: This is the delivery vehicle for every other story. Virtual ports cannot survive a reboot (User Story 1) without the service, and the graphical interface cannot be optional unless the command-line surface is complete on its own.

Independent Test: On a machine with no graphical environment, install the service from the command line, create a virtual port and a route, reboot, and verify from the command line that everything came back — without the graphical interface ever being built or run.

Acceptance Scenarios:

1. Given a freshly installed executable, When the user runs the service install command, Then a per-user service is registered with the operating system's service manager, started immediately, and set to start at every login.
2. Given the service is installed, When the user runs the service status command, Then they are told whether it is installed, whether it is running, its version, and its uptime.
3. Given the service is installed, When the user runs the service uninstall command, Then the service is stopped and deregistered, and the user's configuration is left intact.
4. Given a build produced without the graphical interface, When the user runs any command-line command, Then it behaves identically to the same command on a full build.
5. Given a build produced without the graphical interface, When the user runs the executable with no arguments, Then they are shown command-line help explaining that the graphical interface is not included in this build.
6. Given the service is running, When the user performs any configuration action available in the graphical interface, Then an equivalent command-line command exists that performs the same action against the same running service.
7. Given the user wants to script against Midi Harbor, When they request machine-readable output from any command-line command, Then they receive structured output suitable for automated parsing.
8. Given the service is not installed, When the user opens the graphical interface, Then they are offered installation of the service in one action, and told what that will do.
9. Given the executable is run as the service directly in the foreground, When the user does so, Then it runs the service without registering anything, so it can be supervised by other means or debugged interactively.

---

Edge Cases

• Daemon not running: When the user opens the interface and the background service is not running, the interface offers to start and install it rather than showing an empty or broken view.
• Daemon crash: If the background service terminates unexpectedly, it is restarted automatically by the operating system's service supervisor, and it restores all configured endpoints and routes on startup.
• Version mismatch: When the interface and the background service are different incompatible versions, the user is told clearly which component to update instead of experiencing undefined behaviour.
• Concurrent clients: When more than one interface or command-line client is connected at once, all of them see consistent state and updates.
• No service manager: When the platform's user service manager is unavailable or unsupported (for example a container, or a Linux system without the expected service manager), service installation reports this clearly and the user is told how to run the service in the foreground instead.
• Service already installed: When the user runs service installation and a registration already exists, it is updated in place rather than duplicated, and the user is told it was updated.
• Stale service registration: When a service registration points at an executable that has been moved or deleted, the status command reports the registration as stale and names the missing path.
• Graphical interface requested on a headless build: When a user asks for the graphical interface on a build that excludes it, they are told which build to install rather than seeing a crash or silent exit.

Requirements (mandatory)

Functional Requirements

Service architecture and clients

• FR-036: System MUST run a background service that owns all endpoints and connections and starts automatically at user login.
• FR-037: System MUST keep all connections operating when no graphical interface is running, and MUST NOT disturb any connection when an interface is opened or closed.
• FR-038: System MUST be restarted automatically by the operating system if it terminates unexpectedly, and MUST restore all configured endpoints and routes on startup.
• FR-039: System MUST ship as a single executable that selects its role from its command-line arguments — running the background service, running the graphical interface, performing a command-line action, or managing its own service registration. There MUST NOT be a separate daemon executable.
• FR-039a: System MUST run the background service as a subcommand of that executable, in the foreground when invoked directly, so it can be supervised externally or debugged interactively.
• FR-039b: System MUST make the graphical interface an optional component that can be excluded at build time, producing a fully functional headless build with no graphical dependencies.
• FR-039c: System MUST expose, through command-line commands, every configuration and control action available in the graphical interface, so the graphical interface is never required to operate any feature.
• FR-039d: System MUST offer machine-readable output for command-line commands, so the product can be scripted and automated.
• FR-039e: System MUST show command-line help, explaining that the graphical interface is not included, when a headless build is invoked with no arguments.
• FR-039f: System MUST provide commands to install, uninstall, start, stop, and report the status of its own per-user service registration, using the platform's native user service manager, and MUST NOT require the user to author service configuration files by hand.
• FR-039g: System MUST install its service as a per-user service that starts at login and is restarted by the operating system if it terminates unexpectedly.
• FR-039h: System MUST leave the user's configuration intact when its service is uninstalled.
• FR-040: System MUST support multiple clients connected at once, each seeing consistent state and receiving updates as state changes.
• FR-041: System MUST detect incompatible client and service versions and report clearly which component needs updating.
• FR-042: System MUST offer to install and start the background service in one action when a client finds it is not running, and MUST state what installing it will do.
• FR-043: System MUST operate without requiring administrator or root privileges.

Key Entities

• Endpoint: Anything MIDI can flow to or from. Has a stable identity, a user-visible name, a kind (virtual port, network session, Bluetooth device), an enabled setting, a current state, and traffic counters.

Success Criteria (mandatory)

Measurable Outcomes

• SC-010: The background service uses under 1% of one CPU core when idle with 10 configured endpoints, and under 150 MB of memory under normal use.
• SC-014: The background service continues running and carrying MIDI with zero interruption across 50 consecutive open-and-close cycles of the graphical interface.
• SC-014a: A build produced without the graphical interface has no graphical or display-server dependencies and passes the full command-line acceptance suite on a machine with no desktop environment installed.
• SC-014b: Every configuration and control action available in the graphical interface has a documented command-line equivalent, verified as 100% coverage.
• SC-014c: A user goes from a freshly downloaded executable to a service running at login with a working virtual port using a single install command plus one create command.
• SC-016: All features present on one supported operating system are present and behave equivalently on the other, except those explicitly documented as platform-limited.

Assumptions

• Users are musicians, engineers, and hobbyists comfortable with MIDI concepts such as ports, channels, and controllers, but not necessarily with networking.
• Both supported operating systems are used on a single-user desktop where the person configuring Midi Harbor is the person logged in; multi-user and remote administration are out of scope.
• MIDI 1.0 message semantics are the baseline for routing, recovery, and monitoring. MIDI 2.0 is out of scope for this feature but the design should not preclude it.
• The graphical interface is excluded or included at build time rather than being downloaded or enabled at runtime, so distributions can offer a headless package without graphical dependencies.
• The platform's per-user service manager is assumed available: launchd on macOS, and systemd user units on Linux. Linux systems without systemd are supported only by running the service in the foreground under whatever supervisor the user prefers.
• Service installation is per-user and needs no elevated privileges, so it registers only for the user who runs it and does not start before that user logs in.
• Windows is not a target for this feature.
• Where the operating system already provides its own inter-application or network MIDI facility, Midi Harbor runs alongside it rather than replacing or reconfiguring it, and both may be in use at once.