Drahtprotokoll

Dieses Dokument ist die vollständige Spezifikation des Nachrichtenformats zwischen agent, exchange und cli. Die Definitionen liegen in crates/proto; alle drei Seiten teilen denselben Code. Jedes Feld wird nur einmal definiert. Abweichungen werden beim Kompilieren statt erst in einer Produktionssitzung sichtbar.

Zielgruppe sind Betriebspersonal, das Paketmitschnitte untersucht, und Entwickler, die das Protokoll ändern oder Drittanbieterclients implementieren.

Inhaltsverzeichnis

• Überblick
• Transport und Endpunkte
• Protokollversion
• Steuernachrichten
  • DeviceUp（agent → exchange）
  • DeviceDown（exchange → agent）
  • OperatorUp（cli → exchange）
  • OperatorDown（exchange → cli）
  • Gemeinsame Datenstrukturen
• Binäre Datenframes
• Übersetzung zwischen zwei Sitzungsnummernräumen
• Handshake-Ablauf
• Fehlerbehandlung und Fehlerklassen
• Verbindungserhaltung und Zeitlimits
• Rückstau
• Android-Bildschirmsteuerung
• Ende-zu-Ende-versiegelte Sitzungen

Überblick

Das Protokoll besteht aus zwei Schichten, die dieselbe WebSocket-Verbindung nutzen:

Streamingdaten als base64 in JSON einzubetten vergrößert sie um etwa 33 %. PTY erzeugt häufig kleine Pakete für einzelne Tastenechos; dieser Aufwand erhöht unmittelbar die Interaktionslatenz. Steuernachrichten sind selten, sodass die Lesbarkeit von JSON mehr Nutzen bringt: Mitschnitte sind direkt verständlich.

Ein binärer WebSocket-Frame enthält vereinbarungsgemäß genau einen Datenframe. Zusätzliche oder fehlende Bytes gelten als Fehler.

Transport und Endpunkte

Die beiden Pfade verwenden unterschiedliche, nicht austauschbare Zugangsdaten. Ein Gerätetoken funktioniert am Operator-Endpunkt nicht und umgekehrt.

Operator-Zugangsdaten stehen im Anfrageheader statt in der URL-Abfrage, weil URLs in Reverse-Proxy-Protokollen, im Browserverlauf und im Referer auftauchen. Gerätetoken werden im ersten Frame übermittelt, weil einige eingebettete Clients nur schwer eigene WebSocket-Handshake-Header setzen können. Außerdem lassen sich dadurch eine inkompatible Protokollversion und ein ungültiges Token mit derselben Antwortnachricht ausdrücken.

In Produktionsumgebungen ist wss:// erforderlich: Beide Arten von Zugangsdaten erscheinen während des Handshakes im Klartext.

Protokollversion

pub const PROTOCOL_VERSION: u16 = 1;

Beim Handshake werden die Versionen auf beiden Seiten verglichen. Abweichungen führen sofort zur Ablehnung mit einer eindeutigen Meldung. So wird verhindert, dass eine Versionsabweichung erst später als unerklärlicher Parserfehler einer Nachricht auftritt, der schwer zu diagnostizieren wäre.

• Geräteseite: agent übermittelt seine Version in register. Bei einer Abweichung antwortet der Server mit register_ack und ok: false; error nennt beide Versionen. Anschließend wird die Verbindung geschlossen.
• Operator-Seite: Nach Verbindungsaufbau sendet der Server selbstständig welcome. Bei einer Abweichung meldet die CLI einen Fehler und fordert zum Upgrade auf eine zu server_version passende Version auf.

Unbekannte Nachrichtenwerte für type werden immer abgelehnt und niemals stillschweigend als bekannter Typ behandelt.

Steuernachrichten

Alle Steuernachrichten sind JSON-Objekte mit type als Kennzeichnung (internally-tagged Enums von serde). Kennzeichnungen und Feldnamen verwenden snake_case. session_id wird transparent als einfache Zahl serialisiert.

DeviceUp（agent → exchange）

Ein zweites register auf einer bereits registrierten Verbindung gilt als Protokollmissbrauch und wird als Warnung protokolliert.

Beispiel:

{"type":"register","protocol_version":1,"device_id":"lab-router","token":"a1b2….c2Vj…","info":{"hostname":"OpenWrt","model":"ath79/generic","openwrt_version":"OpenWrt 23.05.5","kernel":"5.15.137","arch":"mips","agent_version":"0.1.0"}}
{"type":"exec_exit","session_id":31,"code":0,"timed_out":false}

DeviceDown（exchange → agent）

OperatorUp（cli → exchange）

Die Authentifizierung erfolgt beim WebSocket-Handshake; daher gibt es keine Anmeldenachrichten.

Die session_id der vier open_*-Nachrichten wird von der CLI selbst vergeben (siehe Übersetzung zwischen zwei Sitzungsnummernräumen). Folgeframes können deshalb sofort nach der Anfrage gesendet werden, ohne Nummernbestätigung abzuwarten.

OperatorDown（exchange → cli）

Gemeinsame Datenstrukturen

ExecHoldInfo: job_id, kind (exec / download / upload / file), age_secs, session_id?, command_preview, status, timeout_secs, started_at_unix_ms, exit_code?, timed_out. Fehlendes kind wird kompatibel als exec interpretiert, fehlendes age_secs als 0. Listenantworten berechnen das Alter anhand der aktuellen Uhrzeit. Befehls-/Dateipfadkurzfassungen umfassen höchstens etwa 120 Zeichen. Andere Aufträge als exec unterstützen nur kill, kein tail/cat/attach.

DeviceSessionInfo: session_id: u32 (geräteseitige Nummer), operator_session_id: u32, kind: string, hold: bool, age_secs: u64, deadline_unix_ms: u64. Sitzungslisten und erzwungene Abbrüche beantwortet Exchange direkt, ohne neue Gerätesitzung. Schreibgeschützte Konten erhalten forbidden.

DeviceInfo

Statische Geräteinformationen, einmalig bei register gemeldet und in devices.info gespeichert. Außer agent_version sind alle Felder optional. In Nicht-OpenWrt-Umgebungen wie Entwicklungsrechnern und Containern fehlen viele Quellen; agent soll sich trotzdem registrieren statt beim Start zu scheitern. Nicht gesetzte Felder werden bei Serialisierung ausgelassen.

Metrics

Wird in jedem Heartbeat-Zyklus neu erfasst. Erfasst werden nur direkt aus /proc lesbare Werte, ohne Kindprozesse zu starten. Einzelne Lesefehler dürfen die Gesamterfassung nicht scheitern lassen: Ein fehlender Messwert ist besser als ein vollständig fehlgeschlagener Heartbeat, der das Gerät fälschlich offline erscheinen lässt.

InterfaceStats: { name: string, rx_bytes: u64, tx_bytes: u64 }

Binäre Datenframes

 0        1                    5                    9
 +--------+--------------------+--------------------+
 |  kind  |     session_id     |    payload_len     |  payload (payload_len 字节)
 |   u8   |    u32 (大端)      |    u32 (大端)      |
 +--------+--------------------+--------------------+
 └──────────── 9 字节定长头 ────────────┘

Streamtypen

Empfängt agent abwärts ExecStdout / ExecStderr, protokolliert er eine Warnung und verwirft sie: Die Gegenstelle ist dann fehlerhaft implementiert.

Entwurfsentscheidungen

payload_len ist tatsächlich redundant zum WebSocket-Längenfeld. Es bleibt aus zwei Gründen erhalten: Der Decoder erkennt abgeschnittene Frames, etwa angekündigte 11 statt tatsächlicher 5 Bytes, statt sie stillschweigend als kurzes Paket anzunehmen. Bei einem späteren Wechsel zu reinem TCP bleibt zudem das Frameformat unverändert.

Die Nutzlastgrenze von 1 MiB ist nicht für normalen Verkehr gedacht: PTY und Befehlsausgabe werden inkrementell gestreamt und erreichen diese Größenordnung nicht. Sie verhindert, dass eine Gegenstelle mit einem Header, der 2 GiB Nutzlast behauptet, den Serverspeicher erschöpft.

Leere Nutzlasten sind gültig: In PTY-Sitzungen kommen gelegentlich Lesevorgänge mit null Bytes vor. Der Frame besteht dann nur aus dem 9-Byte-Header.

Die Nutzlast enthält beliebige Bytes, einschließlich ungültiger UTF-8-Sequenzen, und muss unverändert bleiben.

Dekodierfehler

Ein Dekodierfehler betrifft nur diesen Datenframe: exchange protokolliert eine Warnung und verwirft ihn, ohne die Verbindung zu trennen.

Übersetzung zwischen zwei Sitzungsnummernräumen

Dieser Teil des Protokolls wird am leichtesten missverstanden.

In einem Satz

session_id wird vom Initiator vergeben und ist nur innerhalb seiner eigenen Verbindung eindeutig. Operator- und Geräteseite besitzen unabhängige Nummernräume; exchange übersetzt dazwischen. Dieselbe logische Sitzung hat auf beiden Seiten unterschiedliche Nummern.

  remote-cli                    exchange                      remote-agent
                                                        （设备 lab-router）

  ┌────────────┐        ┌────────────────────┐            ┌────────────┐
  │ 运维编号   │        │      路由表        │            │ 设备编号   │
  │  空间      │        │                    │            │  空间      │
  │            │        │  lab-router:       │            │            │
  │  session 7 │───────▶│    31 → (op-A, 7)  │───────────▶│ session 31 │
  │            │◀───────│                    │◀───────────│            │
  └────────────┘        │  op-A:             │            └────────────┘
                        │    7 → (lab-router,│
   由 CLI 自己的        │         31)        │             由 exchange
   SessionIdGenerator   └────────────────────┘             的 DeviceHandle
   分配（1,2,3…）                                          分配（1,2,3…）

Warum dieser Entwurf?

Eine zusätzliche Hin- und Rückübertragung vermeiden. Bei zentraler Nummernvergabe müsste die CLI nach dem Öffnen einer PTY erst eine Bestätigung wie „Ihre Sitzungsnummer ist 31“ abwarten, bevor sie Tastatureingaben senden kann. Durch eigene Vergabe kann sie Datenframes unmittelbar nach open_pty senden.

Nummernkollisionen zwischen Operatoren vermeiden. Zwei Operatoren können gleichzeitig die lokale Nummer 1 für dasselbe Gerät verwenden. Das Gerät muss sie unterscheiden können, sonst gelangt die Ausgabe einer Person zur anderen. exchange vergibt geräteseitige Nummern pro Geräteverbindung; zwei session 1 werden auf 31 und 32 abgebildet.

Gerätenummern von Operatorverhalten unabhängig halten. Die geräteseitigen Nummern werden vollständig von exchange kontrolliert; kein Operator kann sie festlegen oder erraten.

Zwei Tabellen

exchange verwaltet pro Verbindung eine Tabelle. Beide werden stets gemeinsam aktualisiert:

Der Rückwärtsindex dient der Bereinigung: Beim Trennen eines Operators müssen seine Sitzungen auf allen Geräten gefunden und einzeln beendet werden. Andernfalls blieben Prozesse und PTYs zurück, deren Ausgabe niemand empfängt.

Wo die Übersetzung erfolgt

Die Übersetzung ist die einzige Änderung an Datenframes: exchange analysiert, puffert oder verändert kein Nutzlastbyte. DataFrame::with_session_id ersetzt die Nummer direkt, ohne die Nutzlast neu zu allozieren.

Vergaberegeln

Beide Zähler beginnen bei 1, zählen aufwärts und überspringen 0. 0 ist Sentinel für „keiner Sitzung zugehörig“, etwa bei verbindungsbezogenen Fehlern.

• CLI (SessionIdGenerator): Nach Überlauf beginnt der Zähler erneut und überspringt 0. Vier Milliarden Sitzungen auf einer Verbindung sind unrealistisch, aber Umlauf eignet sich für langlebige Prozesse besser als panic.
• Geräteseite (DeviceHandle::open_session): Trifft der Zähler nach Umlauf auf eine noch aktive Sitzung, sucht er den nächsten freien Platz.

exchange lehnt 0 und Wiederverwendung aktiver Operator-Sitzungsnummern ab. Gültigkeit der Geräteverbindung, Parallelitätsgrenze und Einträge in beiden Indizes werden im selben kritischen Abschnitt geprüft, damit gleichzeitiges Öffnen durch mehrere Operatoren die Grenze nicht überschreitet.

Verhalten bei fehlender Route

Stillschweigend verwerfen, keinen Fehler melden. Nach dem Schließen noch eintreffende Restdaten sind ein normaler Wettlauf. Die Regel gilt in beiden Richtungen:

• Gerät antwortet für nicht mehr existierende Sitzung → debug-Protokoll; möglicherweise hat sich der Operator vorher getrennt.
• Operator sendet Daten für verwaiste Sitzung → trace-Protokoll und verwerfen.

Bereinigungspfade für Sitzungen

Der Rückwärtsindex ist an die konkrete Geräteverbindung gebunden. Er wird nach Wiederverbindung nicht anhand der Geräte-ID auf die neue Verbindung umgeleitet. Mehrere Operator-Verbindungen desselben Kontos besitzen eigene Indizes; Trennen einer Verbindung beendet keine Sitzungen einer anderen.

Abschlussbestätigungen bei aktivem Abbruch: exec erhält exec_exit (code: null, timed_out: false), PTY pty_closed (code: null), ubus session_failed (reason: device_error). Damit bestätigt exchange das Schließen der Sitzung, nicht das Ende des entfernten Prozesses. Spätere Restdaten und Exitmeldungen werden verworfen.

Beim Erreichen der Parallelitätsgrenze bereinigt Exchange unter derselben Sitzungssperre zuerst Routen ohne Operator oder mit überschrittener Frist und prüft dann erneut die Grenze. Für exec gilt das tatsächlich übermittelte Zeitlimit plus 15 Sekunden, für Dateien 3600 Sekunden plus 15 Sekunden, für andere Typen 24 Stunden. hold exec innerhalb der Frist wird beim Verlassen des Operators nicht beendet. Bereinigung oder explizites kill_device_session sendet den passenden Abbruchbefehl ans Gerät und entfernt sofort beide Indizes, ohne Geräteantwort abzuwarten. Erreichbare Operatoren erhalten für exec exec_exit (timed_out:true), sonst session_failed (device_error, session reclaimed). Das Audit wird nach Möglichkeit asynchron vervollständigt.

Gerätewiederverbindung und epoch

Jede Geräteverbindung erhält bei Registrierung eine zufällige epoch (UUID). Verbindet sich dasselbe Gerät erneut, ersetzt die neue Verbindung die alte. Doppelte Verbindungen lassen sich nicht zuverlässig von bereits toten, aber serverseitig unerkannten halb offenen Verbindungen unterscheiden. Bei Ablehnung könnte das Gerät bis zum Timeout der alten Verbindung nicht verbinden.

Die Bereinigung der alten Verbindung kann nach Registrierung der neuen erfolgen. Beim Austragen muss deshalb die epoch geprüft werden: Nur wenn die aktuelle Verbindung in der Tabelle dieselbe epoch besitzt, darf sie entfernt werden. Ohne diese Prüfung würde alte Bereinigung das gerade verbundene Gerät sofort wieder offline setzen.

Handshake-Ablauf

Geräteseite

  remote-agent                                        exchange
      │                                                 │
      │  ①  WebSocket 握手（wss://host/ws/device）      │
      │────────────────────────────────────────────────▶│
      │◀────────────────────────────────────────────────│
      │            101 Switching Protocols              │
      │                                                 │
      │                                          ┌──────┴──────┐
      │                                          │ 启动 15 秒  │
      │                                          │ 注册计时器  │
      │                                          └──────┬──────┘
      │  ②  {"type":"register","protocol_version":1,    │
      │      "device_id":"…","token":"…","info":{…}}    │
      │────────────────────────────────────────────────▶│
      │                                                 │
      │                              ┌──────────────────┴──────────────────┐
      │                              │ a. 比对 protocol_version            │
      │                              │ b. split_token → 前缀查 devices 表  │
      │                              │ c. 校验 enabled                     │
      │                              │ d. argon2 verify（前缀不符也照做，  │
      │                              │    避免用耗时区分前缀是否存在）     │
      │                              └──────────────────┬──────────────────┘
      │                                                 │
      │  ③  {"type":"register_ack","ok":true,           │
      │      "error":null,"heartbeat_interval_secs":30} │
      │◀────────────────────────────────────────────────│
      │                                                 │
      │                                          ┌──────┴──────┐
      │                                          │ 登记连接表  │
      │                                          │ 顶替旧连接  │
      │                                          │ 回写 info 与│
      │                                          │ last_seen_at│
      │                                          └──────┬──────┘
      │                                                 │
      │  ④  退避曲线复位，写状态文件 state=connected     │
      │                                                 │
      │══════════════ 转发循环 ═══════════════════════════│
      │                                                 │
      │  heartbeat（每 30 秒，携带 Metrics）             │
      │────────────────────────────────────────────────▶│
      │  WebSocket Ping（随每次 heartbeat 发出）         │
      │────────────────────────────────────────────────▶│
      │                                     WebSocket Pong
      │◀────────────────────────────────────────────────│
      │                                     WebSocket Ping（每 30 秒）
      │◀────────────────────────────────────────────────│
      │  Pong（tungstenite 排队，agent 显式 flush）       │
      │────────────────────────────────────────────────▶│

Fehlerpfade:

• Erster Frame ist kein Textframe, kein gültiges JSON oder kein register → Warnung protokollieren und direkt schließen, ohne ack.
• Kein register innerhalb von 15 Sekunden → Verbindung schließen.
• Versionsabweichung → register_ack{ok:false, error:"协议版本不匹配：设备为 X，服务端为 Y"} senden und schließen.
• Ungültiges Token / Gerät nicht vorhanden / Gerät deaktiviert → immer dieselbe Meldung "设备 ID 或令牌无效" senden und schließen. Keine Ursachenunterscheidung, da sonst der Gerätebestand aufgezählt werden könnte.

agent behandelt diese beiden Fehlerklassen getrennt:

Die Backoff-Kurve wird erst nach erfolgreicher Registrierung zurückgesetzt, nicht beim TCP-Verbindungsaufbau. Sonst würden sofort abgelehnte Verbindungen zu dichten Wiederholungsversuchen im Millisekundentakt führen.

Jitter ist notwendig. Beim Serverneustart erkennen Hunderte oder Tausende Geräte gleichzeitig die Trennung. Mit derselben deterministischen Wiederverbindungskurve blieben sie synchron und würden den gerade gestarteten Server wellenweise überlasten. Ein einzelner Neustart könnte so eine dauerhafte Überlastung auslösen.

Operator-Seite

  remote-cli                                          exchange
      │                                                 │
      │  ①  WebSocket 握手（wss://host/ws/operator）    │
      │      Authorization: Bearer <prefix>.<secret>    │
      │────────────────────────────────────────────────▶│
      │                                                 │
      │                              ┌──────────────────┴──────────────────┐
      │                              │ 在 upgrade 之前完成鉴权：           │
      │                              │ split_token → 前缀查 operators 表   │
      │                              │ → argon2 verify → 校验 enabled      │
      │                              └──────────────────┬──────────────────┘
      │                                                 │
      │      鉴权失败 → HTTP 401「凭证无效」（不升级）   │
      │◀────────────────────────────────────────────────│
      │                                                 │
      │◀────────────────────────────────────────────────│
      │            101 Switching Protocols              │
      │                                                 │
      │  ②  {"type":"welcome","protocol_version":1,     │
      │      "server_version":"0.1.0"}                  │
      │◀────────────────────────────────────────────────│
      │                                                 │
      │  ③  比对 protocol_version（15 秒超时）          │
      │      不一致 → 报错退出，提示升级 CLI            │
      │                                                 │
      │══════════════ 可以发起会话 ═══════════════════════│
      │                                                 │
      │  {"type":"open_pty","session_id":1,             │
      │   "device_id":"lab-router","rows":40,"cols":120}│
      │────────────────────────────────────────────────▶│
      │                                                 │──▶ 查设备在线
      │                                                 │──▶ 查并发上限
      │                                                 │──▶ 查 readonly 角色
      │                                                 │──▶ 写审计（先于下发）
      │                                                 │──▶ 分配设备侧编号
      │  二进制帧（PtyData, session 1, 键盘输入）        │
      │────────────────────────────────────────────────▶│──▶ 改写为设备侧编号
      │                                                 │
      │  二进制帧（PtyData, session 1, 屏幕输出）        │
      │◀────────────────────────────────────────────────│◀── 改写为运维侧编号

Die CLI kann die Datenframes des zweiten Schritts ohne jede Bestätigung abzuwarten senden. Genau dafür vergibt der Initiator die Nummern selbst.

Fehlerbehandlung und Fehlerklassen

SessionFailure

Steht im Feld reason von session_failed; JSON-Werte verwenden snake_case.

is_retryable() schließt forbidden und device_error bewusst aus. Das Wiederholen eines Berechtigungsproblems oder internen Gerätefehlers ist sinnlos und würde die CLI nur beschäftigen.

Die CLI ergänzt die ursprüngliche message um einen Handlungshinweis. Bei device_offline empfiehlt sie etwa remote-cli device list, um den Gerätestatus zu prüfen. Ausnahme ist device_error: Die Gerätenachricht erklärt den Fehler am genauesten und soll nicht durch Standardfloskeln verwässert werden.

Fehlersemantik nach Schicht

Grundsatz: Lokalisierbare Fehler werden niemals zu Verbindungsfehlern hochgestuft, denn eine Geräteverbindung kann gleichzeitig Sitzungen mehrerer Operatoren tragen.

Verbindungserhaltung und Zeitlimits

Auch der Client einer inaktiven Shell antwortet mit Pong. agent flusht die automatisch eingereihte Bibliotheksantwort ausdrücklich, ohne auf den nächsten betrieblichen Heartbeat zu warten. Deshalb wird die Verbindung ohne Tastatureingaben nicht fälschlich als verloren betrachtet (#42). --heartbeat-secs muss größer als 0 sein; ungültige Werte werden beim Parsen der Startargumente abgelehnt.

Rückstau

exchange verwaltet pro Verbindung eine begrenzte Sendewarteschlange mit 512 Nachrichten.

Eine volle Warteschlange bedeutet, dass die Gegenstelle nicht schnell genug konsumiert; bei PTY meist durch blockiertes Netzwerk oder angehaltenen Client. Die Verbindung wird aktiv getrennt, statt weiter zu puffern. Unbegrenzte Puffer würden einen blockierten Client in ein Speicherleck des gesamten Dienstes verwandeln. 512 Nachrichten bieten interaktiven PTYs großen Spielraum; normalerweise liegt die Länge im einstelligen Bereich. Bei Erreichen der Grenze verarbeitet die Gegenstelle praktisch keine Daten mehr.

Zustellung verwendet immer nicht blockierendes try_send. Im Routingpfad wird die Sperre der Verbindungstabelle gehalten. Ein await würde deren Haltedauer an die Verarbeitungsgeschwindigkeit der Gegenstelle koppeln; ein langsamer Client würde die gesamte Tabelle blockieren.

Zwei Zustellfehler werden unterschieden:

Das Schließsignal durchläuft die Sendewarteschlange nicht. Es löst daher auch bei voller Warteschlange oder blockiertem Schreiben die Bereinigung aus. Geräteverbindungsersetzung und Tokenrotation verwenden denselben Mechanismus.

Auch agent besitzt eine ausgehende Warteschlange mit Kapazität 256. Ist sie voll, kann das Netzwerk überhaupt keine Daten mehr versenden. Weiteres Sammeln ist sinnlos; daher wird getrennt und neu verbunden. Ist die PTY-Eingabewarteschlange (64) voll, werden Tasten direkt verworfen: Kleine interaktive Eingaben anzustauen ist nicht sinnvoll.

Android-Bildschirmsteuerung

Die Definitionen liegen in crates/proto/src/android.rs. Verwendet werden bestehendes Routing mit zwei Nummernräumen, Authentifizierung, Parallelitätsgrenzen und Audit. request in open_android / android_req ist ein durch action unterschiedenes JSON-Objekt:

AndroidResult wird durch kind unterschieden; alle Felder sind Pflichtfelder:

Knoten enthalten Strings class_name, package, view_id, text, description, bounds: [left, top, right, bottom] (vorzeichenbehaftete Bildschirm-Pixelkoordinaten) und boolesche Felder clickable, editable, focused, password. Höchstens 200 Knoten und 256 UTF-16-Einheiten pro String; truncated kennzeichnet nur die Knotengrenze. Passwortwerte und -beschreibungen bleiben leer; agent-eigener Konfigurationsunterbaum wird ausgelassen.

Die lange Screenshotseite hat höchstens 1600 Pixel. width/height sind Bildabmessungen, screen_width/screen_height Abmessungen vor Skalierung. Gestenkoordinaten beziehen sich auf unskalierte Abmessungen. Die Java-Brücke liefert höchstens 2 MiB JSON; WebSocket-Verpackung erlaubt zusätzlich 1024 Bytes. Kein neuer binärer Frametyp wird eingeführt.

{"type":"open_android","session_id":1,"device_id":"phone","request":{"action":"input_text","text":"Hello\nWorld"}}
{"type":"android_req","session_id":31,"request":{"action":"input_text","text":"Hello\nWorld"}}
{"type":"android_resp","session_id":31,"result":{"kind":"ok"}}
{"type":"android_resp","session_id":1,"result":{"kind":"ok"}}

screen_capture_enabled zeigt eine derzeit verfügbare Screenshotberechtigung an (MediaProjection oder Bedienungshilfe ab Android 11). Alle tatsächlichen Bildschirmaktionen benötigen weiterhin controls_enabled. Fehlende Berechtigungen, unzugängliche Fenster oder fehlgeschlagene Aktionen beantwortet agent mit session_error; Exchange wandelt dies in session_failed um. Nicht-Android-agents melden ausdrücklich fehlende Unterstützung.

Agent verarbeitet höchstens 4 Android-Anfragen gleichzeitig und kodiert jeweils nur einen Screenshot. Java-Operationen warten höchstens 10 Sekunden, auf Bildschirmframes höchstens 5 Sekunden. Das agent-Anfragelimit beträgt 15 Sekunden, das CLI-Limit 20 Sekunden. Bei Abbruch oder Operator-Trennung sendet Exchange android_cancel; agent schließt lokalen Socket, und APK bricht noch nicht ausgeführte Warteschlangenarbeit ab. Bereits ausgeführte Gesten oder Textänderungen werden nicht rückgängig gemacht.

Die Audit-action lautet android; detail speichert Aktion und Koordinaten. Bei input_text wird nur characters (Anzahl der Unicode-Zeichen) gespeichert; erfolgreiche Ergebnisse enthalten nur outcome: "completed". Textinhalt, Oberflächenbaum und Bilder werden nicht im Audit gespeichert. readonly-Konten dürfen auch status, tree und Screenshots nicht anfordern.

Erweiterung für Dateisitzungen

Agents mit Dateiunterstützung melden Fähigkeit files. Exchange übersetzt open_file {session_id, device_id, request} in file_req {session_id, request}. request.action ist list, download oder upload; Felddefinitionen stehen in crates/proto/src/files.rs.

Steuernachrichten beider Richtungen verwenden JSON: Der Controller sendet file_input {session_id, input}, das Gerät antwortet file_event {session_id, event}. input.kind ist chunk {offset, data}, ack {offset} oder finish; event.kind ist ready {size}, chunk {offset, data}, progress {received}, complete {size} oder list {path, entries, truncated}. Blockinhalte verwenden Standard-Base64. Pro Block höchstens 64 KiB; der Sender wartet vor dem Fortfahren auf Bestätigung.

Das erste ready eines Downloads benötigt ack {offset: 0}; danach bestätigt jeder Block die kumulierte Bytezahl. Ein Upload beginnt mit ready; jedes progress löst nächsten Block aus, nach vollständiger Übertragung wird mit finish abgeschlossen. complete und list sind Abschlussnachrichten; Fehler verwenden vorhandenes session_error / session_failed. close_session sendet file_cancel; Abbruch und Verbindungsverlust entfernen jeweils die Sitzungsroute. Dateinachrichten werden ausschließlich für Dateisitzungen weitergeleitet, damit Operator- und Gerätesitzungs-IDs getrennt bleiben.

Die Protokollversion bleibt 1. Neue Nachrichten erfordern passende Upgrades von Exchange und Agent. Betriebsgrenzen und LAN-Schnittstellen beschreibt Dateiübertragung und direkte LAN-Verbindung.

Plattformübergreifende Erweiterungen

Die Protokollversion bleibt 1. Das Registrierungs-info erhält optionale Felder platform (openwrt / linux / freebsd / netbsd / windows / android / macos), os_version, capabilities (exec / pty / ubus / android_control / files / sensors / net). OpenWrt meldet openwrt_version.

Heartbeat-metrics.unavailable ist ein optionales Stringarray für derzeit nicht erfassbare Werte uptime, load, memory, cpu, interfaces. Fehlt das Array, wird das alte Format verwendet. Werte der darin genannten Messgrößen sind nur Kompatibilitätsplatzhalter; Clients sollen sie als fehlend anzeigen. Windows bietet keine Unix-Durchschnittslast; Android kann manche /proc-Quellen durch Systemberechtigungen beschränken.

Befehle werden durch die Shell des Zielgeräts interpretiert: Linux/OpenWrt/macOS verwenden /bin/sh, Windows PowerShell und Android /system/bin/sh. PTY-Frameformat und Steuernachrichten sind auf den drei Systemen identisch; Windows verwendet ConPTY. Nicht-OpenWrt-Geräte antworten auf ubus-Anfragen mit session_error.

Ende-zu-Ende-versiegelte Sitzungen

Die Protokollversion bleibt 1. Neue Nachrichten: OperatorUp open_sealed {session_id, device_id, hello}, sealed_input {session_id, packet}; DeviceDown sealed_open {session_id, hello}, sealed_input, sealed_close {session_id, detach}; DeviceUp / OperatorDown sealed_accept {session_id, accept}, sealed_event {session_id, packet, last}. Hinzu kommen binärer Frametyp 4 = Sealed (Nutzlast counter ‖ AEAD(inner_kind ‖ bytes)), DeviceInfo.seal_key und Fähigkeit sealed.

Exchange übernimmt bei versiegelten Sitzungen nur Nummernübersetzung, Parallelitätsbegrenzung und Routing. Es analysiert oder auditiert keine Nutzlast; das Audit erfasst lediglich öffentliche Schlüssel, Berechtigungsstufe und Ablauf sowie Abschlussergebnis. Es entscheidet nicht über Berechtigungen, sondern prüft nur, ob das Konto das Gerät sehen darf. Bei last:true wird die Route freigegeben. Versiegelte Routen akzeptieren ausschließlich Sealed-Frames, normale Routen keine Sealed-Frames. agent verwirft jeden Klartext an versiegelte Sitzungsnummern. Autorisierung, Handshake, Schlüsselableitung, Bedrohungsmodell beschreibt Ende-zu-Ende-versiegelte Sitzungen.