199 lines
9.4 KiB
Markdown
199 lines
9.4 KiB
Markdown
# CalDAV Requirements
|
|
|
|
## Purpose
|
|
Define requirements for exposing the plugin calendar through a CalDAV endpoint with read/write behavior and standards-compatible resource representations.
|
|
|
|
## Standards and RFC
|
|
CalDAV behavior must be standards-compatible with:
|
|
|
|
- RFC 4791: Calendaring Extensions to WebDAV (CalDAV)
|
|
- RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)
|
|
- RFC 5545: Internet Calendaring and Scheduling Core Object Specification (iCalendar)
|
|
- RFC 6578: Collection Synchronization for WebDAV (sync report)
|
|
- RFC 7232: HTTP conditional requests (ETag/If-Match semantics)
|
|
|
|
If additional CalDAV/WebDAV extensions are used, they must be documented and not break baseline client interoperability.
|
|
|
|
## Timezone Assumption
|
|
Unless explicitly overridden by a future requirement, all plugin dates and times are assumed to be in the `Europe/London` timezone.
|
|
|
|
## Scope
|
|
This document covers:
|
|
|
|
- CalDAV endpoint structure and resources
|
|
- Required WebDAV/CalDAV operations
|
|
- Mapping between plugin data and CalDAV/iCalendar resources
|
|
- Concurrency, sync, and error behavior
|
|
|
|
## Normative Boundaries
|
|
To avoid ambiguity across requirement documents:
|
|
|
|
- Exact CalDAV URI layout, method matrix, and DAV property/report behavior are defined in `requirements/caldav_endpoints.md`.
|
|
- Authentication and authorization policy is defined in `requirements/authentication.md` and `requirements/authorization.md`.
|
|
- Error response normalization is defined in `requirements/error_model.md`.
|
|
- Recurrence exception semantics are defined in `requirements/recurrence_exceptions.md`.
|
|
- Concrete persistence schema is defined in `requirements/data_schema.md`.
|
|
|
|
## Endpoint and Resource Model
|
|
The plugin must expose a CalDAV hierarchy with authenticated user principals and calendar collections.
|
|
|
|
Minimum resource model:
|
|
|
|
- Principal resource per authenticated CalDAV user
|
|
- Shared calendar home set
|
|
- Single shared `public` calendar collection
|
|
- Event resources as `text/calendar` (`VEVENT`-based `.ics` objects) within collections
|
|
|
|
URI requirements:
|
|
|
|
- Resource URIs must be stable for the lifetime of each object.
|
|
- Event resource URI should be derived from a stable internal event identifier.
|
|
- Recurrence exceptions must remain part of the same logical series and not create split series artifacts.
|
|
|
|
## Authentication and Authorization
|
|
- CalDAV access must require HTTPS and authenticated credentials.
|
|
- Authorization must enforce account approval state (`pending_approval` vs `active`).
|
|
- Unverified or non-approved users must be denied authentication/authorization.
|
|
- `active` users are write-enabled for the shared calendar.
|
|
- All authenticated users access the same shared calendar collection.
|
|
|
|
## Required CalDAV/WebDAV Operations
|
|
The endpoint must support these operations at minimum.
|
|
|
|
### Discovery and Collection Introspection
|
|
- `OPTIONS`: advertise DAV capabilities, including CalDAV support.
|
|
- `PROPFIND`:
|
|
- discover principals, calendar home sets, and calendar collections
|
|
- retrieve core properties (display name, resource type, ctag/sync metadata where available)
|
|
|
|
### Read and Query
|
|
- `REPORT` (`calendar-query`): return events in collection, including time-range filtering.
|
|
- `REPORT` (`calendar-multiget`): fetch specific event resources by href.
|
|
- `GET`: retrieve individual event resource (`text/calendar`).
|
|
|
|
### Create and Update
|
|
- `PUT`: create new event resource or replace an existing event resource.
|
|
- `PUT` updates must preserve recurrence/exception semantics from iCalendar input.
|
|
- CalDAV clients (including Thunderbird) must be able to read current event privacy and update it on edit (for example via `CLASS`).
|
|
- Write operations must require approved authenticated access.
|
|
|
|
### Delete
|
|
- `DELETE`: remove event resource when permitted.
|
|
- Deleting a single occurrence of a recurring event must be represented as a recurrence exception in the series (`EXDATE` and/or `RECURRENCE-ID` override pattern), not by splitting into multiple independent series.
|
|
|
|
### Concurrency and Sync
|
|
- `ETag` must be emitted for event resources.
|
|
- `If-Match`/`If-None-Match` preconditions must be honored for safe updates/creates.
|
|
- `REPORT` (`sync-collection`) should be supported for incremental sync tokens.
|
|
- Sync token invalidation/rotation behavior must be deterministic and documented.
|
|
|
|
## iCalendar Representation Requirements
|
|
CalDAV event payloads must be standards-compatible `VCALENDAR` with `VEVENT` components.
|
|
|
|
Minimum mapping expectations:
|
|
|
|
- Internal stable event id -> `UID`
|
|
- Title -> `SUMMARY`
|
|
- Description -> `DESCRIPTION`
|
|
- Location -> `LOCATION`
|
|
- Category -> `CATEGORIES`
|
|
- Start/end -> `DTSTART` / `DTEND`
|
|
- Last modification timestamp -> `DTSTAMP` (and `LAST-MODIFIED` when available)
|
|
- Recurrence rules -> `RRULE`
|
|
- Recurrence exceptions -> `EXDATE` and/or additional `VEVENT` with matching `UID` plus `RECURRENCE-ID`
|
|
|
|
Privacy visibility mapping:
|
|
|
|
- Event visibility must round-trip through CalDAV/iCalendar semantics (for example `CLASS:PUBLIC` and `CLASS:PRIVATE` where supported).
|
|
- Authenticated CalDAV users must receive full event content for both public and private events.
|
|
- CalDAV feeds are not subject to the public redaction model used by anonymous web/ICS surfaces.
|
|
|
|
Recurrence behavior:
|
|
|
|
- Series-level recurrence remains a single logical event sequence keyed by `UID`.
|
|
- Exception instances must be represented as exceptions to that `UID`, not a new split sequence.
|
|
- Sequence/version metadata should be updated on write operations so clients detect changes.
|
|
- Monthly ordinal rules must round-trip accurately, including `BYDAY=2SA`-style forms and `BYSETPOS=-1` (`last` weekday in month).
|
|
|
|
## Plugin Data Mapping Requirements
|
|
Plugin persistence must represent CalDAV resources in a way that supports idempotent read/write sync.
|
|
|
|
Required persisted mapping fields (direct columns or normalized equivalents):
|
|
|
|
- Internal event id
|
|
- CalDAV resource path/name
|
|
- `UID`
|
|
- Current `ETag`
|
|
- Calendar collection id
|
|
- Last-modified-by user id (nullable for system/import operations)
|
|
- Serialized recurrence rule data
|
|
- Recurrence exception records (date-only exceptions and/or overridden instances)
|
|
- Created/updated timestamps
|
|
|
|
Behavior requirements:
|
|
|
|
- Importing/updating from CalDAV must map to existing records by stable identifiers (`UID` + resource identity rules).
|
|
- Duplicate creation from repeated client retries must be prevented.
|
|
- Data model must preserve enough metadata to regenerate standards-compliant responses.
|
|
|
|
## Error Handling Requirements
|
|
- Malformed iCalendar payloads must return appropriate client error responses.
|
|
- Authorization failures must return appropriate auth status without leaking sensitive details.
|
|
- Write precondition failures (etag mismatch) must return precondition errors and no partial write.
|
|
- Server errors must be logged with enough detail for troubleshooting.
|
|
|
|
## Security and Privacy
|
|
- Transport must be TLS-only for credentials and calendar data.
|
|
- Sensitive tokens/credentials must not be logged in plaintext.
|
|
- Responses must not leak admin-only or internal plugin metadata.
|
|
|
|
## Interoperability Targets
|
|
The implementation should interoperate with common CalDAV clients, including:
|
|
|
|
- Apple Calendar
|
|
- Thunderbird
|
|
- DAVx5-class clients
|
|
|
|
Client-specific workarounds, if required, must be documented.
|
|
|
|
## Majority-Client Compatibility Strategy
|
|
There is no single guaranteed feature set that satisfies every CalDAV client implementation, but interoperability for the majority can be managed by combining:
|
|
|
|
- strict baseline standards compliance (RFC 4791 + RFC 4918 + RFC 5545)
|
|
- a stable compatibility profile for discovery/auth/report/write behavior
|
|
- continuous regression tests against representative client patterns
|
|
|
|
The project must maintain a compatibility profile with three levels:
|
|
|
|
- Level A (required for release): standards-critical discovery/auth/read
|
|
- `401` with `WWW-Authenticate` on unauthenticated CalDAV access
|
|
- principal discovery (`current-user-principal`)
|
|
- principal `calendar-home-set`
|
|
- discoverable calendar collection with `<C:calendar/>`
|
|
- `REPORT` support for `calendar-query` and `calendar-multiget`
|
|
- Level B (required for release): practical write/sync interoperability
|
|
- `PUT`/`DELETE` with stable ETag behavior
|
|
- recurrence + exception round-trip fidelity
|
|
- sync collection stability for incremental updates
|
|
- Level C (best effort): client-specific ergonomics/extensions
|
|
- optional properties beyond baseline RFC surface
|
|
- minor behavior adjustments for specific client quirks that do not break A/B
|
|
|
|
Release gating must include at least:
|
|
|
|
- `fixture-tests/fixture_caldav_client_compat_smoke.sh` (legacy local discovery/auth compatibility; retained for archival comparison)
|
|
- existing fixture smoke + security smoke suites
|
|
- at least one real-client manual smoke (for example Thunderbird or Apple Calendar) for release candidates
|
|
|
|
## Verification Requirements
|
|
Acceptance should verify:
|
|
|
|
- Principal and calendar discovery works via `OPTIONS` and `PROPFIND`.
|
|
- Calendar query and multiget reports return correct data for time-range and href selection.
|
|
- `GET`, `PUT`, and `DELETE` behaviors match access level permissions.
|
|
- ETag and conditional writes prevent lost updates.
|
|
- Sync collection reports provide incremental changes.
|
|
- Recurring-event single-occurrence delete results in exception representation, not sequence split.
|
|
- Returned iCalendar validates against RFC 5545 expectations and is accepted by target clients.
|
|
- Privacy values round-trip through CalDAV edit flows (including Thunderbird) without losing event detail fidelity.
|