Scheduling, Resume & Integrity Mechanisms
This page explains the concrete scheduling formulas, retry budget boundaries, .meta v2 persistence protocol, commit sequence, and aria2 dead-man's switch.
Mirror Selection & Failover Guardrails
- Source Scoring:
Policy.fastestFirst()computes(ema > 0 ? ema : s.weight * 1024L * 1024L) / (1.0 + inFlight), updating EMA after each chunk via0.3 * bps + 0.7 * prevEma.Policy.weighted()performs atomic weighted round-robin usingSource.weight.
- Failure Decisions & Retry Budget:
- Default failure logic:
consecutiveFailures >= 3->DISABLE_SOURCE;attempt <= 1->RETRY_SAME; else ->SWITCH_SOURCE. Runtime disable flags reset at the start of everydownload()call. Downloaderbounds each chunk toMAX_ATTEMPTS_PER_CHUNK = 6, exponential backoffmin(2000, 200 << min(attempt - 1, 16))ms (pollingCancellationevery50ms), andchunkRetryBudgetMs(default60_000ms) counting only failure time and backoff so healthy slow mirrors are never prematurely aborted.
- Default failure logic:
Resumable State (.meta v2) & Commit Order
When allowResume == true and probe.rangeSupported == true, ResumeState writes <target>.part alongside <target>.meta using header anabranch-meta/2 (total, etag, source, unit, count, state of 'P'/'D'/'V'). State updates persist via .meta.tmp + fsync -> renameTo -> directory sync marker .anabranch-dsync.
| Check | Same-Source Resume | Cross-Source Failover Resume |
|---|---|---|
total & unit | Must match | Must match |
ETag | Compared when probeSourceId == meta.source; mismatch discards .part/.meta | Skipped (mirrors emit independent ETags); relies on Integrity digests |
Commit sequence inside Downloader.commit(...):
ch.force(true)flushes.partpages to storage.- Verify
ResumeState.isComplete(). - If
wholeSha256is configured, hash the full.partfile and abort before renaming on mismatch. - Execute
target.delete(),part.renameTo(target),ResumeState.syncDir(...),st.discard(), andlistener.onProgress(total, total). Note thatdelete()+renameTo()is not atomic across arbitrary filesystems if renaming fails.
Out-of-Process aria2 Dead-Man's Switch
Because native SIGSEGV/SIGABRT crashes terminate the JVM without giving Java catch blocks a chance to run, FileBackendSelector persists two files in stateDir:
arm(backend)writes andfsyncsaria2.armedbefore calling native code.disarm()removesaria2.armedonly after cleansessionShutdowncompletes withinDRAIN_BUDGET_MS = 10_000.- On next startup, if
aria2.armedstill exists,current()persists the opposite backend (aria2-openssl<->aria2-gnutls) toaria2.backendfirst and then clearsaria2.armed, ensuring idempotency even across repeated crashes.