PKR-Lab

60080 - carplay-api und iOS-App — Hintergründe

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/6-hintergruende/60080-carplay-api-und-ios-app.md

carplay-api und iOS-App — Hintergründe

Begründungen zum Go-Backend argocd/apps/tech/carplay-api/ und zur SwiftUI-App unter ios/. Bedienung, Einrichtung und Konfiguration:
300d0 und capulus-ios/README (dort auch der Abschnitt zum Transport HTTP/HTTPS).
Der Verzeichnisname carplay-api ist historisch (aus der CarPlay-Vorversion), das Backend bedient heute die reine iOS-App „Homeserver Dashboard“.
Übersicht dieser Kategorie: 60000.


carplay-api

Aufbau und Verträge

Absicherung

Abhängigkeiten und Schwachstellen (Incident 016, 2026-10-17)

carplay-api hat nur gin als direkte Abhängigkeit, alles andere (golang.org/x/net, x/crypto, x/text, x/sys, quic-go) kommt indirekt über gin und steht in go.mod nur als // indirect.

Datenquellen und ihre Eigenheiten

Quelle Hintergrund
VictoriaMetrics (instance-Label) HostConfig.instance muss exakt dem instance-Label des node-exporter-Targets entsprechen. In diesem Cluster gibt es kein Relabeling auf Hostnamen, also IP:9100 und nicht homeserver:9100. Erscheint ein Host nie als online: curl vmsingle…/api/v1/targets. Sechs PromQL-Queries laufen nebenläufig, jede nach instance gruppiert, sodass ein Roundtrip alle Hosts abdeckt.
Traefik-Aktivität ServiceConfig.match ist ein Teilstring des rohen Traefik-service-Labels (Format je nach Provider/Chart-Version: <ns>-<svc>-<port>@kubernetes bei einem Ingress, …@kubernetescrd bei einer IngressRoute). So muss man das Format nicht festnageln, ohne das Live-Cluster abzufragen. Vor dem Deploy mit curl $VM_URL/api/v1/label/service/values gegenprüfen. Die Kennzahl ist die Request-Rate, nicht die Zahl verschiedener Nutzer (Traefik kennt keine Identitäten). Dienste, deren Teilstring nicht im Ergebnis vorkommt, stehen auf 0 Requests/s (noch nicht gescrapt oder wirklich idle).
PromQL-Regex regexAlternation baut aus exakten Werten einen Regex (a\|b\|c) und escaped jeden, damit die Punkte in IPs nicht als Wildcard wirken. Das Ergebnis steckt in einem doppelt gequoteten MetricsQL-String-Literal: Ein einzelner Backslash (regexp.QuoteMeta macht aus 192.168.0.1 192\.168\.0\.1) wird von VictoriaMetrics als String-Escape geparst und mit 422 („cannot parse string literal“) abgelehnt, weil \. kein bekannter Escape ist. Der Backslash wird deshalb verdoppelt und ist beim Regex-Engine wieder einfach.
ntfy Der echte, dokumentierte Polling-Endpunkt ist GET /{topic}/json?poll=1 (kein REST-„list messages“, das gibt es bei ntfy nicht). poll=1 liefert alles im Cache seit since und schließt die Verbindung. Mehrere Topics gehen nativ kommagetrennt (/topic1,topic2/json). Abonniert sind die zwei Topics, die wirklich Nachrichten bekommen: Home-Lab (Alertmanager severity=critical über ntfy-bridge) und Home-Lab-System (thermal_watchdog/resource_watchdog/cluster_power_manager auf dem Host). Der frühere Default alerts hat keinen Publisher, dort erschien nie etwas. Die ntfy-Prioritäten 1–5 werden auf drei Stufen abgebildet: Die 3 (ntfy-Default ohne explizite Priorität) zählt mit 1/2 als „info“, nicht als „warning“, damit nicht jede normale Benachrichtigung orange leuchtet. Sortierung: dringendste zuerst, dann neueste (ein Blick soll zuerst zeigen, was Aufmerksamkeit braucht, nicht was nur am neuesten ist).
Uptime Kuma Es gibt keinen REST-Endpunkt mit Bearer-Token zum Auflisten der Monitore, die einzige stabile, dokumentierte Lese-API ist die öffentliche Status-Page-JSON-API (bewusst unauthentifiziert, das ist der Zweck einer Status-Page). Eine Status-Page mit dem konfigurierten Slug muss in der Kuma-UI existieren, mit allen anzuzeigenden Monitoren. Das JSON-Schema ist upstream nicht versioniert, deshalb wird defensiv geparst: Ein fehlendes oder falsch typisiertes Feld wird übersprungen, statt die ganze Antwort scheitern zu lassen. Der Ping kommt als Bruchteil einer Millisekunde (z. B. 0.457), nicht als Ganzzahl, ein Decode nach *int ließ den ganzen Heartbeat-Abruf scheitern. Der Zeitstempel kommt naiv (YYYY-MM-DD HH:mm:ss in Serverzeit) oder als RFC3339, bei einem Parse-Fehler wird „jetzt“ genommen. Der Status pending (Check gerade fehlgeschlagen, Kuma wiederholt) zählt als down: Ein Blick-Dashboard soll sofort markieren, nicht auf die Bestätigung warten.
Update-Liste (/api/updates) Liest die vom github-release-watcher geschriebene Update-Status-ConfigMap in dessen (anderem!) Namespace, über die In-Cluster-API und die namespace-übergreifende RoleBinding aus dessen role.yaml. Die Werte müssen zu {{ fullname }}-updates dort passen, bei abweichendem Release-Namen anpassen (60040). Sie wird 15 Minuten serverseitig gecacht, und der Watcher läuft nur alle 2 h. Die App ruft sie deshalb einmal pro Ansicht ab, nicht im 30-Sekunden-Loop. Zeiger-Felder sind nil, wenn unbekannt: CurrentVersion ist nil, bis jemand currentVersion im Watcher pflegt, HasUpdate bleibt nil (nicht false), wenn es nicht bestimmbar ist. Die App zeigt dann „unbekannt“ statt eines falschen „aktuell“. Existiert die ConfigMap, der Watcher lief aber noch nicht, ist das kein Fehler, nur nichts zu zeigen.

iOS-App

Transport und Schlüssel

Netzwerk über Tailscale

Modelle, Datenquellen, Bedienung

Stelle Begründung
Unbekannte Alert-Level fallen auf .info zurück Ein unerwarteter Wert vom Backend soll nicht das Dekodieren des ganzen Dashboards scheitern lassen.
alerts/hosts per decodeIfPresent Go serialisiert ein leeres/nil Slice als JSON null, nicht []. decodeIfPresent behandelt ein explizites null wie einen fehlenden Schlüssel und fällt auf [] zurück, statt dass der JSONDecoder wirft.
PowerTarget-Rohwerte mit Bindestrich (worker-0) Sie werden verbatim als JSON gesendet und müssen den Go-String-Konstanten exakt entsprechen.
Offline-Hosts werden ausgeblendet Ein Host, der aus ist (herunterskalierter Worker, NAS im Reboot), wird nicht ausgegraut mit 0 % gezeigt, weil 0 % für einen Offline-Host keine echte Messung ist.
Letzter bekannter Stand bleibt bei Fehlern Ein veralteter Wert ist besser als ein leerer Bildschirm (capulus-ios/README, „Offline-Verhalten“). Die Update-Karte scheitert still (nice-to-know, kein Banner über der Flottenübersicht).
Ein DashboardViewModel für alle Tabs Ein Poll-Loop insgesamt statt einer pro Screen. Die Update-Abfrage liegt bewusst nicht im 30-Sekunden-Loop (Cache 15 min, Watcher alle 2 h), sondern einmal pro Ansicht bzw. Pull-to-Refresh.
Helligkeits-Slider schreibt erst beim Loslassen Helligkeit schreibt über zwei Netzwerk-Hops (App → carplay-api → power-agent) in sysfs des Homeservers. Jeden Zwischenwert zu streamen würde veraltete Schreibvorgänge hinter dem aktuellen aufstauen. Die lokale Anzeige wird optimistisch aktualisiert und mit dem serverseitig begrenzten Wert abgeglichen.
Wake-on-LAN am Vereinsheim ohne Shutdown, ohne Online-Punkt Das Ziel hat keinen Host-Eintrag in carplay-apis Dashboard, es gibt keinen Status außer dem Ergebnis des letzten Weckversuchs. capulus-core hat dafür auch keinen Remote-Shutdown-Pfad.
Shutdown-Code wird nie gespeichert oder vorbelegt Der Code entspricht dem ArgoCD-Admin-Login und wird serverseitig geprüft. Der Homeserver-Shutdown hat zusätzlich eine Warnung.
Statusfarben Grün unter 50 %, gelb 50–75 %, orange 75–90 %, rot über 90 % (CPU/RAM/Disk/Temperatur-Gauges der Host-Karten).
Zwei Modi (PKR-Lab, Alltag), persistiert PKR-Lab sind die ursprünglichen drei Tabs (Übersicht, Steuerung, Alerts), Alltag zeigt Wetter, Tankstellen und News. Kein CarPlay-Scene, universelle iPhone-/iPad-App, kein Mac. Der Umschalter sitzt fest über dem Tab-Inhalt, weil der Moduswechsel das ganze Tab-Set ändert.
iPad: .stack-Navigation, Vollbild Ohne .stack zeigt iPad einen Zwei-Spalten-Split (schmale Sidebar plus leerer Detail-Bereich). Die App ist nicht für das Größenänderungs-Fensterlayout (Split View, Slide Over, Stage Manager) gebaut und braucht UIRequiresFullScreen, sonst startet iPadOS sie als kleines schwebendes Fenster. iPad rotiert (Apple erwartet das), das iPhone bleibt Portrait-only. Der Launch Screen ist die moderne leere Dictionary-Form, weil sich LaunchScreen.storyboard-XML ohne Xcode nicht sinnvoll validieren lässt. Die UITabBar bekommt ein eigenes Aussehen, sonst fällt sie auch im erzwungenen Dark Mode auf ein helles Material zurück.
Erzwungener Dark Mode, „Glas“-Design Die Design-Tokens stammen aus css/style.css der Website (tiefes Navy plus Rot auf fast schwarzem Verlauf), die App erzwingt Dark Mode, weil die Website keine helle Variante hat. Statusfarben behalten ihre universelle Bedeutung (online/warnung/offline) unabhängig von der Markenpalette.
Karten begrenzen die Breite Auf dem iPad strecken sich Karten sonst von Rand zu Rand, auf dem iPhone hat die Begrenzung keinen Effekt.

Direkte Datenquellen der App (Alltag-Modus)