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
- Kleine, read-only Aggregations-API. Sie kombiniert VictoriaMetrics, ntfy und Uptime Kuma zu einem Payload (
GET /api/dashboard), den die App alle 30 Sekunden pollt. Feldnamen und
JSON-Tags sind der Vertrag mit dem iOS-Client, eine Änderung ist ein Breaking Change. Die Swift-Modelle spiegeln die Go-Modelle (models.*) 1:1 und müssen im Gleichschritt bleiben. - Degradieren statt abstürzen. Jeder Client ist timeout-begrenzt und liefert bei „Upstream down“ keinen harten Fehler, sondern einen Null-/Leerwert plus Warn-Log. Eine wacklige
Abhängigkeit reißt so nie das ganze Dashboard mit. Konkret: Fehlt für einen Host eine Metrik, ist der Wert 0. Fehlt seineup-Serie oder istup=0, kommtOnline=falseund jede Metrik auf 0, und
die App blendet die Karte aus, statt „0 %“ zu zeigen. Scheitert die Service-Abfrage, stehen alle Services auf 0 Requests/s. Zusätzlich gibt es ein äußeres Zeitbudget über alle drei Upstreams
(overallTimeout). - Ein-Wert-TTL-Cache: Das Dashboard ist teuer (drei Upstream-Calls), ändert sich aber langsam. Ein gecachter Wert, den alle Requests teilen, genügt, ein Key-Store ist unnötig.
- Keine
client-go-Abhängigkeit. Das Binary hat sonst null Kubernetes-API-Fläche. Für die Update-ConfigMap nutzt es minimal die In-Cluster-API mit dem ServiceAccount-Token des Pods, wie
auch der Python-Watcher des github-release-watcher. Läuft es nicht im Cluster (z. B.go runlokal), gilt das Feature als „nicht verfügbar“:GET /api/updatesliefert eine leere Liste statt
den Start abzubrechen. /healthantwortet immer mit 200, solange der Go-Prozess HTTP bedienen kann. Bei einem Replica würde ein fehlschlagender Liveness-/Readiness-Check wegen eines vorübergehend nicht erreichbaren
Upstreams (ntfy, Uptime Kuma, …) nur einen völlig gesunden Pod neu starten oder aus dem Routing nehmen. Der Zustand je Abhängigkeit steht stattdessen im Body./metricsist handgeschrieben (vier Zähler im Prometheus-Textformat) stattclient_golang: ein Overkill für einen so kleinen Dienst, und so bleiben Dependency-Baum, Image-Größe undgo.sumklein.
Als Label dient die Route, nicht der rohe Pfad, um unbegrenzte Label-Kardinalität durch unbekannte Pfade zu vermeiden.- Logging: Je Request eine strukturierte JSON-Zeile (Methode, Pfad, Status, Dauer, Trace-ID), bewusst ohne Header und Query-Strings. Das Bearer-Token und andere sensible Werte dürfen nie
in Logs landen. - Konfigurationsformate:
HOSTS=id|name|instance,…,SERVICES=id|name|match,…. Fehlerhafte Einträge werden still übersprungen, statt den Start wegen eines Tippfehlers im Helm-Wert
zu verhindern. Die Default-Service-Liste spiegelt die Kurzlink-Kacheln der App (Constants.SelfHostedServices). - Der Server schreibt nichts auf sein Root-FS (Konfiguration komplett aus Env-Vars),
readOnlyRootFilesystemist deshalb unproblematisch. Autoscaling bringt nichts: Ein einzelner App-Client pollt alle 30 s,
ein HPA würde nur die Upstream-Last (VictoriaMetrics/ntfy/Uptime Kuma) vervielfachen. Die Struktur bleibt für den Bedarfsfall stehen.
Absicherung
- Kein mTLS, sondern zwei unabhängige Schichten. Die ursprüngliche Spezifikation verlangte mTLS, aber der Traefik-Ingress dieses Clusters terminiert keine Client-Zertifikat-TLS, „mTLS“ wäre ein Häkchen
ohne Substanz gewesen. Die echte Grenze ist die Netzwerkebene (Tailscale-only-Ingress, 300d0) plus ein Bearer-Token auf Anwendungsebene. - Token ist Pflicht,
/metricsist geschützt, die Proxy-CIDR steht. Fehlte früherCARPLAY_API_TOKEN(zum Beispiel durch ein falsch benanntes Secret), startete der Server mit nur einer Warnzeile ohne Authentifizierung: Eine Fehlkonfiguration öffnete die API still. Jetzt bricht der Start mitCARPLAY_API_TOKEN is not setab (fail closed)./metrics(Request-Statistik) verlangt dasselbe Token,/healthbleibt offen, weil das kubelet es ohne Token abfragt; niemand scrapt/metrics.trustedProxiessteht auf dem Pod-CIDR10.42.0.0/16, damitX-Forwarded-Forvon Traefik ausgewertet wird. Wirkung heute begrenzt: Der ServiceLB-Pod (svclb-traefik) vor Traefik übersetzt die Quelladresse (externalTrafficPolicy: Cluster), im Log steht alsclient_ipseine Pod-IP statt der des Clients; Rate-Limit und Allowlist sehen damit weiter alle Clients als einen. Die echte Adresse kommt erst mitexternalTrafficPolicy: Localam Traefik-Service an (offen). Ohne Proxy davor (Aufruf direkt auf dem Pod) wirdX-Forwarded-Fornur von Adressen in diesem Bereich akzeptiert. Der Router-Aufbau steckt innewRouter, damit Tests ihn ohne Netz prüfen. BearerAuthakzeptiert nur exaktBearer <token>und vergleicht in konstanter Zeit, damit sich das Token nicht per Antwortzeit Byte für Byte erraten lässt.IPAllowlistist die eigentliche Regel „nur unser Netz erreicht das“. Ungültige CIDR-Angaben führen zu einem Panic beim Start, statt still ignoriert zu werden: Ein Tippfehler würde die API sonst
unbemerkt für die ganze Welt öffnen. Die Allowlist ist im Default aus, damit der erste Deploy nicht alle aussperrt, fallstrustedProxiesnoch nicht stimmt (erst nach dem Abschnitt „Absicherung“ in 300d0
scharf schalten).trustedProxiessind die CIDRs der Proxies, denenX-Forwarded-Forgeglaubt wird. Sie sind nötig, damit Allowlist und Access-Log die echte Client-IP hinter Traefik sehen und nicht die
Pod-IP von Traefik (Pod-CIDR mitkubectl -n kube-system get pods -o widebzw. den Traefik-Chart-Werten ermitteln). Als Bereiche dienen der Tailscale-CGNAT-Bereich und das LAN-Subnetz
(c0010).- CORS erlaubt nur die konfigurierten Origins statt gins offenem Default. Non-Browser-Clients wie die
URLSessionder App ignorieren CORS ganz, es zählt also nur für ein hypothetisches Web-Frontend.
Leer heißt: Es wird nie einAccess-Control-Allow-Origin-Header gesetzt. RateLimiter: Fixed-Window (pro Kalenderminute, nicht gleitend), Schlüssel ist die Client-IP, Antwort 429. Das reicht, weil die API hinter Tailscale für eine Handvoll Clients läuft und der Limiter nur
ein Sicherheitsnetz gegen einen Client ist, der den Endpunkt hämmert. Ein Hintergrund-Sweep entfernt veraltete Einträge, damit die Map nicht unbegrenzt wächst.- Secrets:
CARPLAY_API_TOKENistenabled: trueim Default, das Secret muss vor dem ersten Sync versiegelt sein, sonst bleibt der Pod inCreateContainerConfigErrorhängen. Das ist Absicht: Ein Dashboard,
das Systemzustand und Alerts zeigt, soll nicht ungeschützt starten. Erzeugen:openssl rand -hex 32, dann
echo -n "<token>" | kubeseal --raw --namespace carplay-api --name carplay-api-token --cert ~/homelab-certs/sealed-secrets.pem --from-file=/dev/stdin(oder überkubeseal-webgui.tech.homeserver).POWER_AGENT_TOKENist ein eigenes Bearer-Token für den power-agent auf dem Host. Es muss mitpower_agent_tokenin/etc/power-agent/config.envübereinstimmen (beide aus demselben
openssl rand -hex 32). Fehlt das Secret, schlagen Helligkeit/Wake/Shutdown mit 502 fehl, der Rest der App bleibt nutzbar. Es ist bewusst nichtCARPLAY_API_TOKEN: Das App-Token soll allein nicht
genügen, um etwas auszuschalten.SHUTDOWN_CONFIRMATION_CODEist der Code, den die App vor einem Homeserver-Shutdown abfragt. Es gibt bewusst keinen Live-Check gegen ArgoCD (dafür wären RBAC und ein Netzwerkpfad von diesem Pod aus
nötig). Stattdessen wird er manuell auf denselben Wert wie das aktuelle ArgoCD-Admin-Passwort gesetzt (b0010) und bei jeder Passwort-Rotation erneuert
(echo -n "<passwort>" | kubeseal --raw --namespace carplay-api --name carplay-api-shutdown-code --cert … --from-file=/dev/stdin). Bleibt esenabled: false, blockiertPOST /api/power/shutdownfür
target=homeservermit 503, statt einen leeren Code stillschweigend zu akzeptieren.- Das ntfy-Zugriffstoken (
secrets.ntfyToken, Nutzerreader, nur Lesen) wird mitscripts/seal-ntfy-tokens.shversiegelt. Ohne Token liest carplay-api nur, solange ntfyauth-default-access: read-writehat; mitdeny-allliefert der ntfy-Teil des Dashboards sonst einen Fehler im Body.
- power-agent: Ein privilegierter Dienst direkt auf dem Homeserver (60020). Der Pod hat bewusst keinen Host-Zugriff (sysfs-Backlight,
sudo poweroff, SSH-Key des
cluster_power_manager), deshalb wird jede Helligkeits-/Wake-/Shutdown-Anfrage an den Agenten weitergereicht, authentifiziert mit dessen eigenem Token. Die URL (config.powerAgent.url) zeigt auf die Adresse der Pod-Bridgecni0des homeservers (http://10.42.2.1:9101, das Pod-Netz10.42.2.0/24ist dem Node fest zugewiesen), nicht auf die LAN-Adresse: Der Agent lauscht dort ausschließlich (60020), der Token läuft im Klartext, verlässt den Node aber nie. DerPowerHandlergibt den vom
Agenten gemeldeten Statuscode zurück, damit z. B. ein nicht erreichbarer Homeserver-Bildschirm als echter Fehler in der App ankommt statt als irreführendes 200. Der Homeserver ist die dauerhaft laufende
Steuerungsebene und hat keinen WoL-Pfad (nur worker-1 lässt sich wecken; controlplane-1 läuft dauerhaft und erscheint nur als Statuskarte, 20020). Sein Shutdown nimmt den ganzen Cluster samt dieser API mit,
deshalb hat er einen zusätzlichen Bestätigungsschritt.
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.
- Zwei Quellen, zwei Stände. Dependabot meldet nach den GitHub-Advisories,
govulnchecknach der Go-Datenbank (vuln.go.dev) und nur für Code, den das Programm erreicht. Der Dependabot-PR hob
x/netauf 0.54.0 undx/cryptoauf 0.52.0.govulncheckverlangte danach weiterx/net0.60.0 undx/text0.39.0, also wurde nachgezogen. Beide Werkzeuge laufen nebeneinander. - Die Mindestversionen müssen zueinander passen.
go getmit den Zahlen aus der Meldung scheiterte:x/net0.60.0 verlangtx/crypto0.57.0, undx/crypto0.55.0 verlangtx/text0.41.0.
Es genügt, nurx/[email protected]und[email protected]anzufordern, Go zieht den Rest auf die kleinste konsistente Menge (x/crypto0.57.0,x/sys0.48.0,x/text0.42.0). - Die
go-Direktive ingo.modsteigt dabei auf 1.26.0, weilx/net0.60.0 sie verlangt. Die CI nimmtgo-version: stableund das Dockerfilegolang:1.27-alpine, beides erfüllt das. - Prüfen:
cd argocd/apps/tech/carplay-api/src && govulncheck ./...muss „No vulnerabilities found“ melden, dazugo build ./... && go vet ./... && go test ./... && go mod tidy -diff
(der Dienst hat noch keine Unit-Tests,go testübersetzt nur).govulncheckinstalliert man mitgo install golang.org/x/vuln/cmd/govulncheck@latest. - Dependabot-Folge-PRs für einzelne Pakete (z. B.
x/net0.55.0) sind nach einem Bump auf eine höhere Version überholt und werden geschlossen.
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
- HTTPS ohne ATS-Ausnahme.
Constants.swiftverweist aufhttps://carplay-api.prod.homeserver, die App enthält keinenNSAppTransportSecurity-Eintrag mehr (siehe
capulus-ios/README, Abschnitt Transport). Vorher stand dorthttp://mitNSExceptionAllowsInsecureHTTPLoadsfür die Domainhomeserversamt Subdomains: Bearer-Token und Dashboard-Daten liefen
im Heim-WLAN im Klartext, und seit der globalen HTTP→HTTPS-Umleitung von Traefik (2026-09-13) ging jeder Aufruf ohnehin erst über einen301/308. Die Umleitung war kein Schutz, weil der erste Request mit
dem Token schon im Klartext hinausging. Der Hostname steht seit der Tier-Migration in der SAN-Liste des cert-manager-Zertifikats, deshalb brauchte es keine Serveränderung und keinen eigenen TLS-Block im Ingress
(der Standard-TLSStoregreift). - Die Root-CA muss auf dem Gerät aktiv sein, sonst hat die App keine Verbindung. Ohne ATS-Ausnahme gibt es keinen Rückweg über Klartext: Ist das Profil nicht installiert oder in den
Zertifikatsvertrauenseinstellungen nicht aktiviert, scheitert jeder Request mit einem TLS-Fehler. Das ist gewollt (fail closed). Schnelltest:https://carplay-api.prod.homeserver/healthin Safari.
Die Kurzlink-Kacheln brauchen dieselbe Vertrauensstellung und stehen deshalb ebenfalls aufhttps://. - Diese Konfiguration wird aus
project.ymlin dieInfo.plistgeneriert: XcodeGen schreibt die Datei bei jedemgenerateaus diesen Eigenschaften und überschreibt sie komplett, statt mit
handgemachtem Inhalt zu mergen. Alles, was die App braucht (Anzeigename, Launch Screen, Orientierung), muss deshalb inproject.ymlstehen, sonst verschwindet es beim nächstenxcodegen generatestill.
Ein generiertes.xcodeprojlässt sich außerhalb von Xcode kaum von Hand pflegen oder diffen, deshalb wird das Projekt aus dem Text generiert und nicht eingecheckt (Setup:brew install xcodegen,
cd ios && xcodegen generate). - Der WoL-Agent spricht HTTPS mit IP-SAN-Zertifikat. Die Basis-URL ist die rohe Tailscale-IP (
https://100.123.214.4:9102). Mit TLS ist die Frage, ob ATS für numerische IPs greift, gegenstandslos. Das Zertifikat
trägt die IP als Subject Alternative Name, weil es für das Gerät keinen DNS-Namen gibt und*.homeserver-Namen im Tailnet nicht zuverlässig auflösen. Die Root-CA ist dieselbe wie beicarplay-api, auf dem iPhone
ist nichts zusätzlich zu installieren. Der Agent lauscht weiter nur auf der Tailscale-Adresse (60020); TLS schützt zusätzlich gegen einen
Mitleser im Tailnet und gegen einen Agent-Impostor. MTLSDelegatepinnt die Root-CA, mTLS gibt es nicht. Die ursprüngliche Spezifikation wollte Zertifikats-Pinning. Der Delegate prüft für Hosts auf.homeserverund die WoL-Agent-IP100.123.214.4das Serverzertifikat nur gegen die eingebettete Root-CA (SecTrustSetAnchorCertificatesmitSecTrustSetAnchorCertificatesOnly), nicht gegen den Vertrauensspeicher des Geräts. Eine fremde, auf dem iPhone installierte CA reicht damit für einen Mitleser nicht mehr, und das CA-Profil auf dem Gerät ist für die App nicht mehr nötig. Für alle anderen Hosts (Wetter, Pegel, Tankerkönig, News) giltperformDefaultHandling. Die Dateipki/homeserver-root-ca.pemkommt als Resource ins Bundle (project.yml); fehlt sie, scheitern alle gepinnten Anfragen (fail closed), statt das Pinning still auszulassen. Bei einem CA-Wechsel (Ablauf 2036-08-10) die App neu bauen.
Echtes Client-Zertifikats-mTLS (Home-Lab-CA plusRequireAndVerifyClientCertam Traefik) ist eine unimplementierte Idee. Kommt sie, muss die IngressRoute die TLSOptionmtls-homelabreferenzieren, der
Client-Identity-Zweig im Delegate aktiviert und das.p12des Geräts per Keychain bereitgestellt werden. Ein Client-Zertifikat verlangt der Server nicht (kein mTLS).- Keychain statt „Secure Enclave“. Die Spezifikation nannte die Secure Enclave, sie schützt aber private Schlüssel für Signieren/Entschlüsseln und hat keine API für ein beliebiges opakes Token wie ein
Bearer-Credential.kSecAttrAccessibleWhenUnlockedThisDeviceOnlyist das richtige Primitiv: geräteverschlüsselt, von iCloud-/iTunes-Backups ausgenommen und bei gesperrtem Gerät nicht lesbar, also genau die
Sicherheitseigenschaft, die gemeint war. Der Wert wird als Ganzes neu geschrieben, deshalb „löschen dann hinzufügen“ stattSecItemUpdate.
Netzwerk über Tailscale
- Completion-Handler-API statt
async-Variante (session.data(for:)): Über Tailscales VPN-Tunnel (NEPacketTunnelProvider) brach dieasync-Variante jeden Request mit einem nackten
NSURLErrorCancelled(-999) ohne zugrunde liegenden Fehler ab, eine bekannte Wechselwirkung von async/await-Bridging und Packet-Tunnel. Die Completion-Handler-API hat das Problem nicht. waitsForConnectivity = false: Früher verursachte es bei jedem Request ein scheinbar grundlosesNSURLErrorCancelled(-999). Mit Tailscales VPN-Interface als ständig wechselndem Netzwerkpfad begann
URLSessionzu „warten“, bemerkte einen Pfadwechsel und brach das Warten ab, statt es zu wiederholen. Schnelles Scheitern lässt den eigenen 30-Sekunden-Polling-Loop den Retry übernehmen.- Der
RemoteWolAgentClientdupliziert diese Request-Mechanik mit Absicht, statt sie zu teilen: Der Workaround ist an eine konkrete, ohnehin fragile Tailscale-/URLSession-Interaktion gebunden. Bleiben die
beiden Clients unabhängig, riskiert ein künftiger Fix an einem nicht, den anderen still zu brechen. Er spricht direkt mit dem Agenten auf dem Pi und nicht über carplay-api, weil dieser Pod keinen
Netzwerkpfad zu Tailscale-Peers hat (60020). Das Ziel-Enum muss zu einem Schlüssel inbanana_pi_kiosk_wol_devicespassen. TailscaleConnectivity: iOS hat keine öffentliche API, um „ist Tailscale verbunden“ zu fragen (der VPN-Status einer fremden App wird nicht offengelegt). Die Klasse tut das nächstbeste: Sie beobachtet den
allgemeinen Netzwerkpfad (NWPathMonitor), damit die UI sofort „offline“ zeigen kann, statt einen Request-Timeout abzuwarten, und verfolgt getrennt, ob der letzte echte Request an carplay-api geklappt hat. Das
ist das einzige echte Signal, dass Tailscale und API Ende zu Ende erreichbar sind.
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)
- Tankerkönig: Die App fragt die API direkt mit einem eigenen API-Key im Keychain des Geräts, statt über das clusterseitige SealedSecret von Glance. Zeigt nur Super (E5) und Super E10, kein Diesel.
Für geschlossene Stationen sendet Tankerkönigfalsestatt einer Zahl, was als „kein Preis“ gilt statt als Fehler. Die nächste Station wird per Umkreissuche (sort=dist) gefunden, die erste nicht ausgeschlossene
Marke ist die nächste passende. Shell und Aral sind ausgeschlossen, dazu Agip/Eni (in Deutschland umbenannt, in den Daten unter beiden Namen gesehen). - Standort: Ist nur „Ungefährer Standort“ erlaubt, liefert
requestLocation()allein eine um mehrere km verwischte Koordinate, genug, um eine echt nahe (z. B. 5 km entfernte) Tankstelle aus der Umkreissuche zu
drücken. Deshalb wird temporär volle Genauigkeit angefordert (NSLocationTemporaryUsageDescriptionDictionaryin der Info.plist). - Wetter: Open-Meteo, kein API-Key nötig, gleiche Felder wie Glances „Wetter — Morgen“-Widget plus Windspitze, für heute und morgen in einer Abfrage. Die Zeiten sind lokale (ohne Offset) Werte in Europe/Berlin
(der angefordertentimezone). Feste Locale beim Parsen: Ohne sie fällt derDateFormatterauf die Locale/den Kalender des Geräts zurück (z. B. nicht-gregorianische Regionaleinstellung),date(from:)liefert
stillnilund die ganze Sonnenbogen-Karte verschwindet. Der Sonnenverlauf ist ein Bogen aus einer quadratischen Bezier-Kurve statt einer echten Ellipse (genügt visuell und macht die Positionsberechnung
fürs Sonne-/Mond-Symbol trivial, weil dieselbe Formel zum Zeichnen und Platzieren dient). - Pegel: Pegelonline (WSV) ohne API-Key. Die Stations-UUID für Andernach wurde einmal über
/stations.json?waters=RHEINnachgeschlagen und fest eingetragen (ein Pegel bewegt sich nicht). FürstateMnwMhwgibt es
nur drei dokumentierte Werte (niedrig/normal/hoch relativ zu mittlerem Niedrig-/Hochwasser), alles andere bleibt der Rohcode. - News: Je eine Schlagzeile von Tagesschau (öffentliches, inoffizielles JSON), Heise und WELT (RSS/Atom). Die Feeds sind nicht versioniert: Ändert ein Anbieter sein Schema, scheitert nur diese Quelle
(„Nicht verfügbar“), nicht die ganze Seite. Der Parser liest nur das erste Item (RSS<item>oder Atom<entry>) und bricht dann ab (der Abbruchfehler ist erwartet). Atoms<link>ist ein selbstschließendes
Element mithref, RSS 2.0 hat den Link als Text, und<description>(RSS) bzw.<summary>/<content>(Atom) landen im selben Kurztext-Feld. HTML-Markup und Entitäten der Beschreibungen werden entfernt. - Die Kurzlink-Kacheln der Dienste sind reine Link-Listen ohne eigenen Live-Status und öffnen den Dienst in Safari (nicht in der
URLSessionder App, ATS spielt dort keine Rolle).