iCal / ICS Support

Relevant source files

The following files were used as context for generating this wiki page:

• internal/app/ics.go
• internal/app/integrations.go
• internal/app/calendar.go
• internal/db/migrations/0006_integrations.sql
• internal/web/calendar_templ.go
• internal/web/settings_templ.go
• GLOSSARY.md

GoCasa provides comprehensive iCal and ICS support to synchronize calendar data with external clients and services. The system exports local calendars as standard iCalendar feeds and imports external webcal/iCal feeds as read-only calendars.

Sources: internal/app/ics.go, internal/app/integrations.go, GLOSSARY.md

ICS Export System

The export system generates a valid iCalendar (RFC 5545) feed from the internal database. External clients subscribe to this feed to view GoCasa events in third-party calendar applications.

Export Endpoint and Filtering

The application serves the ICS feed at the /calendar.ics endpoint. You can filter the export by appending the calendars query parameter with a comma-separated list of calendar IDs. If you provide no IDs, the system exports all local calendars.

Sources: internal/app/ics.go:27-31, internal/app/ics.go:34-40

Event Mapping Logic

The export logic maps goCasa internal event structures to iCalendar components:

• Series: Exported once with an RRULE.
• One-off edits: Exported as separate VEVENT components using the RECURRENCE-ID property to override a specific occurrence.
• Exception dates: Stored EXDATE values are added to the master series.
• Recurrence dates: Stored RDATE values are added to the master series.

Sources: internal/app/ics.go:34-37, internal/app/ics.go:68-71

This diagram shows the process of transforming database rows into a structured iCalendar response.

Recurring Series Expansion

The system uses icsSeries to adjust stored rules for client compatibility. If a rule does not produce the DTSTART date, the system adds an EXDATE for that first date and converts COUNT limits to UNTIL timestamps.

Sources: internal/app/ics.go:167-180

iCal Feed Import (Integrations)

GoCasa imports external iCal feeds through an integration framework. These feeds appear as read-only calendars within the dashboard.

Feed Synchronization

The syncDue function identifies integrations requiring updates based on the next_sync_at column. The system executes synchronization tasks individually to prevent a single failing feed from blocking others.

Sources: internal/app/integrations.go:42-50, internal/app/integrations.go:72-80

Security and Credentials

The system encrypts external feed URLs before storage. It uses AES-256-GCM encryption driven by the APP_ENCRYPTION_KEY environment variable.

Sources: internal/app/integrations.go:142-148, README.md:32

Integration Data Model

Field	Description	Type
type	Set to 'ical' for feed integrations.	TEXT
credentials_enc	Encrypted feed URL.	BLOB
sync_cursor	Stores ETag or last-modified headers.	TEXT
last_error	Captures the last 500 characters of sync failures.	TEXT
read_only	Hardcoded to 1 for external feeds.	INTEGER

Sources: internal/db/migrations/0006_integrations.sql:1-17, internal/app/integrations.go:94-97

Architecture and Data Flow

The integration between the web interface, the background sync process, and the iCalendar logic ensures data consistency.

This diagram illustrates the lifecycle of adding and initial syncing of an external iCal feed.

Key Implementation Details

• Timezones: Timed events use IANA names. If a client requires strict compliance, the system supports adding VTIMEZONE blocks.
• Empty Feeds: If no events exist, the system returns a minimal valid VCALENDAR header to prevent subscriber errors.
• Sync Backoff: Failing syncs follow an exponential backoff starting at 1 minute, doubling up to a maximum of 6 hours.

Sources: internal/app/ics.go:41, internal/app/ics.go:114-118, internal/app/integrations.go:93-97

User Interface for iCal Support

The UI provides specific controls for managing both exports and imports.

Export Controls

On the main calendar page, the system displays absolute ICS links. Each individual local calendar also provides a specific "ICS" link for filtered subscriptions.
Sources: internal/web/calendar_templ.go:198-204

Feed Management

The Settings page allows Admins to:

1. Add new feeds by providing a name, color, and address (webcal/http/https).
2. Monitor sync status, including "Last synced" time and "consecutive failures".
3. Remove feeds, which triggers a cascading deletion of associated calendar events.

Sources: internal/web/settings_templ.go:190-205, internal/app/integrations.go:215-223

iCal and ICS support allows goCasa to function as a central hub for household scheduling by bridging local data with the wider calendar ecosystem.