Design Decisions & Releasing
This page preserves key architectural rationale behind Anabranch Core's clean-room design, the empirical deprecation of Aria2Engine, .meta compatibility guarantees, and the release process.
Core Design Rationale
- Stateless Library Boundary: The library stores no hard-coded mirror tables, ships zero URLs, writes no preferences, and binds no logging framework (
NONEdefaults forLogger,Listener,Cancellation).Source.Resolverreplaces naivebase + nameconcatenation so signed cloud URLs and mismatched mirror paths work cleanly. - Five Explicit Non-Goals: Anabranch Core does not handle APK/archive extraction or install, foreground notifications/UI, cross-restart task orchestration, bundled remote configs, or domain-specific manifest concepts.
- Separate
ListenerandCancellation+ Rawbytes/sec: Splitting observation from polling cancellation avoids forcing progress listeners to implement cancel logic, andListener.onSpeed(double)reports raw bytes/sec without ambiguous MB/MiB scaling. - Why Keep
Downloader.probeAll: Althoughdownload()probes only until the first usable source for speed,probeAll()gives callers a low-cost preflight to detect stale mirrors whose file sizes diverge before downloading chunks.
Why Aria2Engine implements Engine Was Retired
On 2026-09-01, testing aria2 1.37.0 against a request-logging loopback HTTP server showed that feeding a custom Range: bytes=1000-1999 header into aria2 causes a fatal protocol conflict: aria2 writes the 1000 bytes, then reads the total file length from the 206 Content-Range header and hangs indefinitely waiting for the remaining bytes instead of exiting or failing.
Per the rule against half-working fallback paths, Aria2Engine was removed entirely in favor of Aria2Downloader (whole-file multi-URI addUri). At the same time, control moved away from argv + localhost JSON-RPC to the --enable-libaria2 public C++ session API driven by a single Java runOnce loop—eliminating local RPC ports, secrets, cross-thread calls, and exit() aborts on bad CLI flags. See docs/ARIA2.md for full details.
Versioning, .meta Contract & Releasing
0.x.yAPI Stability: Java public signatures may evolve during0.x.y..metaResume Format Guarantee: Unknown.metaversions (current headeranabranch-meta/2) are safely discarded rather than misread; any incompatible.metachange bumps at least the minor version.- Manual Publishing (
docs/RELEASING.md): Releases are strictly manual—either locally (gradle build+gradle centralBundle) or via.github/workflows/build-core.yml(workflow_dispatch, optionally compiling and bundlinganabranch-aria2AAR and corresponding GPL source tarball). Consultdocs/RELEASING.mdandaria2/THIRD-PARTY-NOTICES.mdbefore publishing.