CardDAV: mirror address books, suggest contacts while composing, edit with two-way sync

[jo2904]

Closes #157

Adds CardDAV: mirror address books from Nextcloud (or Radicale, Baïkal, Fastmail, iCloud…), suggest their contacts while composing, and edit them from a new Contacts page with two-way sync.

It is built the way CalDAV already is, and reuses its WebDAV layer rather than adding a second one.

What a user gets

• Settings → Contacts: connect a CardDAV server (same form and flow as CalDAV: address, credential, then tick the address books to mirror). Each book shows its last sync or its last error, and has a sync-now button.

• Contacts page (user menu → Contacts): list, search, create, edit, delete. Read-only books (shared or global address lists) are shown but not editable.

• Composer autocomplete and JMAP Contact/autocomplete now suggest address-book contacts as well as harvested addresses, in one ranking shared by both:

  1. mail frequency;
  2. then whether the address is in an address book;
  3. then recency, then name.

  With no address book the order is exactly as before. JMAP suggestions gain an inAddressBook flag.

How it is built (14 commits, one idea each)

The first five build the feature; the nine after them are fixes and one refactor from a review pass, each with its own test.

1. CalDavDiscovery refactor. The RFC 6764 bootstrap now takes a DavService (Calendar or AddressBook), so .well-known/carddav and addressbook-home-set use the same discovery code. This includes its SSRF re-validation on every redirect. Calendars are the default; no behaviour change for CalDAV.
2. CardDAV model and sync.
   • Connection: Provider::CardDav is a connection under a new ServiceKind::Contacts. It is kept out of the file picker and the calendar screens.
   • Entities: AddressBook (the counterpart of Calendar) and ContactCard.
   • Driver: CardDavDriver reuses CalDavClient and MultiStatusParser. Error wording is provider-aware, so a contacts failure never says "calendar server". The read-only rule (DavResource::isReadOnly()) and the etag read-back after a PUT (CalDavClient::etagAfterWrite()) are shared with the CalDAV driver rather than copied; no CalDAV behaviour changes.
   • Sync:
     • Local edits are pushed before the pull.
     • Writes are conditional (If-None-Match: * and If-Match). On a 412 the server's version wins and the loss is logged.
     • A 403 on one card is given up on the same way (logged with the discarded vCard), so one refused card cannot stop the whole book syncing. Any other failure (unreachable, 507 out of space, 401) keeps the edit pending for the retry.
     • A dead sync token, whether reported as a moved ctag or as the valid-sync-token precondition, is dropped and the book is read from scratch.
     • Only a full listing deletes cards it did not mention; a delta or a truncated report never does, including a truncated report that gives no token to continue from.
     • Removals are applied last, and the href/UID index is kept current while a pull is applied, so a card "moved" on the server (same UID, new href) keeps its row whichever order the report lists the move in.
   • Schedule: app:contacts:sync --stale runs every 15 minutes, offset to :11 so it does not stack on the mail and calendar sweeps.
3. UI.
   • The connect form is CalDavConnectType with a protocol option, so the reuse-a-mail-password rule and the probe-on-save rule are not duplicated.
   • Edits are saved locally, marked pending, and pushed by the worker. Nothing waits on the CardDAV server.
4. Autocomplete merge (ContactSuggester), used by both the web route and JMAP. Only cards that carry an address are asked for, in SQL before the limit, so a book full of number-only phone contacts does not crowd out the ones you can write to.
5. Docs: docs/providers/carddav.md (English and German), the index, and CHANGELOG.

vCards are edited, not rebuilt. ContactCard keeps the raw vCard, and an edit only touches FN, N, EMAIL, TEL, ORG and NOTE. Photos, birthdays, postal addresses and phone-specific X- properties survive a round trip. A kept address also keeps its TYPE and its Apple grouping.

Migration

Adds the address_book and contact_card tables. Nothing existing changes. doctrine:schema:validate --skip-sync passes; index and FK names follow DBAL's generator.

Testing

Run here without Postgres:

• 65 new or updated unit tests pass: vCard converter, CardDAV driver against a scripted server, sync service with an in-memory repository, card editor, suggester, provider enum, discovery.
• Documentation, translation-parity and informal-German tests pass.
• lint:container, lint:twig and targeted PHPStan (src and tests) are clean.
• The new templates were rendered against in-memory entities.
• Compared with main, the full suite shows no newly failing test. The remaining failures are the DB-dependent ones, plus Graph time-zone tests that need an ICU this host lacks; they fail the same way on main.

Not run here (needs the stack):

• tests/Controller/AddressBook/ContactsFlowTest.php, end to end with a scripted Nextcloud on a .test host: connect, discover, subscribe, list, search, edit, create, delete, read-only, cross-user isolation.
• The existing JMAP autocomplete tests, one of which now expects the inAddressBook key.

Please run them with npm run test:unit:docker, or let CI run them.

Not in this PR

Inherited from the CalDAV code this mirrors, and left alone here because fixing them means changing the calendar side too:

• CalDavCalendarDriver has the same "truncated sync report with no token" exit that is fixed here for CardDAV. CalendarChangeSet has no full-listing flag, so the fix there touches the calendar engine.
• A connect that fails its probe still saves the connection (as CalDAV does). Resubmitting the same dialog without changing the name then hits the (usr, provider, name) unique key.
• No per-book lock: two sync runs for the same book at once (an edit's dispatch and the sweep) can both push the same pending card. The second gets a 412 and lets the server win, which is the server's copy of the same edit. The calendar sync has no lock either.

Out of scope:

• A "Connect my Nextcloud" shortcut for contacts. It belongs with NEXTCLOUD_URL in Connect my Nextcloud: one-click CalDAV connection when NEXTCLOUD_URL is set #108 and can follow once that is merged.
• Moving a contact between address books.
• Field-level merge on conflict.

🤖 Generated with Claude Code

https://claude.ai/code/session_018nYWPc4bWacb79hm4ytfni

[karatektus]

Thanks for CardDAV, @jo2904. Contacts are wanted, and building it on the CalDAV layer rather than a second one is the right call. It's accepted for v0.4.0 (#157).

One thing has to change before review: how it connects. We decided in #158 that a Nextcloud connection is made once and gives files, calendars and contacts, with the one app password the existing Nextcloud integration (Settings → Integrations) already holds. So for Nextcloud, address books should come from that connection, not from a separate CardDAV connection with its own address and password. A standalone CardDAV connection is still right for servers that aren't Nextcloud: Radicale, Baïkal, Fastmail, iCloud.

The sync engine, AddressBook/ContactCard, the Contacts page and the composer ranking look like they fit #158 as they are; it's the connection model that has to follow it. Could you read #158 and say there how you'd hang address books off the Nextcloud connection, before reworking? Agreeing that first will keep this from being redone.

It also needs the French catalogue (messages.fr.yaml), which landed after you branched; the catalogue-parity test checks all four.