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.2 KiB
3.2 KiB
Agent brief — CORE (libveloxcore)
Starts when PROTO freezes VERSION. The critical path runs through you.
You own
core/** tools/bench/** tools/fuzz/**
You may read contracts/ and docs/. You write nowhere else — in particular you never
touch daemon/: if the daemon needs something, expose it as a core API and tell DAEMON.
Read first
docs/04-engine-design.md end to end. It is your specification, not background reading.
Hard architectural constraints
- No JSON, no SQL, no Qt, no RPC in
core/. Your public API takes aDownloadSpecand emits typed callbacks. If you find yourself including a protocol header, stop. - C++23,
-Wall -Wextra -Werror, no rawnew/delete, no nakedpthread. - Every public header under
core/include/vdm/compiles standalone. - Errors are returned (
std::expected-styleResult<T>), not thrown, on the transfer path. - No allocation in the curl write callback. The ring buffer is preallocated at task start. This is checked in review and by a bench assertion.
Build order
util/—Result<T>, event bus, thread pool, logging, byte-span helpers.net/http_client— libcurl multi wrapper, onecurl_multiper worker thread, poll loop, proxy/auth/redirect/cookie plumbing.net/probe— HEAD then ranged-GET fallback, header parsing,Content-DispositionRFC 5987/6266 including the legacy forms (this is a classic source of mojibake — give it its own test table and a fuzz target).io/sparse_file+io/write_buffer—posix_fallocate, per-segment ring buffer sized bybuffer_bytes,pwriteat absolute offsets,posix_fadvise(DONTNEED), timedfdatasync.meta/veloxpart— the resume sidecar indocs/04§5, CRC-verified,fdatasync'd at segment boundaries. Write the reader first and fuzz it — this file is attacker- adjacent (it lives in a world-writable-ish download dir).segment/segmenter+segment/stealer— dynamic segment stealing,min_segment_bytesfloor, per-host connection caps.rate/token_bucket— hierarchical global → queue → task.task/download_task— the state machine indocs/04§1, retry/backoff policy, mirrors.rules/— filename sanitization + collision policy + category matching (pure functions; DAEMON supplies the rule table).media/— M4, not now. Leave the directory empty.
Definition of done (M1)
- 5 GB download saturates a 1 Gbit link at ≤ 8 % of one core (recorded in
tools/bench/). kill -9at ~60 % → resume completes → SHA-256 matches the reference byte for byte.- Every hostile mode in
tools/testserverhandled: no-Range, lyingAccept-Ranges, ETag change mid-download, 401, 416, redirect chains, slow-loris, connection reset, expiring signed URL,Content-Lengthmismatch. - ASan + UBSan + TSan clean under a 20-task load test.
- Fuzz targets for
Content-Disposition, the.veloxpart.metareader, and URL parsing run 1 M+ execs with no crash. - Public API documented in
core/include/vdm/README.mdand reviewed by DAEMON before M2.
Do not
- Do not start with
io_uring. It's a post-1.0 experiment gated on a ≥10 % bench win. - Do not implement HLS/DASH in M1.
- Do not add a "just for testing" JSON dependency.