youtube-legend-cli 0.4.0

//! JSON [`Provider`] backed by the noiz.io landing endpoint.
//!
//! A single `GET` returns the whole transcript. Unlike
//! [`crate::provider::decopy`], which exposes no language parameter at
//! all, this endpoint accepts one — but accepting it and honouring it
//! are not the same thing, and this module claimed the second for a
//! long time on the strength of the first.
//!
//! MEASURED on 2026-09-04 against `zHGqpjCV6Tg`, a video whose watch
//! page publishes a single ASR track in `pt`. Requesting `en` and
//! requesting `pt` returned the same body: 128 309 bytes, identical
//! SHA-256, differing only in the language this crate had itself put
//! into `source_url`. The `404` that `classify_status` documents for
//! "no track in this language" never came; the native track came back
//! under whatever label was asked for.
//!
//! This is why `delivered_language` is pinned to `None` (GAP-2026-158)
//! rather than echoing the request: the envelope names no track, so the
//! only honest statement about what arrived is that we do not know.
//!
//! # Why it is last in the chain
//!
//! The anonymous quota is five requests per day and the 429 body says
//! so literally. Ten measured attempts with distinct languages returned
//! 429 for every one of them, including from inside a real browser
//! session. The provider is therefore useful as a last resort and
//! useless as a primary, which is exactly where the `auto` chain puts
//! it.
//!
//! # Format
//!
//! Segments carry a floating-point start plus a duration, which is
//! enough to render real `SubRip`. The provider advertises
//! [`SubtitleFormat::Srt`].

use std::collections::HashMap;
use std::sync::Mutex;
use std::time::Duration;

use async_trait::async_trait;
use serde::Deserialize;

use super::decopy::cue;
use super::{Format, Provider, SubtitleFormat, SubtitleInfo};
use crate::error::{AppError, AppResult, NoSubtitleReason};
use crate::secret_endpoints::{noiz_api_base, noiz_api_host, noiz_subtitles_path};

/// Stable provider identifier. Mirrored into
/// [`SubtitleInfo::provider`] and into every tracing event.
pub const PROVIDER_NAME: &str = "provider-noiz";

/// Wall-clock ceiling for the single upstream request.
///
/// Compiled default behind `providers.noiz.request_timeout_secs`.
const DEFAULT_NOIZ_REQUEST_TIMEOUT_SECS: u64 = 60;

/// Wall-clock ceiling for the single upstream request.
///
/// Resolves `providers.noiz.request_timeout_secs`. A zero would abort
/// before the request leaves, so the range starts at one second.
fn noiz_request_timeout() -> Duration {
    Duration::from_secs(crate::config::tuning_u64_in_range(
        "providers.noiz.request_timeout_secs",
        DEFAULT_NOIZ_REQUEST_TIMEOUT_SECS,
        1,
        3_600,
    ))
}

/// Maximum response body accepted before parsing.
///
/// Compiled default behind `providers.noiz.max_body_bytes`.
const DEFAULT_NOIZ_MAX_BODY_BYTES: usize = 16 * 1024 * 1024;

/// Maximum response body accepted before parsing.
///
/// Resolves `providers.noiz.max_body_bytes`.
fn noiz_max_body_bytes() -> usize {
    crate::config::tuning_usize_in_range(
        "providers.noiz.max_body_bytes",
        DEFAULT_NOIZ_MAX_BODY_BYTES,
        1_024,
        1_073_741_824,
    )
}

/// Query parameter carrying the bare 11-character video id.
const PARAM_VIDEO_ID: &str = "video_id";

/// Query parameter carrying the wanted track, upper-cased and
/// hyphenated (`PT-BR`, `EN`).
const PARAM_LANGUAGE: &str = "language";

/// Response envelope. Only the transcript array is modelled.
#[derive(Debug, Deserialize)]
struct NoizEnvelope {
    /// Timed segments, in presentation order.
    #[serde(default)]
    transcript_parts: Vec<NoizPart>,
}

/// One timed segment as the upstream spells it.
#[derive(Debug, Deserialize)]
struct NoizPart {
    /// Offset from the start of the video, in seconds.
    #[serde(default)]
    start: f64,
    /// Length of the segment, in seconds.
    #[serde(default)]
    duration: f64,
    /// Segment text.
    #[serde(default)]
    text: String,
}

/// noiz.io provider. Construct with [`ProviderNoiz::new`].
pub struct ProviderNoiz {
    base_url: String,
    cache: Mutex<HashMap<String, Vec<u8>>>,
}

impl Default for ProviderNoiz {
    fn default() -> Self {
        Self::new()
    }
}

impl ProviderNoiz {
    /// Build a provider against the production endpoint.
    #[must_use]
    #[tracing::instrument(level = "debug")]
    pub fn new() -> Self {
        Self {
            base_url: noiz_api_base(),
            cache: Mutex::new(HashMap::new()),
        }
    }

    /// Builder-style: point the provider at a different origin.
    ///
    /// The only production origin is the provider's compiled-in API
    /// base; this exists so
    /// the integration suite can aim the provider at a local mock
    /// server without a network round trip.
    #[must_use]
    pub fn with_base_url(mut self, base_url: impl Into<String>) -> Self {
        self.base_url = base_url.into();
        self
    }

    /// Absolute URL of the subtitles endpoint, without a query string.
    fn subtitles_url(&self) -> String {
        format!(
            "{}{}",
            self.base_url.trim_end_matches('/'),
            noiz_subtitles_path()
        )
    }

    /// Absolute URL of the subtitles endpoint for one video and track.
    ///
    /// The query string is assembled here rather than through
    /// `RequestBuilder::query`, which this crate's `reqwest` feature set
    /// does not compile in.
    fn subtitles_url_for(&self, video_id: &str, wire_language: &str) -> String {
        let query = url::form_urlencoded::Serializer::new(String::new())
            .append_pair(PARAM_VIDEO_ID, video_id)
            .append_pair(PARAM_LANGUAGE, wire_language)
            .finish();
        format!("{}?{}", self.subtitles_url(), query)
    }
}

/// Render a BCP 47 tag the way the endpoint expects it: upper case,
/// hyphen-separated, region preserved.
///
/// `pt-BR` becomes `PT-BR` and `en` becomes `EN`. An underscore-joined
/// POSIX locale is normalised on the way through so `pt_BR` does not
/// reach the wire as an unrecognised token.
pub(crate) fn wire_language(tag: &str) -> String {
    tag.trim().replace('_', "-").to_ascii_uppercase()
}

/// Turn a parsed envelope into `SubRip` bytes.
///
/// # Errors
///
/// Returns [`AppError::NoSubtitle`] carrying
/// [`NoSubtitleReason::LanguageUnavailable`] when the endpoint answered
/// successfully with an empty transcript. The endpoint is language-
/// scoped, so an empty answer means "not in this language", never "this
/// video has no captions at all" — collapsing the two would let the
/// chain report a confirmed absence it never observed.
fn envelope_to_srt(envelope: NoizEnvelope) -> AppResult<String> {
    let cues: Vec<cue::Cue> = envelope
        .transcript_parts
        .into_iter()
        .map(|p| cue::Cue {
            start_secs: p.start,
            end_secs: p.start + p.duration.max(0.0),
            text: p.text.trim().to_string(),
        })
        .collect();
    let srt = cue::render_srt(&cues);
    if srt.is_empty() {
        return Err(AppError::NoSubtitle(NoSubtitleReason::LanguageUnavailable));
    }
    Ok(srt)
}

/// Classify a non-success HTTP status from this endpoint.
///
/// The endpoint answers `404` when the requested language has no track,
/// which is [`NoSubtitleReason::LanguageUnavailable`] and not the
/// generic `NotFound` that [`super::http_failure`] would infer from the
/// status alone. Everything else defers to the shared classifier, so
/// `429` keeps its `Retry-After` and `5xx` stays degraded.
fn classify_status(status: reqwest::StatusCode, headers: &reqwest::header::HeaderMap) -> AppError {
    if status == reqwest::StatusCode::NOT_FOUND {
        return AppError::NoSubtitle(NoSubtitleReason::LanguageUnavailable);
    }
    if status == reqwest::StatusCode::TOO_MANY_REQUESTS {
        tracing::warn!(
            target: "events",
            provider = PROVIDER_NAME,
            "noiz daily quota exhausted; degrading"
        );
    }
    super::http_failure(status, headers, PROVIDER_NAME)
}

#[async_trait]
impl Provider for ProviderNoiz {
    fn name(&self) -> &'static str {
        PROVIDER_NAME
    }

    async fn fetch_subtitle(
        &self,
        video_id: &str,
        language: &str,
        _format: Format,
    ) -> AppResult<SubtitleInfo> {
        if crate::provider::is_offline() {
            return Err(AppError::ProviderUnavailable {
                provider: PROVIDER_NAME,
            });
        }

        // NFR-007: confirm the ruleset permits the endpoint before the
        // first byte leaves the process.
        crate::provider::robots::check_allowed(
            &noiz_api_host(),
            &noiz_subtitles_path(),
            &crate::net::user_agent(),
            PROVIDER_NAME,
        )
        .await?;

        // Canonicalise before hitting the wire so `pt_BR.UTF-8` becomes
        // `pt-BR` and a malformed tag fails as `LanguageParseError`
        // rather than as an opaque upstream 404.
        let requested = crate::cli::LanguageArg::parse(language)?;
        let tag = requested.as_str().to_string();
        let wire = wire_language(&tag);

        let client = crate::net::session::chrome_client(noiz_request_timeout())?;

        tracing::debug!(
            target: "events",
            provider = PROVIDER_NAME,
            video_id,
            language = %wire,
            "fetch_subtitle_started"
        );

        let response = client
            .get(self.subtitles_url_for(video_id, &wire))
            .send()
            .await
            .map_err(AppError::Http)?;

        let status = response.status();
        if !status.is_success() {
            return Err(classify_status(status, response.headers()));
        }

        let raw = response.text().await.map_err(AppError::Http)?;
        if raw.len() > noiz_max_body_bytes() {
            return Err(AppError::SubtitleTooLarge(raw.len()));
        }
        let envelope: NoizEnvelope =
            serde_json::from_str(&raw).map_err(|e| AppError::ProviderProtocolError {
                provider: PROVIDER_NAME,
                detail: format!("returned a body this crate cannot model: {e}"),
            })?;
        let srt = envelope_to_srt(envelope)?;

        let source_url = format!("noiz://{video_id}/{tag}/srt");
        self.cache
            .lock()
            .map_err(|_| AppError::Internal("noiz cache poisoned".to_string()))?
            .insert(source_url.clone(), srt.clone().into_bytes());

        tracing::debug!(
            target: "events",
            provider = PROVIDER_NAME,
            video_id,
            language = %tag,
            body_bytes = srt.len(),
            "fetch_subtitle_completed"
        );

        Ok(SubtitleInfo {
            video_id: video_id.to_string(),
            language: tag,
            // GAP-2026-158: the noiz envelope carries only
            // `transcript_parts`; nothing in it names the track, so the
            // delivered language stays declared-unknown.
            delivered_language: None,
            format: Format::Srt,
            source_url,
            byte_size: srt.len(),
            format_hint: SubtitleFormat::Srt,
            provider: PROVIDER_NAME,
        })
    }

    async fn fetch_content(&self, info: &SubtitleInfo) -> AppResult<Vec<u8>> {
        let bytes = self
            .cache
            .lock()
            .map_err(|_| AppError::Internal("noiz cache poisoned".to_string()))?
            .get(&info.source_url)
            .cloned();
        match bytes {
            Some(b) if !b.is_empty() => Ok(b),
            _ => Err(AppError::NoSubtitle(NoSubtitleReason::NotPublished)),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn provider_name_is_stable() {
        assert_eq!(ProviderNoiz::new().name(), PROVIDER_NAME);
    }

    #[test]
    fn wire_language_upper_cases_and_keeps_the_region() {
        assert_eq!(wire_language("pt-BR"), "PT-BR");
        assert_eq!(wire_language("en"), "EN");
    }

    #[test]
    fn wire_language_normalises_a_posix_locale() {
        assert_eq!(wire_language("pt_BR"), "PT-BR");
    }

    #[test]
    fn subtitles_url_does_not_double_the_slash() {
        let p = ProviderNoiz::new().with_base_url("https://example.test/");
        assert_eq!(
            p.subtitles_url(),
            format!("https://example.test{}", noiz_subtitles_path())
        );
    }

    #[test]
    fn envelope_renders_subrip_from_start_plus_duration() {
        let raw = r#"{"transcript_parts":[
            {"start":0.0,"duration":2.5,"text":"hello"},
            {"start":2.5,"duration":1.5,"text":"world"}]}"#;
        let envelope: NoizEnvelope = serde_json::from_str(raw).expect("fixture parses");
        let srt = envelope_to_srt(envelope).expect("cues render");
        assert!(srt.starts_with("1\n00:00:00,000 --> 00:00:02,500\nhello\n\n"));
        assert!(srt.contains("2\n00:00:02,500 --> 00:00:04,000\nworld"));
    }

    #[test]
    fn empty_transcript_is_language_unavailable_not_not_published() {
        let envelope: NoizEnvelope =
            serde_json::from_str(r#"{"transcript_parts":[]}"#).expect("fixture parses");
        let err = envelope_to_srt(envelope).expect_err("no cues");
        assert!(
            matches!(
                err,
                AppError::NoSubtitle(NoSubtitleReason::LanguageUnavailable)
            ),
            "got {err:?}"
        );
    }

    #[test]
    fn status_404_is_language_unavailable() {
        let headers = reqwest::header::HeaderMap::new();
        let err = classify_status(reqwest::StatusCode::NOT_FOUND, &headers);
        assert!(
            matches!(
                err,
                AppError::NoSubtitle(NoSubtitleReason::LanguageUnavailable)
            ),
            "got {err:?}"
        );
    }

    #[test]
    fn status_429_keeps_the_retry_after() {
        let mut headers = reqwest::header::HeaderMap::new();
        headers.insert(reqwest::header::RETRY_AFTER, "30".parse().expect("ascii"));
        let err = classify_status(reqwest::StatusCode::TOO_MANY_REQUESTS, &headers);
        assert!(
            matches!(
                err,
                AppError::RateLimited {
                    retry_after_secs: Some(30),
                    ..
                }
            ),
            "got {err:?}"
        );
    }

    #[test]
    fn status_503_degrades_rather_than_claiming_absence() {
        let headers = reqwest::header::HeaderMap::new();
        let err = classify_status(reqwest::StatusCode::SERVICE_UNAVAILABLE, &headers);
        assert!(
            matches!(err, AppError::ProviderUnavailable { .. }),
            "got {err:?}"
        );
    }

    /// noiz cannot enumerate what a video offers, so the honest menu is
    /// the empty one the trait default provides.
    #[tokio::test]
    async fn list_tracks_is_the_empty_default() {
        assert!(ProviderNoiz::new()
            .list_tracks("dQw4w9WgXcQ")
            .await
            .expect("menu")
            .is_empty());
    }
}