MQTT — magistrala zdarzeń

Komunikacja opisana literalnie w dokumentacji źródłowej:

Wniosek: wersja Julii opisana dla komisji jest aplikacją desktopową z dominującym HTTP/S i SDK SimConnect, a nie klientem MQTT.

Repozytorium Pilot Hangar może ewoluować w stronę fleet / telemetry z użyciem MQTT dla innych komponentów (edge, workerzy, mostek do Firestore). Taka architektura nie zastępuje opisu PDF Julii+MSFS — jest ortogonalna.

Jeśli w przyszłości pojawi się oficjalny rejestr tematów i kontrakty JSON dla JET/Hangar, należy je dodać tutaj jako osobną sekcję wersjonowaną.

Poniższe nie pochodzi z PDF Julii — to wzór dla ewentualnych komponentów IoT/symulatora rozproszonego:

Konwencja tematów (referencyjna)

jet/{tenant}/{siteId}/session/{hwid}/telemetry/gps
jet/{tenant}/{siteId}/session/{hwid}/cmd/desired
jet/{tenant}/{siteId}/session/{hwid}/cmd/ack

QoS (typowe decyzje)

TLS i ACL

• Produkcja: TLS (np. port 8883); wyłączyć anonimowy dostęp.
• ACL per rola: edge, worker, admin — zasada najmniejszych uprawnień.
• Brak sekretów w payloadach MQTT — tokeny krótkotrwałe przez HTTPS.

Retained i LWT

• Retained oszczędnie (np. ostatni stan online).
• LWT przy reconnect — sensowny keepalive i firewall nie „ucinający” sesji bez LWT.

Jeśli worker subskrybuje MQTT i zapisuje do Firestore:

• throttling zapisów (koszt i limity),
• pola updatedAt, seq,
• bufor ostatniej wartości — zapis po interwale lub progu zmiany pozycji.

• Metryki brokera: połączenia, throughput, odrzucone publikacje (ACL).
• Korelacja: clientId, hwid, traceId w payloadach krytycznych ścieżek.

Poniższy blok to pełna warstwa operacyjna opisu MQTT w ekosystemie JULIA/JET (portal, workerzy, edge poza desktopową Julją+MSFS). Nie zastępuje tabeli „Co jest w PDF zamiast MQTT” — uzupełnia ją o parametry wdrożeniowe, gdy broker jest w użyciu.

Rola MQTT w stosie JULIA/JET

• Deklaratywny model pub/sub — węzły nie muszą znać adresów IP konsumentów; wystarczy kontrakt tematów.
• Luźne sprzężenie — nowy subskrybent (np. analityka) bez zmiany producentów, przy zachowaniu ACL.
• Semantyka „at least once” dla większości telemetrii stanowej (QoS 1), z wyjątkami w tabeli QoS.
• Granica zaufania — broker jest punktem centralnym; jego hardening (TLS, ACL, rate limiting) jest krytyczny.

Topologia brokerów i tenancy

Środowisko deweloperskie

• Jeden broker (Mosquitto) na hoście lub w kontenerze eclipse-mosquitto:2.
• Sieć w Docker Compose (hangar-internal), bez ekspozycji publicznej.

Środowisko produkcyjne

• Broker dedykowany na region / site albo klaster HA (dwa węzły + VIP, lub usługa zarządzana).
• Izolacja tenancy: prefiks pierwszego poziomu identyfikuje organizację (jet/{tenantId}/… albo julia/{region}/…). Utrzymaj jedną konwencję w całym projekcie.

Zasada: nie mieszaj na jednym brokerze produkcji dev i prod bez silnej separacji ACL — preferowane osobne instancje lub rozłączne prefiksy root z osobnymi credentialami.

Konwencja nazewnictwa tematów (rejestr referencyjny)

jet/{tenant}/{siteId}/session/{hwid}/telemetry/gps
jet/{tenant}/{siteId}/session/{hwid}/telemetry/imu
jet/{tenant}/{siteId}/session/{hwid}/status/heartbeat
jet/{tenant}/{siteId}/session/{hwid}/cmd/desired
jet/{tenant}/{siteId}/session/{hwid}/cmd/ack
julia/{region}/bus/health
julia/{region}/bus/diag/{serviceId}

Zasady: stałe segmenty (telemetry, status, cmd) utrudniają literówki i ułatwiają ACL typu jet/+/+/session/+/telemetry/#. Unikaj głębokich hierarchii bez potrzeby. Przy łamaniu kompatybilności payloadu rozważ nowy segment (telemetry/gps/v2).

Poziomy QoS — decyzje inżynierskie

Antywzorzec: QoS 2 dla setek wiadomości/s na jednym temacie — zwykle niepotrzebny koszt.

Retained messages i Last Will (szczegóły)

Retained: używaj oszczędnie (np. ostatni status/online per hwid z małym JSON). Nie ustawiaj retained na strumieniach wysokiej częstotliwości.

LWT: przy connect temat np. .../status/lwt z payloadem {"state":"offline","reason":"tcp_drop"}. Upewnij się co do keepalive i firewalla (ciche zerwanie bez LWT).

Payloady JSON — szkielety kontraktów

Telemetria GPS (przykład referencyjny)

{
  "schema": "jet.telemetry.gps.v1",
  "hwid": "string",
  "ts": "2026-03-27T12:00:00.000Z",
  "lat": 52.2297,
  "lon": 21.0122,
  "acc_m": 4.2,
  "src": "gnss"
}

Komenda desired → ack

{ "cmdId": "uuid", "action": "sync_config", "params": { "profile": "night" } }

{ "cmdId": "uuid", "status": "applied", "detail": "ok" }

Zasady: zawsze schema lub pole wersji; timestampy UTC ISO 8601; nigdy sekretów w MQTT plaintext — tokeny krótkotrwałe przez HTTPS.

TLS, certyfikaty i tożsamość klienta

• Port 8883 (TLS) w produkcji; wyłącz czysty 1883 na interfejsach publicznych.
• mTLS tam, gdzie urządzenia są w PKI.
• Rotacja certyfikatów zautomatyzowana; monitoruj Not After.
• SNI i hostname zgodne z CN/SAN certyfikatu serwera.

ACL brokerowe (przykład Mosquitto aclfile)

user julia_edge
topic readwrite jet/acme/+/session/+/telemetry/#
topic readwrite jet/acme/+/session/+/status/#
topic read jet/acme/+/session/+/cmd/desired
topic write jet/acme/+/session/+/cmd/ack

user hangar_worker
topic read jet/acme/#
topic write julia/eu-west/bus/diag/#

Testuj ACL w CI (sub/pub z oczekiwanym Not authorized).

WebSockets i przeglądarka

• Hangar lub panel diagnostyczny przez WebSocket → WSS i te same zasady TLS.
• Limity rozmiaru wiadomości po stronie brokera (message_size_limit) — ochrona przed DoS.

Telemetria a throttling zapisu w Firestore

Wzorzec: MQTT może dostarczać dane częściej niż ekonomia Firestore pozwala. Subskrybent buforuje, zapisuje co interwał lub po progu przemieszczenia; payload może nosić seq.

# Pseudokod — weryfikacja przed produkcją
last = {}
INTERVAL = 5.0

async def on_gps(hwid: str, payload: dict) -> None:
    now = time.monotonic()
    prev = last.get(hwid)
    if prev and (now - prev[0]) < INTERVAL:
        last[hwid] = (now, payload)
        return
    last[hwid] = (now, payload)
    await firestore_save(hwid, payload)

Back-pressure i odporność

• Subskrybenci nieblokujący lub z ograniczoną kolejką — w przeciwnym razie TCP do brokera się zapcha.
• W Pythonie: asyncio + kolejka z limitem; przy overflow strategia „ostatnia wartość wygrywa” lub próbkowanie.
• Reconnect z jitterem — unikaj burzy po restarcie brokera.

Observability (rozszerzenie)

• Metryki: liczba połączeń, throughput, retained count, publikacje odrzucone (ACL).
• Alerty: skok messages_dropped, brak heartbeat regionu, wzrost opóźnień (jeśli broker eksponuje latency).

Failover i scenariusze awarii

1. Broker niedostępny — edge buforuje w RAM (ograniczony) lub lokalnie; po powrocie synchronizacja z idempotencją.
2. Split-brain klastra — przestrzegaj kworum i testuj podział sieci.
3. Złośliwy klient — rate limit per username/IP, max_connections, monitoring nietypowych tematów.

• Potwierdź w kontrakcie produktu, czy dany deployment używa MQTT — PDF Julia MSFS go nie wymaga.
• Jeśli MQTT jest używane: TLS, ACL, testy „zły temat → odmowa”, idempotencja przy QoS 1.
• Nie myl zdarzeń MQTT z telemetrią SimConnect w produkcie desktopowej Julii.
• Ustalony rejestr tematów i wersji payloadów.
• QoS i retained zweryfikowane na stagingu pod obciążeniem.
• LWT i keepalive skorelowane z realnymi timeoutami sieci.
• Subskrybenci odporni na duplikaty (QoS 1).
• Procedura rotacji credentiali bez downtime (dwa zestawy, overlap).