cjw/Oxicloud
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

fixing db error and upgrading technical documentation

Browse Source
This commit is contained in:
Dionisio
2026-02-12 22:29:35 +01:00
parent ab8f3191cb
commit 8123406ab9
43 changed files with 6366 additions and 4555 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/caldav-technical-spec.md
+239
View File
@@ -0,0 +1,239 @@
# 26 - CalDAV Technical Spec
CalDAV (RFC 4791) provides calendar synchronization. Clients like Thunderbird, Apple Calendar, GNOME Calendar, and DAVx5 (Android) connect to manage calendars and events via standard CalDAV.
## Protocol Compliance
- **DAV compliance**: `1, 2, calendar-access`
- **RFC 4791**: Calendar Access (CalDAV)
- **iCalendar**: RFC 5545 (VEVENT parsing and generation)
## Endpoint Structure
All CalDAV endpoints are mounted at the top level (not under `/api`):
```
ANY /caldav → handle_caldav_methods_root
ANY /caldav/ → handle_caldav_methods_root
ANY /caldav/{*path} → handle_caldav_methods
```
### Path Hierarchy
| Path | Resource | Description |
|---|---|---|
| `/caldav/` | Calendar home | User's calendar collection |
| `/caldav/{calendar_id}/` | Calendar | Individual calendar |
| `/caldav/{calendar_id}/{ical_uid}.ics` | Event | Individual calendar event |
### Supported HTTP Methods
| Method | Description |
|---|---|
| `OPTIONS` | Returns DAV capabilities and allowed methods |
| `PROPFIND` | List calendars, calendar properties, events |
| `REPORT` | CalendarQuery, CalendarMultiget, SyncCollection |
| `MKCALENDAR` | Create a new calendar |
| `PUT` | Create/update events (iCalendar format) |
| `GET` | Retrieve individual event as iCalendar |
| `DELETE` | Delete calendars or events |
| `PROPPATCH` | Update calendar properties |
## Architecture
| Layer | Component | File |
|---|---|---|
| Domain Entity | **Calendar**, **CalendarEvent** | `src/domain/entities/calendar.rs`, `calendar_event.rs` |
| Domain Repository | **CalendarRepository**, **CalendarEventRepository** | `src/domain/repositories/calendar_repository.rs`, `calendar_event_repository.rs` |
| Application Port | **CalendarUseCase**, **CalendarStoragePort** | `src/application/ports/calendar_ports.rs` |
| Application Service | **CalendarService** | `src/application/services/calendar_service.rs` |
| Application Adapter | **CalDavAdapter** (XML parsing/generation) | `src/application/adapters/caldav_adapter.rs` |
| Infrastructure | **CalendarPgRepository**, **CalendarEventPgRepository** | `src/infrastructure/repositories/pg/` |
| Interfaces | **CalDavHandler** | `src/interfaces/api/handlers/caldav_handler.rs` |
## Domain Entities
### Calendar
```rust
pub struct Calendar {
id: Uuid,
name: String,
owner_id: String,
description: Option<String>,
color: Option<String>, // #RRGGBB format
created_at: DateTime<Utc>,
updated_at: DateTime<Utc>,
custom_properties: HashMap<String, String>,
}
```
Validation: **name** non-empty, **owner_id** non-empty, **color** must be `#RRGGBB` hex format.
### CalendarEvent
```rust
pub struct CalendarEvent {
id: Uuid,
calendar_id: Uuid,
summary: String,
description: Option<String>,
location: Option<String>,
start_time: DateTime<Utc>,
end_time: DateTime<Utc>,
all_day: bool,
rrule: Option<String>, // iCal RRULE format (e.g., "FREQ=WEEKLY")
ical_uid: String, // unique iCal identifier
ical_data: String, // full VEVENT block
created_at: DateTime<Utc>,
updated_at: DateTime<Utc>,
}
```
Validation: **summary** non-empty, `end_time >= start_time`, **rrule** starts with `FREQ=`, **ical_data** contains `BEGIN:VEVENT`/`END:VEVENT`.
The constructor `from_ical(calendar_id, ical_data)` parses iCalendar data to extract summary, dates, location, etc.
## REPORT Types
The CalDAV **REPORT** method supports three report types:
### CalendarQuery
Filters events by time range. Used for initial sync and view rendering.
```xml
<C:calendar-query xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:prop xmlns:D="DAV:">
<D:getetag/>
<C:calendar-data/>
</D:prop>
<C:filter>
<C:comp-filter name="VCALENDAR">
<C:comp-filter name="VEVENT">
<C:time-range start="20240101T000000Z" end="20240201T000000Z"/>
</C:comp-filter>
</C:comp-filter>
</C:filter>
</C:calendar-query>
```
### CalendarMultiget
Fetches specific events by href. Used for selective sync.
```xml
<C:calendar-multiget xmlns:C="urn:ietf:params:xml:ns:caldav">
<D:prop xmlns:D="DAV:">
<D:getetag/>
<C:calendar-data/>
</D:prop>
<D:href>/caldav/cal-1/event-1.ics</D:href>
<D:href>/caldav/cal-1/event-2.ics</D:href>
</C:calendar-multiget>
```
### SyncCollection
Incremental sync using sync tokens. Used for ongoing synchronization.
```xml
<D:sync-collection xmlns:D="DAV:">
<D:sync-token>sync-token-value</D:sync-token>
<D:prop>
<D:getetag/>
</D:prop>
</D:sync-collection>
```
## XML Namespaces
| Prefix | Namespace |
|---|---|
| `D:` | `DAV:` |
| `C:` | `urn:ietf:params:xml:ns:caldav` |
| `CS:` | `http://calendarserver.org/ns/` |
## CalDAV Adapter
**CalDavAdapter** in `src/application/adapters/caldav_adapter.rs` handles all XML parsing and generation:
- `parse_report(reader)` -> **CalDavReportType**
- `parse_mkcalendar(reader)` -> `(name, description, color)`
- `generate_calendars_propfind_response(...)` -- multi-calendar PROPFIND
- `generate_calendar_collection_propfind(...)` -- single calendar with events
- `generate_calendar_events_response(...)` -- REPORT response
## Calendar Sharing
Calendars support sharing with access levels:
| Level | Permissions |
|---|---|
| `read` | View calendar and events |
| `write` | Create, modify, delete events |
| `owner` | Full control including sharing and deletion |
## Database Schema
```sql
CREATE SCHEMA IF NOT EXISTS caldav;
-- Calendars
CREATE TABLE caldav.calendars (
id UUID PRIMARY KEY,
name TEXT NOT NULL,
owner_id VARCHAR(36) REFERENCES auth.users(id) ON DELETE CASCADE,
description TEXT,
color VARCHAR(9),
is_public BOOLEAN DEFAULT FALSE,
ctag VARCHAR(64) DEFAULT '0',
created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
);
-- Calendar Events
CREATE TABLE caldav.calendar_events (
id UUID PRIMARY KEY,
calendar_id UUID REFERENCES caldav.calendars(id) ON DELETE CASCADE,
summary TEXT NOT NULL,
description TEXT,
location TEXT,
start_time TIMESTAMPTZ NOT NULL,
end_time TIMESTAMPTZ NOT NULL,
all_day BOOLEAN DEFAULT FALSE,
rrule TEXT,
ical_uid VARCHAR(255) NOT NULL,
ical_data TEXT,
etag VARCHAR(64),
created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
);
-- Calendar Shares
CREATE TABLE caldav.calendar_shares (
id SERIAL PRIMARY KEY,
calendar_id UUID REFERENCES caldav.calendars(id) ON DELETE CASCADE,
user_id VARCHAR(36) REFERENCES auth.users(id) ON DELETE CASCADE,
access_level VARCHAR(10) DEFAULT 'read',
created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
UNIQUE(calendar_id, user_id)
);
-- Calendar Properties
CREATE TABLE caldav.calendar_properties (
id SERIAL PRIMARY KEY,
calendar_id UUID REFERENCES caldav.calendars(id) ON DELETE CASCADE,
property_name TEXT NOT NULL,
property_value TEXT NOT NULL,
UNIQUE(calendar_id, property_name)
);
```
Indexes: `idx_calendars_owner_id`, `idx_calendar_events_calendar_id`, `idx_calendar_events_ical_uid`, `idx_calendar_events_time_range (start_time, end_time)`.
## Client Configuration
See `dav-client-setup.md` for client-specific configuration instructions.
CalDAV URL: `https://oxicloud.example.com/caldav/`