23 KiB
23 KiB
aria2 Compatibility Ledger
Status values:
planned: required but not implemented.implemented: implementation exists but is not fully verified.verified: behavior is covered by tests or golden evidence.deferred: intentionally delayed with a recorded reason.approved-incompatible: explicitly approved incompatibility.
No row may remain planned for the 1.0 release.
Public Surfaces
| Surface | Target | Status | Evidence |
|---|---|---|---|
| CLI executable | aria2-compatible command behavior | verified | crates/aria2-rust-pro-cli/src/lib.rs now exposes startup profile, command surface, config validation, runtime report models, aria2-shaped --version / --help=#all rendering, and real filtered `--help=<tag |
| CLI options | original aria2 plus current Pro options | verified | normalized option registry in crates/aria2-rust-pro-compat/src/options.rs now exposes registry-backed CLI/config/RPC spelling helpers (cli_spellings, config_spellings, lookup_spellings), help placeholders, help synopsis generation, and a live_option_specs() view of the implemented surface, while crates/aria2-rust-pro-cli/src/lib.rs now directly proves long-form compat alias canonicalization (http-want-digest -> no-want-digest-header), bool/value option parsing, and representative live option preservation through parse_cli() |
| Config file | aria2 config syntax | verified | crates/aria2-rust-pro-compat/src/config.rs now directly covers config AST/document/profile/normalization, BOM handling, long-form and short-form compatibility alias canonicalization, strict unknown-option rejection, and normalized profile loading, while crates/aria2-rust-pro-cli/src/lib.rs proves file-backed config loading plus CLI-over-config precedence for representative runtime/session/transport options |
| JSON-RPC | aria2 JSON-RPC methods and fields | verified | method ledger plus dispatcher/router/handlers/jsonrpc module tree in crates/aria2-rust-pro-rpc/src/ now have direct evidence for batch handling, routed id preservation, invalid-request/invalid-param shaping, success-payload rendering, effective default-plus-inherited option views, upstream-style per-download GID/state errors, transport-visible HTTP/WebSocket behavior, and JSON/XML parity across the covered method surface; crates/aria2-rust-pro-rpc/src/dispatcher.rs now additionally proves a raw JSON-RPC success request can parse, dispatch, and render a transport-visible success payload without leaking an error member |
| XML-RPC | original aria2 XML-RPC compatibility | verified | crates/aria2-rust-pro-rpc/src/xmlrpc.rs now has request/response/value/fault models, shared XML-RPC-to-RPC conversion, deterministic XML rendering helpers, and XML parsers for methodCall/methodResponse/fault; typed scalar parsing now also tolerates whitespace-padded int / i4 / i8 / biginteger / boolean / double / dateTime.iso8601 / base64 tags without regressing the earlier large-integer fallback behavior; crates/aria2-rust-pro-rpc/src/dispatcher.rs now routes ordinary XML-RPC methods through the real in-process dispatcher instead of stub handlers, so XML-RPC tellStatus, getGlobalStat, and other non-multicall methods reuse the same payload semantics as JSON-RPC; top-level XML-RPC faults now use upstream-style faultCode=1 / faultString, XML-RPC system.multicall now emits upstream-style in-band fault structs instead of JSON-style code / message members, crates/aria2-rust-pro-rpc/src/server.rs now recognizes obvious XML-RPC methodCall bodies on normalized /rpc paths even when the client omits a helpful Content-Type and prefixes the payload with a BOM/comment prelude, and crates/aria2-rust-pro-tests/src/lib.rs now proves XML-RPC methodCall parse/render can drive aria2.addMetalink dispatch while still converging on the protocol-layer preferred resource candidate |
| Session files | aria2 session/input conventions | verified | crates/aria2-rust-pro-storage/src/session.rs session file and metadata state shell now has explicit coverage for mixed legacy/v2 session lines, multiple URIs, and escaped metadata while still preserving conservative resume/runtime extension keys via metadata maps; crates/aria2-rust-pro-tests/src/lib.rs now proves JSON-RPC saveSession output is readable by storage session loading, and crates/aria2-rust-pro-core/src/engine.rs now round-trips multi-URI downloads through session save/load without collapsing to one URI |
| Control files | .aria2 resume behavior |
verified | crates/aria2-rust-pro-storage/src/control.rs now auto-detects upstream binary .aria2 files, reads both the legacy v0000 little-endian and v0001 network-order headers, reconstructs verified/in-flight piece state from the upstream bitfields, and writes an upstream-readable binary prefix plus a Rust trailer that preserves richer metadata such as retry counts and last-error state; the same file now carries fixture-backed binary-reader tests plus core session/control recovery coverage |
| HTTP/HTTPS | range, resume, retry, checksum | verified | crates/aria2-rust-pro-protocol/src/http.rs now computes inline-payload checksum verification in completion_model(), carries streamed observed-length/digest truth, models unsatisfied Content-Range responses for 416 Range Not Satisfiable, and preserves clearer resume truth when a server ignores a requested range; crates/aria2-rust-pro-protocol/src/downloader.rs directly covers fixture/downloader-generated streamed responses, request-proxy routing with bypass rules, finer DNS/TLS/proxy failure mapping, fixture/live 416 parsing, live query emission, redirect-origin provenance, and negotiated HTTP version mapping; crates/aria2-rust-pro-cli/src/lib.rs and crates/aria2-rust-pro-tests/src/lib.rs together cover partial-range completion, retry, checksum-aware completion, and connector-backed runtime execution across the current HTTP/HTTPS surface |
| FTP | original aria2 FTP behavior | verified | crates/aria2-rust-pro-protocol/src/ftp.rs FTP model plus fixture-backed downloader support in crates/aria2-rust-pro-protocol/src/downloader.rs, CLI runtime execution wiring in crates/aria2-rust-pro-cli/src/lib.rs, and a local real FTP server smoke in CLI tests that exercises USER/PASS/PASV/RETR over real sockets |
| SFTP | original aria2 SFTP behavior | verified | crates/aria2-rust-pro-protocol/src/sftp.rs SFTP model plus fixture-backed downloader support in crates/aria2-rust-pro-protocol/src/downloader.rs, CLI runtime execution wiring in crates/aria2-rust-pro-cli/src/lib.rs, and a local live SFTP smoke using a Docker loopback server |
| Metalink | Metalink3/4 compatibility | verified | crates/aria2-rust-pro-protocol/src/metalink.rs now has a structured XML parser, preferred-resource selection helpers, and a shared multi-file download-plan surface, separates document-level <identity> from file-level <identity>, preserves CDATA-backed <signature> / <url> payloads, normalizes checksum algorithms/values plus resource location / lang / type / private metadata, ignores piece-level hashes for file verification, and uses richer preferred-resource tie-breaking; crates/aria2-rust-pro-cli/src/lib.rs now resolves both local .meta4 / .metalink files and remote HTTP/HTTPS Metalink documents through that shared plan before downloading every actionable file while injecting implied per-file out / checksum defaults into execution, crates/aria2-rust-pro-rpc/src/dispatcher.rs uses the same plan for aria2.addMetalink and returns one GID per actionable file, crates/aria2-rust-pro-protocol/src/bt_metalink.rs now delegates wrapper parsing to the real parser instead of returning a root-only stub document while preserving that richer normalized model, and crates/aria2-rust-pro-tests/src/lib.rs exercises both JSON-RPC and XML-RPC entrypoints for the same multi-file expansion semantics while CLI tests cover local and remote Metalink document execution |
| BitTorrent | torrent, magnet, DHT, tracker, seeding | verified | crates/aria2-rust-pro-protocol/src/magnet.rs, torrent.rs, tracker.rs, transport.rs, and bt_metalink.rs directly cover magnet parsing/serialization, torrent metadata/info-hash extraction, tracker announce/scrape parsing plus live HTTP tracker transport, UDP tracker codecs, peer-wire codecs, and typed DHT helpers; crates/aria2-rust-pro-rpc/src/dispatcher.rs now directly proves .torrent and magnet registration, tracker announce/scrape ingestion, peer-wire exchange, ping / find_node / get_peers / announce_peer runtime updates, select-file, BT share/seeding visibility, and metadata-only magnet promotion through BEP10/BEP9 ut_metadata negotiation into the same torrent-backed runtime surface used by .torrent bootstrap; crates/aria2-rust-pro-cli/src/lib.rs and crates/aria2-rust-pro-tests/src/lib.rs provide CLI-visible BT status/share snapshots, false-completion/select-file contracts, pressure smokes, mixed magnet/torrent status/getServers coverage, and the dedicated bt_magnet_promotion regression that locks the promotion path at the public surface |
| Docker env | current Pro Docker compatibility | verified | docker/Dockerfile, docker/entrypoint.sh, docker/docker-compose.yml, docker/.env.example, xtask docker smoke, and xtask docker smoke-local now provide a source-building container path with verified daemon-free and daemon-backed smokes; scripts/docker/smoke.ps1 and scripts/docker/smoke-local.ps1 are compatibility wrappers around those Cargo-native commands; the entrypoint now maps the legacy env names (PUID, PGID, UMASK_SET, RPC_SECRET, RPC_PORT, LISTEN_PORT, DISK_CACHE, IPV6_MODE, UPDATE_TRACKERS, CUSTOM_TRACKER_URL, SPECIAL_MODE) into the generated runtime config and bundled hook/tracker behavior, including seeded bt-tracker, tracker updates, and move / rclone completion hooks |
Compatibility relock note: crates/aria2-rust-pro-core/src/engine.rs now rejects invalid pause/unpause state transitions instead of silently accepting them, and crates/aria2-rust-pro-rpc/src/dispatcher.rs now has targeted tests proving upstream-style cannot be paused now / cannot be unpaused now errors for real invalid states as well as missing GIDs.
Compatibility relock note: public JSON-RPC methods that take a GID from param 0 now distinguish missing params from malformed GIDs, returning upstream-style Invalid GID ... application errors for bad hex input instead of collapsing those cases into invalid_params or unknown_method.
Compatibility relock note: the invalid-GID regression matrix now explicitly covers tellStatus, getOption, changeOption, getUris, getFiles, changeUri, changePosition, pause, unpause, remove, and removeDownloadResult, so the shared dispatcher helper change is backed by method-level evidence instead of only a subset of entrypoints.
Compatibility relock note: aria2.changePosition failures now use the upstream waiting-queue-specific wording GID#... not found in the waiting queue. instead of the earlier generic local Could not change position... message.
Compatibility relock note: the BT/tracker/DHT helper entrypoints in dispatcher.rs now follow the same GID semantics as the public RPC layer, using Invalid GID ... for malformed hex and No such download for GID#... when the referenced download does not exist, instead of leaking unknown_method.
Compatibility relock note: aria2.changeUri now matches the upstream mixed-array parsing behavior more closely by silently skipping non-string delUris / addUris entries while still applying delete-then-insert semantics to string members, and it now has explicit coverage for the upstream-style valid-but-missing-GID error Cannot remove URIs from GID#....
Compatibility relock note: across the currently covered per-download and BT helper paths, the repo now distinguishes the upstream-style failure buckets for missing params, malformed GIDs, nonexistent downloads, invalid pause / unpause states, waiting-queue misses, and valid-but-missing changeUri removals instead of collapsing them into generic local dispatcher errors.
Compatibility relock note: the JSON-RPC transport now preserves broader upstream-style request-id shapes, including boolean and structured ids, treats malformed request shapes as synthetic invalid-request / invalid-params dispatches instead of transport parse aborts, and ignores non-object batch members while keeping shared JSON/XML error shaping aligned through model.rs, router.rs, handlers.rs, and jsonrpc.rs.
Compatibility relock note: the XML-RPC surface now accepts a wider set of real-client request forms, including processing instructions, comments, whitespace-tolerant self-closing tags, empty value/container forms, nil, and decimal/hex numeric entities, while preserving shared fault semantics and avoiding lossy large-number truncation on RPC-to-XML rendering.
Compatibility relock note: crates/aria2-rust-pro-core/src/request.rs now normalizes multi-URI request invariants by filtering empty URI entries, de-duplicating/repositioning repeated URIs, and repairing stale primary URI state at RequestGroup::with_context, reducing drift between changeUri, getUris, and session replay paths.
Option Ledger
| Option | Source | Required behavior | Status | Evidence |
|---|---|---|---|---|
dir |
Original | local file output directory option | verified | aria2/src/OptionHandlerFactory.cc (PREF_DIR) |
out |
Original | per-download output filename option | verified | aria2/src/OptionHandlerFactory.cc (PREF_OUT) |
split |
Original | split count option (default 5) |
verified | aria2/src/OptionHandlerFactory.cc (PREF_SPLIT) |
continue |
Original | resume partial download (-c) |
verified | aria2/src/OptionHandlerFactory.cc (PREF_CONTINUE) |
enable-rpc |
Original | enable JSON-RPC/XML-RPC server | verified | aria2/src/OptionHandlerFactory.cc, aria2/src/usage_text.h |
rpc-listen-port |
Original | RPC listen port (default 6800) |
verified | aria2/src/OptionHandlerFactory.cc, aria2/src/usage_text.h |
listen-port |
Original | BT TCP/UDP listen port | implemented | crates/aria2-rust-pro-compat/src/options/mod.rs, crates/aria2-rust-pro-cli/src/lib.rs, docker/entrypoint.sh, xtask docker smoke-local |
dht-listen-port |
Original | DHT UDP listen port | implemented | crates/aria2-rust-pro-compat/src/options/mod.rs, crates/aria2-rust-pro-cli/src/lib.rs, docker/entrypoint.sh, xtask docker smoke-local |
disable-ipv6 |
Original | disable IPv6 sockets and resolution | implemented | crates/aria2-rust-pro-compat/src/options/mod.rs, crates/aria2-rust-pro-cli/src/lib.rs, docker/entrypoint.sh, xtask docker smoke-local |
bt-save-metadata |
Original | save bt metadata during magnet flow | verified | aria2/src/OptionHandlerFactory.cc, aria2/src/usage_text.h |
follow-torrent |
Original | control how torrent/metalink references are followed | verified | aria2/src/OptionHandlerFactory.cc (PREF_FOLLOW_TORRENT) |
metalink-enable-unique-protocol |
Original | enforce unique protocol in metalink handling | verified | aria2/src/OptionHandlerFactory.cc (PREF_METALINK_ENABLE_UNIQUE_PROTOCOL) |
max-connection-per-server |
Pro | no 16-connection cap | implemented | crates/aria2-rust-pro-compat/src/options/mod.rs option registry |
split |
Original | per-download split count participates in HTTP connection budgeting and bounded follow-up range planning | implemented | crates/aria2-rust-pro-compat/src/options/mod.rs plus runtime/task integration in crates/aria2-rust-pro-cli/src/lib.rs |
min-split-size |
Pro | minimum 1K target in later phase behavior |
implemented | crates/aria2-rust-pro-compat/src/options/mod.rs option registry target |
piece-length |
Pro | minimum 1K target in later phase behavior |
implemented | crates/aria2-rust-pro-compat/src/options/mod.rs option registry target |
retry-on-400 |
Pro | retry only when enabled and retry-wait > 0 |
implemented | crates/aria2-rust-pro-compat/src/options/mod.rs option registry target |
retry-on-403 |
Pro | retry only when enabled and retry-wait > 0 |
implemented | crates/aria2-rust-pro-compat/src/options/mod.rs option registry target |
retry-on-406 |
Pro | retry only when enabled and retry-wait > 0 |
implemented | crates/aria2-rust-pro-compat/src/options/mod.rs option registry target |
retry-on-unknown |
Pro | retry only when enabled and retry-wait > 0 |
implemented | crates/aria2-rust-pro-compat/src/options/mod.rs option registry target |
no-want-digest-header |
Pro | canonical option for digest header behavior | implemented | crates/aria2-rust-pro-compat/src/options/mod.rs alias-aware registry |
http-want-digest |
CompatibilityAlias | compatibility alias mapped to no-want-digest-header |
implemented | crates/aria2-rust-pro-compat/src/options/mod.rs alias-aware registry |
Current Coverage
| Area | Status | Evidence |
|---|---|---|
| Core download/task model | implemented | crates/aria2-rust-pro-core/src/engine.rs, request.rs, progress.rs, session.rs, scheduler.rs; current Phase 3 core now carries concrete segment assignments in RequestGroup and scheduler-built byte ranges in schedule_once() |
| HTTP/HTTPS protocol surface | implemented | crates/aria2-rust-pro-protocol/src/http.rs, downloader.rs, transport.rs, auth.rs |
| FTP/SFTP fallback | implemented | crates/aria2-rust-pro-protocol/src/ftp.rs and sftp.rs model shells, plus fixture-backed downloader execution in crates/aria2-rust-pro-protocol/src/downloader.rs and runtime dispatch in crates/aria2-rust-pro-cli/src/lib.rs |
| Magnet parsing | implemented | crates/aria2-rust-pro-protocol/src/magnet.rs now has magnet URI parsing/serialization helpers and tests, while bt_metalink.rs keeps the compatibility wrapper aligned with the shared parser |
| Metalink parser facade | implemented | crates/aria2-rust-pro-protocol/src/metalink.rs now parses file/resource/checksum XML structure and exposes deterministic preferred-resource / first-actionable-candidate helpers, while bt_metalink.rs still provides compatibility bridge helpers |
| Torrent parser facade | implemented | crates/aria2-rust-pro-protocol/src/torrent.rs now parses torrent bencode metadata, derives raw-info SHA1 hashes, materializes file/piece/tracker models, builds tracker request metadata, and carries peer-wire handshake/message parse-serialize helpers; crates/aria2-rust-pro-protocol/src/tracker.rs now parses announce/scrape responses, builds encoded tracker URLs, and carries UDP tracker protocol helpers |
| RPC method ledger | implemented | crates/aria2-rust-pro-rpc/src/methods.rs |
| In-process RPC bridge | implemented | crates/aria2-rust-pro-rpc/src/dispatcher.rs and handlers.rs |
| Storage piece/control skeleton | implemented | crates/aria2-rust-pro-storage/src/model.rs, control.rs, resume.rs, store.rs |
| CLI-to-runtime bridge | implemented | crates/aria2-rust-pro-cli/src/lib.rs runtime/config/report bridge |
Phase 3 HTTP Range/Resume/Retry Notes (In Progress)
| Topic | Current state | Status | Evidence | Next step |
|---|---|---|---|---|
| Range request modeling | Range units/specs and request header surfaces are modeled | implemented | crates/aria2-rust-pro-protocol/src/http.rs (RangeSpec, RangeUnit, HttpRequestModel) |
Bind modeled ranges to runtime piece/progress accounting for active transfers |
| Resume state persistence bridge | Session/control and resume model shells exist, including piece-state serialization surfaces, session metadata extension keys, request-level resume state, and control-file recovery of partial completed-length / retry-count state | implemented | crates/aria2-rust-pro-storage/src/session.rs, crates/aria2-rust-pro-storage/src/control.rs, crates/aria2-rust-pro-storage/src/resume.rs, crates/aria2-rust-pro-core/src/request.rs, crates/aria2-rust-pro-core/src/engine.rs |
Extend from single-partial recovery into live segmented resume flows |
| Retry policy modeling | Retry policy/strategy types exist, runtime config carries retry toggles, aggregate retry counts surface through runtime/RPC state, and richer retry-attempt history is now retained across request/engine/RPC layers | implemented | crates/aria2-rust-pro-protocol/src/http.rs (RetryPolicy, RetryStrategy), crates/aria2-rust-pro-core/src/request.rs, crates/aria2-rust-pro-core/src/runtime.rs, crates/aria2-rust-pro-rpc/src/dispatcher.rs (retryCount, retryAttempts) |
Persist richer retry-attempt history through more real session/control flows without overcommitting the public surface |
| Runtime transfer truth | Successful fixture HTTP transfers already feed length/completion/connection/retry-count state back into engine/RPC, control-file reload recovers partial progress when session metadata omits it, multi-step partial responses advance follow-up Range requests across segments, scheduler/session bridges now carry segment-plan, retry-history, active-segment counts, and concrete per-group segment assignments, split plus checksum-aware completion now constrain follow-up planning, and post-bootstrap core-planned follow-up ranges now run through a real concurrent segment executor rather than a serial CLI loop; inline payload checksum verification is real, storage now exposes observed byte sinks including a file-backed variant with explicit write-failure coverage, connector-returned inline bodies are normalized through the same sink before protocol/CLI/RPC consume it, and a live blocking HTTP connector can fetch local responses into sink-backed streamed results that runtime can complete against, but broader live-transport truth is still incomplete |
implemented | crates/aria2-rust-pro-storage/src/io.rs, crates/aria2-rust-pro-protocol/src/downloader.rs, crates/aria2-rust-pro-protocol/src/http.rs, crates/aria2-rust-pro-core/src/engine.rs, crates/aria2-rust-pro-core/src/request.rs, crates/aria2-rust-pro-core/src/scheduler.rs, crates/aria2-rust-pro-core/src/session.rs, crates/aria2-rust-pro-rpc/src/dispatcher.rs, crates/aria2-rust-pro-cli/src/lib.rs, crates/aria2-rust-pro-tests/src/lib.rs |
Extend beyond scripted fixture success paths into TLS-specific live coverage and deeper segment progress persistence through session/control/RPC |
Binary .aria2 compatibility |
Upstream binary .aria2 headers are auto-detected on read, decoded into current control metadata, and emitted again as the leading prefix when the metadata can be represented safely |
verified | crates/aria2-rust-pro-storage/src/control.rs binary reader/writer plus fixture-backed tests for v0000/v0001 and round-trip recovery |
Compatibility note: this ledger records that HTTP range/resume/retry has strong type/model coverage and partial runtime wiring, but does not yet claim full aria2-equivalent runtime behavior until retry/partial-range/restart-coherence is validated end-to-end.