Selektoren

Selektoren legen fest, auf welches Gerät und auf welche Sitzung eine HTTP-Anfrage oder ein WebSocket-Befehl abzielt.

Geräte-Selektor — URL-Pfad

Wird in allen gerätebezogenen HTTP-Routen in der Form /{device_type}/{id_or_index}/… verwendet.

Routenbeispiel	Bedeutung des Selektors
inverse3/0	Erster Inverse3 nach Index (0-basiert)
inverse3/A14	Inverse3 mit Geräte-ID A14
inverse3/*	Alle Inverse3-Geräte (Wildcard)
*inverse/*	Alle Geräte der Inverse-Familie (Inverse3, Inverse3x, Minverse)
inverse3:left/0	Erster linkshändiger Inverse3 nach Index
*inverse:right/0	Erstes rechtshändiges Gerät der Inverse-Familie nach Index
verse_grip/0	Erster kabelgebundener VerseGrip nach Index
wireless_verse_grip/*	Alle drahtlosen VerseGrips
*verse_grip/*	Alle Geräte der VerseGrip-Familie (kabelgebunden, drahtlos, benutzerdefiniert)
*verse_grip:custom/0	Erster benutzerdefinierter VerseGrip nach Index (entspricht custom_verse_grip/0)

Klassenfilter werden vor der Indizierung aufgelöst

Ein <type>:<class>/<N>-Selektor wendet zuerst den Klassenfilter an und indiziert anschließend die gefilterte Menge. <N> bezieht sich auf eine Position in der gefilterten Liste, nicht in der rohen Geräteliste:

• *inverse:left/0 — das nullte linkshändige Gerät der Inverse-Familie. Sind drei Inverse-Geräte verbunden (rechts, links, rechts), wird dies zum zweiten Gerät aufgelöst – nicht zu Index 0, gefiltert auf „muss links sein“.
• inverse3:right/0 — der nullte rechtshändige Inverse3.
• *inverse:left/3 — 404, wenn weniger als vier linkshändige Inverse-Geräte verbunden sind, selbst wenn insgesamt mehr als vier Inverse-Geräte vorhanden sind.

Dieselbe Regel gilt für Wildcard-Selektoren: *inverse/* und *verse_grip/* treffen jedes Gerät der Familie, und POST- bzw. DELETE-Anfragen, die auf diese Selektoren zielen, wenden die Operation auf jeden Treffer an – nicht nur auf den ersten.

Regeln:

• GET lehnt Wildcard-Selektoren ab (mehrdeutig) → 400
• POST und DELETE akzeptieren Wildcards – die Operation wird auf alle Treffer angewendet
• 404-Antworten verwenden die Form no device matches selector '<sel>', wobei <sel> der ursprüngliche Selektorausdruck in der empfangenen Form ist

Unterstützte {device_type}-Werte: inverse3, verse_grip, wireless_verse_grip oder Familien-Wildcards *inverse, *verse_grip.

Sitzungs-Selektor — ?session=<expr>-Abfrageparameter

Sitzungsbezogene HTTP-Endpunkte (basis, mount, preset, filters, navigation, SDF) benötigen einen Abfrageparameter ?session=<expr>, der festlegt, in welchem Sitzungskontext sie arbeiten.

Ausdruck	Bedeutung
(weggelassen)	Alle Sitzungen (nur bei DELETE erlaubt)
#123 oder 123	Sitzung mit numerischer ID 123
:0	Erste Sitzung nach Index
:-1	Letzte Sitzung nach Index
profile_name	Erste Sitzung mit diesem Profil (kann mehrdeutig sein)
profile_name:0	Erste Sitzung mit diesem Profil und Index 0
:default:0	Erste Sitzung mit Profil default an Index 0
co.haply.hub::*:0	Erste Sitzung, deren Profil mit co.haply.hub:: beginnt (Glob-Wildcard)
:co.haply.hub::*:-1	Letzte Sitzung im Namensraum co.haply.hub::

Beispiel:

GET /inverse3/0/config/navigation?session=:default:0

Wildcards für Profilnamen

Profilmuster akzeptieren zwei Glob-Metazeichen:

Metazeichen	Bedeutung
*	steht für eine beliebige Zeichenfolge (auch leer)
?	steht für genau ein Zeichen

Alle anderen Zeichen – einschließlich :, ., -, [, ] – werden wörtlich verglichen (Zeichenklassen wie [abc] werden nicht unterstützt). Der Vergleich unterscheidet zwischen Groß- und Kleinschreibung.

Ein alleinstehendes * (oder all) behält seine bisherige Bedeutung von allen Sitzungen. Um Profile abzugleichen, deren Name mit * beginnt, geben Sie mindestens ein weiteres Zeichen an (z. B. *foo).

Nützliche Muster:

• co.haply.hub::* — jedes Profil im Namensraum co.haply.hub::
• *-update — jedes Profil, dessen Name auf -update endet
• co.haply.*:* — jedes Profil, dessen Namensraum mit co.haply. beginnt
• defaul? — jedes Profil mit 7 Zeichen, das mit defaul beginnt

Ein Wildcard-Muster ist für sich allein mehrdeutig (es kann mehr als eine Sitzung treffen). Um es an einem GET- oder POST-Endpunkt zu verwenden, lösen Sie die Mehrdeutigkeit durch einen nachgestellten :<index> auf:

# First session in the Haply Hub namespace
GET /inverse3/0/config/basis?session=co.haply.hub::*:0

# Last session in a Unity namespace
GET /inverse3/0/config/mount?session=:co.haply.unity::*:-1

Mehrdeutige Wildcards (ohne Index) werden bei GET/POST mit 400 abgelehnt. Toleriert werden sie nur auf Routen, die ausdrücklich Treffer mehrerer Sitzungen akzeptieren – GET /sessions/<sel> (gibt jeden Treffer zurück) und DELETE-Endpunkte (werden auf jeden Treffer angewendet).

Sitzungs-Selektor — URL-Pfad

Der Endpunkt /sessions/{selector} akzeptiert denselben Ausdruck wie ein Pfadparameter – nützlich, um eine einzelne Sitzung abzurufen oder zu prüfen, dass sie existiert:

GET /sessions                      # list all active sessions
GET /sessions/:default:0           # one session by profile + index
GET /sessions/:-1                  # last active session
GET /sessions/#42                  # session id 42
GET /sessions/co.haply.hub::*      # every session in the co.haply.hub:: namespace
GET /sessions/co.haply.hub::*:0    # first session in that namespace

Dies ist funktional äquivalent zu GET /sessions?session=<selector>; beide Routen rufen denselben Handler auf. GET /sessions/<sel> ist einer der wenigen Endpunkte, die ein mehrdeutiges Wildcard-Muster ohne :<index>-Suffix tolerieren – er gibt alle Treffer in derselben Listenstruktur zurück wie GET /sessions.

Selektoren unverändert übergeben

Jede oben genannte Selektorform – einschließlich #42 und Profilmuster mit * – wird von Standard-HTTP-Clients (Python requests, libhv, curl, fetch) unverändert übertragen. Eine clientseitige URL-Kodierung ist nicht erforderlich. In Shells sollten Sie Ausdrücke, die # oder * enthalten, in Anführungszeichen setzen (z. B. --session "#42", --session "co.haply.hub::*:0"), damit die Shell sie nicht als Kommentare interpretiert oder gegen lokale Dateien per Glob expandiert.

Eine Ausnahme: Das Glob-Metazeichen ? ist in Pfaden das Trennzeichen der URL-Abfrage. In einem Selektor in Pfadform (z. B. /sessions/defaul?:0) muss es als %3F prozentkodiert werden – GET /sessions/defaul%3F:0. In einem Selektor in Abfrageform (?session=defaul?:0) teilt nur das erste ? die Abfrage, und nachfolgende ?-Zeichen werden unverändert übernommen.

WebSocket-Sitzungen benötigen keine Selektoren

Bei einer WebSocket-Verbindung sind Sie die Sitzung – Ihre Einträge configure und commands zielen automatisch auf die Geräte der aktuellen Sitzung. Sitzungs-Selektoren werden nur für HTTP-Anfragen benötigt (einschließlich sitzungsübergreifender Fernsteuerung – siehe Sitzungen).