Firelink/TORRENT_FEATURES.md

# Firelink Torrent feature matrix

This is the current product-facing comparison for BitTorrent features exposed
by Firelink's bundled Aria2 engine. It intentionally excludes Aria2's generic
HTTP/FTP/Metalink options, shell hooks, and daemon-admin RPC methods that do not
belong in the download UI. The Aria2 reference is the [1.37.0 manual](https://aria2.github.io/manual/en/html/aria2c.html).

## Implemented

- Local `.torrent` files, magnet links, and remote HTTP(S) `.torrent` metadata.
  Remote metadata is bounded, SSRF-checked, redirect-checked, parsed, and
  cached before it enters the normal `addTorrent` path.
- Bencode validation, canonical info-hash checks, safe output paths, managed
  metadata retention, selected-file preview, `select-file`, and `index-out`.
- Firelink queue admission, per-queue/global permits, pause/resume, cancel,
  retry/GID replacement, restart recovery, terminal reconciliation, and
  output ownership for Torrent lifecycles.
- Optional seeding by time and/or ratio, upload progress, upload limits,
  seeders telemetry, per-Torrent maximum peers, and the Aria2
  `bt-request-peer-speed-limit` threshold.
- Bounded, read-only Torrent peer diagnostics through `aria2.getPeers`.
  Firelink discards peer IPs, ports, IDs, and bitfields at the native boundary;
  the selected-Torrent detail view exposes only operational speeds, seeder,
  and choking flags, with a bounded display count.
- Global DHT, IPv6 DHT, PEX, and Local Peer Discovery toggles.
- Configurable TCP and UDP listen-port ranges, external BitTorrent IP,
  IPv4/IPv6 DHT entry points, IPv6 DHT listen address, and LPD interface.
  Values are validated, persisted, applied at Aria2 startup, and accompanied
  by platform and firewall/port-forwarding warnings.
- Optional peer-ID prefix and BitTorrent peer-agent controls. Values are
  bounded and validated, remain disabled by default, and include explicit
  privacy, protocol-identity, and compatibility warnings.
- Optional piece-integrity verification, including the explicit policy that
  disables unverified seeding when verification is requested.
- Optional stall timeout through `bt-stop-timeout`, persisted with each
  Torrent and re-applied when it starts or retries. A value of zero disables
  the policy; Aria2 stops the Torrent after the configured consecutive
  zero-download-speed interval.
- Additional per-Torrent tracker URLs through `bt-tracker`, with bounded and
  credential-free HTTP/HTTPS/UDP validation.
- Per-Torrent tracker exclusion through `bt-exclude-tracker`, including Aria2's
  explicit `*` value for excluding all announce URLs. Exclusions are persisted,
  normalized, reapplied on retries, and do not change DHT or PEX settings.
- Optional `bt-prioritize-piece` preview policy for the head, tail, or both
  ends of every selected file. The constrained policy is validated, persisted,
  normalized, and reapplied when a Torrent starts or retries.
- One validated Torrent encryption policy mapped to Aria2's
  `bt-force-encryption`, `bt-require-crypto`, and `bt-min-crypto-level`:
  disabled, required obfuscated handshake, or forced ARC4 payload encryption.
  The policy is persisted and reapplied when a Torrent starts or retries.
- Optional tracker timing controls through `bt-tracker-connect-timeout`,
  `bt-tracker-timeout`, and `bt-tracker-interval`. Connect and request
  timeouts are bounded to 1–604800 seconds; interval 0 restores Aria2's
  response/progress-driven scheduling. Timing is persisted and reapplied when
  a Torrent starts or retries.
- Generic Aria2 downloads explicitly disable `follow-torrent` and
  `follow-metalink`, so a URL that happens to return Torrent or Metalink
  metadata cannot create an unmanaged child GID. Generic follow behavior is
  not exposed until parent/child GID ownership is represented across queue
  admission, progress, cancellation, retry, and restart recovery.
- Global `bt-max-open-files` control for multi-file Torrents, bounded to
  1–4096 with Aria2's default of 100. The setting is persisted, applied at
  daemon startup, and updateable through Aria2's global-option RPC; changes
  affect newly added Torrents without restarting Aria2.
- Optional `bt-remove-unselected-file` cleanup after completion when a
  selected-file subset is configured. Firelink requires explicit confirmation,
  reserves the unselected paths against competing downloads, keeps those
  paths separate from removable download ownership, and clears the reservation
  after observing Aria2's completion cleanup (or on terminal failure,
  cancellation, or reconfiguration).
- Deterministic local Aria2 smoke coverage for metadata resolution, selected
  output, piece priority, encryption policy, tracker timing, pause/resume,
  ownership, cancellation/removal, unavailable trackers, daemon failure, and
  `bt-stop-timeout` terminal behavior; RPC-boundary coverage is separate.

## Priority tiers for remaining work

### Tier 0 — reliability and user-visible control

No remaining Tier 0 items.

### Tier 1 — transfer policy and storage behavior

No remaining Tier 1 items.

### Tier 2 — advanced networking and daemon tuning

1. Aria2 `follow-torrent`/in-memory follow behavior for generic downloads only
   if the resulting child-GID ownership model can be represented safely; the
   current explicit metadata path intentionally avoids unmapped child jobs.
   Generic `addUri` now forces both follow options to `false` as the safe
   default; the child-GID feature remains pending until the end-to-end
   ownership model is implemented.

The first implementation in this task was remote `.torrent` metadata intake;
follow-up implementations add stall-timeout control, bounded peer diagnostics,
persisted tracker exclusion, piece-preview priority, safe unselected-file
removal, the validated encryption policy, tracker timing controls, the global
Torrent open-file limit, launch-scoped Torrent network binding controls, and
peer identity/agent controls.