docs(download): document MediaDownloader and the MediaConnection → MediaRoute breaking change - #469
Conversation
…nnection breaking change whatsapp-rust#1194 replaced wacore::download::MediaConnection with MediaRoute (auth is now optional) and added MediaDownloader, a session-less downloader for callers with no connected Client. Document the new types and API on api/download.mdx, and add a guide section on guides/media-handling.mdx showing how to download persisted media references after disconnecting.
Cross-reference the new MediaDownloader from whatsapp-rust#1194 in the media-handling guide, for readers who want to download persisted CDN references after the client has disconnected.
📝 WalkthroughWalkthroughThe documentation adds session-independent media downloading through ChangesOffline media download
Estimated code review effort: 3 (Moderate) | ~20 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
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. Comment |
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@api/download.mdx`:
- Around line 380-382: Update the breaking-change warning to direct removed
MediaConnection callers to construct a MediaRoute with
MediaRoute::authenticated(hosts, auth). Mention MediaRoute::from(&media_conn)
only for callers that still have a client-side MediaConn, and preserve the note
that Client::download APIs are unaffected.
- Around line 81-84: Update the Note in the download documentation to replace
the inconsistent prepare_requests reference with the documented
DownloadUtils::prepare_download_requests symbol, preserving the existing
explanation about static_url media and media-conn requests.
- Around line 323-337: Update the MediaDownloadError documentation table to
describe Other as an unspecified or future error category rather than narrowly
tying it to missing URL fields, and remove the duplicated “no host was
contacted” wording. Clarify that #[non_exhaustive] requires consumers to include
a wildcard match arm when matching MediaDownloadError.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 1ea25792-3404-4443-b753-e3d2bb176abd
📒 Files selected for processing (2)
api/download.mdxguides/media-handling.mdx
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 97840b4ec3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
- Qualify "download needs a connected Client" — static_url media is the documented exception, and the top Tip contradicted the note below it. - Stop implying the client re-fetches CDN hosts on every download; it's cached and refreshed automatically per the existing retry docs. - Don't attribute DownloadParams persistence to PersistenceManager, which only covers device/session state. - Distinguish a stale MediaRoute auth token (401/403, recoverable via without_auth()) from a genuinely expired reference (404/410, terminal) in the MediaDownloadError table, and note the #[non_exhaustive] wildcard requirement. - Fix the MediaConnection migration guidance: MediaRoute::from(&media_conn) converts mediaconn::MediaConn (the server response type), not the removed MediaConnection struct — point removed-type callers at MediaRoute::authenticated(hosts, auth) instead. Addresses review comments from coderabbitai and chatgpt-codex-connector on PR #469.
…atic_url media The "Downloading without an active session" note categorically said client.download() needs a connected Client, contradicting the static_url exception documented on the download API page. Cross-reference it here too. Addresses a chatgpt-codex-connector review comment on PR #469.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4e70c7ca5c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…e into the guide The API reference already distinguishes a stale MediaRoute auth token (401/403, recoverable via without_auth()) from a genuinely expired reference (404/410, terminal), but this guide's Note still called every rejection "expired or revoked." Bring it in line. Addresses a chatgpt-codex-connector review comment on PR #469.
1 participant
Summary
Documents oxidezap/whatsapp-rust#1194, which:
wacore::download::MediaConnection(requiredauth: String) withMediaRoute(auth: Option<String>), plus a newMediaHost::newandDEFAULT_MEDIA_HOSTS— a breaking change for any caller usingDownloadUtils::prepare_download_requestsdirectly.MediaDownloader, a session-less counterpart toClient::download/download_to_writerthat needs only anHttpClient+Runtime, for downloading persisted media references after the client has disconnected.MediaDownloadError(ReferenceRejected/HostsUnreachable/NoHosts/Other) for the new session-less path, classifying failures a caller with no session to refresh can't recover from the same wayClient::downloaddoes.Client::prepare_requestsskip the media-conn IQ entirely forstatic_urldownloads (newsletter/channel media), since that IQ's answer was previously discarded unread.Changes
api/download.mdx— added## MediaDownloader(withMediaDownloadErrorandMediaRoute/MediaHostsubsections), updated theDownloadUtilstable entry forprepare_download_requeststo reflect theMediaRouteparameter, added a note on thestatic_urlIQ skip, and cross-linkedMediaDownloaderfrom the top ofdownload.guides/media-handling.mdx— added a "Downloading without an active session" subsection under Downloading Media, with aMediaDownloaderexample, and cross-referenced it from the existing retry/failover note.No changelog entry was added, per the note that changelog entries are human-authored.
Test plan
mint dev/mint broken-links) — not run in this environment; please verify locally or via CI if configured.#mediadownloader,#mediadownloaderror,#mediaroute-and-mediahost) against the links referencing them.whatsapp-rust-docsmain content changes for the actual public API surface (public struct/enum/fn signatures) added or changed in whatsapp-rust#1194.Generated by Claude Code
Summary by cubic
Adds
MediaDownloaderfor session-less media downloads and documents the breaking change replacingwacore::download::MediaConnectionwithMediaRoute. Also clarifies thestatic_urlexception, credential/host caching, and distinguishes stale auth (401/403) vs expired references (404/410) in both API and guide.New Features
api/download.mdx: addsMediaDownloader(download/download_to_writer) andMediaDownloadError(#[non_exhaustive], clear 401/403 vs 404/410); documentsMediaRoute/MediaHost/DEFAULT_MEDIA_HOSTS; updatesDownloadUtils::prepare_download_requests(route); notesstatic_urldownloads skip the media‑conn round trip and that host/token data is cached.guides/media-handling.mdx: adds “Downloading without an active session” with aMediaDownloaderexample; clarifies it can’t refresh credentials and that apps must persist CDN fields; explicitly calls out thestatic_urlexception; aligns error guidance with API docs (retry once withroute.without_auth()on 401/403; treat 404/410 as terminal).Migration
MediaConnectionwithMediaRouteif you callDownloadUtils::prepare_download_requests.MediaRoute::authenticated(hosts, auth)orMediaRoute::unauthenticated(hosts);authis nowOption<String>.MediaRoute::from(&mediaconn)converts the server’smediaconn::MediaConnresponse, not the removedMediaConnection.Written for commit 98807de. Summary will update on new commits.
Summary by CodeRabbit
New Features
MediaDownloaderfor downloading and decrypting media without an active client session.Documentation