feat: pos network download — aria2 RPC daemon + queue control (add/torrent/metalink, watch, limits)

Persistent aria2c as a systemd user service (pos-aria2.service, enable --now, linger warning) on localhost:6800 with a generated RPC secret in ~/.config/linux_post_install/download.env (chmod 600, env override). 18 commands: start/stop/status, add/torrent/metalink (auto-start, --tmux live view), list/info/files/peers, pause/resume/remove/purge/move, limit/set, watch (2s live repoll). JSON built via jq -nc --arg, never string interpolation. Deps: aria2 in preinstall PACKAGES, aria2c/jq/curl guards before --help. Docs: POS.md + howto/network.md + indices + Common Tasks row.
2026-08-12 01:55:16 -04:00
parent ac44f972dc
commit c5dd6466ba
9 changed files with 657 additions and 18 deletions
@@ -10,19 +10,19 @@

 <!-- GEN:START docmap -->
 | ## 1. Project Overview | 28–43 |
-| ## 2. Directory Structure | 44–188 |
-| ## 3. Installation Flow | 189–241 |
-| ## 4. The `pos` CLI System | 242–310 |
-| ## 5. Shared Library — `lib/common.sh` | 311–342 |
-| ## 6. Docker Compose / ScaleTail | 343–385 |
-| ## 7. Optional Apps (`apps/`) | 386–415 |
-| ## 8. Entertainment Module | 416–429 |
-| ## 9. Systemd Services | 430–442 |
-| ## 10. Configuration Files | 443–469 |
-| ## 11. Coding Conventions | 470–502 |
-| ## 12. Development Workflow | 503–555 |
-| ## 13. Key File Quick Reference | 556–611 |
-| ## 14. Common Tasks for Agents | 612–639 |
+| ## 2. Directory Structure | 44–189 |
+| ## 3. Installation Flow | 190–242 |
+| ## 4. The `pos` CLI System | 243–312 |
+| ## 5. Shared Library — `lib/common.sh` | 313–344 |
+| ## 6. Docker Compose / ScaleTail | 345–387 |
+| ## 7. Optional Apps (`apps/`) | 388–417 |
+| ## 8. Entertainment Module | 418–431 |
+| ## 9. Systemd Services | 432–444 |
+| ## 10. Configuration Files | 445–471 |
+| ## 11. Coding Conventions | 472–504 |
+| ## 12. Development Workflow | 505–557 |
+| ## 13. Key File Quick Reference | 558–614 |
+| ## 14. Common Tasks for Agents | 615–643 |
 <!-- GEN:END docmap -->

 ## 1. Project Overview
@@ -76,6 +76,7 @@ Linux_post_install/
 │   ├── pos-media-mp3                       # Download audio as MP3 (yt-dlp)
 │   ├── pos-media-mp4                       # Download video as MP4 (smart/interactive format select)
 │   ├── pos-network-checkport               # Check TCP/UDP port reachability (nmap, or bash/nc fallback) + local interface view
+│   ├── pos-network-download                # aria2 RPC daemon + queue control (add/torrent/metalink, watch, limits)
 │   ├── pos-network-hotspot                 # Wi-Fi hotspot via create_ap + wihotspot-gui
 │   ├── pos-network-ip                      # Show interfaces, routes, public IP + location
 │   ├── pos-network-scan                    # Parallel ping sweep of CIDR
@@ -276,6 +277,7 @@ All non-interactive `pos` commands log output to `~/.local/share/linux_post_inst
 | media | mp3 | `pos-media-mp3` | Download audio as MP3 (yt-dlp) |
 | media | mp4 | `pos-media-mp4` | Download video as MP4 (smart/interactive format select) |
 | network | checkport | `pos-network-checkport` | Check TCP/UDP port reachability (nmap, or bash/nc fallback) + local interface view |
+| network | download | `pos-network-download` | aria2 RPC daemon + queue control (add/torrent/metalink, watch, limits) |
 | network | hotspot | `pos-network-hotspot` | Wi-Fi hotspot via create_ap + wihotspot-gui |
 | network | ip | `pos-network-ip` | Show interfaces, routes, public IP + location |
 | network | scan | `pos-network-scan` | Parallel ping sweep of CIDR |
@@ -558,7 +560,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | File | Lines | Purpose |
 |------|-------|---------|
 | `install.sh` | 206 | Main orchestrator — 4 phases with CLI flags, `--feature`, prebuilt arch bins |
-| `preinstall.sh` | 55 | System packages + hotspot deps + yt-dlp + fail2ban |
+| `preinstall.sh` | 73 | System packages + hotspot deps + yt-dlp + fail2ban |
 | `postinstall.sh` | 152 | fail2ban config, PATH, bash completion, systemd (flag-gated) |
 | `lib/common.sh` | 144 | Shared library (log/warn/err/run/spawn, dry-run aware, `load_system_env`) |
 | `lib/flags.sh` | 60 | Feature flag store (set/clear/is_set/value/list/status) |
@@ -570,7 +572,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `bin/flag-clear` | 21 | Unset a flag |
 | `features/autostart.sh` | 14 | Boot-time feature (moved from `bin/`, flag-gated service) |
 <!-- GEN:START filetable -->
-| `bin/pos` | 290 | CLI dispatcher with smart arg matching + logging + category help |
+| `bin/pos` | 291 | CLI dispatcher with smart arg matching + logging + category help |
 | `bin/pos-ai-gemini` | 311 | Chat with Google Gemini (ask, chat, models, sessions) |
 | `bin/pos-communication-matrix-listener` | 565 | Matrix listener: map /command → bash, run them on room messages |
 | `bin/pos-communication-matrix-sender` | 224 | Send messages to a Matrix room via the client-server API (send, test, login) |
@@ -589,6 +591,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `bin/pos-media-mp3` | 80 | Download audio as MP3 (yt-dlp) |
 | `bin/pos-media-mp4` | 126 | Download video as MP4 (smart/interactive format select) |
 | `bin/pos-network-checkport` | 496 | Check TCP/UDP port reachability (nmap, or bash/nc fallback) + local interface view |
+| `bin/pos-network-download` | 558 | aria2 RPC daemon + queue control (add/torrent/metalink, watch, limits) |
 | `bin/pos-network-hotspot` | 93 | Wi-Fi hotspot via create_ap + wihotspot-gui |
 | `bin/pos-network-ip` | 69 | Show interfaces, routes, public IP + location |
 | `bin/pos-network-scan` | 271 | Parallel ping sweep of CIDR |
@@ -603,7 +606,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | `bin/pos-system-firewall` | 291 | Interactive UFW management |
 | `bin/pos-system-health` | 209 | Host health dashboard (disk, RAM, services, backup age, fail2ban, docker); exit 1 if any FAIL |
 | `bin/pos-tree` | 112 | Show the pos CLI command tree: categories, commands, and subcommands |
-| `completions/pos.bash` | 289 | Dynamic bash completion |
+| `completions/pos.bash` | 291 | Dynamic bash completion |
 <!-- GEN:END filetable -->
 | `apps/install.sh` | 171 | App install/uninstall picker/orchestrator |

@@ -629,6 +632,7 @@ Use conventional prefixes: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`
 | Modify Docker health check | Edit `bin/pos-docker-health` |
 | Modify vbox (Docker VM) logic | Edit `bin/pos-docker-vbox` |
 | Modify USB forwarding logic | Edit `bin/pos-share-usb-server` |
+| Modify aria2 download daemon / queue logic | Edit `bin/pos-network-download` |
 | Modify NFS share logic | Edit `bin/pos-share-nfs-server` / `bin/pos-share-nfs-client` |
 | Modify SMB share logic | Edit `bin/pos-share-smb-server` / `bin/pos-share-smb-client` |
 | Modify AI/Gemini logic | Edit `bin/pos-ai-gemini` (config scope `ai` via `pos config ai`; `AI_GEMINI_API_KEY`/`AI_GEMINI_MODEL` in `~/.config/linux_post_install/ai.env`) |
@@ -10,7 +10,7 @@ authoritative one-line reference (every command + flag), see
 | Category | What you can do | Guide |
 |----------|-----------------|-------|
 | `pos ai` | Chat with Google Gemini from CLI or Telegram | [ai](howto/ai.md) |
-| `pos network` | IP info, hotspot, scan, port check | [network](howto/network.md) |
+| `pos network` | IP info, hotspot, scan, port check, aria2 download daemon | [network](howto/network.md) |
 | `pos docker` | Compose services, container dashboards, disposable VMs | [docker](howto/docker.md) |
 | `pos media` | Download audio/video via yt-dlp | [media](howto/media.md) |
 | `pos system` | Backups, firewall, health dashboard | [system](howto/system.md) |
@@ -86,6 +86,7 @@ Precedence: `--model` flag > `AI_GEMINI_MODEL` env > config file > `gemini-2.5-f
 | `pos network checkport <ip:port>` | `bin/pos-network-checkport` | Check if a TCP port is open | None. Uses `/dev/tcp` with a 2s timeout; exit 0/1 via OPEN/CLOSED |
 | `pos network scan <cidr> [--full] [--retries N]` | `bin/pos-network-scan` | Two-phase nmap scan | See below |
 | `pos network hotspot [cmd]` | `bin/pos-network-hotspot` | Wi-Fi hotspot via `create_ap` (CLI) or `wihotspot-gui` (GUI) | Uses the precompiled binaries from `x64_bin/`; see below |
+| `pos network download <cmd>` | `bin/pos-network-download` | aria2 RPC daemon + queue control (add/torrent/metalink, watch, limits) | `aria2c`/`jq`/`curl`; daemon = systemd user service; secret in `~/.config/linux_post_install/download.env`; see below |

 **`pos network scan` in detail:**

@@ -107,6 +108,30 @@ Backed by the precompiled binaries shipped in `x64_bin/` (see [SCRIPTS.md → x6
 | `pos network hotspot stop [<id>]` | Stops the running access point via `create_ap --stop`; `<id>` is an interface name or PID, auto-detected if omitted |
 | `pos network hotspot status` | Runs `create_ap --list-running` |

+**`pos network download` in detail:**
+
+Runs a persistent `aria2c` JSON-RPC daemon (`localhost:6800`) as a **systemd user service** (`pos-aria2.service`, enabled with `systemctl --user enable --now`; prints a linger warning on headless boxes). `start` installs the unit and generates a random `RPC_SECRET` into `~/.config/linux_post_install/download.env` (chmod 600); the secret is also respected as the `RPC_SECRET` env var. Unit flags: `--continue=true --max-connection-per-server=16 --split=16 --seed-time=0 --dir=$HOME/Downloads`.
+
+| Command | Behavior |
+|---------|----------|
+| `pos network download start` / `stop` | Install+enable the systemd user service / stop and remove it |
+| `pos network download status` | Daemon health + global transfer stats (`getGlobalStat`) |
+| `pos network download add <url>...` | Enqueue HTTP/FTP downloads (auto-starts the daemon); options `--dir`, `--out`, `--split`, `--tmux` |
+| `pos network download torrent <file|magnet>...` | Enqueue `.torrent` files (base64 via `addTorrent`) or magnet links; `--seed` keeps seeding (default `--seed-time=0`), `--dir`, `--tmux` |
+| `pos network download metalink <file|url>...` | Enqueue `.metalink` files or URLs; `--tmux` |
+| `pos network download list` | Table of active / waiting / finished downloads (GID, status, %, dl/up speeds, name) |
+| `pos network download info <gid>` | Full `tellStatus` dump (status, progress, speeds, ETA, error) |
+| `pos network download files <gid>` / `peers <gid>` | Files of a download / peers of a torrent |
+| `pos network download pause\|resume [gid\|all]` | Pause/resume one or all (default `all`) |
+| `pos network download remove [gid\|all]` | Remove one or all; `--force` = `forceRemove` (kills immediately) |
+| `pos network download purge` | Clear finished/error history |
+| `pos network download move <gid> <pos>` | Reorder the waiting queue (`changePosition`) |
+| `pos network download limit [gid] <speed>` | Speed limit, global or per-download (`--upload` = upload speed; `0` = unlimited); accepts `2M`/`512K` |
+| `pos network download set <k=v>...` | Set global aria2 options (`--gid <gid>` = per-download) |
+| `pos network download watch [gid]` | Live table, 2 s refresh; with a GID it exits when that download completes |
+
+**`--tmux`:** after enqueueing, `add`/`torrent`/`metalink` open a detached tmux session `dl-<name>` running `watch <gid>` (name from `--out` or the URL basename, sanitized and truncated to 40 chars; `-2` suffix on collision). The session closes itself when the download finishes — attach with `tmux attach -t dl-<name>`.
+
 ### docker

 | Command | File | Purpose | Configuration |
@@ -109,6 +109,53 @@ local firewall — check `sudo pos system firewall` rules and service binds

 ---

+## `pos network download` — aria2 download daemon + queue
+
+Runs a persistent `aria2c` JSON-RPC daemon as a systemd **user** service
+(`pos-aria2.service`, enabled via `systemctl --user enable --now`; a linger
+warning is printed when no session is active, so the daemon survives logout).
+The RPC secret lives in `~/.config/linux_post_install/download.env` (chmod 600).
+Downloads land in `~/Downloads` by default.
+
+```bash
+# enqueue one or many files (auto-starts the daemon if needed)
+pos network download add https://example.com/ubuntu.iso
+pos network download add https://example.com/a.bin https://example.com/b.bin --dir /mnt/hdd/dl
+
+# torrents / magnets — keep seeding with --seed (default: stop at 100%)
+pos network download torrent debian.torrent --seed
+pos network download torrent "magnet:?xt=urn:btih:…"
+
+# watch progress live (Ctrl+C detaches); with a GID it exits when that one finishes
+pos network download watch
+pos network download watch a1b2c3d4e5f60718
+
+# the queue
+pos network download list
+pos network download pause a1b2c3d4e5f60718     # resume / remove work the same
+pos network download remove --force all          # kill everything immediately
+pos network download limit 2M                    # global speed cap (0 = unlimited)
+pos network download move a1b2c3d4e5f60718 0     # jump to the front of the queue
+```
+
+**Recipe:** grab a big ISO in the background and keep an eye on it from a
+terminal:
+
+```bash
+pos network download add https://example.com/ubuntu.iso --tmux
+tmux attach -t dl-ubuntu.iso      # live progress; session closes itself when done
+```
+
+`--tmux` opens a detached `dl-<name>` session running `watch <gid>` (name from
+`--out` or the URL basename, sanitized; `-2` suffix on collision).
+
+**Troubleshooting:** "RPC failed — is the daemon running?" → `pos network
+download status`; if the unit failed, check the journal with
+`journalctl --user -u pos-aria2 -n 50`. Seed/limit knobs live on `add`/`torrent`
+(`--seed`, `--split`) and on `limit`/`set` for the running queue.
+
+---
+
 ## Related

 - Reference tables: [DOC/POS.md → network](../POS.md)