samiandClaude Opus 5
8bb683b09d
Lays out Velox Download Manager (IDM-class download manager for Ubuntu 26.04) as a monorepo ready for parallel lane development. No implementation code by design. - docs/: architecture, roadmap M0-M7, IDM-parity GUI spec, engine design, Firefox extension spec, risks/spikes, packaging - contracts/: wire-contract skeleton (JSON Schema + fixture templates) — the single synchronization point between lanes - docs/agents/: one brief per lane (PROTO, CORE, DAEMON, GUI, EXT, PKG/QA) with owned directories, build order and definition of done - CLAUDE.md: rules of engagement — lane ownership, layering, non-negotiables - CMake scaffolding with dev/tsan/release/ci presets Two environment findings shape the design: Firefox here is the Mozilla snap (native-messaging risk, so the extension carries a loopback-WebSocket fallback), and Wayland forbids passive clipboard monitoring (so clipboard capture is explicit-action-first). Co-Authored-By: Claude Opus 5 <[email protected]>
112 lines
5.3 KiB
Markdown
112 lines
5.3 KiB
Markdown
# 06 — Risks and spikes
|
|
|
|
Each spike is a **timeboxed M0/M1 investigation with a written answer in `docs/adr/`**.
|
|
Do not let any of these be discovered in M6.
|
|
|
|
---
|
|
|
|
## R1 — Snap-packaged Firefox blocks native messaging ⚠ HIGH
|
|
|
|
**Evidence gathered on this machine (2026-09-09):**
|
|
```
|
|
$ snap list firefox → firefox 154.0 mozilla**
|
|
$ snap connections firefox → home connected
|
|
network connected
|
|
network-bind connected
|
|
personal-files (dot-mozilla-firefox)
|
|
```
|
|
Ubuntu ships Firefox as a strictly-confined snap. Executing a native-messaging host binary
|
|
that lives outside the snap's confinement has a long history of breaking, and even when the
|
|
manifest is found, the host runs under the snap's constraints.
|
|
|
|
**Why it's already handled:** `network` and `network-bind` are connected, so a loopback
|
|
WebSocket to `127.0.0.1` is available regardless. The dual-transport design in
|
|
`docs/05-extension-spec.md` §4 is not belt-and-braces engineering for its own sake — it is
|
|
the direct consequence of this finding.
|
|
|
|
**Spike S1 (2 days, M0, lane EXT):** on a clean 26.04 VM, install a trivial native host
|
|
into each of the four manifest locations and record exactly which ones snap Firefox can
|
|
launch, and whether the launched process can reach `$XDG_RUNTIME_DIR`. Write the result to
|
|
`docs/adr/0003-native-messaging-under-snap.md`.
|
|
|
|
**Decision rule:** if native messaging works → prefer it, keep WS as fallback. If it does
|
|
not → WS becomes the primary path, `velox-nmhost` still ships for deb/flatpak/tarball
|
|
Firefox users, and the installer detects the snap and configures pairing automatically.
|
|
Either way, M2 ships. The *installer* must detect which Firefox is in use and say so.
|
|
|
|
---
|
|
|
|
## R2 — Wayland clipboard monitoring ⚠ HIGH (feature-shaping)
|
|
|
|
Ubuntu 26.04 defaults to GNOME on Wayland. A Wayland client **cannot** passively observe
|
|
clipboard changes made by other applications — that is a deliberate security property, not
|
|
a bug, and it is the mechanism IDM's clipboard capture relies on.
|
|
|
|
**Spike S2 (2 days, M1, lane GUI):** test, on this exact desktop, (a) whether Qt receives
|
|
`QClipboard::dataChanged` for copies made in another app, (b) whether Mutter exposes
|
|
`ext-data-control-v1` / `wlr-data-control`, (c) whether `org.freedesktop.portal.GlobalShortcuts`
|
|
gives a reliable "grab clipboard now" hotkey, (d) XWayland fallback behaviour.
|
|
|
|
**Ship-regardless design:** the extension context menu covers the browser case (where
|
|
almost all copied download links come from), the portal global shortcut covers explicit
|
|
capture, and the Add-URL dialog pre-fills from the clipboard when opened. Background
|
|
monitoring is a bonus if the spike says yes. **Do not let this block the release, and do
|
|
not promise it in the UI before S2 answers.**
|
|
|
|
---
|
|
|
|
## R3 — AMO review friction 🟠 MEDIUM
|
|
|
|
`<all_urls>` + `webRequestBlocking` + `nativeMessaging` is a heavyweight permission set;
|
|
a download manager legitimately needs it, but reviews take longer and can bounce.
|
|
**Mitigation:** run `web-ext lint` in CI from day one, no remote code execution *at all*
|
|
(no CDN scripts, no `eval`), ship readable source with a build-reproduction script, write
|
|
the permission justification in M1 rather than at submission, and submit an early
|
|
unlisted build in M3 to shake out review problems while there's still time.
|
|
|
|
---
|
|
|
|
## R4 — Servers that lie about ranges 🟠 MEDIUM
|
|
|
|
`Accept-Ranges: bytes` present but `206` never delivered; ETags that change per request;
|
|
CDNs that 403 a second connection; signed URLs that expire mid-download.
|
|
**Mitigation:** resumability is *proven* by an actual 206 with a matching `Content-Range`
|
|
(`docs/04` §2); `tools/testserver` implements each of these as an explicit hostile mode and
|
|
CORE's DoD requires passing all of them; `download.refreshUrl` exists so the user can paste
|
|
a fresh signed URL into a running task.
|
|
|
|
---
|
|
|
|
## R5 — Qt 6 LGPL compliance 🟢 LOW but do it right
|
|
|
|
Dynamic linking against unmodified system Qt satisfies LGPLv3. **Do not** static-link Qt
|
|
into the AppImage without reading the terms; if the AppImage bundles Qt, bundle it as
|
|
shared objects and ship the relink information. Record in `docs/adr/0002-qt-licensing.md`.
|
|
|
|
---
|
|
|
|
## R6 — ffmpeg/libav licensing for the media grabber 🟢 LOW
|
|
|
|
Depend on the distro's ffmpeg rather than bundling; keep the muxer behind a runtime check
|
|
so the app degrades gracefully when ffmpeg is absent. Never bundle a GPL build into a
|
|
package whose licence conflicts.
|
|
|
|
---
|
|
|
|
## R7 — Contract drift between lanes 🟠 MEDIUM
|
|
|
|
The classic parallel-development failure: GUI and extension each "fix" the protocol in
|
|
their own tree and integration in M2 becomes a rewrite.
|
|
**Mitigation:** the entire `contracts/` discipline — single owner, generated code, golden
|
|
fixtures, conformance suite as a merge gate. If a lane finds the contract wrong, it opens
|
|
a `contracts/`-only PR; it does **not** work around it locally. This is the single most
|
|
important process rule in the project.
|
|
|
|
---
|
|
|
|
## R8 — Scope creep into a browser-agnostic product 🟢 LOW
|
|
|
|
Chrome/Chromium support means losing blocking `webRequest` and rebuilding capture on
|
|
`declarativeNetRequest` + `downloads.onDeterminingFilename`, which is a different design.
|
|
Ship Firefox 1.0 first. Revisit after M7 as its own project, not as an M3 side quest.
|