Support managed attachments (RFC 8607)

[tobixen]

The task is to do research on RFC 8607, assess if it's relevant for the caldav library, and (if it's deemed worth it) implement support. Claude has already done some research, see the findings below.

---

⚠️ This issue is AI-generated (Claude Opus 5 via Claude Code) on behalf of tobixen, from the prompt: "3.1 managed attachments needs an issue"

Tracking issue for section 3.1 of docs/design/FEATURE_COMPLETE_ROADMAP.md, which had no issue behind it.

There is no attachment support in the library today — no hits for ATTACH, MANAGED-ID or attachment anywhere in caldav/.

Scope: managed attachments, not attachments in general

Worth separating two things that both go by "attachment":

• Inline / URI ATTACH (RFC 5545) — a plain iCalendar property, either a URI or base64 binary. This already works, in the sense that the library treats it as opaque iCalendar data and hands it to icalendar; tests/test_caldav_unit.py even has a large base64 ATTACH fixture. Nothing to implement, though convenience accessors could be argued for.
• Managed attachments (RFC 8607) — the attachment is stored server-side, outside the calendar object. The client POSTs the file to a separate URL, the server answers with an ATTACH property carrying a MANAGED-ID, and add/update/remove are HTTP POSTs with ?action=attachment-add|attachment-update|attachment-remove. This is what is missing, and it is what this issue is about.

Tasks

• Detect server support — the CALDAV:managed-attachments-server-URL property, and the calendar-managed-attachments token in the DAV: header
• attachment-add, attachment-update, attachment-remove POST operations
• Handle MANAGED-ID, and the FMTTYPE / FILENAME / SIZE parameters
• event.add_attachment() / event.remove_attachment() on the object API
• Respect the server's max-attachment-size and max-attachments-per-resource limits, and give a decent error when they are exceeded
• Compatibility hints, so the tests skip rather than fail
• Decide what the API takes and returns — a path, a file object, or bytes; and whether a download streams or buffers

Why this may not be worth doing soon

The roadmap already rates it low priority, and I think that is right:

• Server support is thin. Apple Calendar Server implements it; most of the servers in the docker test matrix do not, so most of the work would be untestable.
• It drags file handling into a library that currently only moves text around — streaming, temp files, memory limits for large blobs. That is a real API design question, not just a protocol binding.
• The people who ask for attachments usually mean inline ATTACH, which already round-trips.

So: worth having the issue so section 3.1 is not an orphan, but not obviously worth doing before ACL, alarms or the robustness work.

RFC: https://datatracker.ietf.org/doc/html/rfc8607

⚠️ AI-generated by Claude Opus 5 via Claude Code on behalf of tobixen.