CalDAV / iCloud
Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.
Crate: adapter-caldav · Capabilities: calendars, tasks, contacts
CalDAV/CardDAV is the open standard behind Apple iCloud and many self-hosted servers (Nextcloud, Radicale, …). One adapter serves them all; iCloud is just CalDAV with Apple’s endpoints.
Protocol
Section titled “Protocol”- Discovery + listing:
PROPFINDto enumerate collections (calendars, task lists viaVTODO, address books) and their properties (displayname,calendar-color,getctag,sync-token). - Incremental sync:
REPORTwithsync-collectionreturns the resources changed since async-token, plus per-resource deletions. An invalid token triggers a full re-bootstrap. - Bootstrap / bulk read: a depth-1
PROPFINDlists every resource href, thencalendar-multiget/addressbook-multigetfetches their bodies in chunks (so a large iCloud calendar doesn’t time out on one giant request). - Folder-complete caching: because the bootstrap already enumerated the
whole collection, the event sync multigets all dates (not just the
view window) and marks the change set
complete, so the host caches an unbounded window. Later views are served from cache and only a backgroundsync-collectiondelta touches the network. Servers withoutsync-collectionfall back to a windowed, range-scoped read. - Bodies are iCalendar (
VEVENT/VTODO) and vCard. Events are read and written byical-mapping(crates/ical-mapping), the mapping the iCal feeds and file import, and Exchange’s invitations share; it stays reachable here asadapter_caldav::mapping.RRULE/EXDATEare carried through; occurrences are expanded on the frontend.
Authentication
Section titled “Authentication”HTTP Basic over TLS with a username + password (for iCloud, an app-specific password, not the Apple ID password). There is no OAuth. The server base URL is user-supplied for self-hosted servers; iCloud uses Apple’s well-known endpoints.
Quirks
Section titled “Quirks”-
A busy server, and a write sent twice. A request is sent again once when its connection broke (
http.rs). Then the first attempt may have reached the server, and the replay’s answer may be about it. Every write is sent throughsend_write, and a replay answered with any failure is unsure (WriteAnswer::settled, a network error that says it may have been saved), never a refusal or a busy server. A caller’s own reading goes first: a replayed 404 on a delete is gone, a 405 on a MKCALENDAR is the collection the first attempt made, a 412 on a create guarded byIf-None-Matchis the first attempt’s resource when Aperio named the resource (a minted UID, or the fresh{uuid}.icsof a kept UID that is no plain name); the 412 of a resource a kept UID names isuid-taken, replay or not (see below). A first attempt answered 429 did nothing: a busy provider (busy_detail, decision 270), and an update says so before any refusal. A walk over every calendar or address book (delete, EXDATE) stops at the first busy answer; a delete walk that met a replayed 404 before it is unsure, never done, and so is one where another calendar refused the delete: the event may be gone already. A failure on an earlier calendar that may have landed (a lost answer, a server error) stays what it was, whatever a later calendar answers (WalkFailures). A contact’s PUT replaces the whole vCard, so a busy read of its photo sends nothing rather than wiping the avatar. -
A busy server on a read. A read answered 429, or 503 with
Retry-After(http::read_failure; a write answered so may have been carried out, so writes never read it that way), is a busy provider, and it starts no fallback: a delta does not fall back to a full bootstrap, the bootstrap’s PROPFIND not to a windowed read, a multiget batch is not asked again one resource at a time, a busy sync-token read does not fall back to the CTag (the collection would stay on it), and a bootstrap that cannot read its token fails rather than storing a snapshot without one. The scheduling probe met by a busy server is asked again, never cached as “does not schedule”, and a write that needs it while the server is still busy stops as busy rather than dropping a meeting’s invitees. A free/busy query says busy instead of “availability unknown”, which read as every attendee free. An answer to an invitation whose read is busy sent nothing and says busy. Well-known discovery reads a 429, or a 503 withRetry-After, as busy, not as a missing well-known, and a busy home-set probe fails discovery rather than caching the account without calendars or contacts. How iCloud throttles is not measured. -
Both homes are best-effort. Discovery probes
calendar-home-setANDaddressbook-home-setindependently and fails only when neither is found. A CalDAV-only server (no address books) and a CardDAV-only server (e.g. Synology Contacts — advertises anaddressbook-home-setbut nocalendar-home-set) both work; the missing side’s listings just come back empty. Well-known resolution tries/.well-known/caldavthen/.well-known/carddav. (Before this, a contacts-only server failed account creation with a “not found” error because the calendar home was mandatory.) -
Contacts read via multiget, never inline PROPFIND.
get_contactsdoes a Depth-1 PROPFIND for hrefs then anaddressbook-multigetfor the bodies — it does not ask for inline<CR:address-data/>in a plain PROPFIND. That shortcut is non-standard; iCloud and Synology Contacts silently return resources with no body, so the old inline read yielded zero contacts while persisting a sync token, leaving address books permanently empty (a one-timecache.contactsMultigetHealV2heal clears those poisoned tokens so books re-bootstrap). -
Stable ids. A resource is keyed by
{href}|{uid}so renames/moves and per-resource deletions resolve correctly. The bareUIDis also the event’sical_uid, the override’s included, whatever the resource is called. -
An invitation from a file is written as someone else’s. Calendars say
invitation_import: kept. A create markedkeeps_invitationwrites the file’s ORGANIZER withSCHEDULE-AGENT=CLIENTand the account’s own ATTENDEE row withSCHEDULE-AGENT=NONE(RFC 6638 §7.1), adding that row where the file named the account under another address or not at all; the event reads back organized elsewhere and silenced. iCloud sent nothing for such a create, nor for Aperio’s reply and delete on it, even without the markers (live run 100518). One whose organizer is the account itself is the account’s own meeting. -
A kept UID names the resource. A create with
uid_to_keep(an import) writes that UID and, as for a minted one, names the resource after it, so a 412 onIf-None-Match: *means the calendar holds the appointment. A UID that is no plain name (anything but letters, digits,-_.~@, or longer than 200 bytes) goes into a fresh{uuid}.icsinstead, and the id is the composite{href}|{uid}. The server’s ownno-uid-conflict(RFC 4791, 403 or 409) says the same. Each is refused asuid-taken. -
Subtasks ride
RELATED-TO. A VTODO’s parameter-lessRELATED-TO(RELTYPE defaults to PARENT; CHILD/SIBLING entries are ignored) carries the parent’s bare UID on the wire; the read path resolves it to the composite{href}|{uid}task id against the fetched set. Because theicalendarcrate keeps only oneRELATED-TOper component when parsing, the link is scanned from the raw iCal text — severalRELATED-TOlines (RFC-legal; e.g. jtx Board’s reciprocalRELTYPE=CHILDentries) would otherwise drop the parent order-dependently. An incremental delta whose parent didn’t itself change falls back to one tolerantuid → idlisting; if that read fails the delta fails too (token not advanced) rather than caching a falsified flat parent. Writes strip the composite id back to the UID; removing the parent just regenerates the VTODO without the property. -
A changed occurrence lives in its series’ resource. The server keeps it as a second VEVENT beside the master, with the same UID and a
RECURRENCE-IDnaming its slot. A PUT replaces the whole resource, so any write to one occurrence reads the resource first and puts the rest back:- Updating an override swaps its VEVENT for the rewritten one and puts
everything else back byte for byte. The
RECURRENCE-IDline is copied exactly as the server wrote it, because it has to match the master’sDTSTARTin kind and zone. If the resource cannot be read block by block, or the slot holds no override any more, nothing is written. - Skipping an occurrence (
add_event_exdate, anddelete_eventwith an override id) adds theEXDATEto the master and drops the override in that slot. The master is rebuilt from core fields, as for any master write, so properties Aperio does not model are lost there. The other overrides go back byte for byte, and so does everyVTIMEZONEthey name. A resource that holds overrides without their master (an invitation to single occurrences) loses the one block, and the resource itself goes with its last block. - A series made single (
clear_recurrence, decision 280) is written without any of its overrides; left, they would stand beside the single as ghosts. Only on that flag, whichguard_updatesets when the cached copy repeats, the edit does not, and both carry the same ETag: a missing rule alone keeps every override, as a rule Aperio cannot read is missing too.
- Updating an override swaps its VEVENT for the rewritten one and puts
everything else back byte for byte. The
-
Keep recurring masters. The folder-complete sync keeps every event regardless of date; the legacy windowed fallback still keeps any event with a recurrence even when its first occurrence is outside the window (
event_in_windowreturns true forrecurrence.is_some()). -
iCloud date sentinels / colours. Colours arrive as
#RRGGBBAA; the alpha is dropped to a plain hex. -
Apple’s silent alarm. An iPhone adds the account’s default alert to every appointment that lacks a VALARM with
ACTION:NONEandTRIGGER;VALUE=DATE-TIME:19760401T005545Z, however many alarms it has; it writes that alarm into every appointment it makes itself (measured on iOS 27.2, 2026-11-08). The read shows no reminder for it, nor for any alarm with an ACTION other than DISPLAY, AUDIO or EMAIL or at that trigger (RFC 5545 §3.8.6.1, RFC 9074 §8), and a rebuilt VEVENT carries every alarm the read did not show back as the server’s text (mapping::PriorAlarms), turning a DISPLAY alarm at that trigger without a location back into the silent alarm (Aperio’s saves wrote it that way before). On iCloud every write that sends an appointment’s content adds the silent alarm to each VEVENT that has neither it nor an alarm flaggedX-APPLE-DEFAULT-ALARM:TRUE(apple_alarm::with_silent_alarm,WriteCtx::apple_silent_alarm), so the iPhone shows exactly the appointment’s alerts — none for one without reminders. Other servers get none: Nextcloud’s web client shows it as a reminder in 1976 and DAVx5 rewrites it. -
A
TZIDresolves three ways. A tzdata name as it is; a Windows id (W. Europe Standard Time, what Outlook, Teams and Exchange write) through the core’s CLDR table (cal_core::windows_zone), and then the series’ zone is the tzdata name; any other name by the body’s ownVTIMEZONE(zone_definitions.rs: observances with a yearly nth-weekday rule orRDATEs). Such a zone keeps its own name, which no expansion knows, so its series repeats in UTC. A time none of the three resolves still reads as UTC. The same reader serves the iCal feeds and the.icsimport. -
getctagfast-path. When the collection’s ctag is unchanged, the adapter can skip a full enumeration. -
The account is every href of its
calendar-user-address-set. A server names a calendar user by whichever href it likes. iCloud writes a principal path with the address in anEMAILparameter, for ORGANIZER and for the account’s ownROLE=CHAIRrow (live measurement M1):ORGANIZER;CN=…;EMAIL=toni@example.org:/aB1/principal/. Discovery keeps every href (identity::OwnIdentity), and the account organizes an event whose ORGANIZER any of them names, each compared by its own rules (amailto:by address in any case, a path resolved against the principal apart from one trailing slash, aurn:case-insensitively), or whoseEMAILequals one of its addresses. Any other ORGANIZER, or any ORGANIZER on a server that reports no address, makes the eventorganized_elsewhere; an event without ORGANIZER is the account’s own. The read shows a non-mail calendar user by itsEMAIL, and drops the row that names the same user as ORGANIZER from the invitees. When the probe for the addresses fails on a network or server error, it is repeated before the next read that needs it, and while it keeps failing that read fails: the host keeps its cache instead of storing a guess that a delta would never revisit. -
A write carries a meeting’s lines; it never rebuilds them. On an RFC 6638 server the organizer’s copy is the invitation: the server mails the attendees whenever it changes, and a PUT without ORGANIZER is a “remove” that cancels the meeting for everyone (§3.2.3.1). Every update therefore reads the resource first and fails if it cannot (
scheduling::plan_block): ORGANIZER, ATTENDEE, SEQUENCE and STATUS go back as the server wrote them, folding and parameter order included. Only a change to the invitees changes rows: the ones that stay verbatim, the removed ones dropped (the server cancels for them), new ones generated (ROLE=REQ-PARTICIPANT;PARTSTAT=NEEDS-ACTION;RSVP=TRUE), and all of them gone when the host confirmed every invitee removed (clear_attendees, decision 74a). A guest change reaches the series’ overrides too. On someone else’s meeting a change to the invitees is refused. A master update puts every override of the resource back byte for byte; skipping an occurrence inserts one rawEXDATEline and leaves the rest of the resource untouched. A save that changes nothing the server stores (only a colour kept on this device or a reminder’s sound, say) is not sent, nor is skipping an occurrence the series skips already, because every PUT of a meeting mails its guests. A 403 on a PUT or DELETE (a save, a delete, an answer to an invitation) is reported as the server’s refusal (Forbidden, with theDAV:errorprecondition), not as a login problem. -
And it takes only the attendee’s own changes. Those calendars also carry
invitations_reply_only, so the editors show a meeting somebody else organizes read-only apart from the reply and the account’s own reminders (decision 77a). The adapter writes such a copy by splicing: the server’s own VEVENT goes back byte for byte with its VALARMs replaced (write_attendee_copy), so the zone,SEQUENCE,STATUS, the people, Apple’s own properties and every line the adapter does not model survive. An alarm the read shows as a reminder is claimed by that reminder whatever its ACTION orRELATED(mapping::raw_alarm_reminder— classifying it more strictly would keep it and render a second one beside it); one Aperio never showed is kept untouched; adding or removing alarms drops the event-levelX-APPLE-DEFAULT-ALARM. Any other changed field is refused before the PUT (cal_core::invitation::reply_only_change), and a protected difference against a copy the caller never saw is a conflict, not a refusal: that is the organizer’s change, not the user’s. The PUT uses If-Match against the CALLER’s ETag, as every other write here does: the alarms are spliced into the copy just read, but the reminders written are the ones the caller saw, and a reminders-only edit passes the verdict whatever the version — so the ETag is what keeps it from overwriting an alarm another device set in the meantime. -
Such a server always notifies. Calendars on a scheduling server carry
always_notifies_attendees(andnotifier_name“iCloud” on iCloud): the editors show “iCloud informs the attendees of every change” instead of the checkbox, and the delete dialogs say who informs them instead of offering to remove silently (decisions 76a, 80a). A new event names its invitees, with the account as ORGANIZER, only when the user notifies; otherwise it is a plain appointment and the event returned names nobody. -
Unless the event says otherwise.
SCHEDULE-AGENT(RFC 6638 §7.1) on theORGANIZERline, or on the account’s ownATTENDEErow, can tell the server to stay out of this event’s scheduling:CLIENTmeans some client sends the messages,NONEthat nobody does. The read carries that asEvent.scheduling_silenced, and the surfaces then say nobody is told instead of naming a sender (decision 98). It is not a guess: an invitation imported from a.icsfile carries both markers, and iCloud sent neither the reply to an answer nor the cancellation on a delete (live round 6).SCHEDULE-AGENTon ANOTHER attendee’s row is not read — the server still mails the rest. -
One occurrence can be kept inside its series. A save or a drag of a single occurrence writes a
RECURRENCE-IDexception into the series’ own resource (decision 79b) instead of skipping the slot and creating a standalone event beside it. The calendar declares that it can hold one (Calendar::stores_occurrence_exceptions), andupdate_eventmints the block when nothing stands in the slot yet (mint_override). TheRECURRENCE-IDtakes the form of the MASTER’s ownDTSTART—VALUE=DATE,TZID=<its own spelling>, a UTC value or a floating one (RFC 5545 §3.8.4.4) — because that is the form a client matches against its expansion, and the zone name must resolve against aVTIMEZONEalready in this resource. The minted value is read back the way the reader reads it and must answer the same slot; where it cannot (a local time that happens twice, a zone this build cannot resolve), and where the master is not recurring, has noDTSTART, already skips the slot, or is somebody else’s invitation, the write is REFUSED rather than turned into something else.
Testing
Section titled “Testing”mockito serves canned PROPFIND/REPORT/multiget XML. Tests assert the
sync-collection token round-trip, per-resource deletions, the
{href}|{uid} id scheme, and the iCalendar → cal-core mapping (whose own
tests live in ical-mapping, with the provider samples both crates read under
its test-fixtures feature). For a
live smoke test, an iCloud account with an app-specific password works.