Gateway arhitektuur

Viimati uuendatud: 2026-01-22

Ülevaade

  • Üks pikaajaline Gateway omab kõiki sõnumivahetuse pindu (WhatsApp läbi Baileys, Telegram läbi grammY, Slack, Discord, Signal, iMessage, WebChat).
  • Kontroll-tasandi kliendid (macOS rakendus, CLI, veeb UI, automatiseeringud) ühenduvad Gateway-ga üle WebSocket konfigureeritud sidumishostil (vaikimisi 127.0.0.1:18789).
  • Sõlmed (macOS/iOS/Android/headless) ühenduvad samuti üle WebSocket, kuid deklareerivad role: node selgesõnaliste caps/käskudega.
  • Üks Gateway hosti kohta; see on ainus koht, mis avab WhatsApp sessiooni.
  • canvas host teenindatakse Gateway HTTP serveri poolt:
    • /__mayros__/canvas/ (agendi muudetav HTML/CSS/JS)
    • /__mayros__/a2ui/ (A2UI host) See kasutab sama porti mis Gateway (vaikimisi 18789).

Komponendid ja vood

Gateway (daemon)

  • Hooldab pakkuja ühendusi.
  • Paljastab tipitud WS API (taotlused, vastused, serveri push sündmused).
  • Valideerib sissetulevaid raame JSON Schema vastu.
  • Emiteerib sündmusi nagu agent, chat, presence, health, heartbeat, cron.

Kliendid (mac rakendus / CLI / veeb admin)

  • Üks WS ühendus kliendi kohta.
  • Saada taotlusi (health, status, send, agent, system-presence).
  • Telli sündmusi (tick, agent, presence, shutdown).

Sõlmed (macOS / iOS / Android / headless)

  • Ühendu samale WS serverile role: node abil.
  • Paku seadme identiteeti connect-is; sidumine on seadmepõhine (roll node) ja kinnitus asub seadme sidumise poes.
  • Paljasta käske nagu canvas.*, camera.*, screen.record, location.get.

Protokolli üksikasjad:

WebChat

  • Staatiline UI, mis kasutab Gateway WS API vestluse ajaloo ja saatmiste jaoks.
  • Kaug seadistustes ühendub sama SSH/Tailscale tunneli kaudu kui teised kliendid.

Ühenduse elutsükkel (üks klient)

mermaid
sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: või res error + sulge
    Note left of Client: payload=hello-ok<br>hetktõmmis: presence + health

    Gateway-->>Client: event:presence
    Gateway-->>Client: event:tick

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent<br>ack {runId, status:"accepted"}
    Gateway-->>Client: event:agent<br>(voogedastamine)
    Gateway-->>Client: res:agent<br>final {runId, status, summary}

Juhtme protokoll (kokkuvõte)

  • Transport: WebSocket, teksti raamid JSON kasulikkede koormusega.
  • Esimene raam peab olema connect.
  • Pärast käepigistust:
    • Taotlused: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
    • Sündmused: {type:"event", event, payload, seq?, stateVersion?}
  • Kui MAYROS_GATEWAY_TOKEN (või --token) on määratud, peab connect.params.auth.token vastama või socket sulgub.
  • Idempotentsuse võtmed on nõutud kõrvalmõjusid omavate meetodite jaoks (send, agent), et turvaliselt korda; server hoiab lühiajalist dedupe vahemälu.
  • Sõlmed peavad sisaldama role: "node" pluss caps/käsud/load connect-is.

Sidumine + kohalik usaldus

  • Kõik WS kliendid (operaatorid + sõlmed) sisaldavad seadme identiteeti connect-il.
  • Uued seadme ID-d nõuavad sidumise kinnitust; Gateway väljastab seadme tokeni järgnevate ühenduste jaoks.
  • Kohalikud ühendused (loopback või gateway hosti enda tailnet aadress) saab automaatselt kinnitada, et hoida sama hosti kasutajakogemus sujuv.
  • Mitte-kohalikud ühendused peavad allkirjastama connect.challenge nonce ja nõuavad selgesõnalist kinnitust.
  • Gateway auth (gateway.auth.*) kehtib endiselt kõigile ühendustele, kohalikud või kaugühendused.

Üksikasjad: Gateway protokoll, Sidumine, Turvalisus.

Protokolli tippimine ja codegen

  • TypeBox skeemid määratlevad protokolli.
  • JSON Schema genereeritakse nendest skeemidest.
  • Swift mudelid genereeritakse JSON Schema-st.

Kaugligipääs

  • Eelistatud: Tailscale või VPN.

  • Alternatiiv: SSH tunnel

    bash
    ssh -N -L 18789:127.0.0.1:18789 user@host

  • Sama käepigistus + auth token kehtivad tunneli üle.

  • TLS + valikuline kinnitamine saab lubada WS jaoks kaug seadistustes.

Operatsioonide hetktõmmis

  • Alusta: mayros gateway (esiplaanil, logib stdout-i).
  • Tervis: health üle WS (sisaldub ka hello-ok-s).
  • Järelevaatus: launchd/systemd automaatseks taaskäivituseks.

Invariandid

  • Täpselt üks Gateway kontrollib üht Baileys sessiooni hosti kohta.
  • Käepigistus on kohustuslik; ükskõik milline mitte-JSON või mitte-connect esimene raam on kõva sulgemine.
  • Sündmusi ei korratud; kliendid peavad lünkadel värskendama.