nrouter 3.1.4

nRouter SDK — one API key for models across six provider clouds
Documentation
//! Per-request metadata carried on nRouter response headers.
//!
//! Every field is optional on purpose. The gateway omits a header rather than
//! sending a placeholder, and the two that matter most are omissions:
//! `x-nr-request-cost` is ABSENT when the model is unpriced — never `0` — and
//! `x-nr-limit-source` is absent when nothing measured the refusal.

/// Metadata from the `x-nr-*` headers of one response.
#[derive(Debug, Clone, Default, PartialEq)]
pub struct ResponseMeta {
    /// Present on every response; the join key for a spend row or a log line.
    pub request_id: Option<String>,
    /// Milliseconds the gateway measured from edge arrival to response headers
    /// ready.
    ///
    /// TIME TO HEADERS, not time to the last byte: on a streamed response the
    /// headers are ready before the first token, so this is never a
    /// total-generation figure.
    pub latency_ms: Option<u64>,
    /// The gateway's OpenTelemetry trace id, absent when no valid trace exists.
    ///
    /// A caller may SEND `x-nr-trace-id` (and `x-nr-session-id`) to correlate
    /// its own spans; the gateway overwrites the response value with its own,
    /// so join on this rather than assuming it echoes what was sent.
    pub trace_id: Option<String>,
    /// Exact USD cost. `None` when unpriced — treating that as `0.0` would
    /// report a free request, which no enabled model is.
    pub cost: Option<f64>,
    /// `exact` or `unpriced`.
    pub cost_status: Option<String>,
    pub model: Option<String>,
    pub input_tokens: Option<u64>,
    pub output_tokens: Option<u64>,
    pub total_tokens: Option<u64>,
    pub cache_read_tokens: Option<u64>,
    pub cache_write_tokens: Option<u64>,
    /// On a 429, which limit measured the refusal.
    pub limit_source: Option<String>,
    /// Set when this request crossed a soft budget you configured; it still
    /// served. `<scope> soft_budget <spend>/<ceiling>`, e.g.
    /// `org soft_budget 80.00/100.00`.
    pub budget_warning: Option<String>,
    /// Posture of the PRE-CALL guardrail chain: `none`, `monitor`, `redacted`,
    /// `pass`, `partial`, `blocked` or `unavailable`, matched exactly and
    /// case-sensitively. `redacted` means an enforcing chain REWROTE part of
    /// the prompt before the provider saw it and the request then served;
    /// `partial` means only that some content went uninspected, never that
    /// anything was rewritten.
    ///
    /// `None` means the gateway made NO guardrail claim about this response —
    /// never "no guardrail applied", which is the explicit `none`. Posture only
    /// by design: policy name, policy id, detector family, rule count and (for
    /// `partial`) which channel went uninspected are deliberately withheld.
    pub guardrails: Option<String>,
    /// On a 401, the gateway's stable reason.
    pub auth_reason: Option<String>,
    /// `hit` or `miss`; absent when the response cache did not participate.
    pub response_cache: Option<String>,
    /// Age in seconds of a response-cache hit.
    pub response_cache_age: Option<u64>,
    /// Prompt compression outcome: `applied`, `not_requested`, `off`, or `skipped`.
    pub compression: Option<String>,
    /// Which chain entry answered: `direct` or `fallback:<n>`.
    pub routing: Option<String>,
    /// Provider calls made for this request, retries and failovers alike.
    pub attempts: Option<u64>,
    /// The top intent category evaluated by the preflight chain, if intent routing was requested.
    pub intent: Option<String>,
    /// How this response was funded.
    pub funding_source: Option<String>,
    /// When the current usage allowance resets.
    pub allowance_reset: Option<u64>,
    /// True when the served model carries a retirement date in the gateway catalog.
    pub model_deprecated: Option<bool>,
    /// Human-readable retirement warning when `x-nr-model-deprecated` is `true`.
    pub deprecation_notice: Option<String>,
}

/// Every header this SDK reads, exactly as the spec names them.
pub const HEADER_NAMES: [&str; 25] = [
    "x-nr-request-id",
    "x-nr-latency-ms",
    "x-nr-trace-id",
    "x-nr-request-cost",
    "x-nr-cost-status",
    "x-nr-model",
    "x-nr-input-tokens",
    "x-nr-output-tokens",
    "x-nr-total-tokens",
    "x-nr-cache-read-tokens",
    "x-nr-cache-write-tokens",
    "x-nr-limit-source",
    "x-nr-budget-warning",
    "x-nr-guardrails",
    "x-nr-auth-reason",
    "x-nr-response-cache",
    "x-nr-response-cache-age",
    "x-nr-compression",
    "x-nr-routing",
    "x-nr-attempts",
    "x-nr-intent",
    "x-nr-funding-source",
    "x-nr-allowance-reset",
    "x-nr-model-deprecated",
    "x-nr-deprecation-notice",
];

impl ResponseMeta {
    /// Parse from anything that can look a header up by lowercase name.
    ///
    /// An unparseable numeric header yields `None` rather than a default: a
    /// zero here would be indistinguishable from a real zero.
    pub fn from_lookup<F>(get: F) -> Self
    where
        F: Fn(&str) -> Option<String>,
    {
        let num = |name: &str| get(name).and_then(|v| v.parse::<u64>().ok());
        let flag = |name: &str| match get(name).as_deref().map(str::trim) {
            Some("true") => Some(true),
            Some("false") => Some(false),
            _ => None,
        };
        Self {
            request_id: get("x-nr-request-id"),
            // `num`, not a raw read: the gateway sends whole milliseconds, so
            // a fractional or garbage value is a mangled header rather than a
            // latency a caller should chart.
            latency_ms: num("x-nr-latency-ms"),
            trace_id: get("x-nr-trace-id"),
            cost: get("x-nr-request-cost").and_then(|v| v.parse::<f64>().ok()),
            cost_status: get("x-nr-cost-status"),
            model: get("x-nr-model"),
            input_tokens: num("x-nr-input-tokens"),
            output_tokens: num("x-nr-output-tokens"),
            total_tokens: num("x-nr-total-tokens"),
            cache_read_tokens: num("x-nr-cache-read-tokens"),
            cache_write_tokens: num("x-nr-cache-write-tokens"),
            limit_source: get("x-nr-limit-source"),
            budget_warning: get("x-nr-budget-warning"),
            guardrails: get("x-nr-guardrails"),
            auth_reason: get("x-nr-auth-reason"),
            response_cache: get("x-nr-response-cache"),
            response_cache_age: num("x-nr-response-cache-age"),
            compression: get("x-nr-compression"),
            routing: get("x-nr-routing"),
            attempts: num("x-nr-attempts"),
            intent: get("x-nr-intent"),
            funding_source: get("x-nr-funding-source"),
            allowance_reset: num("x-nr-allowance-reset"),
            model_deprecated: flag("x-nr-model-deprecated"),
            deprecation_notice: get("x-nr-deprecation-notice"),
        }
    }

    /// Parse from a `reqwest`/`http` header map.
    pub fn from_headers(headers: &reqwest::header::HeaderMap) -> Self {
        Self::from_lookup(|name| {
            headers
                .get(name)
                .and_then(|v| v.to_str().ok())
                .map(str::to_owned)
        })
    }

    /// True when the gateway priced this request exactly.
    pub fn is_priced(&self) -> bool {
        self.cost_status.as_deref() == Some("exact") && self.cost.is_some()
    }

    /// True when the response came from the nRouter response cache.
    pub fn is_cache_hit(&self) -> bool {
        self.response_cache.as_deref() == Some("hit")
    }

    /// True when the response was a cache miss.
    pub fn is_cache_miss(&self) -> bool {
        self.response_cache.as_deref() == Some("miss")
    }

    /// Returns the age of a cached response in seconds, or 0 if not cached or absent.
    pub fn cache_age_seconds(&self) -> u64 {
        self.response_cache_age.unwrap_or(0)
    }

    /// Parses structured budget warning information if present.
    pub fn parse_budget_warning(&self) -> Option<BudgetWarningInfo> {
        let warning = self.budget_warning.as_deref()?.trim();
        let parts: Vec<&str> = warning.split_whitespace().collect();
        if parts.len() != 3 || parts[1] != "soft_budget" {
            return None;
        }
        let amounts: Vec<&str> = parts[2].split('/').collect();
        if amounts.len() != 2 {
            return None;
        }
        let spend = amounts[0].parse::<f64>().ok()?;
        let ceiling = amounts[1].parse::<f64>().ok()?;
        if spend.is_nan()
            || spend.is_infinite()
            || spend < 0.0
            || ceiling.is_nan()
            || ceiling.is_infinite()
            || ceiling <= 0.0
        {
            return None;
        }
        Some(BudgetWarningInfo {
            scope: parts[0].to_string(),
            spend,
            ceiling,
        })
    }
}

/// Structured details from an `x-nr-budget-warning` header.
#[derive(Debug, Clone, PartialEq)]
pub struct BudgetWarningInfo {
    pub scope: String,
    pub spend: f64,
    pub ceiling: f64,
}

/// Extract trace routing headers (e.g. `x-nr-request-id`) from response metadata.
pub fn extract_trace_headers(meta: &ResponseMeta) -> std::collections::HashMap<String, String> {
    let mut out = std::collections::HashMap::new();
    if let Some(ref req_id) = meta.request_id {
        out.insert("x-nr-request-id".to_string(), req_id.clone());
    }
    out
}

/// Inject trace context headers, returning an error if trace_id or session_id contains CRLF characters.
pub fn with_trace_context(
    headers: &std::collections::HashMap<String, String>,
    trace_id: Option<&str>,
    session_id: Option<&str>,
) -> Result<std::collections::HashMap<String, String>, crate::errors::NRouterError> {
    if let Some(tid) = trace_id {
        if tid.contains('\r') || tid.contains('\n') {
            return Err(crate::errors::NRouterError::Configuration(
                "trace_id must not contain CRLF characters".into(),
            ));
        }
    }
    if let Some(sid) = session_id {
        if sid.contains('\r') || sid.contains('\n') {
            return Err(crate::errors::NRouterError::Configuration(
                "session_id must not contain CRLF characters".into(),
            ));
        }
    }

    let mut out = std::collections::HashMap::with_capacity(headers.len() + 2);
    for (k, v) in headers {
        if !v.contains('\r') && !v.contains('\n') {
            out.insert(k.clone(), v.clone());
        }
    }
    if let Some(tid) = trace_id {
        out.insert("x-nr-trace-id".to_string(), tid.to_string());
    }
    if let Some(sid) = session_id {
        out.insert("x-nr-session-id".to_string(), sid.to_string());
    }
    Ok(out)
}