owltide/docs/dev/server-sent-events.md

<!--
	SPDX-FileCopyrightText: © 2025 Hornwitser <code@hornwitser.no>
	SPDX-License-Identifier: AGPL-3.0-or-later
-->
# Server-sent events

To update in real time this application sends a `text/event-source` stream using [Server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events). These streams use the current session if any to filter restricted resources and ends when the session rotates timeout is hit, necessitating a reconnect by the user agent. (If there are no session associated with the connection it ends after the session rotates timeout).

## Events

Upon connecting a `"connect"` event is emitted with the session the connection was made under. This is the primary mechanism a user agent discovers its own session having been rotated into a new one, which also happens when the access level of the account associated with the session changes.

After the `"connect"` event the user agent will start to receive updates to resources it has access to that has changed. There is no filtering for what resoucres the user agent receives updates for at the moment as there's not enough events to justify the complexity of server-side subscriptions and filtering.

## Id and order

Events are guaranteed to be delivered in order, and to maintain consistency the server provides the following guarantee: Any entities fetched after receiving a response from `/api/last-event-id` will include updates from all events up to and including the `id` received from the response.

This means that a client can fetch an up to date and live representation of any API entity by first fetching the last event from `/api/last-event-id`, and then in parallel fetch any entities as well as opening the `/api/events` stream with the `lastEventId` query param set to the value received from the `/api/last-event-id` endpoint.
Close event streams for expired sessions When a session expires close any event streams that have been opened with that session. This prevents an attacker with a leaked session cookie from opening a stream and receiving updates indefinitely without being detected. By sending the session the event stream is opened with when the stream is established this closure on session expiry also serves as a way for a user agent to be notified whenever its own access level changes. 2025-07-08 15:43:14 +02:00			`<!--`
			`SPDX-FileCopyrightText: © 2025 Hornwitser <code@hornwitser.no>`
			`SPDX-License-Identifier: AGPL-3.0-or-later`
			`-->`
			`# Server-sent events`

Separate rotation and expiry of sessions If a session is rotate in the middle of a server side rendering then some random portions of requests made on the server side will fail with a session taken error as the server is not going to update the cookies of the client during these requests. To avoid this pitfall extend the expiry time of sessions to be 10 seconds after the session has been rotated. This is accomplished by introducing a new timestamp on sessions called the rotateAt at time alongside the expiresAt time. Sessions used after rotateAt that haven't been rotated get rotated into a new session and the existing session gets the expiresAt time set to 10 seconds in the future. Sessions that are past the expiredAt time have no access. This makes the logic around session expiry simpler, and also makes it possible to audit when a session got rotated, and to mark sessions as expired without a chance to rotate to a new session without having to resort to a finished flag. 2025-07-09 14:54:54 +02:00			To update in real time this application sends a `text/event-source` stream using [Server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events). These streams use the current session if any to filter restricted resources and ends when the session rotates timeout is hit, necessitating a reconnect by the user agent. (If there are no session associated with the connection it ends after the session rotates timeout).
Close event streams for expired sessions When a session expires close any event streams that have been opened with that session. This prevents an attacker with a leaked session cookie from opening a stream and receiving updates indefinitely without being detected. By sending the session the event stream is opened with when the stream is established this closure on session expiry also serves as a way for a user agent to be notified whenever its own access level changes. 2025-07-08 15:43:14 +02:00
			`## Events`

			Upon connecting a `"connect"` event is emitted with the session the connection was made under. This is the primary mechanism a user agent discovers its own session having been rotated into a new one, which also happens when the access level of the account associated with the session changes.

			After the `"connect"` event the user agent will start to receive updates to resources it has access to that has changed. There is no filtering for what resoucres the user agent receives updates for at the moment as there's not enough events to justify the complexity of server-side subscriptions and filtering.
Refactor to persist and reliably deliver events Store events that are to be broadcasted in the database, and fetch events to serve in the /api/event stream to the client from the database. This ensures that events are not lost if the operation to open the stream takes longer than usual, or the client was not connected at the time the event was broadcast. To ensure no events are lost in the transition from server generating the page to the client hydrating and establishing a connection with the event stream, the /api/last-event-id endpoint is first queried on the server before any other entities is fetched from the database. The client then passes this id when establishing the event stream, and receives all events greater than that id. 2025-09-20 20:11:58 +02:00
			`## Id and order`

			Events are guaranteed to be delivered in order, and to maintain consistency the server provides the following guarantee: Any entities fetched after receiving a response from `/api/last-event-id` will include updates from all events up to and including the `id` received from the response.

			This means that a client can fetch an up to date and live representation of any API entity by first fetching the last event from `/api/last-event-id`, and then in parallel fetch any entities as well as opening the `/api/events` stream with the `lastEventId` query param set to the value received from the `/api/last-event-id` endpoint.