thaler 0.1.0

The Thaler API: financial data from SEC filings, with the source filing for every value.
Documentation
//! The account's limits, as every answer reports them.
//!
//! The API carries the IETF RateLimit header fields on every answer to a
//! request with a valid key:
//!
//! ```text
//! ratelimit-policy: "minute";q=60;w=60, "month";q=20000, "concurrent";q=4;qu="concurrent-requests"
//! ratelimit: "minute";r=59;t=42, "month";r=19873;t=536400, "concurrent";r=3
//! ```
//!
//! `q` is the limit and `w` its window in seconds; `r` is what remains and
//! `t` the seconds until the count resets. The client reads them to pace
//! itself, and every [`Response`](crate::Response) and
//! [`ApiError`](crate::ApiError) carries them parsed.

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

use reqwest::header::HeaderMap;

/// The longest wait a header can ask for, a year: past that the value is
/// nonsense, and a `Duration` must not overflow on it.
pub(crate) const MAX_HEADER_SECONDS: u64 = 366 * 86_400;

/// One limit: what it allows, what remains, and when it resets.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct Window {
    /// `minute`, `month` or `concurrent`.
    pub name: String,
    /// The requests the policy allows, when the policy was reported.
    pub limit: Option<u64>,
    /// The requests left, when reported.
    pub remaining: Option<u64>,
    /// Seconds until the count resets, when reported; the concurrent limit
    /// has none.
    pub reset_seconds: Option<u64>,
}

/// The account's limits as one answer reported them.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct RateLimit {
    /// Requests a minute.
    pub minute: Option<Window>,
    /// Requests a month.
    pub month: Option<Window>,
    /// Requests at a time.
    pub concurrent: Option<Window>,
}

impl RateLimit {
    /// The windows with nothing left, in the order the API lists them.
    pub fn exhausted(&self) -> Vec<&Window> {
        [&self.minute, &self.month, &self.concurrent]
            .into_iter()
            .flatten()
            .filter(|window| window.remaining == Some(0))
            .collect()
    }
}

fn items(header: Option<&str>) -> HashMap<String, HashMap<String, String>> {
    let mut out = HashMap::new();
    let Some(header) = header else {
        return out;
    };
    for item in header.split(',') {
        let item = item.trim();
        let Some(rest) = item.strip_prefix('"') else {
            continue;
        };
        let Some((name, params)) = rest.split_once('"') else {
            continue;
        };
        let params: HashMap<String, String> = params
            .split(';')
            .filter_map(|param| param.trim().split_once('='))
            .map(|(key, value)| {
                (
                    key.trim().to_string(),
                    value.trim().trim_matches('"').to_string(),
                )
            })
            .collect();
        out.insert(name.to_string(), params);
    }
    out
}

fn header(headers: &HeaderMap, name: &str) -> Option<String> {
    headers
        .get(name)
        .and_then(|value| value.to_str().ok())
        .map(str::to_string)
}

/// The limits in an answer's headers, or `None` when it carries none (an
/// answer to a request without a valid key).
pub fn parse_rate_limit(headers: &HeaderMap) -> Option<RateLimit> {
    let state = items(header(headers, "ratelimit").as_deref());
    let policy = items(header(headers, "ratelimit-policy").as_deref());
    if state.is_empty() && policy.is_empty() {
        return None;
    }
    let window = |name: &str| -> Option<Window> {
        if !state.contains_key(name) && !policy.contains_key(name) {
            return None;
        }
        let number = |map: &HashMap<String, HashMap<String, String>>, key: &str| {
            map.get(name)
                .and_then(|params| params.get(key))
                .and_then(|value| value.parse().ok())
        };
        Some(Window {
            name: name.to_string(),
            limit: number(&policy, "q"),
            remaining: number(&state, "r"),
            reset_seconds: number(&state, "t").map(|t: u64| t.min(MAX_HEADER_SECONDS)),
        })
    };
    Some(RateLimit {
        minute: window("minute"),
        month: window("month"),
        concurrent: window("concurrent"),
    })
}

/// `Retry-After`, when the answer carries one as seconds; a year at most.
pub fn parse_retry_after(headers: &HeaderMap) -> Option<Duration> {
    header(headers, "retry-after")?
        .trim()
        .parse::<f64>()
        .ok()
        .filter(|seconds| seconds.is_finite())
        .map(|seconds| Duration::from_secs_f64(seconds.clamp(0.0, MAX_HEADER_SECONDS as f64)))
}

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

    #[test]
    fn the_ietf_fields_are_read() {
        let mut headers = HeaderMap::new();
        headers.insert(
            "ratelimit-policy",
            HeaderValue::from_static("\"minute\";q=60;w=60, \"month\";q=20000, \"concurrent\";q=4;qu=\"concurrent-requests\""),
        );
        headers.insert(
            "ratelimit",
            HeaderValue::from_static(
                "\"minute\";r=59;t=42, \"month\";r=19873;t=536400, \"concurrent\";r=3",
            ),
        );
        let limits = parse_rate_limit(&headers).unwrap();
        let minute = limits.minute.as_ref().unwrap();
        assert_eq!(
            (minute.limit, minute.remaining, minute.reset_seconds),
            (Some(60), Some(59), Some(42))
        );
        let concurrent = limits.concurrent.as_ref().unwrap();
        assert_eq!(
            (
                concurrent.limit,
                concurrent.remaining,
                concurrent.reset_seconds
            ),
            (Some(4), Some(3), None)
        );
        assert!(limits.exhausted().is_empty());

        let mut spent = HeaderMap::new();
        spent.insert(
            "ratelimit",
            HeaderValue::from_static(
                "\"minute\";r=0;t=23, \"month\";r=19811;t=536400, \"concurrent\";r=4",
            ),
        );
        spent.insert("retry-after", HeaderValue::from_static("23"));
        let limits = parse_rate_limit(&spent).unwrap();
        assert_eq!(
            limits
                .exhausted()
                .iter()
                .map(|w| w.name.as_str())
                .collect::<Vec<_>>(),
            ["minute"]
        );
        assert_eq!(limits.minute.unwrap().limit, None);
        assert_eq!(parse_retry_after(&spent), Some(Duration::from_secs(23)));
        assert_eq!(parse_rate_limit(&HeaderMap::new()), None);
        assert_eq!(parse_retry_after(&HeaderMap::new()), None);
    }

    #[test]
    fn a_value_past_reason_is_a_year_not_a_panic() {
        let mut absurd = HeaderMap::new();
        absurd.insert("retry-after", HeaderValue::from_static("1e300"));
        absurd.insert(
            "ratelimit",
            HeaderValue::from_static("\"minute\";r=0;t=99999999999999999999"),
        );
        assert_eq!(
            parse_retry_after(&absurd),
            Some(Duration::from_secs(MAX_HEADER_SECONDS))
        );
        // A `t` that does not fit a u64 does not parse; one that does is
        // clamped.
        assert_eq!(
            parse_rate_limit(&absurd)
                .unwrap()
                .minute
                .unwrap()
                .reset_seconds,
            None
        );
        absurd.insert(
            "ratelimit",
            HeaderValue::from_static("\"minute\";r=0;t=9000000000000000000"),
        );
        assert_eq!(
            parse_rate_limit(&absurd)
                .unwrap()
                .minute
                .unwrap()
                .reset_seconds,
            Some(MAX_HEADER_SECONDS)
        );
        let mut negative = HeaderMap::new();
        negative.insert("retry-after", HeaderValue::from_static("-5"));
        assert_eq!(parse_retry_after(&negative), Some(Duration::ZERO));
        let mut date = HeaderMap::new();
        date.insert(
            "retry-after",
            HeaderValue::from_static("Wed, 21 Oct 2026 07:28:00 GMT"),
        );
        assert_eq!(parse_retry_after(&date), None);
    }
}