104 lines
23 KiB
Markdown
104 lines
23 KiB
Markdown
# 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|keyword>` output while `docs/compatibility/goldens/cli/` captures the current release-binary output for both `--version` and `--help=#all`; `crates/aria2-rust-pro-compat/src/help.rs` has direct tests for the aria2-style version banner, full help, and filtered help |
|
|
| 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.
|