Protocol
kōan's apps talk to a kōan server over Subsonic, and to each other through it and directly on the local network. Every kōan client links koan-core and shares its Rust types, but old and new versions meet across a release, and other clients and servers may speak the same protocol. These pages are its specification.
| Page | Covers |
|---|---|
| Link | The standing WebSocket between an app and its server: every message, relaying between devices, acks, shares |
| Nearby | Devices on one network finding and controlling each other without the server: discovery, the handshake, trust |
| Pairing and invites | Signing a device in without typing the password on it |
| Server extensions | Each koan* OpenSubsonic extension: endpoints, parameters, answers, credentials |
| Push relay | push.koan.rocks: how servers without Apple's key reach a suspended iPhone, and what the relay sees |
Schema
docs/reference/protocol/schema/ holds JSON Schema (draft 2020-12) for every message: link-command.json and link-report.json for the link and nearby connections, envelope.json for a command carrying an ack id, pair-message.json for a pairing socket, and nearby-frame.json for the nearby handshake and signed frames. They are generated from the Rust types, so they state what the code accepts; these pages state what the messages mean. envelope.json admits every command type, but acked is never sent in an envelope: its own ack field is the id of the command being answered. just protocol-schema regenerates them, and the test suite fails when the committed files differ from what the types produce.
Capabilities
A client decides what to use from what the other end says it supports, never from the server calling itself kōan.
- Server extensions. A kōan server lists its additions in
getOpenSubsonicExtensions, probed once per sign-in. A client uses an extension only where it is listed. Every extension is at version 1, and clients check the name only. Two exceptions remain. A server whose OpenSubsonictypeiskoanis linked to even withoutkoanLink, for servers that linked before it was listed. AndcreateShareon a kōan server takes an album asal-<id>, so a client prefixes album ids there only when thetypeiskoan. - Link parameters. A client says what it understands when it opens the link:
devices=1,acks=1,deviceKey. The server sendsdevices,sharesanddeviceKeysonly to links that asked, and attaches an ack id only for a device that sentacks=1. - Device flags. Each device in
devicescarriesacks, so a sender knows whether to wait for an answer from it. On the local network the listener'shellosays the same withacks, and with anoncethat it can prove itself; areports.prefix on the nonce says it signs its reports.
Compatibility rules
These hold today, and a change to the protocol keeps them.
Unknown messages are ignored. A receiver that cannot parse a frame, or does not know its type, drops it and keeps the connection open: an unreadable frame never closes a link or a nearby connection. The reasons a connection does close are on Link and Nearby. A command that is parsed and then refused is answered with a refused ack when it carried an id.
Unknown fields are ignored. No message type rejects fields it does not know. The push relay's requests are the exception: the relay refuses a field it does not know, since it accepts nothing it does not write itself.
Optional fields may be missing. A missing optional field takes its default: false, 0, empty, or absent. A missing required field, or an unknown value of a nested enum (play mode, repeat mode, a state's repeat and sleep, sleepTimer kind, output kind, ack result), fails the whole message, which is then ignored. Required fields are those the pages list without saying they may be absent.
Relayed commands are re-serialised. The server parses every command it relays, keeps for an absent device, or pushes, and sends its own serialisation. A field the server does not know does not survive the hop, and a command type it does not know is not relayed. A new field on a relayed command therefore needs the server updated before devices can rely on it, and anything that must survive an older server, as the ack id does, travels beside the command rather than inside it.
A new capability is announced before it is used. A new endpoint or behaviour on the server comes with a new extension name. A new message a device must understand is sent only to links that asked for it with a link parameter, or to devices whose devices entry or hello says they understand it. News an older client can safely miss, such as historyChanged, may go to every link, since it is ignored there.
Old meets new. An older client of a newer server sees the extensions it knows and ignores the rest; messages it was not built for are dropped. A newer client of an older server finds extensions missing from the list and leaves those features off, and commands for devices are carried with the fields the older server knows.