Public API & Extension Contracts
This page summarizes public contracts in io.anabranch, hard rules for custom extensions, and key semantic differences when opting into io.anabranch.aria2.Aria2Downloader.
Public Core Contracts (io.anabranch)
| Type | Key Members | Contract Guarantee |
|---|---|---|
Downloader | download(Request, SourceSet, Listener, Cancellation)download(Request, String url, Listener, Cancellation)probeAll(String key, SourceSet, Cancellation) | Thread-safe reusable coordinator; resets per-source runtime disable flags on every download() |
Request | key, target, integrity, chunks, allowResume, Request.of(...) | chunks <= 0 falls back to builder default; Request.of omits digests and sets allowResume=true |
Result | totalBytes, etag, chunkVerified, transferredBytes | etag defaults to "" (never null); transferredBytes distinguishes resumed vs full downloads |
Source | id, weight (>=1), maxChunks, enabled, Resolver | Callers guarantee mirrors serve identical bytes; note maxChunks is currently metadata only |
SourceSet | SourceSet(List<Source>, Policy) / SourceSet.single(url) | Defaults to Policy.fastestFirst(); holds EMA and failure Stats |
Integrity | chunkSize, chunkHashes[], wholeSha256, wholeOnly(...) | Lowercase hex SHA-256 strings; when chunkHashes exist, downloader unit size aligns to chunkSize |
ProbeReport | ok, failed, sizesAgree, size, etagsAgree, anyUsable() | etagsAgree == false is advisory and does not block cross-source resume |
Listener | onTotal, onProgress, onSpeed(double bytesPerSec), onChunkDone, onChunkVerifyFailed, onSourceSwitch | Default methods are no-op (Listener.NONE); speed is strictly bytes/sec |
Cancellation | boolean isCancelled() / Cancellation.NONE | Polled across reads, rate limiting, and 50ms backoff loops |
Extension Contracts: Engine, Policy, Source.Resolver
- Custom
Engine(e.g., OkHttp): Implementprobe(url, cancel)(HEADwithGET Range: bytes=0-0fallback) andfetchRange(url, start, endInclusive, out, listener, cancel). Must reject HTTP200whenstart > 0, throw if written byte count differs fromendInclusive - start + 1, pollCancellation, and obeytools/check-core-boundaries.py(noandroid.*, zero third-party deps insidesrc/io/anabranch/, no dependency onDownloader/SourceSet/Policy/Stats/ResumeState). - Custom
Source.Resolver: Provide dynamic URL resolution for mirrors with differing paths, pre-signed URLs, or expiring CDN tokens viaurlFor(key). - Custom
Policy: ReadStats(emaBytesPerSec,consecutiveFailures,inFlight,lastSuccessAtMillis,isDisabled) and returnSourcefrompick(...)plusDecision(RETRY_SAME,SWITCH_SOURCE,DISABLE_SOURCE,ABORT) fromonFailure(...).
Aria2Downloader Behavioral Differences
Aria2Downloader shares Request, SourceSet, Listener, Cancellation, and Result, allowing drop-in backend switching at the call site, but enforces three different internals:
- Internal routing by
libaria2: All available URLs are resolved viaurlFor(key)and passed together toaddUri. CorePolicy,Stats, andSource.weightdo not participate; onlyRequest.chunks > 0maps to aria2split. - Process-wide serialization: Calls synchronize on
BUSYand drivelibaria2via single-threadedrunOncepolling (with 200ms callback throttling and a 10s shutdown drain budget). - Post-download verification: Integrity checks run after
.a2partcompletes. Verification failures delete both.a2partand.a2part.aria2, whereas network errors keep them for resumption.
Extension FAQ
- Why is
Cancellationpolled instead of usingThread.interrupt()? Interrupts linger on caller worker threads and break unrelated downstream I/O after cancellation. - Why isn't
Source.maxChunksenforced yet? The field exists for API completeness and future per-source caps; today concurrency is bounded globally byBuilder.maxConcurrentand balanced via1.0 + inFlightinPolicy.fastestFirst().