62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
# ICS Endpoint Requirements
|
|
|
|
## Purpose
|
|
Define the ICS endpoint path, visibility model, caching behavior, and synchronization expectations.
|
|
|
|
## Scope
|
|
This document covers:
|
|
|
|
- ICS endpoint routing and response contract
|
|
- Public vs authenticated access policy
|
|
- Caching/refresh behavior
|
|
- Multi-calendar considerations
|
|
|
|
## Normative Boundaries
|
|
- This document is authoritative for ICS endpoint path/access/cache behavior.
|
|
- ICS payload formatting and field mapping are defined in `requirements/ics.md`.
|
|
- Recurrence exception export behavior is defined in `requirements/recurrence_exceptions.md`.
|
|
- Authorization policy integration is defined in `requirements/authorization.md`.
|
|
- Error normalization is defined in `requirements/error_model.md`.
|
|
|
|
## Endpoint Contract
|
|
- Default endpoint path: `/calendar.ics`
|
|
- If `url_slug` is configured in setup, canonical endpoint path is `/<url_slug>/calendar.ics`.
|
|
- Alternative implementation path may be used if documented; one canonical URL must be exposed in UI.
|
|
- Response content type: `text/calendar; charset=utf-8`
|
|
|
|
## Access Policy
|
|
- Access mode is configurable in `Setup`:
|
|
- `public_read`: endpoint accessible without auth, only public events included
|
|
- `authenticated_read`: endpoint requires authenticated access
|
|
- Default mode: `public_read` unless overridden by policy requirements.
|
|
|
|
## Data Scope
|
|
- ICS output includes only events intended for the selected endpoint audience.
|
|
- Internal/admin-only metadata must never appear in output.
|
|
- Recurrence and exception semantics follow `requirements/ics.md` and `requirements/recurrence_exceptions.md`.
|
|
|
|
## Stability and Subscription
|
|
- Endpoint URL should remain stable for long-lived subscriptions.
|
|
- If URL must change, documented migration/redirection behavior is required.
|
|
|
|
## Caching and Freshness
|
|
- Responses should include deterministic cache headers.
|
|
- `ETag` and/or `Last-Modified` should be emitted where practical.
|
|
- Cache policy must balance freshness and performance for subscriber clients.
|
|
|
|
## Failure Behavior
|
|
- On generation failure, return a clear HTTP error status and log details.
|
|
- Endpoint must not return malformed partial ICS payload.
|
|
|
|
## Multi-Calendar Support
|
|
- First pass supports single canonical calendar feed.
|
|
- If multiple feeds are added later, each feed requires stable URL and explicit audience rules.
|
|
|
|
## Verification Requirements
|
|
Acceptance should verify:
|
|
|
|
- Canonical ICS URL is discoverable from web UI.
|
|
- Access policy mode is enforced correctly.
|
|
- Payload is valid and subscriber-compatible.
|
|
- ETag/Last-Modified behavior supports efficient refresh checks.
|