ADR 0019: The browser extension without a server¶
Context¶
The browser extension (#65) forwards the new tab to a running Waylight server. Someone without a server cannot try Waylight at all, and the extension is about to be listed on addons.mozilla.org (#290), where most visitors will not have one.
291 asks for a "Use without a server" mode: the web app runs inside the¶
extension against local storage. In scope are bookmarks, notes, to-dos, countdowns, the focus timer, habits, the clock and the weather; everything that needs background jobs or secrets (services, Docker, parcels, notifications and the like) stays out. Data must be exportable in a form the server imports, so moving to a server later is an import.
Two facts shape the decision:
- Every frontend feature already talks to its backend through a port in its
use case ring (
NotesGateway,TodosGateway, …) implemented by anadapter/apiclass, and the container inweb/src/appchooses the implementation. The offline editing of to-dos and notes (#80) already wraps these gateways with an IndexedDB outbox. - The extension is deliberately tiny today (10 files, no dependencies, three
permissions;
scripts/check.mjsenforces that).
Options¶
A. A local HTTP adapter¶
An HttpClient implementation that answers /api/... requests inside the
browser from IndexedDB, mirroring the server's endpoints for the modules in
scope. The rest of the app stays unchanged.
- One place to implement, and the use cases do not notice.
- It has to imitate HTTP: routes, status codes, the error format, DTO shapes and the server's validation messages. Every server change can silently break it, and nothing in the type system notices.
B. A local gateway per feature¶
Each feature in scope gets a second implementation of its existing port,
for example LocalNotesGateway implements NotesGateway, backed by IndexedDB.
The container chooses the local or the API gateways once, at start, from the
mode.
- Uses the seams the architecture already has; the compiler checks each local gateway against its port, so a changed port fails the build.
- Validation that today lives only in Go has to exist in TypeScript too for the features in scope. Most of it is already in the frontend domains for instant form feedback (#80 needed the same).
- More files: one local gateway per feature, plus the dashboard, appearance and the modules list.
C. A WebAssembly build of the Go server¶
Compile the server to WebAssembly and run it in the extension.
- Exact behaviour, no duplicated rules.
- Several megabytes of WebAssembly, SQLite in the browser, no background jobs in a Manifest V3 service worker that is stopped when idle; far beyond the lean budget of ADR 0011.
Decision¶
Option B, local gateways per feature, with these rules:
- A new composition root
web/src/app/localContainer.tsbuilds the container with local gateways for: dashboard (tabs, widgets, layout), appearance, modules (a fixed list of the modules in scope), bookmarks, notes, to-dos, countdowns, focus, habits. Auth is skipped: the extension is a single person's browser profile. - Weather calls Open-Meteo directly from the extension page, so the
extension gains exactly one host permission,
https://api.open-meteo.com/*, requested only when the user chooses local mode (optional_host_permissions).check.mjsallows this one host and nothing else. - Storage is IndexedDB, one object store per feature, in the shape of the server's tables (IDs, timestamps), so that the export (below) is a direct mapping.
- Export and moving to a server: the local mode writes the JSON export
format of the
transfermodule (formatwaylight-export, sections per module with table rows). When the user later enters a server address, the extension offers to import that file into the server through the existing import endpoint, then switches to forwarding mode. - Modules out of scope are hidden, not broken: the local modules list contains only the modules in scope, and the widget picker, settings and search already follow that list.
- Pointer to the full version: local mode says plainly what it leaves out. Where a module is hidden (widget picker, settings, modules list) and in a short "What you get with a server" section in the settings, the extension names what a server or the Raspberry Pi image adds (services, Docker, parcels, notifications, several devices and accounts, sync) and links to the installation guides. The hint is static text bundled with the extension, can be dismissed, and causes no outbound request.
- Build: a second Vite entry
web/src/extension.tsbuilds the app intoextension/app/for the extension zip. The forwarding mode stays as it is; the local app is only loaded when the user chooses local mode. - Budget: a new entry in
budgets.json, extension zip, starting at the measured size + 10 % (expected around 1.5 MB, mostly the app bundle). - Tests: each local gateway runs the same use case tests as the API gateway (shared test cases per port), and one Playwright test loads the extension in local mode, adds a note and a to-do, exports, and imports the file into a test server.
Consequences¶
- The extension stops being a 10-file package: it carries the app bundle and becomes subject to a size budget and the store review of a larger add-on.
- Validation rules of the features in scope exist twice (Go and TypeScript); the shared test cases per port keep them in step.
- New features are server-only by default; adding one to the local mode is a deliberate step with its own local gateway.
- The export format of the
transfermodule becomes a contract with the extension; changing a table's columns needs a matching change in the local export (a test round-trips an export through the server import).
Follow-up work¶
- Vite entry and
localContainer.ts; extension packaging and budget. - Local gateways: dashboard, appearance, modules list.
- Local gateways: bookmarks, notes, to-dos, countdowns, focus, habits; weather with the optional host permission.
- Export in the transfer format; import into a server when an address is entered.
- Options page: choose "Use without a server" or enter a server; store listing text updated (#290).
- Pointer to the full version in the widget picker, the modules list and the settings, with links to the server and Raspberry Pi guides.