Versand & Sync

Wie Datensätze von Apple Health zu deinen Servern gelangen, was die Zustände bedeuten und was Courier beim Timing verspricht (und ehrlicherweise nicht verspricht).

Auslöser

1. Hintergrundzustellung — Apple Health empfängt neue Schlaf-/Workout-Daten und iOS weckt Courier kurz auf; die App liest das Delta und versendet.
2. Öffnen der App — Vordergrund-Sync beim Start und bei der Rückkehr.
3. Manuell — die Versand-Aktionen in der App oder der Kurzbefehl Jetzt versenden.
4. Stapelversand — Redaktion → Stapelversand: Zeitraum wählen und die Historie an einen beliebigen Abonnenten nachliefern.

Alle vier speisen dieselbe Pipeline.

Eintragszustände

Jeder ausgehende Datensatz durchläuft eine explizite Zustandsmaschine, die persistiert wird, damit ein erzwungenes Beenden oder ein Neustart nichts aus den Augen verliert:

Zustand	Bedeutung
queued	Wartet, bis es dran ist
awaitingRoute	Outdoor-Workout, dessen GPS-Track noch nicht von der Watch angekommen ist — Courier wartet, statt einen unvollständigen Datensatz zu senden
sending	Anfrage unterwegs
sent	Zugestellt (2xx). Im Journal festgehalten
failed	Fehlgeschlagen und quittiert — wird nie automatisch erneut versucht; nutze den manuellen erneuten Versand
needsAttention	Fehlgeschlagen/unvollständig und noch nicht quittiert: Wiederholungen erschöpft, Route nie angekommen oder die Quelldaten sind verschwunden. Roter Punkt + Mitteilung

Wiederholungen

• Vordergrund-Versände wiederholen Netzwerkfehler mit exponentiellem Backoff (2 s → 4 s → 8 s → 16 s).
• Hintergrund-Versände bekommen einen einzigen Versuch mit 15 Sekunden Timeout — Hintergrundzeit unter iOS ist knapp, und Courier verzockt sie nicht. Fehlschläge reihen sich einfach zur Prüfung ein.
• Nichts wird jemals automatisch wiederholt, sobald es failed erreicht hat — du behältst die Kontrolle darüber, was erneut gesendet wird.

Idempotenz

Jede Anfrage trägt einen Idempotency-Key-Header:

• Normale Sendungen und manuelle Wiederholungen verwenden die stabile canonical id des Datensatzes — ein Endpunkt, der anhand des Schlüssels dedupliziert, speichert dasselbe Workout nie doppelt, egal wie oft die Zustellung wiederholt wird.
• Absichtliche Duplikate („noch eine Kopie senden") rotieren den Schlüssel zu id#2, id#3, …, damit idempotente Endpunkte gewollte Kopien trotzdem annehmen können.

Wenn dein Server Idempotency-Key respektiert (oder per data.id upsertet), wird die gesamte Pipeline an jedem Punkt gefahrlos wiederholbar.

Das Journal

Redaktion → Versandverlauf zeigt jeden Versand mit Zeitstempel, Abonnent, HTTP-Status und Antwort-Ausschnitt. Das Journal bewahrt 6 Monate Historie auf; ältere Einträge werden automatisch aufgeräumt — die zugestellten Inhalte selbst liegen natürlich weiter auf deinen Endpunkten.

Timing, ganz ehrlich

Die Hintergrundzustellung wird von iOS gedrosselt. Rechne mit Minuten bis etwa einer Stunde Verzögerung; im schlimmsten Fall passiert der Versand beim nächsten Öffnen der App. Courier macht das in seinen UI-Texten sichtbar, statt Echtzeit vorzutäuschen. Wenn du eine garantierte Sendung sofort brauchst: Öffne die App oder nutze den Kurzbefehl Jetzt versenden.

Mitteilungen

Zwei Modi (Redaktion → Mitteilungen):

• Immer — eine zusammenfassende Mitteilung nach jeder automatischen Versandrunde, ob Erfolg oder Fehlschlag. Standard.
• Nur bei Fehlern — Stille, außer etwas braucht dich.

Mitteilungen benötigen die Systemberechtigung; wurde sie verweigert, zeigt Courier den echten Status und eine Abkürzung zu den iOS-Einstellungen, statt so zu tun, als würde es funktionieren.