Live Update Stream

Relevant source files

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

• internal/app/app.go
• internal/web/calendar_templ.go
• internal/app/calendar.go
• internal/app/live_test.go
• internal/app/integrations.go

The Live Update Stream provides real-time notifications to web clients when data changes occur within the GoCasa ecosystem. It uses Server-Sent Events (SSE) to push updates from the backend to connected browsers, allowing the UI to refresh sections automatically without manual page reloads.

Sources: internal/app/app.go:88, internal/web/calendar_templ.go:211-213

Architecture and Components

The system relies on a central message bus and a dedicated HTTP endpoint to manage persistent connections and broadcast events.

Event Bus

The Bus serves as the internal message broker. It handles client subscriptions and broadcasts messages when entities like events, members, or calendars are created, updated, or deleted.
Sources: internal/app/app.go:53, internal/app/live_test.go:94-103

Stream Endpoint

The application exposes a GET /events/stream endpoint. This handler upgrades the HTTP connection to a long-running SSE stream. It disables proxy buffering by setting the X-Accel-Buffering: no header.
Sources: internal/app/app.go:88, internal/app/live_test.go:66-70

Client-Side Integration

Browsers use the native EventSource API to connect to the stream. A script embedded in pages (like the Calendar) listens for messages and performs a partial DOM swap. When an update arrives, the client refetches the current page and replaces the #live region with the updated content.
Sources: internal/web/calendar_templ.go:225-246

Data Flow

The following diagram illustrates the flow from a data change to a UI update:

The application triggers a publish action after successful database operations.
Sources: internal/app/calendar.go:167, internal/app/integrations.go:222, internal/app/live_test.go:76-88

Technical Implementation

Event Format

Messages sent over the stream are formatted as JSON objects within SSE "data" lines. Each message identifies the type of change and the affected entity.

Field	Description	Example
type	The action performed	created, updated, deleted
entity	The object modified	event, member, calendar
id	Unique identifier	1, 2

Sources: internal/app/live_test.go:76-88

Connectivity and Reliability

The stream includes several features to ensure connection stability:

• Heartbeats: The server sends periodic : heartbeat comments to prevent idle timeouts by reverse proxies or browsers.
• Automatic Reconnect: If the EventSource errors or closes, the client-side script reloads the page or retries the connection after a 5-second delay.
• Catch-up: The client triggers a full refresh upon initial connection (onopen) to ensure it has the latest state.
• Conflict Prevention: The client uses an AbortController to cancel older, slower fetch requests if a newer update arrives.

Sources: internal/app/live_test.go:90-92, internal/web/calendar_templ.go:228-244

Server Settings

The stream handler explicitly manages headers to support different deployment environments.

Header	Value	Purpose
Content-Type	text/event-stream	Required for SSE
X-Accel-Buffering	no	Prevents Nginx from buffering the stream

Sources: internal/app/live_test.go:66-70, README.md:92-94

Summary

The Live Update Stream enables a reactive user experience for the GoCasa dashboard. By combining a backend event bus with standard SSE and targeted DOM replacement, the system maintains data consistency across multiple devices without complex client-side state management.