Glossary
Terms used across Apollo Download Manager's documents, issues and code, in alphabetical order. Where a term comes from the research report, the section is given. Code and docs use these words with these meanings. A new term is added here in the same PR that introduces it.
| Term | Meaning |
|---|---|
| Adaptive connections (ramp) | Opening every connection a download may use, a step at a time (1, 2, 4, 8; #247), then dropping one at a time while the speed holds, and bringing back the last one whose loss made it slower. The asked-for count is the most it may use, not a must (ENGINE_INTERNALS.md; #47, #221) |
| ADR | Architecture decision record: one numbered, accepted decision with its context and consequences. See decisions/ |
| Anomaly | An answer that contradicts its request: a wrong or malformed Content-Range, a length that disagrees with it, a multipart body, or a body that stops short of or runs past its range. The first is retried; a second on the same download ends ranges for it (ENGINE_INTERNALS.md; report §5.1; #41) |
| Apollo DM | This application, Apollo Download Manager, in short (ADR-0018). It installs and runs beside V1, with its own identity (#11, ADR-0003) |
| Automatic category | The category a download gets from its file name's extension: the first category that lists it. Also when the server names the file after the download started (FILE_NAMING.md; #31) |
| Back-pressure | Pausing a transfer while the bounded disk-write queue is full, so a slow disk slows the network instead of growing memory (report §5.2; #49) |
| Browser bridge | The app's side of the browser integration: the local connection Apollo DM's native host reaches it on, authenticated by a per-launch token, and what it does with each link from the browser (BROWSER_EXTENSION.md; #65) |
| Budget | The connection allowance per host (8) and across all downloads (48), which the engine shares max-min fairly between running downloads (ENGINE_INTERNALS.md; #47) |
| Build identity record | build-info.json: what one native build contains and how it was made: each library's source, SHA-256, signature result and build options, what curl -V reports as linked, the artefact checksums, the toolchains and the Apollo DM commit (#35; BUILDING_NATIVE.md) |
| Capability | Something an engine or build really supports, such as a protocol, live connection changes or validator-checked resume. It is reported, never assumed, so the UI can explain differences truthfully (report §4.2; #57) |
| Changed object | A file that changed on the server during a download, detected through its validator, its total length or its encoding. The old bytes are discarded and the download restarts once (report §5.3; #45) |
| Checkpoint | The durable record of a transfer's progress: the format version, the source without login or query, the total length, the validators, the content encoding and the durable coverage D. The engine sends it after syncing the part file, and the app saves it in its database (report §5.2; #43; ENGINE_INTERNALS.md) |
| Coverage (C) | The disjoint byte intervals of a file that were written to disk by the lease that owned them (report §5.2) |
| Credentials | A login for a download's server: a user name and password, sent as HTTP Basic only to the first URL's origin. They cross the DirectTransfer contract in memory, through the engine's pipe only, and Debug output never shows them. They replaced the credential handle of contract versions 1 to 7 (ENGINE_CONTRACT.md; #40, #70) |
DirectTransfer | The engine-neutral contract between the manager and the direct-download engine: add, pause, resume, cancel, remove, limits, connections, snapshots and events (report §4.2; #36) |
| Durable coverage (D) | The part of coverage that was fsynced and then recorded in a checkpoint. After a crash, only D is trusted (report §5.2) |
| Engine | The component that performs transfers. Apollo DM has its own transfer engine for direct downloads, and libtorrent for BitTorrent. Apollo DM contains no aria2 (ADR-0001) |
| Epoch | The period during which one validator holds. A validator change starts a new epoch with empty coverage (report §5.2, invariant I4) |
| Failure class | How a failure is treated. Transient is retried after a wait. Throttled means the server asked to slow down: it is retried after what Retry-After asks for, with fewer connections. Permanent is never retried automatically (ENGINE_INTERNALS.md; #48) |
| Full jitter | A retry wait drawn at random between zero and the doubled wait, so clients that failed together don't come back together (#48) |
| Hash frontier | Hashing the file's contiguous prefix from byte 0 as it becomes covered. Segment hashes can't be combined into a whole-file hash, so the rest is read back at the end (report §5.3; #46) |
| Invariants I1–I7 | The scheduler properties checked after every simulated event: partition, exclusivity, acceptance, monotonic coverage, durability, completion and conservation (report §5.2; #42) |
| Jain's index | A fairness measure for shares x₁…xₙ: (Σx)² / (n·Σx²). It is 1 when all are equal and 1/n when one gets everything; the concurrent-download fixtures require at least 0.9 (#47) |
| Lease | Exclusive ownership of a byte range [cursor, end) by one request, with an id that is never reused. States: Assigned, InFlight, Completed, Failed and Revoked. Bytes from a revoked or unknown lease are dropped and counted as wasted (report §5.2; #42) |
| libcurl layer | The only code that calls libcurl: FFI and the Multi event loop on its own thread (report §4.2; crates/velocity-curl, ADR-0002) |
| Local address | An address on this computer or a private network: loopback, private (RFC 1918), shared (RFC 6598), link-local, unspecified or IPv6 unique-local. A link from the browser that connects to one waits for the user's confirmation (ADR-0006; SECURITY.md; #67) |
| Metalink | An XML document that lists files with their sources (mirrors), hashes and piece hashes: Metalink 4 (RFC 5854, .meta4) or Metalink 3 (.metalink). The manager reads it and adds one download per file; a link that turns out to be one is followed while Metalink is on (#54; ENGINE_INTERNALS.md) |
| Mirror (source) | One of a download's URLs other than the first, such as a Metalink file's. Proven mirrors share the file's ranges, the faster ones more; an unproven one is only a fallback (#55; ENGINE_INTERNALS.md) |
| Multiplexing | Running several requests as HTTP/2 streams of one connection. Apollo DM tries it first, and switches a download to connections of their own only when that is measurably faster (#47) |
| Native host | The small program a browser starts for Apollo DM's extension, velocity-native-host-v2: it checks each message and passes the valid ones to the running app. Registered with each browser for this user only (BROWSER_EXTENSION.md; #65) |
| Native lock file | scripts/native/deps.lock: the pinned version, source URL, SHA-256, signing key and licence of every native library Apollo DM builds (#35; DEPENDENCIES.md) |
| No-clobber finalisation | Completing a download by renaming its part file to the final name without replacing an existing file (report §5.3; #43) |
| Origin | A URL's scheme, host and port (RFC 6454), as libcurl reads the URL. A download's login and custom headers go only to its first URL's origin; once a redirect leaves it, no request carries them (ENGINE_INTERNALS.md; #40) |
| Part file | The file being downloaded, <destination>.vdmpart, until it is complete and renamed into place without replacing an existing file. Sparse on Windows (#43) |
| Performance profile | Conservative, Balanced (the default), Maximum or Custom: limits for the adaptive engine, the most connections per server and the smallest piece. Within them the engine keeps only the connections that help (SETTINGS.md; ADR-0005; #57) |
| Piece hashes | Trusted digests of a file's fixed-size pieces, such as a Metalink file's <pieces>. Each piece is checked once it is covered, and a bad one is fetched again on its own (report §5.3; #46, #54) |
| PO | The Product Owner, who decides scope, architecture, dependencies, licensing, security, repository settings, merges and releases |
| Probe | The first request of a download: a bounded range request whose bytes are kept. Its response decides between ranges, sequential ranges and a single stream, without a wasted full transfer. Apollo DM doesn't use HEAD as proof of range support (report §5.1; #41) |
| Queue | The manager's order of unfinished downloads and its limit on how many run at once (3 by default). A download is given to the engine only on its turn; a paused or finished one frees its slot. move_download reorders the waiting ones (#50) |
| Ranges lost | The state when a server that accepted ranges stops honouring them: a 200 for a later range, or a second anomaly. The rest comes as one stream that writes only the bytes not yet covered (report §5.1; #41) |
| Remembered login | A download's login, custom headers and SSH key passphrase saved in the system keychain because the user ticked "Remember this login"; it comes back after a restart, and is deleted with the download (ADR-0015; #70) |
| Resume data | libtorrent's own record of one torrent: its metadata, which pieces it has, its file choice, its trackers and its seeding totals. The torrent helper sends it in chunks, and a torrent is added back from it after check_resume_data. Not a checkpoint, which is Apollo DM's own format for direct downloads (TORRENTS.md; #62) |
| Secret | A password, SSH key passphrase or custom header value, held as Secret: wiped from memory when dropped, never printed, and never written to the database, a checkpoint, a log or a process's arguments (SECURITY.md; #70) |
| Sequential ranges | A server that honours ranges but gives no total (bytes 0-b/*). The rest is fetched as one open range at a time, without parallel segments, until a 416 marks the end (report §5.1; #41) |
| Schedule window | The local-time window in which scheduled downloads run: from startTime on an enabled day to stopTime, which may fall on the next day. Opening starts them, closing pauses them (#50, V1's rules) |
| Seeding policy | When a completed torrent stops uploading: never (the default, ADR-0005), after a time, at a share ratio, at whichever comes first, or not until the user stops it (TORRENTS.md; #62) |
| Seeding queue | The torrents allowed to seed beyond the most that may seed at once (maxActiveSeeds), waiting for a slot, the longest waiting first (TORRENTS.md; #62) |
| Sidecar | A helper program shipped with the app and started by it: the child-process engine (ADR-0012) and the torrent helper (ADR-0014) |
| Sparse file | A file whose unwritten ranges take no space and are never filled with zeros. Apollo DM's part files are sparse on Windows, because NTFS otherwise zero-fills the gap in front of a write far into a new file (#42's measurement, #43) |
| Single stream | Downloading over one connection from byte 0, used when the server ignores ranges (report §5.1) |
| Split (work-stealing) | Halving the largest remaining lease so a free worker can take the second half. The old request stops at the new boundary (report §5.2; #42) |
| Stall | Time with no byte from the network. After 15 s the download shows Stalled; after 30 s the request is reset and retried. A slow but steady transfer is never a stall, and time spent waiting for the disk doesn't count (starting values; #48) |
| Strong validator | An ETag without the W/ prefix, or a Last-Modified date that RFC 9110 §8.8.2.2 treats as strong. Only a strong validator may be sent in If-Range (report §5.3; #45) |
| Supervisor | velocity_child's supervisor, as SupervisedEngine for the engine and SupervisedTorrentEngine for the torrent helper: it starts the child process, restarts it after a crash or when it stops answering (at most 5 times in 5 minutes; #48), and otherwise leaves it unavailable until the user restarts it by hand (ENGINE_PROTOCOL.md; #39, #62) |
| Test CA | A certificate authority made fresh for one TLS test, with a unique name, that signs the fixture's server certificates and its revocation list. Tests trust it through velocity-curl's test-only test-ca feature, never by turning verification off (SECURITY.md; #69) |
| Token bucket | How a speed limit is kept: a store of bytes that refills at the limit's rate. A transfer may write only while its buckets (its own and the global one) have tokens; otherwise it pauses until they refill (RateLimit; #49) |
| Torrent helper | velocity-torrent serve: libtorrent in a child process the app starts and supervises, so a fault in libtorrent ends only the helper (ADR-0014; TORRENTS.md; #62) |
| Transfer engine | Apollo DM's own direct-download engine: probe, leases, checkpoints, integrity, retries and limits, over the libcurl layer, in crates/velocity-transfer (ADR-0002), run as a child process (ADR-0012) |
| V1 | The original Velocity Download Manager (Singlbase-Technologies-Limited/velocity-download-manager). A reference for features and benchmarks only. Never modified from Apollo DM work |
V2 | The working name of Apollo Download Manager until 0.2.0. Older issues, code comments and identifiers still use it, such as velocity-native-host-v2 and com.velocity.downloadmanager.v2; the identifiers keep it on purpose (COEXISTENCE.md) |
| Validator | A response header that identifies one version of a file, either an ETag or Last-Modified. It is used to detect a changed object between requests (report §5.3). See also strong validator |
| Verification (Verified, Size verified, Not verified) | What was proven about a completed download: Verified when a checksum or trusted piece hashes matched, Size verified when every byte arrived and the length matched, Not verified when it resumed from bytes on disk without a strong validator. "Verified" is shown only when a hash was checked (report §5.3; ADR-0010; #46) |
| Verification levels (L1–L5) | The test levels: L1 fast local checks, L2 focused tests, L3 pre-merge selection, L4 expensive suites, L5 production acceptance. See TESTING.md and #15 |
| Version floor | The oldest libcurl Apollo DM accepts, today 8.23.0. A build below it fails, and the engine refuses to start (report §8.1; #35) |
| Wasted bytes | Bytes received but not accepted into coverage, such as from a revoked lease, an overrun or a rejected response. Counted and reported, never hidden (report §5.1) |
| Waiting for network | The status of a download that failed because no connection could be made. It keeps its bytes and starts again when the system's network changes (#318, ADR-0019) |