gflights 0.3.0

use super::config::Currency;
use crate::parsers;
use crate::parsers::common::FixedFlights;
use crate::parsers::constants::{CLK_URL, FLIGHTS_MAIN_PAGE};
use crate::requests::config::deals::{DealConfig, DealResult};
use crate::requests::config::explore::ExploreResult;
use crate::requests::config::{Config, ExploreConfig, MultiCityConfig, TripType};
use anyhow::Result;
use chrono::{Duration, Months, NaiveDate};
use futures::StreamExt as _;
use governor::{DefaultDirectRateLimiter, Quota};
use parsers::calendar_graph_request::GraphRequestOptions;
use parsers::calendar_graph_response::GraphRawResponseContainer;
use parsers::city_request::CityRequestOptions;
use parsers::city_response::ResponseInnerBodyParsed;
use parsers::common::ToRequestBody;
use parsers::date_grid_request::{DateGridRequestOptions, DATE_GRID_MAX_CELLS};
use parsers::date_grid_response::{parse_date_grid_response, CheapDate, DateGridResponse};
use parsers::deals_request::DealsRequestOptions;
use parsers::deals_response::parse_deals_response;
use parsers::explore_request::ExploreRequestOptions;
use parsers::explore_response::parse_explore_response;
use parsers::flight_request::{FlightRequestOptions, MultiCityRequestOptions};
use parsers::flight_response::{create_raw_response_vec, FlightResponseContainer};
use parsers::offer_response::{self, OfferRawResponseContainer};
use regex::Regex;
use reqwest::header::{HeaderMap, HeaderValue};
use reqwest::{Client, Response, StatusCode};
use std::num::NonZeroU32;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
use std::time::{SystemTime, UNIX_EPOCH};

/// Returned when the Google Flights API responds with HTTP 429 (Too Many Requests).
///
/// Once any request on an [`ApiClient`] receives a 429, that client (and all
/// its clones, which share the same flag) will refuse to send further requests
/// until [`ApiClient::reset_rate_limit`] is called.
///
/// You can match on this error type via [`anyhow::Error::downcast_ref`]:
///
/// ```rust,ignore
/// if let Some(_) = err.downcast_ref::<RateLimitedError>() {
///     // wait and retry, or surface to the user
/// }
/// ```
#[derive(Debug)]
pub struct RateLimitedError;

impl std::fmt::Display for RateLimitedError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "Google Flights returned HTTP 429 Too Many Requests — all further requests on this client are blocked; call ApiClient::reset_rate_limit() to resume")
    }
}

impl std::error::Error for RateLimitedError {}

/// Configuration for automatic retry with exponential back-off.
///
/// Applied to transient server errors (HTTP 500/502/503/504) and timed-out
/// connections.  429s and 4xx client errors are never retried.
///
/// # Example
/// ```rust
/// use gflights::requests::api::RetryConfig;
/// let cfg = RetryConfig { max_attempts: 5, base_delay_ms: 200, cap_delay_ms: 10_000 };
/// ```
#[derive(Debug, Clone)]
pub struct RetryConfig {
    /// Total number of attempts (including the first).  `1` means no retries.
    pub max_attempts: u32,
    /// Base delay in milliseconds before the first retry.  Doubles each attempt.
    pub base_delay_ms: u64,
    /// Maximum delay cap in milliseconds (before jitter).
    pub cap_delay_ms: u64,
}

impl Default for RetryConfig {
    fn default() -> Self {
        Self {
            max_attempts: 3,
            base_delay_ms: 500,
            cap_delay_ms: 30_000,
        }
    }
}

/// The `ApiClient` struct is used to send requests to the Google Flights website.
///
/// Cloning this struct is cheap — all clones share the same underlying HTTP
/// client, rate-limiter, and rate-limit flag via `Arc`.
#[derive(Clone)]
pub struct ApiClient {
    pub rate_limiter: Arc<DefaultDirectRateLimiter>,
    pub client: Arc<Client>,
    frontend_version: String,
    /// Set to `true` the first time any request on this client (or any clone)
    /// receives HTTP 429.  While `true`, every call to `do_request` returns
    /// [`RateLimitedError`] immediately without touching the network.
    rate_limited: Arc<AtomicBool>,
    /// Retry policy for transient server errors and timeouts.
    retry_config: RetryConfig,
    /// User-Agent sent with every request. Chosen from a rotating pool at
    /// construction (see [`pick_user_agent`]) or overridden via
    /// [`ApiClient::with_user_agent`].
    user_agent: String,
    /// Result currency applied to every request (sent via the locale header).
    currency: Currency,
    /// BCP-47 language subtag applied to every request, e.g. `"en"`.
    language: String,
    /// ISO 3166-1 alpha-2 country code applied to every request, e.g. `"GB"`.
    country: String,
}

impl ApiClient {
    /// Creates a new instance of `ApiClient` with a default rate limiter of 10 requests per second.
    pub async fn new() -> Self {
        // NonZeroU32::MIN is 1; saturating_add(9) gives 10 with no possibility of panic.
        let rate_limiter_quota = Quota::per_second(NonZeroU32::MIN.saturating_add(9));
        Self::new_with_ratelimit(rate_limiter_quota).await
    }

    /// Creates a new instance of `ApiClient` with a custom rate limiter.
    pub async fn new_with_ratelimit(rate_limiter_quota: Quota) -> Self {
        // A proxy-less client cannot fail to build (same guarantee as
        // `reqwest::Client::new`, which panics on failure).
        Self::build(rate_limiter_quota, None)
            .await
            .expect("building a proxy-less HTTP client never fails")
    }

    /// Creates a new instance of `ApiClient` whose requests are routed through
    /// the given proxy.
    ///
    /// The proxy applies to every request, including the one-time frontend
    /// version probe. Supports `http://`, `https://`, and `socks5://` URLs
    /// (e.g. `"http://user:pass@host:3128"`, `"socks5://127.0.0.1:9050"`).
    ///
    /// # Errors
    /// Returns an error if the proxy URL is invalid or the HTTP client cannot
    /// be built with it.
    ///
    /// ```rust
    /// # use gflights::requests::api::ApiClient;
    /// # async fn example() -> anyhow::Result<()> {
    /// let client = ApiClient::new_with_proxy("socks5://127.0.0.1:9050").await?;
    /// # Ok(())
    /// # }
    /// ```
    pub async fn new_with_proxy(proxy: impl Into<String>) -> Result<Self> {
        let rate_limiter_quota = Quota::per_second(NonZeroU32::MIN.saturating_add(9));
        Self::build(rate_limiter_quota, Some(proxy.into())).await
    }

    /// Shared construction path: builds the HTTP client (optionally through a
    /// proxy), selects a User-Agent, and probes the frontend version using that
    /// same client so the proxy (if any) covers every request.
    async fn build(rate_limiter_quota: Quota, proxy: Option<String>) -> Result<Self> {
        let rate_limiter: Arc<DefaultDirectRateLimiter> =
            Arc::new(DefaultDirectRateLimiter::direct(rate_limiter_quota));
        let user_agent = pick_user_agent().to_string();
        tracing::debug!(%user_agent, proxy = ?proxy, "constructing client");
        let client = build_reqwest_client(proxy.as_deref())?;
        let frontend_version = get_frontend_version(&user_agent, &client).await;

        Ok(Self {
            rate_limiter,
            client: Arc::new(client),
            frontend_version: frontend_version
                .unwrap_or("boq_travel-frontend-flights-ui_20260527.01_p0".into()),
            rate_limited: Arc::new(AtomicBool::new(false)),
            retry_config: RetryConfig::default(),
            user_agent,
            currency: Currency::default(),
            language: "en".to_string(),
            country: "GB".to_string(),
        })
    }

    /// Overrides the retry policy for this client.
    ///
    /// ```rust
    /// # use gflights::requests::api::{ApiClient, RetryConfig};
    /// # async fn example() {
    /// let client = ApiClient::new().await
    ///     .with_retry_config(RetryConfig { max_attempts: 5, base_delay_ms: 200, cap_delay_ms: 10_000 });
    /// # }
    /// ```
    pub fn with_retry_config(mut self, retry_config: RetryConfig) -> Self {
        self.retry_config = retry_config;
        self
    }

    /// Overrides the User-Agent header for this client.
    ///
    /// By default a User-Agent is chosen from a small rotating pool of real
    /// desktop browser strings at construction time, so traffic from repeated
    /// client creation is not trivially fingerprintable by a single static
    /// value. Use this to pin a specific User-Agent instead.
    ///
    /// ```rust
    /// # use gflights::requests::api::ApiClient;
    /// # async fn example() {
    /// let client = ApiClient::new().await
    ///     .with_user_agent("Mozilla/5.0 (X11; Linux x86_64; rv:126.0) Gecko/20100101 Firefox/126.0");
    /// # }
    /// ```
    pub fn with_user_agent(mut self, user_agent: impl Into<String>) -> Self {
        self.user_agent = user_agent.into();
        self
    }

    /// Returns the User-Agent this client sends with every request.
    pub fn user_agent(&self) -> &str {
        &self.user_agent
    }

    /// Sets the result currency applied to every request on this client.
    pub fn with_currency(mut self, currency: Currency) -> Self {
        self.currency = currency;
        self
    }

    /// Sets the BCP-47 language subtag (e.g. `"en"`, `"fr"`) for every request.
    pub fn with_language(mut self, language: impl Into<String>) -> Self {
        self.language = language.into();
        self
    }

    /// Sets the ISO 3166-1 alpha-2 country code (e.g. `"GB"`, `"US"`) for every request.
    pub fn with_country(mut self, country: impl Into<String>) -> Self {
        self.country = country.into();
        self
    }

    /// Sets currency, language and country in one call.
    pub fn with_locale(
        mut self,
        currency: Currency,
        language: impl Into<String>,
        country: impl Into<String>,
    ) -> Self {
        self.currency = currency;
        self.language = language.into();
        self.country = country.into();
        self
    }

    /// Returns the currency this client applies to every request.
    pub fn currency(&self) -> &Currency {
        &self.currency
    }

    /// Returns the language subtag this client applies to every request.
    pub fn language(&self) -> &str {
        &self.language
    }

    /// Returns the country code this client applies to every request.
    pub fn country(&self) -> &str {
        &self.country
    }

    /// Returns `true` if this client has been halted by a 429 response.
    ///
    /// All clones of the same `ApiClient` share this flag.
    pub fn is_rate_limited(&self) -> bool {
        self.rate_limited.load(Ordering::SeqCst)
    }

    /// Clears the 429 flag so the client can send requests again.
    ///
    /// Call this after an appropriate back-off period.  The client will resume
    /// normal operation on the next request.
    pub fn reset_rate_limit(&self) {
        self.rate_limited.store(false, Ordering::SeqCst);
    }

    /// Sends a request to retrieve information about a city/airport.
    ///
    /// # Arguments
    ///
    /// * `city` - The name of the city, in english
    ///
    /// # Returns
    ///
    /// Returns a `ResponseInnerBodyParsed` object containing the parsed response.
    /// This will contains both the airport associated and the city.
    #[tracing::instrument(skip(self))]
    pub async fn request_city(&self, city: &str) -> Result<ResponseInnerBodyParsed> {
        let options = CityRequestOptions {
            city: city.to_owned(),
            frontend_version: self.frontend_version.clone(),
        };
        let city_response: &str = &self
            .do_request(&options, None, &self.language, &self.country)
            .await?
            .text()
            .await?;
        let cities_res = ResponseInnerBodyParsed::try_from(city_response)?;
        Ok(cities_res)
    }

    /// Sends a request to retrieve flight graph data.
    ///
    /// # Arguments
    ///
    /// * `args` - The configuration options for the request.
    /// * `months` - The number of months to include in the graph.
    ///
    /// # Returns
    ///
    /// Returns a `GraphRawResponseContainer` object containing the parsed response.
    #[tracing::instrument(skip_all)]
    pub async fn request_graph(
        &self,
        args: &Config,
        months: Months,
    ) -> Result<GraphRawResponseContainer> {
        let date_end_graph = args
            .get_end_graph(months)
            .ok_or_else(|| anyhow::anyhow!("date overflow when computing graph end date"))?
            .to_string();
        let req_options = GraphRequestOptions {
            departing_city: &args.departure,
            arriving_city: &args.destination,
            date_start: &args.departing_date,
            date_return: args.return_date.as_ref(),
            date_end_graph: &date_end_graph,
            travellers: args.travellers.clone(),
            travel_class: &args.travel_class,
            stop_option: &args.stop_options,
            departing_times: &args.departing_times,
            return_times: &args.return_times,
            stopover_max: &args.stopover_max,
            stopover_min: &args.stopover_min,
            duration_max: &args.duration_max,
            frontend_version: &self.frontend_version,
            language: &self.language,
            country: &self.country,
            sort_order: &args.sort_order,
        };
        let body = self
            .do_request(
                &req_options,
                Some(self.currency.clone()),
                &self.language,
                &self.country,
            )
            .await?
            .text()
            .await?;
        GraphRawResponseContainer::try_from(body.as_ref())
    }

    /// Sends a request to retrieve the date-grid price matrix.
    ///
    /// Returns a price for every (departure_date, return_date) combination
    /// that falls within the two supplied date windows.
    ///
    /// The backend rejects requests whose cell count
    /// (`dep_window_days × ret_window_days`) exceeds [`DATE_GRID_MAX_CELLS`]
    /// (200).  This method transparently splits large windows into multiple
    /// sub-requests and merges the results, so callers are free to supply any
    /// window size.
    ///
    /// # Arguments
    ///
    /// * `args` — Config supplying route, travellers, cabin class, etc.
    ///   `args.departing_date` / `args.return_date` are used as reference
    ///   dates inside the itinerary body; they must fall within the respective
    ///   windows and a return date must be set.
    /// * `dep_start` / `dep_end` — window of candidate departure dates.
    /// * `ret_start` / `ret_end` — window of candidate return dates.
    #[tracing::instrument(skip_all)]
    pub async fn request_date_grid(
        &self,
        args: &Config,
        dep_start: NaiveDate,
        dep_end: NaiveDate,
        ret_start: NaiveDate,
        ret_end: NaiveDate,
    ) -> Result<DateGridResponse> {
        args.return_date
            .ok_or_else(|| anyhow::anyhow!("date grid requires a return date in Config"))?;

        let dep_days = (dep_end - dep_start).num_days() + 1;
        let ret_days = (ret_end - ret_start).num_days() + 1;
        let total_cells = dep_days * ret_days;

        if total_cells <= DATE_GRID_MAX_CELLS as i64 {
            // Fits in a single request.
            return self
                .request_date_grid_chunk(args, dep_start, dep_end, ret_start, ret_end)
                .await;
        }

        // Split both dimensions so each sub-request stays within the limit.
        //
        // Per-dimension chunk size: floor(sqrt(DATE_GRID_MAX_CELLS)).
        // For DATE_GRID_MAX_CELLS = 200 this gives 14 × 14 = 196 ≤ 200.
        // Using a fixed per-axis chunk keeps each request within the backend's
        // per-axis limit even when one window is much larger than the other.
        let chunk_dim = (DATE_GRID_MAX_CELLS as f64).sqrt() as i64; // 14

        // Enumerate all (dep_window, ret_window) chunk pairs up front.
        let mut chunks: Vec<(NaiveDate, NaiveDate, NaiveDate, NaiveDate)> = Vec::new();
        let mut chunk_dep_start = dep_start;
        while chunk_dep_start <= dep_end {
            let chunk_dep_end = (chunk_dep_start + Duration::days(chunk_dim - 1)).min(dep_end);
            let chunk_dep_days = (chunk_dep_end - chunk_dep_start).num_days() + 1;
            let max_ret_chunk = ((DATE_GRID_MAX_CELLS as i64) / chunk_dep_days).max(1);

            let mut chunk_ret_start = ret_start;
            while chunk_ret_start <= ret_end {
                let chunk_ret_end =
                    (chunk_ret_start + Duration::days(max_ret_chunk - 1)).min(ret_end);
                chunks.push((
                    chunk_dep_start,
                    chunk_dep_end,
                    chunk_ret_start,
                    chunk_ret_end,
                ));
                chunk_ret_start = chunk_ret_end + Duration::days(1);
            }

            chunk_dep_start = chunk_dep_end + Duration::days(1);
        }

        tracing::info!(
            dep_days,
            ret_days,
            chunk_dim,
            chunk_count = chunks.len(),
            "date grid too large, splitting into parallel chunks"
        );

        // Run all chunks with bounded concurrency.  The rate-limiter inside
        // `do_request` gates the send rate (10 req/s), but it does not cap how
        // many responses are simultaneously awaited.  With 5 s average latency
        // and 10 req/s throughput, uncapped concurrency would open ~50
        // connections at peak — enough for Google to send EOF mid-stream.
        // `buffer_unordered(8)` keeps at most 8 connections in-flight at once.
        const MAX_CONCURRENT: usize = 8;
        let results: Vec<Result<DateGridResponse>> = futures::stream::iter(chunks)
            .map(|(dep_s, dep_e, ret_s, ret_e)| async move {
                self.request_date_grid_chunk(args, dep_s, dep_e, ret_s, ret_e)
                    .await
            })
            .buffer_unordered(MAX_CONCURRENT)
            .collect()
            .await;

        let mut all_entries = Vec::new();
        for result in results {
            all_entries.extend(result?.entries);
        }

        Ok(DateGridResponse {
            entries: all_entries,
        })
    }

    /// Single `GetCalendarGrid` request — windows must be ≤ [`DATE_GRID_MAX_CELLS`] cells.
    ///
    /// The return reference date is clamped to `[ret_start, ret_end]` so it
    /// stays valid when this is called from the chunking loop.
    async fn request_date_grid_chunk(
        &self,
        args: &Config,
        dep_start: NaiveDate,
        dep_end: NaiveDate,
        ret_start: NaiveDate,
        ret_end: NaiveDate,
    ) -> Result<DateGridResponse> {
        // Clamp the config's reference dates to lie within the supplied windows.
        let dep_ref = args.departing_date.max(dep_start).min(dep_end);
        let ret_ref = args
            .return_date
            .unwrap_or(ret_start)
            .max(ret_start)
            .min(ret_end);

        let req_options = DateGridRequestOptions::new(
            &args.departure,
            &args.destination,
            &dep_ref,
            &ret_ref,
            &dep_start,
            &dep_end,
            &ret_start,
            &ret_end,
            args.travellers.clone(),
            &args.travel_class,
            &args.stop_options,
            &args.departing_times,
            &args.return_times,
            &args.stopover_max,
            &args.duration_max,
            &self.frontend_version,
        );

        // Retry the full request on body-read errors (e.g. unexpected EOF from
        // a forcibly-closed connection).  `do_request` retries transport/5xx
        // errors but returns a `Response` handle before the body is streamed,
        // so body-read failures need their own retry here.
        let max_attempts = self.retry_config.max_attempts.max(1);
        let mut last_err: anyhow::Error = anyhow::anyhow!("all body-read attempts exhausted");
        for attempt in 0..max_attempts {
            if attempt > 0 {
                let delay_ms = (self.retry_config.base_delay_ms * (1u64 << (attempt - 1).min(30)))
                    .min(self.retry_config.cap_delay_ms);
                tracing::debug!(attempt, delay_ms, "body read error — retrying chunk");
                tokio::time::sleep(std::time::Duration::from_millis(delay_ms)).await;
            }
            let res = self
                .do_request(
                    &req_options,
                    Some(self.currency.clone()),
                    &self.language,
                    &self.country,
                )
                .await?;
            match res.text().await {
                Ok(body) => return parse_date_grid_response(&body),
                Err(e) => {
                    tracing::warn!(attempt, error = %e, "body read failed for date-grid chunk");
                    last_err = e.into();
                }
            }
        }
        Err(last_err)
    }

    /// Sends a request to retrieve flight data.
    ///
    /// # Arguments
    ///
    /// * `args` - The configuration options for the request.
    ///
    /// # Returns
    ///
    /// Returns a `FlightResponseContainer` object containing the parsed response.
    #[tracing::instrument(skip_all, fields(
        from = ?args.departure.iter().map(|l| l.loc_identifier.as_str()).collect::<Vec<_>>(),
        to = ?args.destination.iter().map(|l| l.loc_identifier.as_str()).collect::<Vec<_>>(),
        date = %args.departing_date,
        class = ?args.travel_class,
        stops = ?args.stop_options,
    ))]
    pub async fn request_flights(&self, args: &Config) -> Result<FlightResponseContainer> {
        tracing::info!("Requesting flights");
        let body = self.fetch_flight_body(args).await?;
        create_raw_response_vec(body)
    }

    /// Sends a request to retrieve flight offer data.
    ///
    /// # Arguments
    ///
    /// * `args` - The configuration options for the request.
    ///
    /// # Returns
    ///
    /// Returns an `OfferRawResponseContainer` object containing the parsed response.
    #[tracing::instrument(skip_all, fields(
        from = ?args.departure.iter().map(|l| l.loc_identifier.as_str()).collect::<Vec<_>>(),
        to = ?args.destination.iter().map(|l| l.loc_identifier.as_str()).collect::<Vec<_>>(),
        date = %args.departing_date,
        class = ?args.travel_class,
        stops = ?args.stop_options,
    ))]
    pub async fn request_offer(&self, args: &Config) -> Result<OfferRawResponseContainer> {
        tracing::info!("Requesting offers");
        let body = self.fetch_flight_body(args).await?;
        tracing::trace!(body = %body, "raw offer response body");
        offer_response::create_raw_response_offer_vec(body)
    }

    /// Builds the request options from a [`Config`] and POSTs to the flights endpoint,
    /// returning the raw response body.
    ///
    /// Shared by [`Self::request_flights`] and [`Self::request_offer`], which differ only
    /// in how they parse the body.
    async fn fetch_flight_body(&self, args: &Config) -> Result<String> {
        let date_start = args.departing_date.to_string();
        let date_return = args.return_date.map(|f| f.to_string());
        // DepartureTime/ArrivalTime are client-side-only sorts; the backend does
        // not accept those discriminants and returns an empty result if sent.
        let server_sort = args.sort_order.server_sort();
        let req_options = FlightRequestOptions {
            departing_city: &args.departure,
            arriving_city: &args.destination,
            date_start: &date_start,
            date_return: date_return.as_deref(),
            travellers: args.travellers.clone(),
            travel_class: &args.travel_class,
            stop_option: &args.stop_options,
            departing_times: &args.departing_times,
            return_times: &args.return_times,
            stopover_max: &args.stopover_max,
            stopover_min: &args.stopover_min,
            duration_max: &args.duration_max,
            frontend_version: &self.frontend_version,
            fixed_flights: &args.fixed_flights,
            language: &self.language,
            country: &self.country,
            sort_order: &server_sort,
            airlines_include: &args.airlines_include,
            airlines_exclude: &args.airlines_exclude,
            connecting_airports: &args.connecting_airports,
            lower_emissions: args.lower_emissions,
            max_price: args.max_price,
            baggage: args.baggage,
        };
        Ok(self
            .do_request(
                &req_options,
                Some(self.currency.clone()),
                &self.language,
                &self.country,
            )
            .await?
            .text()
            .await?)
    }

    /// Sends a multi-city (open-jaw) flight search request.
    ///
    /// Returns all flight options across all legs in a single
    /// [`FlightResponseContainer`].  Call [`FlightResponseContainer::get_all_flights`]
    /// to obtain the deduplicated itinerary list.
    ///
    /// # Arguments
    ///
    /// * `args` — [`MultiCityConfig`] built via [`MultiCityConfig::builder()`].
    ///
    /// # Example
    ///
    /// ```no_run
    /// use gflights::requests::{api::ApiClient, config::MultiCityConfig};
    /// use chrono::NaiveDate;
    ///
    /// #[tokio::main]
    /// async fn main() -> anyhow::Result<()> {
    ///     let client = ApiClient::new().await;
    ///     let config = MultiCityConfig::builder()
    ///         .add_leg("LUX", "FCO", NaiveDate::from_ymd_opt(2026, 9, 10).unwrap(), &client).await?
    ///         .add_leg("FCO", "MAD", NaiveDate::from_ymd_opt(2026, 9, 13).unwrap(), &client).await?
    ///         .add_leg("MAD", "LUX", NaiveDate::from_ymd_opt(2026, 9, 17).unwrap(), &client).await?
    ///         .build()?;
    ///     let results = client.request_multi_city_flights(&config).await?;
    ///     let flights = results.get_all_flights();
    ///     println!("{} itineraries found", flights.len());
    ///     Ok(())
    /// }
    /// ```
    #[tracing::instrument(skip_all, fields(
        legs = args.legs.len(),
        class = ?args.travel_class,
    ))]
    pub async fn request_multi_city_flights(
        &self,
        args: &MultiCityConfig,
    ) -> Result<FlightResponseContainer> {
        tracing::info!("Requesting multi-city flights");
        let req_options = MultiCityRequestOptions {
            config: args,
            frontend_version: &self.frontend_version,
            language: &self.language,
            country: &self.country,
        };
        let body = self
            .do_request(
                &req_options,
                Some(self.currency.clone()),
                &self.language,
                &self.country,
            )
            .await?
            .text()
            .await?;
        create_raw_response_vec(body)
    }

    /// Search for cheap flight destinations from a given origin.
    ///
    /// Uses the `GetExploreDestinations` Google Flights endpoint, which powers
    /// the "Explore" mode on the website.  Given an origin, it returns a list
    /// of destinations ranked by price, optionally filtered by month, duration,
    /// budget, interest category, and more.
    ///
    /// # Arguments
    ///
    /// * `config` — An [`ExploreConfig`] describing the search parameters.
    ///
    /// # Returns
    ///
    /// A `Vec<ExploreResult>` sorted by the server's relevance ordering.
    /// Returns an empty vec if the response cannot be parsed rather than
    /// propagating a parse error (the streaming format is partially reverse-
    /// engineered — see `explore_response` for uncertainty notes).
    ///
    /// # Example
    ///
    /// ```no_run
    /// use gflights::requests::{api::ApiClient, config::{ExploreConfig, ExploreDuration}};
    /// use gflights::parsers::common::{Location, PlaceType, TravelClass};
    ///
    /// #[tokio::main]
    /// async fn main() -> anyhow::Result<()> {
    ///     let client = ApiClient::new().await;
    ///     let config = ExploreConfig {
    ///         origin: vec![Location {
    ///             loc_identifier: "LUX".into(),
    ///             loc_type: PlaceType::Airport,
    ///             location_name: None,
    ///         }],
    ///         trip_duration: ExploreDuration::OneWeek,
    ///         ..Default::default()
    ///     };
    ///     let destinations = client.request_explore(&config).await?;
    ///     for d in &destinations {
    ///         println!("{} ({}) — {:?}", d.name, d.nearest_airport, d.price);
    ///     }
    ///     Ok(())
    /// }
    /// ```
    #[tracing::instrument(skip_all, fields(
        origin = ?config.origin.iter().map(|l| l.loc_identifier.as_str()).collect::<Vec<_>>(),
        duration = ?config.trip_duration,
    ))]
    pub async fn request_explore(&self, config: &ExploreConfig) -> Result<Vec<ExploreResult>> {
        tracing::info!("Requesting explore destinations");
        let req_options = ExploreRequestOptions {
            config,
            frontend_version: &self.frontend_version,
            language: &self.language,
            country: &self.country,
        };
        let body = self
            .do_request(
                &req_options,
                Some(self.currency.clone()),
                &self.language,
                &self.country,
            )
            .await?
            .text()
            .await?;
        parse_explore_response(&body)
    }

    /// Requests discounted destinations (flight deals) from an origin.
    ///
    /// # Arguments
    /// * `config` — A [`DealConfig`] describing the origin, trip-length anchor,
    ///   and optional filters.
    ///
    /// # Returns
    /// A `Vec<DealResult>` of discounted destinations with price vs typical
    /// price, discount percentage, and a ready-to-open booking deep link.
    #[tracing::instrument(skip_all, fields(
        origin = ?config.origin.iter().map(|l| l.loc_identifier.as_str()).collect::<Vec<_>>(),
    ))]
    pub async fn request_deals(&self, config: &DealConfig) -> Result<Vec<DealResult>> {
        tracing::info!("Requesting flight deals");
        let req_options = DealsRequestOptions {
            config,
            frontend_version: &self.frontend_version,
            language: &self.language,
            country: &self.country,
        };
        let body = self
            .do_request(
                &req_options,
                Some(self.currency.clone()),
                &self.language,
                &self.country,
            )
            .await?
            .text()
            .await?;
        parse_deals_response(&body)
    }

    /// Resolves a `click_token` from an `OfferGroup` or `BookingSubOption`
    /// into the final airline / OTA booking URL.
    ///
    /// Internally this POSTs the token to Google's click-tracker endpoint
    /// (`/travel/clk/f`) and extracts the redirect URL from the HTML
    /// `<meta http-equiv="refresh">` response.
    ///
    /// Find the cheapest departure dates for a route over a date range.
    ///
    /// * `trip_duration_days = None` — one-way mode: scans the price calendar
    ///   over `months` from `config.departing_date` and returns dates sorted by
    ///   price ascending.
    /// * `trip_duration_days = Some(n)` — round-trip mode: queries the date
    ///   grid for all departure dates in the range and returns only
    ///   `(dep, dep + n)` pairs, sorted by price ascending.
    ///
    /// # Example
    /// ```no_run
    /// # async fn example() -> anyhow::Result<()> {
    /// use gflights::requests::api::ApiClient;
    /// use gflights::parsers::common::{Location, PlaceType};
    /// use gflights::requests::config::Config;
    /// use chrono::{Months, NaiveDate};
    ///
    /// let client = ApiClient::new().await;
    /// let config = Config::builder()
    ///     .departure_location(Location {
    ///         loc_identifier: "LUX".into(),
    ///         loc_type: PlaceType::Airport,
    ///         location_name: None,
    ///     })
    ///     .destination_location(Location {
    ///         loc_identifier: "JFK".into(),
    ///         loc_type: PlaceType::Airport,
    ///         location_name: None,
    ///     })
    ///     .departing_date(NaiveDate::from_ymd_opt(2026, 9, 1).unwrap())
    ///     .build()?;
    ///
    /// // Cheapest one-way days over the next 3 months
    /// let oneway = client.cheapest_dates(&config, Months::new(3), None).await?;
    ///
    /// // Cheapest 7-night round trips over the next 3 months
    /// let roundtrip = client.cheapest_dates(&config, Months::new(3), Some(7)).await?;
    /// # Ok(())
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub async fn cheapest_dates(
        &self,
        config: &Config,
        months: Months,
        trip_duration_days: Option<u32>,
    ) -> Result<Vec<CheapDate>> {
        match trip_duration_days {
            None => {
                let graph = self.request_graph(config, months).await?;
                let mut results: Vec<CheapDate> = graph
                    .get_all_graphs()
                    .into_iter()
                    .filter_map(|e| {
                        e.proposed_trip_cost.as_ref().map(|c| CheapDate {
                            departure_date: e.proposed_departure_date,
                            return_date: e.proposed_return_date,
                            price: c.trip_cost.price,
                        })
                    })
                    .collect();
                results.sort_by_key(|e| e.price);
                Ok(results)
            }
            Some(n) => {
                let dep_start = config.departing_date;
                let n_duration = Duration::days(i64::from(n));
                let dep_end = dep_start + months;
                let ret_start = dep_start + n_duration;
                let ret_end = dep_end + n_duration;

                // request_date_grid requires a round-trip config with return_date set.
                let rt_config = Config {
                    return_date: Some(dep_start + n_duration),
                    trip_type: TripType::Return,
                    fixed_flights: FixedFlights::new(2),
                    ..config.clone()
                };

                let grid = self
                    .request_date_grid(&rt_config, dep_start, dep_end, ret_start, ret_end)
                    .await?;

                let mut results: Vec<CheapDate> = grid
                    .entries
                    .into_iter()
                    .filter(|e| e.return_date - e.departure_date == n_duration)
                    .map(|e| CheapDate {
                        departure_date: e.departure_date,
                        return_date: Some(e.return_date),
                        price: e.price,
                    })
                    .collect();
                results.sort_by_key(|e| e.price);
                Ok(results)
            }
        }
    }

    /// # Example
    /// ```no_run
    /// # async fn example(client: gflights::requests::api::ApiClient, token: &str) {
    /// let url = client.resolve_booking_url(token).await.unwrap();
    /// println!("Book here: {url}");
    /// # }
    /// ```
    #[tracing::instrument(skip_all)]
    pub async fn resolve_booking_url(&self, click_token: &str) -> Result<String> {
        use std::time::{SystemTime, UNIX_EPOCH};

        // Honour the shared rate-limit flag — same guard as do_request().
        if self.rate_limited.load(Ordering::SeqCst) {
            return Err(anyhow::Error::new(RateLimitedError));
        }
        // Consume one rate-limiter slot.
        let _permit = self.rate_limiter.until_n_ready(NonZeroU32::MIN).await;

        let t = SystemTime::now().duration_since(UNIX_EPOCH)?.as_millis();

        let url = format!("{CLK_URL}?t={t}");
        // The token is URL-safe base64 so no extra percent-encoding is needed,
        // but we send it as a form body value.
        let body = format!("u={click_token}");

        tracing::debug!(%url, "resolving booking URL");

        let html = self
            .client
            .post(&url)
            .body(body)
            .headers(get_headers(None, "en", "GB", &self.user_agent)?)
            .send()
            .await?
            .text()
            .await?;

        // Response is: <meta content="0;url='https://...'" http-equiv="refresh">
        // Handle both single-quoted and double-quoted url values.
        let re = Regex::new(r#"(?i)url=['"]([^'"]+)['"]"#).unwrap();
        let raw = re
            .captures(&html)
            .and_then(|c| c.get(1))
            .map(|m| m.as_str().to_string())
            .ok_or_else(|| anyhow::anyhow!("no redirect URL found in clk/f response"))?;

        // The URL is embedded in HTML, so & is encoded as &amp; — decode it.
        Ok(raw.replace("&amp;", "&"))
    }

    /// Sends a single HTTP request, enforcing the shared rate-limit flag and
    /// retrying on transient server errors according to [`RetryConfig`].
    ///
    /// Returns [`RateLimitedError`] (as an `anyhow::Error`) in two situations:
    /// - The flag is already set from a previous 429 on this client or any clone.
    /// - The server responds with HTTP 429 (the flag is then set for all clones).
    ///
    /// Retries (up to `retry_config.max_attempts - 1` times) are performed for:
    /// - HTTP 500, 502, 503, 504
    /// - Connection timeouts (`reqwest::Error::is_timeout()`)
    ///
    /// 4xx errors (other than 429) are not retried.
    #[tracing::instrument(skip_all)]
    async fn do_request(
        &self,
        options: &impl ToRequestBody,
        currency: Option<Currency>,
        language: &str,
        country: &str,
    ) -> Result<Response> {
        // Refuse immediately if a previous request already received a 429.
        if self.rate_limited.load(Ordering::SeqCst) {
            return Err(anyhow::Error::new(RateLimitedError));
        }

        let req_payload = options.to_request_body()?;
        tracing::debug!(user_agent = %self.user_agent, "outgoing request User-Agent");
        let headers = get_headers(currency, language, country, &self.user_agent)?;

        let decoded_body = percent_encoding::percent_decode_str(&req_payload.body)
            .decode_utf8_lossy()
            .into_owned();
        tracing::trace!(
            url = %req_payload.url,
            body = %decoded_body,
            ?headers,
            "Outgoing POST request"
        );

        let max_attempts = self.retry_config.max_attempts.max(1);
        let base_delay = self.retry_config.base_delay_ms;
        let cap_delay = self.retry_config.cap_delay_ms;

        // `last_err` is only read when the loop is exhausted (attempt == max_attempts - 1).
        let mut last_err: anyhow::Error = anyhow::anyhow!("all retry attempts exhausted");

        for attempt in 0..max_attempts {
            if attempt > 0 {
                // Exponential back-off: base * 2^(attempt-1), capped, plus deterministic
                // jitter derived from the attempt number (no `rand` dependency needed).
                let backoff = (base_delay * (1u64 << (attempt - 1).min(30))).min(cap_delay);
                let jitter = (attempt as u64 * 37) % 101;
                let delay_ms = backoff + jitter;
                tracing::debug!(
                    attempt,
                    delay_ms,
                    "transient error — retrying after back-off"
                );
                tokio::time::sleep(std::time::Duration::from_millis(delay_ms)).await;
            }

            // Consume one rate-limiter slot per attempt.
            let _permit = self
                .rate_limiter
                .until_n_ready(NonZeroU32::MIN) // MIN == 1
                .await;

            let res = match self
                .client
                .post(req_payload.url.as_str())
                .body(req_payload.body.clone())
                .headers(headers.clone())
                .send()
                .await
            {
                Ok(r) => r,
                Err(e) if e.is_timeout() => {
                    tracing::warn!(attempt, error = %e, "request timed out");
                    last_err = e.into();
                    continue; // retry
                }
                Err(e) => return Err(e.into()), // non-transient network error
            };

            tracing::trace!(
                status = %res.status(),
                http_version = ?res.version(),
                "Response received"
            );

            match res.status() {
                StatusCode::OK => return Ok(res),
                StatusCode::TOO_MANY_REQUESTS => {
                    // Signal all clones to stop; they will return RateLimitedError
                    // on their next attempt without hitting the network.
                    self.rate_limited.store(true, Ordering::SeqCst);
                    return Err(anyhow::Error::new(RateLimitedError));
                }
                StatusCode::INTERNAL_SERVER_ERROR
                | StatusCode::BAD_GATEWAY
                | StatusCode::SERVICE_UNAVAILABLE
                | StatusCode::GATEWAY_TIMEOUT => {
                    tracing::warn!(
                        attempt,
                        status = %res.status(),
                        "server error — will retry if attempts remain"
                    );
                    last_err = anyhow::anyhow!("server error: {}", res.status());
                    // continue to next attempt
                }
                status => {
                    tracing::warn!(
                        http_version = ?res.version(),
                        status_code = %status,
                        "Unexpected HTTP response status"
                    );
                    return Ok(res);
                }
            }
        }

        Err(last_err)
    }
}

/// Fallback User-Agent used if a supplied override is not a valid header value
/// (in practice never, since real User-Agent strings are ASCII).
const DEFAULT_USER_AGENT: &str =
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:121.0) Gecko/20100101 Firefox/121.0";

/// Pool of real desktop browser User-Agent strings spanning several
/// browser/OS combinations. One is chosen per [`ApiClient`] construction so a
/// single static User-Agent does not fingerprint all traffic from this client.
const USER_AGENTS: &[&str] = &[
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0.0.0 Safari/537.36",
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:126.0) Gecko/20100101 Firefox/126.0",
    "Mozilla/5.0 (Macintosh; Intel Mac OS X 14.5; rv:126.0) Gecko/20100101 Firefox/126.0",
    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4.1 Safari/605.1.15",
    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36 Edg/124.0.0.0",
];

/// Picks a User-Agent from [`USER_AGENTS`] using a cheap time-seeded index.
///
/// No external RNG dependency is needed: the sub-second nanosecond component of
/// the wall clock at construction time has enough entropy to vary the choice
/// across separately-constructed clients.
fn pick_user_agent() -> &'static str {
    let idx = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.subsec_nanos() as usize)
        .unwrap_or(0)
        % USER_AGENTS.len();
    USER_AGENTS[idx]
}

/// Static base headers shared by all requests, with the given User-Agent.
///
/// Note: `x-goog-batchexecute-bgr` is intentionally omitted — its value is
/// difficult to reverse-engineer and its absence only slightly reduces result
/// accuracy.
fn base_headers(user_agent: &str) -> HeaderMap {
    let mut headers = HeaderMap::new();
    headers.insert(
        reqwest::header::ACCEPT_LANGUAGE,
        HeaderValue::from_static("en-US,en;q=0.9"),
    );
    headers.insert(
        reqwest::header::CONTENT_TYPE,
        HeaderValue::from_static("application/x-www-form-urlencoded;charset=UTF-8"),
    );
    headers.insert(
        reqwest::header::PRAGMA,
        HeaderValue::from_static("no-cache"),
    );
    headers.insert(
        reqwest::header::CACHE_CONTROL,
        HeaderValue::from_static("no-cache"),
    );
    headers.insert(
        reqwest::header::USER_AGENT,
        HeaderValue::from_str(user_agent)
            .unwrap_or_else(|_| HeaderValue::from_static(DEFAULT_USER_AGENT)),
    );
    headers.insert(reqwest::header::ACCEPT, HeaderValue::from_static("*/*"));
    headers
}

/// Returns request headers, optionally inserting the currency/locale preference header.
///
/// # Errors
/// Returns an error if the formatted header string contains characters that
/// are not valid as an HTTP header value (in practice this never occurs since
/// all [`Currency`] codes and locale tags are plain ASCII).
fn get_headers(
    currency: Option<Currency>,
    language: &str,
    country: &str,
    user_agent: &str,
) -> Result<HeaderMap> {
    let mut headers = base_headers(user_agent);
    if let Some(currency) = currency {
        let country_upper = country.to_uppercase();
        let currency_header = format!(
            r#"["{language}-{country_upper}","{country_upper}","{}",1,null,[-120],null,[[72534415,72446893,97456553,72399613]],1,[]]"#,
            currency
        );
        let header_value = reqwest::header::HeaderValue::from_str(&currency_header)
            .map_err(|e| anyhow::anyhow!("invalid currency header value: {e}"))?;
        headers.insert(
            reqwest::header::HeaderName::from_static("x-goog-ext-259736195-jspb"),
            header_value,
        );
    }
    Ok(headers)
}

/// Builds a reqwest [`Client`], optionally routing all traffic through `proxy`.
///
/// `proxy` accepts `http://`, `https://`, and `socks5://` URLs. Returns an
/// error if the proxy URL is invalid or the client cannot be built.
fn build_reqwest_client(proxy: Option<&str>) -> Result<Client> {
    let mut builder = Client::builder();
    if let Some(url) = proxy {
        builder = builder.proxy(
            reqwest::Proxy::all(url).map_err(|e| anyhow::anyhow!("invalid proxy {url:?}: {e}"))?,
        );
    }
    builder
        .build()
        .map_err(|e| anyhow::anyhow!("failed to build HTTP client: {e}"))
}

/// Retrieves the frontend version from the Google Flights website, reusing the
/// supplied client so any configured proxy applies here too.
async fn get_frontend_version(user_agent: &str, client: &Client) -> Option<String> {
    let headers = base_headers(user_agent); // no currency header needed for the version fetch
    let url = FLIGHTS_MAIN_PAGE.to_string();
    let res = client.get(&url).headers(headers).send().await.ok()?;

    let status = res.status();
    let final_url = res.url().to_string();
    // Only warn when the base path changes (different host or path).
    // Ignore minor redirects that only add/change query parameters.
    fn base_url(u: &str) -> &str {
        u.split_once('?').map_or(u, |(base, _)| base)
    }
    if base_url(&final_url) != base_url(&url) {
        tracing::warn!(
            original_url = %url,
            final_url = %final_url,
            status = %status,
            "main page request was redirected to a different URL"
        );
    } else {
        tracing::debug!(url = %final_url, status = %status, "main page response");
    }

    let response_body = res.text().await.ok()?;

    // Matches both:
    //   boq_travel-frontend-ui_20260527.01_p0  (old)
    //   boq_travel-frontend-flights-ui_20260527.01_p0  (new)
    let regex = match Regex::new(
        r"(boq_travel-frontend-[\w-]*ui_202[456789](01|02|03|04|05|06|07|08|09|10|11|12)\d{2}.\w{5,})",
    ) {
        Ok(r) => r,
        Err(e) => {
            tracing::warn!(error = %e, "failed to compile version regex; using fallback version");
            return None;
        }
    };

    let result = regex
        .captures_iter(&response_body)
        .map(|f| f.extract::<2>())
        .next();

    match &result {
        Some((version, _)) => tracing::debug!(version, "frontend version extracted"),
        None => tracing::warn!(
            response_len = response_body.len(),
            "frontend version not found in main page response; using hardcoded fallback"
        ),
    }

    Some(result?.0.to_string())
}

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

    /// Build a minimal ApiClient without hitting the network (no frontend-version fetch).
    fn make_client() -> ApiClient {
        let quota = governor::Quota::per_second(NonZeroU32::new(100).unwrap());
        ApiClient {
            rate_limiter: Arc::new(DefaultDirectRateLimiter::direct(quota)),
            client: Arc::new(Client::new()),
            frontend_version: "test".into(),
            rate_limited: Arc::new(AtomicBool::new(false)),
            retry_config: RetryConfig::default(),
            user_agent: pick_user_agent().to_string(),
            currency: Currency::default(),
            language: "en".to_string(),
            country: "GB".to_string(),
        }
    }

    #[test]
    fn not_rate_limited_by_default() {
        let client = make_client();
        assert!(!client.is_rate_limited());
    }

    #[test]
    fn pick_user_agent_is_from_pool() {
        assert!(USER_AGENTS.contains(&pick_user_agent()));
    }

    #[test]
    fn user_agent_pool_is_nonempty_and_valid_headers() {
        assert!(!USER_AGENTS.is_empty());
        for ua in USER_AGENTS {
            assert!(
                HeaderValue::from_str(ua).is_ok(),
                "User-Agent is not a valid header value: {ua}"
            );
        }
    }

    #[test]
    fn with_user_agent_overrides_and_getter_reflects_it() {
        let client = make_client().with_user_agent("Custom-UA/1.0");
        assert_eq!(client.user_agent(), "Custom-UA/1.0");
    }

    #[test]
    fn default_client_user_agent_is_from_pool() {
        let client = make_client();
        assert!(USER_AGENTS.contains(&client.user_agent()));
    }

    #[test]
    fn build_client_accepts_valid_proxies_and_none() {
        assert!(build_reqwest_client(None).is_ok());
        assert!(build_reqwest_client(Some("http://127.0.0.1:3128")).is_ok());
        assert!(build_reqwest_client(Some("https://proxy.example.com:8443")).is_ok());
        assert!(build_reqwest_client(Some("socks5://127.0.0.1:9050")).is_ok());
    }

    #[test]
    fn build_client_rejects_invalid_proxy() {
        let err = build_reqwest_client(Some("http://has a space/")).unwrap_err();
        assert!(
            err.to_string().contains("invalid proxy"),
            "unexpected error: {err}"
        );
    }

    #[test]
    fn rate_limited_flag_can_be_set_and_reset() {
        let client = make_client();
        client.rate_limited.store(true, Ordering::SeqCst);
        assert!(client.is_rate_limited());
        client.reset_rate_limit();
        assert!(!client.is_rate_limited());
    }

    #[test]
    fn clones_share_the_rate_limited_flag() {
        let client = make_client();
        let clone = client.clone();

        // Set on original — clone sees it.
        client.rate_limited.store(true, Ordering::SeqCst);
        assert!(clone.is_rate_limited());

        // Reset on clone — original sees it.
        clone.reset_rate_limit();
        assert!(!client.is_rate_limited());
    }

    #[test]
    fn rate_limited_error_is_downcasted() {
        let err = anyhow::Error::new(RateLimitedError);
        assert!(err.downcast_ref::<RateLimitedError>().is_some());
    }

    #[test]
    fn retry_config_default_values() {
        let cfg = RetryConfig::default();
        assert_eq!(cfg.max_attempts, 3);
        assert_eq!(cfg.base_delay_ms, 500);
        assert_eq!(cfg.cap_delay_ms, 30_000);
    }

    #[test]
    fn with_retry_config_overrides_defaults() {
        let client = make_client();
        let custom = RetryConfig {
            max_attempts: 5,
            base_delay_ms: 200,
            cap_delay_ms: 10_000,
        };
        let client = client.with_retry_config(custom.clone());
        assert_eq!(client.retry_config.max_attempts, 5);
        assert_eq!(client.retry_config.base_delay_ms, 200);
        assert_eq!(client.retry_config.cap_delay_ms, 10_000);
    }

    #[test]
    fn retry_config_max_attempts_one_means_no_retries() {
        // max_attempts=1 → the loop runs exactly once; no retry occurs
        let cfg = RetryConfig {
            max_attempts: 1,
            base_delay_ms: 500,
            cap_delay_ms: 30_000,
        };
        // max(1,1) == 1, so range 0..1 has a single iteration
        assert_eq!(cfg.max_attempts.max(1), 1);
    }

    // -----------------------------------------------------------------------
    // Booking URL: meta-refresh extraction logic (offline, structural)
    // -----------------------------------------------------------------------

    /// The regex used in `resolve_booking_url` extracts the URL from a
    /// single-quoted meta-refresh response.
    #[test]
    fn booking_url_regex_extracts_single_quoted_url() {
        let html =
            r#"<meta content="0;url='https://example.com/book?foo=bar'" http-equiv="refresh">"#;
        let re = Regex::new(r#"(?i)url=['"]([^'"]+)['"]"#).unwrap();
        let extracted = re
            .captures(html)
            .and_then(|c| c.get(1))
            .map(|m| m.as_str().to_string());
        assert_eq!(
            extracted,
            Some("https://example.com/book?foo=bar".to_string())
        );
    }

    /// The same regex handles double-quoted url values.
    #[test]
    fn booking_url_regex_extracts_double_quoted_url() {
        let _html = r#"<meta content="0;url=&quot;https://airline.com/booking?ref=123&amp;src=gf&quot;" http-equiv="refresh">"#;
        // double-quote form uses literal &quot; — after HTML-decode the url= value is double-quoted
        // here we test the raw pattern against a double-quoted variant directly
        let html2 =
            r#"<meta content='0;url="https://airline.com/booking?ref=123"' http-equiv="refresh">"#;
        let re = Regex::new(r#"(?i)url=['"]([^'"]+)['"]"#).unwrap();
        let extracted = re
            .captures(html2)
            .and_then(|c| c.get(1))
            .map(|m| m.as_str().to_string());
        assert_eq!(
            extracted,
            Some("https://airline.com/booking?ref=123".to_string())
        );
    }

    /// `&amp;` in the extracted URL is decoded to `&`.
    #[test]
    fn booking_url_amp_entity_is_decoded() {
        let raw = "https://example.com/book?foo=1&amp;bar=2";
        let decoded = raw.replace("&amp;", "&");
        assert_eq!(decoded, "https://example.com/book?foo=1&bar=2");
    }

    /// When the response contains no meta-refresh, the extraction returns `None`.
    #[test]
    fn booking_url_regex_returns_none_on_missing_url() {
        let html = "<html><head><title>Error</title></head><body>Not found</body></html>";
        let re = Regex::new(r#"(?i)url=['"]([^'"]+)['"]"#).unwrap();
        let extracted = re
            .captures(html)
            .and_then(|c| c.get(1))
            .map(|m| m.as_str().to_string());
        assert_eq!(extracted, None);
    }

    /// The chunk dimension used for 2-D date-grid splitting must produce chunks
    /// whose cell count stays within DATE_GRID_MAX_CELLS.
    #[test]
    fn date_grid_chunk_dim_fits_within_limit() {
        use parsers::date_grid_request::DATE_GRID_MAX_CELLS;
        let chunk_dim = (DATE_GRID_MAX_CELLS as f64).sqrt() as i64;
        let cells = chunk_dim * chunk_dim;
        assert!(
            cells <= DATE_GRID_MAX_CELLS as i64,
            "chunk_dim={chunk_dim} → {cells} cells exceeds limit {DATE_GRID_MAX_CELLS}"
        );
    }

    /// A 92-day × 92-day window (3 months) produces the expected number of chunks.
    ///
    /// chunk_dim = 14, so ceil(92/14) = 7 dep chunks × 7 ret chunks = 49 total.
    /// All 49 run concurrently in up to MAX_CONCURRENT=6 batches, not sequentially.
    #[test]
    fn date_grid_chunk_count_three_month_window() {
        use chrono::NaiveDate;
        use parsers::date_grid_request::DATE_GRID_MAX_CELLS;

        let chunk_dim = (DATE_GRID_MAX_CELLS as f64).sqrt() as i64; // 14
        let dep_start = NaiveDate::from_ymd_opt(2026, 9, 1).unwrap();
        let dep_end = dep_start + chrono::Months::new(3);
        let ret_start = dep_start + Duration::days(7);
        let ret_end = dep_end + Duration::days(7);

        // Replicate the enumeration logic from request_date_grid.
        let mut count = 0usize;
        let mut d = dep_start;
        while d <= dep_end {
            let de = (d + Duration::days(chunk_dim - 1)).min(dep_end);
            let dd = (de - d).num_days() + 1;
            let max_ret = ((DATE_GRID_MAX_CELLS as i64) / dd).max(1);
            let mut r = ret_start;
            while r <= ret_end {
                let re = (r + Duration::days(max_ret - 1)).min(ret_end);
                count += 1;
                r = re + Duration::days(1);
            }
            d = de + Duration::days(1);
        }
        // Sep+Oct+Nov = 91 days dep window, 91 days ret window (shifted by 7).
        // ceil(91/14) = 7 dep chunks; ret chunks per dep chunk ≤ 7 → ~46 total.
        assert_eq!(
            count, 46,
            "expected 46 chunks for a 3-month round-trip scan (Sep-Nov)"
        );
    }
}