Selektoren

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

Geräteauswahl — 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 (Platzhalter)
*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 kabellosen VerseGrips
*verse_grip/*	Alle Geräte der VerseGrip-Familie (kabelgebunden, kabellos, kundenspezifisch)
*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>- Der Selektor wendet zunächst den Klassenfilter an ein und indiziert anschließend die gefilterte Menge. <N> bezieht sich auf eine Position in der gefilterten Liste, nicht in der unbearbeiteten Geräteliste:

• *inverse:left/0 — das nullte Linkshänder Gerät der Inverse-Familie. Sind drei Inverse-Geräte miteinander verbunden (rechts, links, rechts), wird dies zum zweiten Gerät aufgelöst – nicht zum Index. 0, gefiltert nach „muss links sein“.
• inverse3:right/0 — der nullte Rechtshänder Inverse3.
• *inverse:left/3 — 404, wenn weniger als vier linkshändige Inverse-Geräte angeschlossen 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 Familiengerät, und POST- bzw. DELETE-Abfragen, die auf diese Selektoren abzielen, wenden die Operation auf jeden Treffer – und zwar nicht nur auf den ersten.

Regeln:

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

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

Sitzungsauswahl — ?session=<expr>-Abfrageparameter

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

Ausdruck	Bedeutung
(ausgelassen)	Alle Sitzungen (nur bei DELETE erlaubt)
#123 oder 123	Sitzung mit der Nummer 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	Erstes Treffen mit Profil default ein Index 0
co.haply.hub::*:0	Erste Sitzung, deren Profil mit co.haply.hub:: beginnt (Glob-Platzhalter)
:co.haply.hub::*:-1	Letzte Sitzung im Namensraum co.haply.hub::

Beispiel:

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

Platzhalter 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). Bei dem Vergleich wird zwischen Groß- und Kleinschreibung unterschieden.

Ein freistehendes * (oder all) behält seine bisherige Bedeutung von alle Sitzungen. Um Profile abzugleichen, deren Name mit * beginnt, geben Sie mindestens ein weiteres Zeichen ein (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 Platzhaltermuster ist für sich genommen mehrdeutig (Es kann mehr als eine Sitzung betreffen). Um es an einem GET- oder POST-Um den Endpunkt zu verwenden, beseitigen 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 Platzhalter (ohne Index) werden bei GET/POST mit 400 abgelehnt. Sie werden nur auf Routen toleriert, die ausdrücklich Treffer aus mehreren Sitzungen zulassen – 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 überprüfen, ob 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 entspricht funktional GET /sessions?session=<selector>; beide Routen rufen denselben Handler auf. GET /sessions/<sel> ist einer der wenigen Endpunkte, die ein mehrdeutiges Platzhaltermuster ohne :<index>- Suffix „tolerieren“ – es gibt alle Treffer in derselben Listenstruktur zurück wie GET /sessions.

Selektoren unverändert übergeben

Jede der oben genannten Selektorformen – einschließlich #42 und Profilmuster mit * – wird von Standard-HTTP-Clients (Python requests, libhv, curl, fetch) unverändert übernommen. 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 auf lokale Dateien mittels Glob-Expansion ausweitet.

Eine Ausnahme: Das Glob-Metazeichen ? ist in Pfade 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 Form einer Abfrage (?session=defaul?:0) gibt nur das erste an ? die Abfrage und die darauf folgenden ?-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 beziehen sich automatisch auf die Geräte der aktuellen Sitzung. Sitzungsselektoren werden nur für HTTP-Anfragen erforderlich (einschließlich sitzungsübergreifender Fernsteuerung – siehe Sitzungen).