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]>
3.5 KiB
3.5 KiB
Agent brief — DAEMON (veloxd)
Starts with CORE. You are the only process that owns state.
You own
daemon/** cli/** nmhost/** packaging/nativehost/**
Read contracts/, core/include/, docs/. Never write in core/, gui/, or extension/.
Read first
docs/01-architecture.md §2–§5, contracts/README.md, docs/05-extension-spec.md §4
(you implement the daemon half of pairing).
Build order
- RPC server —
rpc/uds_server(NDJSON over$XDG_RUNTIME_DIR/velox/velox.sock, 0600,SO_PEERCREDsame-UID check) andrpc/ws_server(bind127.0.0.1only, first free port in 52000–52016, write the chosen port tows.port). One dispatcher, generated fromcontracts/. Never block the RPC loop — disk and network work goes to CORE's pools. - Auth & pairing —
session.pairtriggers a user prompt (GUI dialog if connected, else a desktop notification with actions). Tokens: 256-bit, stored hashed, per-install, revocable. Failed-auth rate limit 5/min then 60 s lockout. Enforcex-transportsandx-privilegedfrom the schema: privileged methods are refused over WS with-32003. - Store — SQLite WAL. Tables:
tasks,segments,categories,queues,rules,settings,history,pairings. Numbered migrations instore/migrations/, applied at startup, with a forward-only test from every released schema version. Credentials never go in SQLite — Secret Service via libsecret. - Scheduler & queues — concurrency governor (global max active, per-queue max, per-host caps), time windows, days-of-week, one-shot vs periodic, "when queue completes" actions.
- Event fan-out — per-subscription filtering, and
event.task.progressbatched at ≤ 4 Hz into a single array message. Do not emit one message per task per tick; that is how you turn 20 downloads into a GUI that burns a core. - Capture endpoint —
capture.offermust answer within 750 ms, always. Apply the rules table, resolve the category folder, dedupe against active tasks, returntake/ignore. If anything internally is slow, answerignoreand let Firefox have it. Never make the browser wait. - Integration — systemd user units (
velox.service+velox.socketfor socket activation), single-instance lock, XDG autostart,org.freedesktop.Notifications, graceful shutdown that flushes buffers and meta files. veloxCLI —add,ls,pause,resume,rm,queue,settings,--jsonoutput. Build this early: it is how you test the daemon before the GUI exists.velox-nmhost— 4-byte-length-prefixed stdio ⇄ Unix socket pump. Under 300 lines, zero business logic, and it must exit cleanly when Firefox closes the pipe. Install manifests to all four locations listed indocs/05§4.
Definition of done (M1)
- Passes the full conformance suite as a server, over both transports.
- Kill and restart the daemon mid-download: all tasks reload with correct state and resume.
- 1 000 tasks in the DB:
download.listwith paging under 50 ms. - Pairing flow works from a real Firefox extension; unpair revokes immediately.
systemctl --user status veloxclean; socket activation verified from cold.- Security review passed: no bind beyond loopback, no path traversal in
saveDir(canonicalize and check against allowed roots →-32011), no plaintext secrets.
Do not
- Do not put download logic here — that's CORE. You schedule and persist; CORE transfers.
- Do not invent protocol fields. File a request with PROTO.