pyTorrent/TODO.md

# TODO

## Done

- Fixed remote system statistics after the rTorrent service split so CPU/RAM are read from the rTorrent host again.
- Fixed split system service dependencies for `default_download_path` and `list_torrents`, restoring disk/system status calls.
- Fixed split rTorrent package exports so private compatibility helpers, remote caches and post-check state remain visible after refactor.
- Restored remote directory browsing in the split rTorrent system service.
- Split the largest backend files into smaller route modules while keeping existing API behavior.
- Split rTorrent service logic into a package with focused modules and compatibility exports.
- Updated OpenAPI coverage for backend routes, including Planner and Poller endpoints.
- Split Planner and Adaptive Poller into separate Tools tabs.
- Added Download Planner settings:
  - master enable switch,
  - night-only downloads as a separate option,
  - quiet hours,
  - weekday and weekend speed limits,
  - CPU protection,
  - disk protection,
  - auto-resume for planner-paused torrents.
- Added speed presets and Mbit/s sliders while keeping exact B/s fields for rTorrent values.
- Moved disk protection configuration out of Preferences and into Planner.
- Kept worker-side disk-start protection wired to Planner disk settings.
- Added footer Planner shortcut visible only when Planner is enabled.
- Added Adaptive Poller settings:
  - active interval,
  - idle interval,
  - error interval,
  - system stats interval,
  - slow stats interval,
  - heartbeat interval.
- Reduced unnecessary heartbeat emissions.
- Added tick duration tracking for the poller.
- Cleaned stale backup files from the package.
- Normalized Planner and Poller UX to match Smart Queue style.
- Cleaned Planner/Poller CSS and removed redundant UI wrappers.
- Kept the WebSocket live refresh responsive by moving slow poller tasks (torrent stats, Smart Queue, automations and Planner enforce) into a guarded background task.
- Added a regression smoke check for fixed-mode poller metrics while a slow background task is running.
- Set Adaptive Poller startup defaults to the requested fast-live profile: active/torrent loop 0.5s, idle 3s, errors 2s, system stats 1s, queue 5s, heartbeat 5s, slow threshold 10000ms and slowdown multiplier 1.
- Added poller runtime diagnostics for real tick gap, effective interval and configured minimum interval so 0.5s polling can be verified from the UI.

## Planned

### Phase 1 - Stabilization and maintainability

- Split `static/app.js` into smaller frontend modules:
  - `api.js`,
  - `state.js`,
  - `torrents.js`,
  - `modals.js`,
  - `smartQueue.js`,
  - `planner.js`,
  - `poller.js`,
  - `rss.js`,
  - `charts.js`.
- Add request validation for API endpoints instead of repeated manual `request.json` parsing.
- Add typed application exceptions:
  - `RtorrentError`,
  - `RtorrentTimeout`,
  - `ProfileAccessError`,
  - `ValidationError`,
  - `UnsafePathError`,
  - `BackgroundJobError`.
- Reduce broad `except Exception` blocks and map expected errors to clear API responses.
- Add structured logging with request ID, profile ID and operation timing.
- Add endpoint timing metrics for API calls and rTorrent operations.
- Add a deeper healthcheck endpoint covering:
  - database readability/writability,
  - active profile state,
  - rTorrent connection,
  - background queue state,
  - poller state.

### Phase 2 - Tests and safety

- Add unit tests for torrent parsing.
- Add unit tests for Smart Queue decisions.
- Add unit tests for Planner schedule windows.
- Add unit tests for quiet hours.
- Add unit tests for Planner speed limit selection.
- Add unit tests for disk protection and CPU protection.
- Add unit tests for RSS rule matching.
- Add unit tests for ratio rules.
- Add unit tests for profile validation.
- Add auth and permission tests.
- Add path safety tests for move, remove and ZIP download operations.
- Add mocked rTorrent integration tests for Planner pause/resume and speed limit application.
- Add mocked poller tests for adaptive cadence without requiring a live rTorrent instance.
- Add visual regression checks for Tools tabs on narrow screens.
- Add CI checks for Python compile, JS syntax, linting and tests.

### Phase 3 - Planner improvements

- [x] Add named Planner profiles:
  - night mode,
  - weekend mode,
  - low power mode,
  - unlimited mode.
- [x] Keep Planner settings per active rTorrent profile.
- [x] Add Planner preview with the currently matched rule and next scheduled change.
- [x] Add Planner action history:
  - paused torrents,
  - resumed torrents,
  - speed limit changes,
  - CPU protection triggers,
  - disk protection triggers.
- [x] Add dry-run mode for Planner actions.
- [x] Add optional network/load protection rules.
- [x] Add configurable grace period before auto-resume.
- [x] Add manual override timeout, including `disable Planner for 1 hour`.
- [x] Add clearer status badges in the footer and Tools panel.

Implementation notes:
- Frontend settings live in the Planner tab and are stored through `/api/download-planner`.
- Preview/history are exposed through `/api/download-planner/preview`.
- Manual override is exposed through `/api/download-planner/override`.
- Dry-run mode records intended actions without calling rTorrent mutations.

### Phase 4 - Adaptive poller improvements

- [x] Make polling intervals configurable per rTorrent profile.
- [x] Add automatic slowdown when rTorrent responses are slow.
- [x] Add automatic recovery after repeated rTorrent errors.
- [x] Split polling loop configuration by data type:
  - torrent list,
  - system stats,
  - tracker stats,
  - disk stats,
  - queue/job stats.
- [x] Emit WebSocket torrent updates only when data changed, with heartbeat fallback.
- [x] Add per-tick metrics:
  - duration,
  - emitted payload size,
  - rTorrent call count,
  - skipped emissions,
  - current adaptive mode.
- [x] Add a Poller diagnostics panel.
- [x] Add safe fallback mode if adaptive polling is misconfigured.

Implementation notes:
- Frontend settings live in the Poller tab and are stored through `/api/poller/settings`.
- Runtime metrics are included in heartbeat/system stats payloads and shown in Poller diagnostics.
- Fallback mode clamps unsafe intervals during normalization.

### Phase 5 - UX and dashboard

- [x] Add a torrent health dashboard with sections for:
  - torrents without seeders,
  - stopped torrents that should be active,
  - tracker errors,
  - duplicate torrents,
  - slowest torrents,
  - dead torrents,
  - largest torrents,
  - torrents below target ratio.
- [x] Add Smart Views:
  - Needs attention,
  - Large and slow,
  - Seeding too long,
  - New from RSS,
  - No label,
  - Private trackers.
- [x] Add global search across:
  - torrent name,
  - hash,
  - label,
  - tracker,
  - path,
  - ratio group,
  - error status.
- [x] Add a persistent notification center for:
  - rTorrent errors,
  - RSS errors,
  - automation errors,
  - disk warnings,
  - Smart Queue decisions,
  - Planner actions,
  - port status.
- [x] Add a Diagnostics page for profile, rTorrent, poller, database and worker state.

Implementation notes:
- Health and Smart Views are calculated client-side from the live torrent snapshot.
- `Seeding too long` uses rTorrent completion timestamp when available and falls back safely when older rTorrent builds do not expose it.
- Global search uses torrent name, hash, label, tracker domain, path, ratio group and warning/error text.
- App Status now stays application-focused: process, workers, database and cleanup counters.
- Diagnostics owns profile, rTorrent connection, poller, planner, database and worker snapshots to avoid duplicated status cards.

### Phase 6 - RSS and automation

- Add RSS feed preview before saving a rule.
- Add RSS rule testing against the latest feed entries.
- Add RSS dry-run mode.
- Add duplicate detection by info-hash where possible.
- Add RSS rule priorities.
- Add RSS history explaining why an item was accepted or rejected.
- Add cleanup rules:
  - remove completed torrents after target ratio,
  - move completed data to a destination path,
  - remove dead torrents after a configurable time,
  - remove torrents with missing data,
  - stop seeding after a configured upload amount.
- Add import/export for automation rules.

### Phase 7 - File and torrent operations

- Improve the Files view with extension filters.
- Add bulk priority actions by file type, for example `.mkv`, `.srt`, `.nfo`.
- Add folder-level priority actions by path pattern.
- Add safer selected-file download handling for large selections.
- Add missing-file detection.
- Add duplicate torrent detection and merge/cleanup suggestions.

### Phase 8 - Profiles and rTorrent diagnostics

- Add SCGI connection test before saving a profile.
- Add profile diagnostics:
  - rTorrent version,
  - base paths,
  - write permissions,
  - free disk space,
  - response time.
- Add import/export for profiles.
- Show profile status in the profile picker:
  - online,
  - offline,
  - slow,
  - error.
- Add per-profile API and polling limits.

### Phase 9 - Security and API

- Require changing default admin credentials on first login when auth is enabled.
- Add login rate limiting.
- Add optional TOTP/2FA.
- Add stronger CSRF protection for state-changing requests.
- Set secure session flags when running behind HTTPS.
- Add API tokens:
  - read-only token,
  - full-access token,
  - profile-limited token,
  - token revocation,
  - token usage log.
- Generate or validate OpenAPI schemas from backend request/response models.
- Add generated JS API client from OpenAPI.

### Phase 10 - Database, backup and release quality

- Add explicit database migrations with version numbers.
- Add `PRAGMA busy_timeout` configuration.
- Add periodic `VACUUM` or WAL checkpoint maintenance.
- Add indexes for history and frequently filtered data.
- Add retention limits for RSS history, automation history and Planner history.
- Add backup checksums.
- Add backup restore validation.
- Keep release archives free from `.bak`, cache and local debug files.


## Phase 5 implementation status

- [x] Torrent health dashboard in Tools.
- [x] Smart Views filters, including completion-time based `Seeding too long`.
- [x] Global search expanded to hash, label, tracker, path, ratio group and error/status.
- [x] Persistent local notification center.
- [x] Diagnostics tool panel for profile, rTorrent, poller, database and workers.