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]>
61 lines
3.2 KiB
Markdown
61 lines
3.2 KiB
Markdown
# 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 a `DownloadSpec`
|
|
and emits typed callbacks. If you find yourself including a protocol header, stop.
|
|
- C++23, `-Wall -Wextra -Werror`, no raw `new`/`delete`, no naked `pthread`.
|
|
- Every public header under `core/include/vdm/` compiles standalone.
|
|
- Errors are returned (`std::expected`-style `Result<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
|
|
|
|
1. `util/` — `Result<T>`, event bus, thread pool, logging, byte-span helpers.
|
|
2. `net/http_client` — libcurl multi wrapper, one `curl_multi` per worker thread, poll
|
|
loop, proxy/auth/redirect/cookie plumbing.
|
|
3. `net/probe` — HEAD then ranged-GET fallback, header parsing, **`Content-Disposition`
|
|
RFC 5987/6266 including the legacy forms** (this is a classic source of mojibake — give
|
|
it its own test table and a fuzz target).
|
|
4. `io/sparse_file` + `io/write_buffer` — `posix_fallocate`, per-segment ring buffer sized
|
|
by `buffer_bytes`, `pwrite` at absolute offsets, `posix_fadvise(DONTNEED)`, timed
|
|
`fdatasync`.
|
|
5. `meta/veloxpart` — the resume sidecar in `docs/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).
|
|
6. `segment/segmenter` + `segment/stealer` — dynamic segment stealing, `min_segment_bytes`
|
|
floor, per-host connection caps.
|
|
7. `rate/token_bucket` — hierarchical global → queue → task.
|
|
8. `task/download_task` — the state machine in `docs/04` §1, retry/backoff policy, mirrors.
|
|
9. `rules/` — filename sanitization + collision policy + category matching (pure functions;
|
|
DAEMON supplies the rule table).
|
|
10. `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 -9` at ~60 % → resume completes → SHA-256 matches the reference byte for byte.
|
|
- Every hostile mode in `tools/testserver` handled: no-Range, lying `Accept-Ranges`,
|
|
ETag change mid-download, 401, 416, redirect chains, slow-loris, connection reset,
|
|
expiring signed URL, `Content-Length` mismatch.
|
|
- ASan + UBSan + TSan clean under a 20-task load test.
|
|
- Fuzz targets for `Content-Disposition`, the `.veloxpart.meta` reader, and URL parsing run
|
|
1 M+ execs with no crash.
|
|
- Public API documented in `core/include/vdm/README.md` and 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.
|