발행과 동기화
기록이 Apple 건강에서 당신의 서버까지 어떻게 이동하는지, 각 상태가 무엇을 의미하는지, 그리고 타이밍에 관해 Courier가 무엇을 약속하는지(그리고 솔직히 무엇을 약속하지 않는지) 설명합니다.
트리거
- 백그라운드 배달 — Apple 건강에 새 수면/운동 데이터가 들어오면 iOS가 Courier를 잠깐 깨우고, Courier가 변경분을 읽어 발행합니다.
- 앱 열기 — 실행 시와 복귀 시의 포그라운드 동기화.
- 수동 — 앱 안의 발행 액션, 또는 지금 발행 단축어.
- 일괄 발행 — 편집부 → 일괄 발행: 날짜 범위를 골라 과거 기록을 원하는 구독자에게 채워 넣습니다.
네 가지 모두 같은 파이프라인으로 들어갑니다.
항목 상태
밖으로 나가는 모든 기록은 명시적인 상태 기계를 거치며, 강제 종료나 재부팅에도 추적을 잃지 않도록 영속적으로 저장됩니다.
| 상태 | 의미 |
|---|---|
queued | 차례를 기다리는 중 |
awaitingRoute | Watch에서 GPS 트랙이 아직 도착하지 않은 야외 운동 — Courier는 불완전한 기록을 보내는 대신 기다립니다 |
sending | 요청 전송 중 |
sent | 배달 완료 (2xx). 장부에 기록됨 |
failed | 실패했고 확인 처리됨 — 절대 자동으로 재시도되지 않으며, 수동 재전송을 사용하세요 |
needsAttention | 실패/불완전 상태로 아직 확인되지 않음: 재시도 소진, 경로 미도착, 또는 원본 데이터 소실. 빨간 점 + 알림 |
재시도
- 포그라운드 발행은 네트워크 오류를 지수 백오프로 재시도합니다 (2초 → 4초 → 8초 → 16초).
- 백그라운드 발행은 15초 타임아웃으로 단 한 번만 시도합니다 — iOS의 백그라운드 시간은 귀하므로 Courier는 도박하지 않습니다. 실패하면 그냥 주의 대기열에 들어갑니다.
failed에 도달한 항목은 절대 자동 재시도되지 않습니다 — 무엇을 다시 보낼지는 언제나 당신이 결정합니다.
멱등성
모든 요청에는 Idempotency-Key 헤더가 실립니다.
- 일반 전송과 수동 재시도는 기록의 안정적인 canonical
id를 사용합니다 — 키로 중복을 제거하는 엔드포인트라면 배달을 몇 번 재시도하든 같은 운동을 두 번 저장하는 일이 없습니다. - 의도적인 복제("한 부 더 보내기")는 키를
id#2,id#3, …으로 회전시켜, 멱등한 엔드포인트도 의도적인 사본은 받아들일 수 있게 합니다.
서버가 Idempotency-Key를 존중하거나 data.id로 upsert한다면, 전체 파이프라인은 어느 시점에서든 안전하게 재시도할 수 있게 됩니다.
장부
편집부 → 발행 내역에는 모든 발행이 타임스탬프, 구독자, HTTP 상태, 응답 스니펫과 함께 표시됩니다. 장부는 6개월 치 기록을 보관하며, 더 오래된 항목은 자동으로 정리됩니다 — 물론 배달된 내용 자체는 당신의 엔드포인트에 남아 있습니다.
타이밍, 솔직하게
백그라운드 배달은 iOS에 의해 제한됩니다. 몇 분에서 한 시간 정도의 지연을 예상하세요. 최악의 경우 발행은 다음에 앱을 열 때 이루어집니다. Courier는 즉시 전송되는 척하는 대신 UI 문구에서 이를 그대로 드러냅니다. 지금 당장 보내야 한다면 앱을 열거나 지금 발행 단축어를 사용하세요.
알림
두 가지 모드가 있습니다 (편집부 → 알림):
- 항상 — 자동 발행이 한 차례 끝날 때마다 성공이든 실패든 요약 알림을 보냅니다. 기본값입니다.
- 실패 시에만 — 당신의 손길이 필요할 때만 알립니다.
알림에는 시스템 권한이 필요합니다. 권한이 거부된 경우 Courier는 작동하는 척하는 대신 실제 상태와 iOS 설정으로 가는 바로가기를 보여 줍니다.