Calendar Module

A calendar carries four per-calendar settings, exposed on create/update (POST/PATCH /calendars) and in the calendar response:

The three new-event defaults are read-simple UI values, never filtered or sorted, so they are grouped in a single nullable preferences JSON column (same convention as sync_config) rather than three columns; RepositoryCalendar packs/unpacks them. include_in_freebusy stays relational because it gates an aggregation.

Defaults split into two layers by their lifecycle:

RruleEngine.expand() expands a recurring master into occurrences within a date window. Each generated occurrence carries the master’s recurrence_rule so clients can display recurrence info.

Override priority: when both an EXDATE and a detached override (RECURRENCE-ID) exist for the same slot, the override wins (RFC 5545 §3.8.4.4).

A recurring event can be modified at three granularity levels:

Static processor. process() dispatches to split_occurrence, split_series, or standard update. Returns a ScopeResult carrying the resulting CalEvent and a touched list of (CalEvent, EventAction) pairs - all events that were modified/created/deleted on the organizer’s calendar. The caller passes the ScopeResult to CalendarSources.propagate() which blindly replicates the touched list to each attendee (INSERT/UPDATE/DELETE) and syncs the attendee list.

All examples assume a weekly recurring event with key evt-key.

Modify all events:

Modify this event only:

Move a single occurrence (drag & drop):

This and following events:

Delete this and following (truncate only):

Cancel a single occurrence (EXDATE):

Delete all events:

Decline a single occurrence as attendee:

GET /calendars/{key}/export enqueues a JobExportIcs job and returns 202 {job_id}. Recurring masters keep their RRULE intact - the expansion happens on the recipient side. Query parameters (forwarded to the job):

The serialised ICS is offloaded to the agent’s ClientStorage (the shared file store, see Agent); the job result carries only the storage reference (sogo:file:<key>) plus {filename, size_bytes}. The caller fetches the bytes from GET /jobs/{job_id}/result (text/calendar); ?download=true adds Content-Disposition: attachment so browsers download instead of inlining.

Worker-side (JobExportIcs → InterfaceAgentCalendar → ModuleCalendar), the module fetches both events and tasks without expansion via CalendarSource.get_all_events(…​, expand=False) and get_all_tasks(…​, expand=False), attaches them to the CalCalendar (its transient events field), then CalCalendarSerializerIcal.serialize(calendar) builds the VCALENDAR: it owns the calendar-level header (PRODID, VERSION, CALSCALE, the X-WR-CALNAME/X-WR-CALDESC/X-WR-TIMEZONE descriptors) and delegates the body - one VEVENT/VTODO per event - to CalEventsSerializerIcal. expand=False keeps recurring masters with their RRULE (no flat occurrences) and skips the Python date filter since the SQL fetch already bounds the range.

POST /calendars/{key}/import accepts a multipart/form-data upload with a single file part. The view exposes accepted_content_types = {"multipart/form-data"} so the global check_content_type middleware skips its default JSON rule (declared per-route via the accepted_content_types attribute). The total request size is capped at the WSGI layer (MAX_CONTENT_LENGTH); the module enforces the per-import limit (MAX_IMPORT_ICS_BYTES).

The endpoint enqueues a JobImportIcs job and returns 202 {job_id}. The import counters {inserted, updated, deleted, total, skipped} are returned inline in the job result, readable via GET /jobs/{job_id}.

The pipeline is ApiCalendarImport (decodes the upload to text - utf-8, latin-1 fallback - the one place the charset is guessed) → InterfaceApiCalendarCalendar.import_calendar → ModuleCalendar.import_calendar (size/ACL check, offloads the text to the agent’s ClientStorage via save_text, enqueues JobRequestImportIcs with the blob reference) → worker JobImportIcs (reads it back with load_text, then deletes the blob) → ModuleCalendar.apply_import → SyncEngine.apply_ics(…​, delete_missing=False, rewrite_owner_email=…​, default_timezone=…​). apply_ics deserialises the payload through CalendarDeserializerIcal, which reads the calendar-level header and delegates the body to CalendarEventsDeserializerIcal; only the parsed events are applied to the target calendar (the imported VCALENDAR’s own name/timezone are not used - the import writes into an existing calendar). Key behaviours:

The token is produced directly with get_unique_token(SHARE_TOKEN_LENGTH) (64 alphanumeric chars, ~381 bits). At that entropy a collision is statistically impossible, so there is no pre-check query: uniqueness is guaranteed by the UNIQUE constraint on the share_token column. Lookups use RepositoryCalendar.find_by_share_token, a global query with no user scope - the token alone identifies the calendar.

The public_url is built by InterfaceApiCalendarCalendar._public_url, which delegates to the transversal helper app.utils.api.external_url.build_external_url: it prefixes the route path with SOGO_P_PUBLIC_BASE_URL when configured (required behind a reverse proxy), otherwise falls back to Flask’s external URL.

GET /public/calendars/{token} declares public_access = True on its MethodView; the auth middleware reads that attribute by introspection (the same mechanism as accepted_content_types) and lets the request through without a bearer token, so app/init.py carries no per-route calendar knowledge. Anonymous requests fall back to default_domain_settings. The endpoint returns the full calendar serialised as text/calendar; charset=utf-8 (synchronous, the same serialisation path as export) - including a REFRESH-INTERVAL / X-PUBLISHED-TTL (PUBLIC_SUBSCRIPTION_REFRESH, default PT12H) that advertises the resync period to subscription clients (Apple, Google, Outlook). An unknown or revoked token is a plain 404 - no data leaks and the token is never logged in full (only token[:8] for correlation), since the token is a secret credential.

The fetch is also gated by the owner’s domain: when SOGO_D_CALENDAR_PUBLIC_LINK_ENABLED is disabled for the calendar owner’s domain, existing URLs go dead with the same 404 as an unknown token (on purpose - a disabled domain must not reveal that a token exists). The token is kept in the database, so re-enabling the setting revives the URLs unchanged. Since the caller is anonymous, the relevant domain is discovered from the token, with the interface orchestrating the two modules sequentially: ModuleCalendar.get_calendar_by_share_token resolves the owner, _calendar_settings_by_uid loads that domain’s settings through ModuleAdminConfig, and export_by_share_token receives them - the calendar module itself never knows the admin module.

The pipeline goes ApiCalendarPublicSubscription → InterfaceApiCalendarCalendar.export_public_calendar → ModuleCalendar.get_calendar_by_share_token → ModuleCalendar.export_by_share_token.

Module methods use two distinct parameter types:

The interface builds CalendarUser from the authenticated user. Until the central ACL module lands, the owner is always the acting user (user == owner); shared-calendar dispatch will plug in here.

Centralizes all permission logic. Three responsibilities:

CalendarPermissions has one CalendarShareLevel per visibility class (public, confidential, private) plus can_create and can_delete flags. Share levels are ordered: NONE < VIEW_DATETIME < VIEW_ALL < RESPOND < MODIFY_IF_ORG < MODIFY.

MODIFY_IF_ORG is the conditional level between RESPOND and MODIFY: the user gets MODIFY only on events they ORGANIZE, and behaves as RESPOND on everything else. Levels serialise by name (modify_if_org in the API), so the numbering is internal.

Each CalCalendar carries a transient permissions field populated at read time - the API response includes the user’s permissions so the UI knows which actions to enable.