Document the Sockethub client and calendar integrations
This commit is contained in:
1 parent
e7dc274520
commit
ce5102cf39
1 file changed
+75
@@ -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.
|
||||
Reference in new issue
Block a user