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

• Add named Planner profiles:
  • night mode,
  • weekend mode,
  • low power mode,
  • unlimited mode.
• Keep Planner settings per active rTorrent profile.
• Add Planner preview with the currently matched rule and next scheduled change.
• Add Planner action history:
  • paused torrents,
  • resumed torrents,
  • speed limit changes,
  • CPU protection triggers,
  • disk protection triggers.
• Add dry-run mode for Planner actions.
• Add optional network/load protection rules.
• Add configurable grace period before auto-resume.
• Add manual override timeout, including disable Planner for 1 hour.
• 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

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

• 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.
• Add Smart Views:
  • Needs attention,
  • Large and slow,
  • Seeding too long,
  • New from RSS,
  • No label,
  • Private trackers.
• Add global search across:
  • torrent name,
  • hash,
  • label,
  • tracker,
  • path,
  • ratio group,
  • error status.
• Add a persistent notification center for:
  • rTorrent errors,
  • RSS errors,
  • automation errors,
  • disk warnings,
  • Smart Queue decisions,
  • Planner actions,
  • port status.
• 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

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