solari_browser/

client.rs

//! [`Client`] plus the `sessions` / `profiles` / `proxy` resource namespaces.
//! Ports `sdk/src/index.ts` (the TypeScript reference) minus `launch()`.
//!
//! One deliberate divergence from the reference: the TS SDK wraps every session
//! endpoint in a Node-side `LocalProxy` loopback rewrite. This crate returns the
//! UPSTREAM `wsEndpoint` / `cdpEndpoint` verbatim — there is no proxy to route
//! through, and callers connect straight to the gateway.

use std::collections::BTreeMap;
use std::time::Duration;

use serde_json::{json, Map, Value};
use url::Url;

use crate::error::{api_error, SolariError, SolariErrorCode};
use crate::http::HttpTransport;
use crate::profile_editor::ProfileEditor;
use crate::types::{
    CreateSessionRequest, CreateSessionResponse, Profile, ProfileSaveResponse, ProfileSaveResult,
    ProxyCountries, ProxySpec, ReplayUrl, ReplayUrlResponse, Session, SessionList, SessionView,
    SolariRegion,
    StorageState,
};

pub(crate) const DEFAULT_MAX_ATTEMPTS: u32 = 2;
pub(crate) const DEFAULT_BACKOFF_MS: u64 = 500;
pub(crate) const DEFAULT_TIMEOUT_MS: u64 = 90_000;
const STORAGE_STATE_FETCH_TIMEOUT: Duration = Duration::from_secs(8);

/// Options for constructing a [`Client`].
///
/// There is no environment-variable fallback by design — the API key and base
/// URL are always explicit constructor arguments.
#[derive(Clone)]
pub struct ClientOptions {
    pub api_key: String,
    pub base_url: String,
    /// Total attempts per request (including the first). Default 2.
    pub max_attempts: u32,
    /// Fixed delay between attempts. Default 500ms.
    pub backoff_ms: u64,
    /// Per-request timeout. Default 90000ms.
    pub timeout_ms: u64,
}

/// Hand-written so the API key is never printed. Do not derive this.
impl std::fmt::Debug for ClientOptions {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ClientOptions")
            .field("api_key", &"<redacted>")
            .field("base_url", &self.base_url)
            .field("max_attempts", &self.max_attempts)
            .field("backoff_ms", &self.backoff_ms)
            .field("timeout_ms", &self.timeout_ms)
            .finish()
    }
}

impl ClientOptions {
    /// Point the client at an explicit base URL (staging / self-hosted gateway).
    pub fn new(api_key: impl Into<String>, base_url: impl Into<String>) -> Self {
        ClientOptions {
            api_key: api_key.into(),
            base_url: base_url.into(),
            max_attempts: DEFAULT_MAX_ATTEMPTS,
            backoff_ms: DEFAULT_BACKOFF_MS,
            timeout_ms: DEFAULT_TIMEOUT_MS,
        }
    }

    /// Point the client at a region's public API. [`SolariRegion::UsWest`]
    /// resolves to `https://api.getsolari.com`.
    pub fn for_region(api_key: impl Into<String>, region: SolariRegion) -> Self {
        ClientOptions::new(api_key, region.base_url())
    }

    /// Point the client at the default region (`us-west`).
    pub fn default_region(api_key: impl Into<String>) -> Self {
        ClientOptions::for_region(api_key, SolariRegion::default())
    }

    pub fn max_attempts(mut self, n: u32) -> Self {
        self.max_attempts = n;
        self
    }

    pub fn backoff_ms(mut self, ms: u64) -> Self {
        self.backoff_ms = ms;
        self
    }

    pub fn timeout_ms(mut self, ms: u64) -> Self {
        self.timeout_ms = ms;
        self
    }
}

/// Options accepted by `POST /sessions`.
///
/// Falsy fields are omitted from the request body; if every field is falsy the
/// request is sent with no body at all.
#[derive(Debug, Clone, Default)]
pub struct CreateSessionOptions {
    /// Attach a stored browser profile (cookies + localStorage).
    pub profile_id: Option<String>,
    /// Enable session recording. Off by default.
    pub recording: bool,
    /// Enable the runtime stealth shim. Off by default.
    pub stealth: bool,
    /// Enable managed captcha solving. Requires `stealth`.
    pub captcha: bool,
    /// Request managed proxy egress. Requires `stealth`.
    pub proxy: Option<ProxySpec>,
    /// End the session earlier than the plan maximum, in milliseconds. `None`
    /// (or zero) leaves the plan maximum. The gateway counts whole seconds, so the
    /// value is rounded up (1001 ms is 2 s), and it refuses anything under 60 s.
    pub session_timeout_ms: Option<u64>,
    /// The same limit in seconds.
    #[deprecated(since = "0.5.0", note = "use `session_timeout_ms`; it wins when both are set")]
    pub timeout_seconds: Option<u32>,
    /// Hold the session after the client disconnects, until its deadline
    /// (`session_timeout_ms`, else an hour, never past the plan maximum) or until
    /// it is released, so a dropped client can reconnect.
    pub keep_alive: bool,
    /// Free-form JSON stored with the session and returned by `get` and `list`.
    pub user_metadata: Option<Map<String, Value>>,
}

impl CreateSessionOptions {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn profile_id(mut self, id: impl Into<String>) -> Self {
        self.profile_id = Some(id.into());
        self
    }

    pub fn recording(mut self, on: bool) -> Self {
        self.recording = on;
        self
    }

    pub fn stealth(mut self, on: bool) -> Self {
        self.stealth = on;
        self
    }

    pub fn captcha(mut self, on: bool) -> Self {
        self.captcha = on;
        self
    }

    pub fn proxy(mut self, spec: impl Into<ProxySpec>) -> Self {
        self.proxy = Some(spec.into());
        self
    }

    /// Session lifetime in milliseconds; see [`CreateSessionOptions::session_timeout_ms`].
    pub fn session_timeout_ms(mut self, ms: u64) -> Self {
        self.session_timeout_ms = Some(ms);
        self
    }

    /// Session lifetime in seconds.
    #[deprecated(since = "0.5.0", note = "use `session_timeout_ms`")]
    #[allow(deprecated)]
    pub fn timeout_seconds(mut self, seconds: u32) -> Self {
        self.timeout_seconds = Some(seconds);
        self
    }

    pub fn keep_alive(mut self, on: bool) -> Self {
        self.keep_alive = on;
        self
    }

    pub fn user_metadata(mut self, metadata: Map<String, Value>) -> Self {
        self.user_metadata = Some(metadata);
        self
    }
}

/// Filters and paging for [`Sessions::list`]. The default lists the first page.
#[derive(Debug, Clone, Default)]
pub struct ListSessionsOptions {
    /// Page size; `None` uses the gateway default.
    pub limit: Option<u32>,
    /// Continue from a previous page's `next_cursor`.
    pub cursor: Option<String>,
    /// Keep sessions whose `user_metadata` has all these string values (at most
    /// 10 pairs; keys and values cannot contain a single quote).
    pub metadata: BTreeMap<String, String>,
}

/// Talks the Solari Browser control-plane REST API.
#[derive(Debug, Clone)]
pub struct Client {
    pub(crate) http: HttpTransport,
}

impl Client {
    pub fn new(opts: ClientOptions) -> Result<Self, SolariError> {
        if opts.api_key.is_empty() {
            return Err(SolariError::config("Solari: apiKey is required"));
        }
        if opts.base_url.is_empty() {
            return Err(SolariError::config("Solari: baseUrl is required"));
        }
        let base_url = opts.base_url.trim_end_matches('/').to_string();
        let http = HttpTransport::new(
            opts.api_key,
            base_url,
            opts.max_attempts,
            opts.backoff_ms,
            opts.timeout_ms,
        )?;
        Ok(Client { http })
    }

    /// Session lifecycle: create / get / release / replay.
    pub fn sessions(&self) -> Sessions<'_> {
        Sessions { client: self }
    }

    /// Stored browser profiles.
    pub fn profiles(&self) -> Profiles<'_> {
        Profiles { client: self }
    }

    /// Managed proxy metadata.
    pub fn proxy(&self) -> Proxy<'_> {
        Proxy { client: self }
    }

    /// The resolved API base URL (trailing slash stripped).
    pub fn base_url(&self) -> &str {
        self.http.base_url()
    }
}

// ---------------------------------------------------------------------------
// sessions
// ---------------------------------------------------------------------------

/// The `sessions` namespace. Obtain via [`Client::sessions`].
pub struct Sessions<'a> {
    client: &'a Client,
}

impl Sessions<'_> {
    /// `POST /sessions` — acquire a browser session.
    pub async fn create(&self, options: CreateSessionOptions) -> Result<Session, SolariError> {
        let req = CreateSessionRequest {
            // TS: `if (options?.profileId)` — falsy (unset OR empty) is omitted.
            profile_id: options
                .profile_id
                .clone()
                .filter(|p| !p.is_empty()),
            recording: options.recording,
            stealth: options.stealth,
            captcha: options.captcha,
            proxy: options.proxy.clone(),
            timeout_seconds: session_timeout_seconds(
                options.session_timeout_ms,
                #[allow(deprecated)]
                options.timeout_seconds,
            )?,
            keep_alive: options.keep_alive,
            user_metadata: options.user_metadata.clone(),
        };
        let body = serde_json::to_value(&req)
            .map_err(|e| SolariError::protocol(format!("Solari: bad create body: {e}")))?;
        // Omit the body entirely when nothing was set.
        let body = match body.as_object() {
            Some(o) if o.is_empty() => None,
            _ => Some(body),
        };

        let res = self
            .client
            .http
            .request_with_key(
                "POST",
                "/sessions",
                body.as_ref(),
                // A create allocates a slot and launches a browser before it can
                // answer, so a response lost after that point would make a retry
                // a SECOND session.
                Some(&crate::http::new_idempotency_key()),
            )
            .await?;
        if !res.ok() {
            return Err(api_error("POST", "/sessions", res.status, &res.body));
        }

        let data: CreateSessionResponse = serde_json::from_str(&res.body).map_err(|e| {
            SolariError::protocol(format!("Solari: unexpected session response: {e}"))
        })?;

        let (session_id, ws_endpoint) = match (data.session_id.clone(), data.ws_endpoint.clone()) {
            (Some(id), Some(ws)) if !id.is_empty() && !ws.is_empty() => (id, ws),
            _ => {
                return Err(SolariError::protocol(format!(
                    "Solari: unexpected session response: {}",
                    res.body
                )))
            }
        };

        let cdp_endpoint = data
            .cdp_endpoint
            .clone()
            .filter(|c| !c.is_empty())
            .unwrap_or_else(|| derive_cdp_from_ws(&ws_endpoint));

        let expires_at = data
            .expires_at
            .clone()
            .filter(|e| !e.is_empty())
            .unwrap_or_else(|| iso8601_utc_in(Duration::from_secs(60 * 60)));

        let mut session = Session {
            id: session_id,
            ws_endpoint,
            cdp_endpoint,
            expires_at,
            storage_state: None,
            proxy: data.proxy,
            user_metadata: data.user_metadata,
        };

        // Storage state is only populated when a profile was requested — TS
        // gates on `options?.profileId !== undefined`.
        if options.profile_id.is_some() {
            session.storage_state = Some(match data.storage_state_url {
                // `storageStateUrl` present → fetch the presigned object.
                Some(Some(ssu)) => self.fetch_presigned_storage_state(ssu.url.as_deref()).await?,
                // Explicit null → profile exists but is empty.
                Some(None) => None,
                // Absent → fall back to any inline state (TS: `?? null`).
                None => data.storage_state.flatten(),
            });
        }

        Ok(session)
    }

    /// `GET /sessions/:id`.
    pub async fn get(&self, id: &str) -> Result<SessionView, SolariError> {
        let path = format!("/sessions/{}", enc(id));
        let res = self.client.http.request("GET", &path, None).await?;
        if !res.ok() {
            return Err(api_error("GET", &path, res.status, &res.body));
        }
        serde_json::from_str(&res.body)
            .map_err(|e| SolariError::protocol(format!("Solari: unexpected session view: {e}")))
    }

    /// `GET /sessions` — one page of the organisation's sessions. Rows never
    /// carry the websocket endpoints; call [`Sessions::get`] for those.
    pub async fn list(&self, options: ListSessionsOptions) -> Result<SessionList, SolariError> {
        let mut query: Vec<String> = Vec::new();
        if let Some(limit) = options.limit.filter(|l| *l > 0) {
            query.push(format!("limit={limit}"));
        }
        if let Some(cursor) = options.cursor.as_deref().filter(|c| !c.is_empty()) {
            query.push(format!("cursor={}", enc(cursor)));
        }
        if !options.metadata.is_empty() {
            query.push(format!("q={}", enc(&metadata_filter(&options.metadata)?)));
        }
        let path = if query.is_empty() {
            "/sessions".to_string()
        } else {
            format!("/sessions?{}", query.join("&"))
        };
        let res = self.client.http.request("GET", &path, None).await?;
        if !res.ok() {
            return Err(api_error("GET", "/sessions", res.status, &res.body));
        }
        serde_json::from_str(&res.body)
            .map_err(|e| SolariError::protocol(format!("Solari: unexpected session list: {e}")))
    }

    /// `DELETE /sessions/:id` — release the session. A bare 404 is tolerated
    /// (the session already ended).
    ///
    /// A 404 carrying [`SolariErrorCode::InvalidSessionId`] is an error. The
    /// gateway acks 204 for any authentic session id, including one whose
    /// session has already ended — the handler is idempotent by design and never
    /// consults the pool before acking. So a 404 does not mean "already
    /// released"; it means the gateway refused the id (malformed, forged, or
    /// another org's) and released nothing, leaving the pool slot held until
    /// orphan-grace. Treating that as success is what made these releases leak
    /// slots silently.
    ///
    /// A bare 404 with no code stays tolerated — that is a pre-InvalidSessionId
    /// gateway, where a 404 may legitimately mean the session is already gone.
    /// Mirrors `releaseRejection` in sdk/src/index.ts.
    ///
    /// Unlike the TS SDK there is no fire-and-forget variant; this is the
    /// equivalent of `releaseAndWait`. Spawn it yourself if you don't want to
    /// await the round-trip.
    pub async fn release(&self, id: &str) -> Result<(), SolariError> {
        let path = format!("/sessions/{}", enc(id));
        let res = self.client.http.request("DELETE", &path, None).await?;
        if res.ok() {
            return Ok(());
        }
        let err = api_error("DELETE", &path, res.status, &res.body);
        if res.status == 404 && err.code() != Some(&SolariErrorCode::InvalidSessionId) {
            return Ok(());
        }
        Err(err)
    }

    /// `GET /sessions/:id/replay-url` — presigned URL for the session's replay.
    /// Available ~1-3s after [`Sessions::release`].
    pub async fn replay_url(&self, id: &str) -> Result<ReplayUrl, SolariError> {
        let path = format!("/sessions/{}/replay-url", enc(id));
        let res = self.client.http.request("GET", &path, None).await?;
        if !res.ok() {
            return Err(api_error("GET", &path, res.status, &res.body));
        }
        let data: ReplayUrlResponse = serde_json::from_str(&res.body).map_err(|e| {
            SolariError::protocol(format!("Solari: unexpected replay-url response: {e}"))
        })?;
        let url = data.url.filter(|u| !u.is_empty()).ok_or_else(|| {
            SolariError::protocol(format!(
                "Solari: unexpected replay-url response: {}",
                res.body
            ))
        })?;
        Ok(ReplayUrl {
            url,
            expires_in_seconds: data.expires_in_seconds.unwrap_or(0),
            content_encoding: data
                .content_encoding
                .unwrap_or_else(|| "gzip".to_string()),
        })
    }

    /// Download the session's replay as NDJSON bytes. May or may not
    /// actually be gzip despite what was uploaded — GCS decompresses
    /// transparently on an ordinary GET, so check `content_encoding` (now
    /// provider-accurate) before attempting to decompress.
    pub async fn download_replay(&self, id: &str) -> Result<Vec<u8>, SolariError> {
        let replay = self.replay_url(id).await?;
        let (status, bytes) = self.client.http.get_presigned_bytes(&replay.url).await?;
        if !(200..300).contains(&status) {
            return Err(SolariError::Api {
                status,
                code: None,
                message: format!("Solari: replay download failed: {status}"),
            });
        }
        Ok(bytes)
    }

    /// GET a presigned storage-state object. `None` url → `None` state.
    async fn fetch_presigned_storage_state(
        &self,
        url: Option<&str>,
    ) -> Result<Option<StorageState>, SolariError> {
        let Some(url) = url.filter(|u| !u.is_empty()) else {
            return Ok(None);
        };
        let res = self
            .client
            .http
            .get_presigned(url, STORAGE_STATE_FETCH_TIMEOUT)
            .await
            .map_err(|e| {
                SolariError::transport(format!("Solari: failed to fetch storageState: {e}"))
            })?;
        if !res.ok() {
            let snippet: String = res.body.chars().take(256).collect();
            return Err(SolariError::Api {
                status: res.status,
                code: None,
                message: format!(
                    "Solari: storageState fetch returned {}: {snippet}",
                    res.status
                ),
            });
        }
        serde_json::from_str(&res.body).map(Some).map_err(|e| {
            SolariError::protocol(format!(
                "Solari: storageState response was not valid JSON: {e}"
            ))
        })
    }
}

// ---------------------------------------------------------------------------
// profiles
// ---------------------------------------------------------------------------

/// The `profiles` namespace. Obtain via [`Client::profiles`].
pub struct Profiles<'a> {
    client: &'a Client,
}

impl Profiles<'_> {
    /// `GET /profiles`.
    pub async fn list(&self) -> Result<Vec<Profile>, SolariError> {
        let res = self.client.http.request("GET", "/profiles", None).await?;
        if !res.ok() {
            return Err(api_error("GET", "/profiles", res.status, &res.body));
        }
        serde_json::from_str(&res.body)
            .map_err(|e| SolariError::protocol(format!("Solari: unexpected profiles response: {e}")))
    }

    /// `POST /profiles`.
    pub async fn create(&self, name: impl Into<String>) -> Result<Profile, SolariError> {
        let body = json!({ "name": name.into() });
        let res = self
            .client
            .http
            .request("POST", "/profiles", Some(&body))
            .await?;
        if !res.ok() {
            return Err(api_error("POST", "/profiles", res.status, &res.body));
        }
        serde_json::from_str(&res.body)
            .map_err(|e| SolariError::protocol(format!("Solari: unexpected profile response: {e}")))
    }

    /// `DELETE /profiles/:id`. 404 is tolerated (already gone).
    pub async fn delete(&self, id: &str) -> Result<(), SolariError> {
        let path = format!("/profiles/{}", enc(id));
        let res = self.client.http.request("DELETE", &path, None).await?;
        if !res.ok() && res.status != 404 {
            return Err(api_error("DELETE", &path, res.status, &res.body));
        }
        Ok(())
    }

    /// `POST /profiles/:id/login-handoff` — open the profile editor on an existing profile.
    /// Send the person to [`ProfileEditor::url`]; it is valid for about 30 minutes.
    /// `reason` is optional free text. There is no auto-save and no save without closing.
    pub async fn edit(&self, id: &str, reason: Option<&str>) -> Result<ProfileEditor, SolariError> {
        ProfileEditor::open(self.client.clone(), id, reason).await
    }

    /// `POST /profiles/:id/save` — persist a storage state onto the profile.
    pub async fn save(
        &self,
        id: &str,
        storage_state: &StorageState,
    ) -> Result<ProfileSaveResult, SolariError> {
        let path = format!("/profiles/{}/save", enc(id));
        let state = serde_json::to_value(storage_state)
            .map_err(|e| SolariError::protocol(format!("Solari: bad storageState: {e}")))?;
        let body = json!({ "storageState": state });
        let res = self.client.http.request("POST", &path, Some(&body)).await?;
        if !res.ok() {
            return Err(api_error("POST", &path, res.status, &res.body));
        }
        let data: ProfileSaveResponse = serde_json::from_str(&res.body).map_err(|e| {
            SolariError::protocol(format!("Solari: unexpected profile save response: {e}"))
        })?;
        Ok(ProfileSaveResult {
            version: data.version.unwrap_or(0),
            size_bytes: data.size_bytes.unwrap_or(0),
        })
    }
}

// ---------------------------------------------------------------------------
// proxy
// ---------------------------------------------------------------------------

/// The `proxy` namespace. Obtain via [`Client::proxy`].
pub struct Proxy<'a> {
    client: &'a Client,
}

impl Proxy<'_> {
    /// `GET /proxy/countries` — supported egress countries, and whether managed
    /// proxy egress is configured on this gateway at all.
    pub async fn countries(&self) -> Result<ProxyCountries, SolariError> {
        let res = self
            .client
            .http
            .request("GET", "/proxy/countries", None)
            .await?;
        if !res.ok() {
            return Err(api_error("GET", "/proxy/countries", res.status, &res.body));
        }
        serde_json::from_str(&res.body).map_err(|e| {
            SolariError::protocol(format!("Solari: unexpected proxy/countries response: {e}"))
        })
    }
}

// ---------------------------------------------------------------------------
// helpers
// ---------------------------------------------------------------------------

/// The most key/value pairs the gateway accepts in a list filter.
const MAX_METADATA_CLAUSES: usize = 10;

/// Render the gateway's list filter grammar: `user_metadata['key']:'value'`
/// clauses joined by `AND`, in key order. A pair it cannot express is refused
/// before any request is sent.
fn metadata_filter(m: &BTreeMap<String, String>) -> Result<String, SolariError> {
    if m.len() > MAX_METADATA_CLAUSES {
        return Err(SolariError::config(format!(
            "Solari: at most {MAX_METADATA_CLAUSES} metadata filter pairs"
        )));
    }
    let mut clauses = Vec::with_capacity(m.len());
    for (k, v) in m {
        if k.is_empty() || k.chars().count() > 128 || k.contains('\'') || v.contains('\'') {
            return Err(SolariError::config(format!(
                "Solari: metadata filter key {k:?} or its value cannot be expressed (1-128 characters, no single quote)"
            )));
        }
        clauses.push(format!("user_metadata['{k}']:'{v}'"));
    }
    Ok(clauses.join(" AND "))
}

/// The wire value for the gateway's `timeoutSeconds`: the millisecond option
/// rounded up to whole seconds, else the deprecated seconds option. `None` or zero
/// means "omit". Refuses a value whose seconds do not fit the wire field (int32, as
/// in the Go SDK) before any request.
pub(crate) fn session_timeout_seconds(
    ms: Option<u64>,
    legacy_seconds: Option<u32>,
) -> Result<Option<u32>, SolariError> {
    const WIRE_MAX: u32 = i32::MAX as u32;
    match ms.filter(|m| *m > 0) {
        Some(ms) => {
            let secs = ms / 1000 + u64::from(ms % 1000 != 0);
            u32::try_from(secs)
                .ok()
                .filter(|s| *s <= WIRE_MAX)
                .map(Some)
                .ok_or_else(|| SolariError::config("Solari: session_timeout_ms is too large"))
        }
        None => match legacy_seconds.filter(|s| *s > 0) {
            Some(s) if s > WIRE_MAX => {
                Err(SolariError::config("Solari: timeout_seconds is too large"))
            }
            other => Ok(other),
        },
    }
}

/// Percent-encode a path segment. Session ids are HMAC composites (`.`-joined
/// base64url) and profile ids are opaque, so only a conservative set of
/// unreserved characters is passed through.
pub(crate) fn enc(s: &str) -> String {
    let mut out = String::with_capacity(s.len());
    for b in s.bytes() {
        match b {
            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'_' | b'.' | b'~' | b'!' | b'*'
            | b'\'' | b'(' | b')' => out.push(b as char),
            _ => out.push_str(&format!("%{b:02X}")),
        }
    }
    out
}

/// Rewrite a Playwright ws endpoint into its raw-CDP sibling: `/ws/<id>` →
/// `/cdp/<id>`. Mirrors `deriveCdpFromWs`; returns the input unchanged when it
/// does not parse or does not match.
pub(crate) fn derive_cdp_from_ws(ws_endpoint: &str) -> String {
    match Url::parse(ws_endpoint) {
        Ok(mut u) => {
            let path = u.path().to_string();
            if let Some(rest) = path.strip_prefix("/ws/") {
                u.set_path(&format!("/cdp/{rest}"));
                u.to_string()
            } else {
                ws_endpoint.to_string()
            }
        }
        Err(_) => ws_endpoint.to_string(),
    }
}

/// An ISO-8601 UTC timestamp `d` from now — the fallback when the API omits
/// `expiresAt` (TS: `new Date(Date.now() + 60*60_000).toISOString()`).
fn iso8601_utc_in(d: Duration) -> String {
    let now = std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map(|x| x.as_secs())
        .unwrap_or(0);
    iso8601_utc(now as i64 + d.as_secs() as i64)
}

/// Format a Unix timestamp as `YYYY-MM-DDTHH:MM:SS.000Z`.
pub(crate) fn iso8601_utc(unix_secs: i64) -> String {
    let days = unix_secs.div_euclid(86_400);
    let sod = unix_secs.rem_euclid(86_400);
    let (y, m, d) = civil_from_days(days);
    format!(
        "{:04}-{:02}-{:02}T{:02}:{:02}:{:02}.000Z",
        y,
        m,
        d,
        sod / 3600,
        (sod % 3600) / 60,
        sod % 60
    )
}

/// Howard Hinnant's `civil_from_days`: days-since-epoch → (year, month, day).
fn civil_from_days(z: i64) -> (i64, u32, u32) {
    let z = z + 719_468;
    let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
    let doe = z - era * 146_097; // [0, 146096]
    let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365; // [0, 399]
    let y = yoe + era * 400;
    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100); // [0, 365]
    let mp = (5 * doy + 2) / 153; // [0, 11]
    let d = (doy - (153 * mp + 2) / 5 + 1) as u32; // [1, 31]
    let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32; // [1, 12]
    (if m <= 2 { y + 1 } else { y }, m, d)
}