Episode and Torrent timestamps reflect publish date of provider

[Zzackllack]

Description

This pull request introduces release-aware timestamps throughout the system, ensuring that episode and torrent timestamps (such as pubDate and added_on) reflect the actual provider publish time when available, rather than the time of the request. This improves the accuracy and reliability of metadata for both users and downstream consumers (like Sonarr/Prowlarr). The changes also refactor and centralize logic for handling release dates, and propagate this information through the API and database layers. Closes #7.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

Testing

• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Screenshots (if applicable)

Additional Notes

Release-aware timestamp handling:

• Added logic to extract and propagate release timestamps from provider metadata, using the actual publish time where available instead of the request time. This affects AniWorld, s.to, and related endpoints, and is now reflected in the README documentation. [1] [2] [3]
• Introduced utility functions (_to_utc_timestamp, release_at_from_extra, etc.) to standardize conversion and retrieval of UTC timestamps across the codebase. [1] [2] [3] [4]

API and data model updates:

• Updated /qbittorrent/sync and /qbittorrent/torrents endpoints to store and return release-aware timestamps for added_on and completion_on fields, ensuring clients receive accurate publish dates. [1] [2] [3] [4] [5]
• Refactored Torznab API endpoints to emit correct pubDate values in RSS feeds, using release-aware timestamps when available, and to store this information in the availability cache. [1] [2] [3] [4] [5] [6] [7] [8]

Internal logic and utilities:

• Centralized and improved merging of extra metadata with release timestamps for both direct and mapped (special) episode probes, ensuring consistency and reducing code duplication. [1] [2] [3] [4] [5] [6] [7] [8] [9]

Overall, these changes make the system's handling of release times more robust and accurate, benefiting both API consumers and end users.

Summary by CodeRabbit

• New Features

  • RSS pubDate and torrent added_on now use provider release timestamps (UTC-normalized), showing actual release moments.
  • Improved extraction and propagation of release dates from provider HTML/metadata (including STO v2) and availability caches, with sensible fallbacks when only completion times exist.

• Tests

  • Added unit and integration tests covering parsing, caching, and end-to-end propagation of release timestamps into torrent adds and RSS pubDate.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Extracts and normalizes provider release timestamps (release_at) from HTML/text, persists them in availability/client-task metadata, and propagates UTC release_at as Torznab RSS pubDate and qBittorrent added_on/completion_on across probe, Torznab, and qBittorrent flows.

Changes

Cohort / File(s)	Summary
Release date parsing core app/utils/release_dates.py	New module: parsing/normalizing release datetimes from text and HTML, ISO helpers, and functions to read/write release_at into extra and probe-info structures.
Provider extraction & enrichment app/providers/sto/v2.py	Parse provider HTML to set episode._anibridge_release_at and _anibridge_sto_v2_html; enrich episode provider/language fields and persist parsed release timestamp.
Probe quality integration app/utils/probe_quality.py	New helper to extract/cached release_at from Episode HTML; augment probe-info per-provider and on success with release_at.
Torznab pubDate propagation app/api/torznab/api.py, app/api/torznab/__init__.py	Introduce ProbeResult, helpers to resolve/merge release_at, propagate release_at into item pubDate and availability upserts; export RELEASE_AT_EXTRA_KEY.
qBittorrent timestamp handling app/api/qbittorrent/utils.py, app/api/qbittorrent/sync.py, app/api/qbittorrent/torrents.py	New _to_utc_timestamp; use cached release_at for added_on/completion_on; pass added_on into DB upsert and return UTC timestamps in API responses.
DB model change app/db/models.py	upsert_client_task(...) gains optional added_on: Optional[datetime] and applies UTC-normalized added_on on insert/update.
Provider HTML helper (docs) .github/README.md	Note mentioning release-aware timestamps added.
Tests tests/test_models.py, tests/test_qbittorrent_torrents.py, tests/test_release_dates.py, tests/test_sto_v2.py, tests/test_torznab.py	New/updated tests for parsing, HTML extraction, round-trip metadata, qBittorrent added_on from cached release_at, and Torznab pubDate derivation.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant Provider as Provider (AniWorld / S.to)
    participant Probe as ProbeQuality
    participant Cache as AvailabilityCache
    participant Torznab as TorznabAPI
    participant QB as qBittorrentSync
    participant DB as Database

    Provider->>Probe: Episode HTML (cached on Episode)
    Probe->>Probe: parse_release_at_from_html(html) -> release_at (UTC)
    Probe->>Cache: upsert_availability(extra={"release_at": ISO8601})
    Torznab->>Cache: fetch availability(extra)
    Torznab->>Torznab: resolve pubDate = release_at or now
    Torznab->>Client: emit RSS item with pubDate
    Client->>Torznab: request add (magnet)
    Torznab->>Cache: fetch availability(extra)
    Torznab->>DB: upsert_client_task(..., added_on=release_at)
    DB->>QB: task payload with added_on/completion_on (UTC)
    QB->>QB: store task timestamps

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• S.to v2 migration and provider extraction #42 — overlaps provider parsing/enrichment for S.to v2 (app/providers/sto/v2.py).
• Mapping of AniWorld Specials/Extras/"Filme" to Sonarr #56 — touches Torznab mapped-special probe and pubDate/metadata propagation (app/api/torznab/api.py).
• Add s.to catalogue support alongside AniWorld for dual-site content brokering #8 — modifies qBittorrent/Torznab flows and DB upsert_client_task signature related to added_on.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Episode and Torrent timestamps reflect publish date of provider' accurately summarizes the main change: implementing release-aware timestamps that use provider publish times instead of request times for both episodes and torrents.
Description check	✅ Passed	The PR description is comprehensive, covering the feature overview, type of change, testing checklist completion, and detailed notes on release-aware timestamp handling, API updates, and utility functions. All required template sections are addressed with substantive content.
Linked Issues check	✅ Passed	The PR successfully addresses all major coding objectives from issue #7: parsing and normalizing release timestamps from AniWorld HTML, persisting them in EpisodeAvailability.extra, emitting release-aware pubDate in Torznab feeds, updating qBittorrent added_on/completion_on fields, and implementing comprehensive tests for HTML parsing, integration, and API endpoints.
Out of Scope Changes check	✅ Passed	All code changes are directly aligned with the objective of implementing release-aware timestamps. Modifications to utilities, API endpoints, database models, and tests are all necessary to support the new release-date feature without introducing unrelated functionality.
Docstring Coverage	✅ Passed	Docstring coverage is 86.96% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch zzackllack-aux/real-release-ages

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Note

Docstrings generation - SUCCESS
Generated docstrings and committed to branch zzackllack-aux/real-release-ages (commit: ea425e73e73961558059de66671b242d79924f97)