Document the Sockethub client and calendar integrations

This commit is contained in:
raucao committed 2026-10-27 18:22:43 +04:00
1 parent e7dc274520
commit ce5102cf39
1 file changed
+75
+75
View File
@@ -0,0 +1,75 @@
# Sockethub client and calendar integrations
Dashtab uses [Sockethub](https://sockethub.org) — a protocol gateway that
speaks ActivityStreams JSON over Socket.IO — to reach protocols a browser cannot
talk to directly. The first consumers are the calendar integrations, which read
events from CalDAV accounts and published ICS/WebCal feeds.
## Bundled client
The official client is bundled rather than loaded from the server. A Manifest V3
extension cannot execute remotely hosted code (the extension-page CSP is pinned
to `script-src 'self'`), so `@sockethub/client` and `socket.io-client` are npm
dependencies. The `@sockethub/client` `latest` tag is a stale `5.0.0-alpha.3`
from 2022; Dashtab pins the `next` line (`5.0.0-beta.0`) that matches the
5.0.0-beta servers. The client is LGPL-3.0+.
`app/services/sockethub.js` wraps `SockethubClient.connect(url, { io })`. The
`io` factory is passed explicitly so the client never falls back to its dynamic
`import("socket.io-client")`.
## Connection lifecycle
There is one global Sockethub server URL, stored in the `settings` namespace
under `sockethub-url` (default `https://sockethub.kosmos.org`). The connection
is opened lazily through a consumer registry:
- `acquire(id)` registers a consumer; the first one connects.
- `release(id)` drops a consumer; the last one disconnects.
The calendar service registers the `calendar` consumer while at least one
calendar is configured. Wizards acquire and release around their verification
steps so an abandoned setup leaves no connection open. `status`, `error`,
`url`, and the discovered `descriptor` are tracked for the UI.
`send(message)` and `sendCredentials(message)` return promises resolved by the
platform's Socket.IO acknowledgement and rejected with `SockethubPlatformError`
when the ack carries an `error`. `SockethubConnectionError` marks discovery or
initialization failures.
## CalDAV platform
All calendar traffic goes through the `caldav` platform (`contextFor('caldav')`)
with a stable actor (`CALENDAR_ACTOR`). The actions used:
- `credentials` — CalDAV URL plus username and password (an app password where
the provider supports one).
- `fetch` — discover the account's calendars.
- `query` — read events from one calendar, filtered to a UTC time range.
- `read` — list the items in a published `.ics`/`webcal:` link, with no
credentials.
Recurring items are returned once with their rule and are not expanded; Dashtab
skips them for now.
## Calendar integrations and the event cache
Two integration types feed one dashboard widget:
- `calendar-caldav` — a CalDAV account with one or more selected calendars.
- `calendar-ics` — a single published feed (a secret/private link).
Each instance stores its credentials and discovered calendars in the
`integrations` namespace. `app/services/calendar.js` refreshes them on a
15-minute interval and writes normalized events to the `events` namespace via
`app/services/calendar-cache.js`, keyed by source calendar. The
`upcoming-events` widget reads only that cache, so opening a tab shows events
immediately and does not refetch.
## Development note
The dev-server build (`pnpm start`) is a plain web page, so the Sockethub server
must allow the dev origin (`http://localhost:4200`) in its `cors.origin`
setting for the Socket.IO connection and descriptor request to succeed. The
existing development CORS proxy only handles `fetch`, not WebSockets. In the
extension, host permissions cover the connection.