# Quality gates — soundcloud provider

Criteria an implementation of `soundclouddy`
(architecture/soundcloud-provider.md) must satisfy. Each is pass/fail by
reading/reasoning; automated coverage lives in `soundclouddy/src/tests.rs`
(unit, no network, over a `FakeSc`) and `soundclouddy/tests/live.rs` (ignored,
real SoundCloud).

**Status (2026-07-24):** G1, G3–G6, G10–G13, G15–G18, G20–G23 are
implemented and verified offline (unit tests + fmt/clippy/machete). G7/G8/G9
(scrape + re-auth + persist) are implemented; their **live** behaviour and
G14/G19 (real resolve/playlist + mp3-HLS play-to-EOS) are confirmed only by
`tests/live.rs` and a manual play-through on a machine with creds/audio. G6's
per-call timeouts are enforced; a whole-HLS-fetch deadline is deferred (the
reqwest client's per-segment timeout bounds each fetch).

## Secrets (hard rule — highest priority)

- [ ] **G1 — `client_id`/`oauth_token` never in `Debug`.** `Settings`, `Client`,
  and `ScApi` `Debug` output redact both. *(test:
  `settings_debug_redacts_secrets`.)*
- [ ] **G2 — The signed media URL never reaches a log or error.** The `.m3u8`
  URL from `Sc::resolve_stream_url` (and the segment URLs in `HlsStream`) are
  never passed to `debug!`/`warn!`/`error!`. Segment fetch errors carry status
  only (use `reqwest::Error::without_url()` like `windowed_http.rs`).
- [ ] **G3 — `ScApi::Debug` redacts `client_id` and `oauth_token`** (manual
  impl, not derived).

## Errors and robustness (hard rule: no panics on input/network)

- [ ] **G4 — No panics on bad input or network failures.** Backend failures map
  to a typed `ProviderError` (`FetchError` for fetches, `MalformedPath` for bad
  paths, `InvalidInput` for empty titles/URLs). No `unwrap`/`expect`/`panic!` on
  request, path, or response data. *(tests: `backend_failures_are_typed`,
  `foreign_and_malformed_paths_reject`.)*
- [ ] **G5 — Defensive decoding.** Wire DTOs use `#[serde(default)]`; missing
  fields degrade (empty string / `None` / dropped entry), never error the whole
  call. Tracks/playlists without an id are dropped, not panicked on.
- [ ] **G6 — Timeouts on every external call.** `ScApi` sets a per-call
  `reqwest` timeout from `call_timeout_secs` (default 30); `HlsStream` bounds
  the whole fetch by `hls_deadline_secs` (default 300).

## Auth: client_id self-heal, optional login (D5)

- [ ] **G7 — Works with no config.** With an empty `soundcloud.toml`, init
  scrapes a `client_id` and the provider serves public browse/play; a total
  scrape failure disables the provider **non-fatally** (never crashes startup).
- [ ] **G8 — Re-scrape on 401.** A `401/403` triggers exactly **one** re-scrape
  and retry; a second failure surfaces as `FetchError::Unauthorized` (no
  infinite loop). *(test: `reauth_rescrapes_once_then_gives_up`.)*
- [ ] **G9 — Scraped `client_id` is persisted.** `settings()` folds the cached
  `client_id`/`app_version` back into the TOML so the next start does not
  re-scrape. *(test: `settings_round_trip_persists_scraped_id`.)*
- [ ] **G10 — Login is optional and gates only personal nodes.** No
  `oauth_token` → `get_lib_root` children are `search` + `resolve` only; a token
  → `likes` + `playlists` also appear. Public browse/play is identical either
  way. *(tests: `root_without_login_has_no_personal_nodes`,
  `root_with_login_shows_personal_nodes`.)*

## Tree and path contract

- [ ] **G11 — Path parsing is total and tag-safe.** Every `/soundcloud/...`
  shape maps to a variant or `MalformedPath`; the literals
  `search`/`resolve`/`likes`/`playlists`/`track`/`playlist` never collide with a
  numeric id. Empty segments (`/soundcloud//x`) are `MalformedPath`. *(tests:
  the `*_parse` / `*_reject` cases.)*
- [ ] **G12 — Canonical leaves.** Every track child points at
  `/soundcloud/track/<id>` and every playlist child at
  `/soundcloud/playlist/<id>`, so a track id alone resolves a stream (no browse
  context needed). *(test: `search_children_use_canonical_paths`.)*
- [ ] **G13 — Search lists tracks *and* playlists.** `/soundcloud/search/<term>`
  children include matching tracks (queueable leaves) and matching playlists
  (containers). *(test: `search_term_lists_tracks_and_playlists`.)*
- [ ] **G14 — Resolve handles both kinds.** `/soundcloud/resolve/<url>` yields a
  single track leaf or a playlist container per the resolved `kind`. *(test:
  `resolve_entry_shapes_track_and_playlist`.)*
- [ ] **G15 — Playlists hydrate within bounds.** A playlist node hydrates stub
  ids in ≤50-id batches up to `playlist_tracks` (default 500); a truncated
  playlist is `log`-ged, not silently cut. *(test:
  `playlist_node_hydrates_stub_tracks`.)*
- [ ] **G16 — Download blessing.** Every node serving tracks and each queueable
  child raises `is_downloadable`, matching abs/fyyd. *(test:
  `queueable_nodes_are_downloadable`.)*
- [ ] **G17 — Search terms / resolve URLs are creatable/editable/deletable.**
  `/soundcloud/search` and `/soundcloud/resolve` are `is_creatable`; their term
  children are `is_editable` + `is_deletable`, with implicit recreation on stale
  paths. *(tests: `create_rename_delete_search_term`,
  `create_resolve_url_entry`.)*

## Playback: HLS (D4)

- [ ] **G18 — `get_urls_for_track` returns one m3u8.** For a `track/<id>` path it
  returns exactly `[m3u8_url]` via `resolve_stream_url`; a non-track path is
  `MalformedPath`; a non-streamable track surfaces a typed error (skipped, never
  a crash). *(test: `get_urls_for_track_returns_m3u8`.)*
- [ ] **G19 — `HlsStream` streams segments in order as continuous mp3.** The
  media playlist is parsed (hand-written; relative URIs resolved against the
  playlist URL; one level of master-playlist fallback), segments are fetched in
  order, and the concatenated bytes decode as mp3. *(gate: live/integration —
  a real or fixture m3u8 plays to EOS without panic.)*
- [ ] **G20 — `HlsStream` is forward-only and non-seekable.** `supports_seek()`
  is `false` and `content_length()` is `None`, so symphonia never attempts the
  end-seek that panics rodio 0.22 on a length-less stream. *(gate: verified in
  the play-to-EOS integration check.)*
- [ ] **G21 — HLS routing.** `audio-player`'s `open_source` routes a `.m3u8`
  URL to `HlsStream` and every other http URL to the windowed-HTTP path;
  opus/other content-sniffing downstream is unchanged.

## Docs and hygiene

- [ ] **G22 — Public items documented.** Every `pub` item has a doc comment
  stating intent and error/edge behavior.
- [ ] **G23 — `cargo fmt`/`clippy` clean** for `soundclouddy` and `audio-player`
  (workspace lint level), and `cargo machete` reports no unused deps.