aria2-rust-pro/docs/migration/README.md

# Migration Guide

This guide reflects the current active modernization state from
`GOAL-modern.md` and `progress.md` for `aria2-rust-pro`. It is written for two
existing audiences:

- users running the current `Aria2-Pro-Core` host binary directly
- users running the current `Aria2-Pro-Docker` container shape

The short version is:

- aria2-style config syntax, session files, and RPC clients are intended to
  carry forward
- the native host binary is now `aria2-rust-pro`, not a published
  `aria2-pro-core` drop-in tarball
- the Docker image keeps the legacy env variable names and now maps the current
  Pro Docker knobs through the entrypoint/runtime config path

## Before You Cut Over

Make a copy of the three things that matter before any migration:

1. your current `aria2.conf`
2. your `aria2.session` plus any adjacent `.aria2` control files
3. the exact runtime command or compose file you use today

For Docker users, also record the current bind mounts or named volumes so that
you know where `/config` and `/downloads` live on disk.

## Compatibility Snapshot

| Surface | Current `aria2-rust-pro` status | Migration meaning |
| --- | --- | --- |
| aria2-style config file | compatible target; current parser/runtime covers the common Pro/Core and Docker paths used here | keep your existing config and validate it with `--dry-run` before switching traffic |
| Session and input files | current session persistence is implemented and covered by tests | keep existing session paths; do not delete `aria2.session` during cutover |
| JSON-RPC and XML-RPC | current RPC surface is implemented enough for representative aria2 clients | reuse the same client URLs and tokens after you verify the new port and secret |
| Native packaging | the self-hosted Gitea `v1.0.0` release includes a Windows archive plus checksums, while broader platform archives remain future work | use the release archive where it matches your host, otherwise plan for a local Cargo build or your own packaged artifact |
| Docker env names | the current Pro Docker env set is accepted and mapped by the entrypoint | keep the same env names, then verify the generated runtime config before cutover |

## From `Aria2-Pro-Core`

### What stays the same

- Keep your existing `aria2.conf` format.
- Keep your current `aria2.session`.
- Keep the Pro/Core option deltas that already exist in this rewrite, including
  the relaxed split and retry knobs tracked in the compatibility ledger.

### What changes

| Area | Old Core habit | `aria2-rust-pro` now |
| --- | --- | --- |
| Binary name | usually `aria2c` | native host binary is `aria2-rust-pro` |
| Install flow | download a release tarball and move `aria2c` into place | build with Cargo or deploy your own packaged artifact |
| RPC startup | config plus your old service wrapper | native startup still needs `--enable-rpc` on the command line to enter the long-running RPC server path |
| Backgrounding | old wrappers often daemonized the process | do not rely on `--daemon` as a POSIX fork; supervise the foreground process with systemd, NSSM, Task Scheduler, or another service manager |

### Recommended host cutover

1. Build the new binary without overwriting the old one yet:

   ```powershell
   cargo build --release -p aria2-rust-pro-cli --bin aria2-rust-pro
   ```

2. Stage a new config root and copy your current config/session into it.

3. Validate the config before swapping any service definition:

   ```powershell
   .\target\release\aria2-rust-pro.exe --dry-run --conf-path C:/ProgramData/aria2-rust-pro/aria2.conf
   ```

4. Update your service or launcher to point at the new binary and keep
   `--enable-rpc` on the command line:

   ```powershell
   .\target\release\aria2-rust-pro.exe --conf-path C:/ProgramData/aria2-rust-pro/aria2.conf --enable-rpc
   ```

5. Probe RPC before you disable the old service:

   ```powershell
xh post http://127.0.0.1:6800/jsonrpc jsonrpc=2.0 id=migrate method=aria2.getVersion params:='["token:replace-with-a-strong-rpc-secret"]'
   ```

If your surrounding scripts still hardcode `aria2c`, keep the old binary in
place until you have either updated those scripts or installed your own wrapper
or symlink that points `aria2c` to `aria2-rust-pro`.

## From `Aria2-Pro-Docker`

### What carries forward

- `/config/aria2.conf` remains the base config path.
- `/config/aria2.session` remains the session file path.
- `/downloads` remains the default download root.
- the container still accepts the familiar Pro Docker env variable names

### What is different from the old Docker behavior

| Env or behavior | Old Pro Docker expectation | `aria2-rust-pro` now |
| --- | --- | --- |
| `RPC_SECRET` | old images often rewrote `aria2.conf` in place and could expose compatibility fallbacks | when set, it appends `rpc-secret` and `rpc-listen-all=true` into the generated runtime config; when empty, the entrypoint warns and keeps RPC loopback-only unless your base config overrides it |
| `RPC_PORT` | runtime env + config rewrite | mapped into `/run/aria2-rust-pro/aria2.generated.conf` |
| `LISTEN_PORT` | runtime env + config rewrite | mapped into generated config for both `listen-port` and `dht-listen-port` |
| `DISK_CACHE` | runtime env + config rewrite | mapped into generated config |
| `IPV6_MODE` | runtime env + config rewrite | mapped into generated config as `disable-ipv6=true/false` |
| `UPDATE_TRACKERS` | functional startup/runtime knob | supported by the entrypoint; when enabled it runs the bundled tracker updater against the generated config |
| `CUSTOM_TRACKER_URL` | functional tracker-updater input | supported by the entrypoint as the tracker updater source URL |
| `SPECIAL_MODE` | functional mode hook | supported by the entrypoint for `move` and `rclone`; it copies default scripts and appends `on-download-complete=` to the generated config |
| Config mutation | old image families often rewrote `/config/aria2.conf` directly | this image copies `/config/aria2.conf` only when missing, then writes overrides to `/run/aria2-rust-pro/aria2.generated.conf` |

### Recommended Docker staging flow

1. Stop the old container without deleting the existing `/config` and
   `/downloads` data.

2. Copy `docker/.env.example` to `docker/.env` and set your real values.

3. If your current data lives somewhere other than the compose defaults, adjust
   the volume paths in `docker/docker-compose.yml` before first start.

4. Build and start the replacement container:

   ```powershell
   docker compose --env-file docker/.env -f docker/docker-compose.yml up -d --build
   ```

5. Confirm that the container preserved the base config and generated the
   runtime overlay:

   ```powershell
   docker exec aria2-rust-pro sh -lc "test -f /config/aria2.conf && sed 's/^rpc-secret=.*/rpc-secret=<redacted>/' /run/aria2-rust-pro/aria2.generated.conf"
   ```

6. Probe RPC from the host:

   ```powershell
xh post http://127.0.0.1:6800/jsonrpc jsonrpc=2.0 id=migrate method=aria2.getVersion params:='["token:replace-with-a-strong-rpc-secret"]'
   ```

### Current Docker status

The Docker deployment lane is now materially real:

- `xtask docker smoke-local` verifies entrypoint/config generation without a
  daemon
- `xtask docker smoke` builds the image, starts the container, verifies
  `aria2c --version`, checks the generated runtime config, and probes live
  JSON-RPC
- `xtask docker export-local` can stage a portable image tar under
`dist\docker\` when the daemon is reachable

The matching `scripts/docker/*.ps1` files remain thin compatibility wrappers
for existing local workflows.

The entrypoint now:

- seeds a bundled `bt-tracker=` snapshot when the config leaves it empty
- honors `UPDATE_TRACKERS` and `CUSTOM_TRACKER_URL` through the bundled tracker
  updater
- honors `SPECIAL_MODE=move` and `SPECIAL_MODE=rclone` by materializing the
  matching hook scripts and appending `on-download-complete=...`

That makes the safe migration posture for existing Pro Docker users:

- stage the new image with the same `/config` and `/downloads` data
- inspect `/run/aria2-rust-pro/aria2.generated.conf` after first boot
- probe RPC before switching user traffic

Inside the container, `/usr/local/bin/aria2c` is a symlink to
`/usr/local/bin/aria2-rust-pro`, so tools that `docker exec ... aria2c ...`
still work after the image swap.

## Rollback

Keep rollback boring:

1. stop the new host service or container
2. restore the old binary or old image reference
3. put back the backed-up `aria2.conf` and `aria2.session`
4. start the old deployment shape again

Rollback is much easier if you do not overwrite the old host binary path or
delete the old Docker volumes until the RPC probe and a small real download
both pass on the new deployment.