zc2 0.0.52

P2P compute broker with yen-denominated billing, WAL, and broker mesh support
//! The hub's Spaces publisher routes, as the dispatcher calls them
//! (`api/dashboard/routers/spaces.py`):
//!
//! | step | route |
//! |---|---|
//! | create | `POST /api/spaces` |
//! | find | `GET /api/spaces` |
//! | progress | `GET /api/spaces/{id}` (`counts`, `status`, `mirror`) |
//! | presign | `POST /api/spaces/{id}/inputs:presign` |
//! | upload | `PUT <presigned url>` (no `Authorization`) |
//! | batches | `POST /api/spaces/{id}/batches` (NDJSON) |
//! | publish | `POST /api/spaces/{id}/publish` |
//! | cancel | `POST /api/spaces/{id}/cancel` |
//! | outputs | `GET /api/spaces/{id}/batches?status=succeeded` + presigned GETs |
//!
//! Every one of these takes `get_current_user`: a SESSION token. The `zk_`
//! key `zc login` saves is refused by them (401); only the provide, worker
//! and La Forge routes take a device key
//! (`dashboard/dependencies.get_current_user_or_device_key`). The client
//! sends whatever credential it is given and reports the hub's refusal as it
//! is; it does not invent a different one.

use base64::Engine;
use serde_json::Value;
use std::path::Path;
use std::time::Duration;

/// How a hub call failed, in the one distinction the outbox acts on.
#[derive(Debug, Clone, PartialEq)]
pub enum HubErr {
    /// Retry with backoff: the hub is unreachable, slow, overloaded (5xx,
    /// 408, 429) or answered something unreadable.
    Transient(String),
    /// A 4xx other than 408/429: the hub refused and says it will not change.
    Permanent { status: u16, message: String },
}

impl std::fmt::Display for HubErr {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            HubErr::Transient(m) => write!(f, "{m}"),
            HubErr::Permanent { status, message } => write!(f, "hub answered {status}: {message}"),
        }
    }
}

/// The readable part of a hub error body (FastAPI's `detail`).
fn detail(body: &str) -> String {
    let v: Value = serde_json::from_str(body).unwrap_or(Value::Null);
    let d = match v.get("detail") {
        Some(Value::String(s)) => s.clone(),
        Some(other) => other.to_string(),
        None => body.to_string(),
    };
    let one: String = d.split_whitespace().collect::<Vec<_>>().join(" ");
    one.chars().take(300).collect()
}

pub fn classify(status: u16, body: &str) -> HubErr {
    match status {
        408 | 429 | 500..=599 => {
            HubErr::Transient(format!("hub answered {status}: {}", detail(body)))
        }
        _ => HubErr::Permanent {
            status,
            message: detail(body),
        },
    }
}

#[derive(Debug, Clone, PartialEq)]
pub struct Upload {
    pub name: String,
    pub key: String,
    pub url: String,
}

#[derive(Clone)]
pub struct SpacesHub {
    api: reqwest::Client,
    transfer: reqwest::Client,
    base: String,
    token: String,
}

impl SpacesHub {
    pub fn new(base: &str, token: &str) -> Self {
        let build = |timeout: Duration| {
            reqwest::Client::builder()
                .connect_timeout(Duration::from_secs(15))
                .timeout(timeout)
                .build()
                .expect("reqwest client builds with rustls")
        };
        Self {
            api: build(Duration::from_secs(60)),
            // Inputs and outputs can be large; a stalled transfer still ends.
            transfer: build(Duration::from_secs(30 * 60)),
            base: base.trim_end_matches('/').to_string(),
            token: token.to_string(),
        }
    }

    pub fn base(&self) -> &str {
        &self.base
    }

    async fn send(&self, req: reqwest::RequestBuilder) -> Result<String, HubErr> {
        let resp = req
            .bearer_auth(&self.token)
            .send()
            .await
            .map_err(|e| HubErr::Transient(format!("could not reach the hub: {e}")))?;
        let status = resp.status().as_u16();
        let body = resp.text().await.unwrap_or_default();
        if (200..300).contains(&status) {
            Ok(body)
        } else {
            Err(classify(status, &body))
        }
    }

    async fn json(&self, req: reqwest::RequestBuilder) -> Result<Value, HubErr> {
        let body = self.send(req).await?;
        serde_json::from_str(&body)
            .map_err(|e| HubErr::Transient(format!("the hub's answer could not be read: {e}")))
    }

    pub async fn create_space(&self, body: &Value) -> Result<Value, HubErr> {
        self.json(
            self.api
                .post(format!("{}/api/spaces", self.base))
                .json(body),
        )
        .await
    }

    pub async fn list_spaces(&self) -> Result<Vec<Value>, HubErr> {
        let v = self
            .json(self.api.get(format!("{}/api/spaces", self.base)))
            .await?;
        Ok(v.get("items")
            .and_then(Value::as_array)
            .cloned()
            .unwrap_or_default())
    }

    pub async fn get_space(&self, id: &str) -> Result<Value, HubErr> {
        self.json(self.api.get(format!("{}/api/spaces/{id}", self.base)))
            .await
    }

    /// Presigned PUTs for `(name, sha256 hex, size)` files.
    pub async fn presign(
        &self,
        id: &str,
        files: &[(String, String, u64)],
    ) -> Result<Vec<Upload>, HubErr> {
        let body = serde_json::json!({"files": files.iter().map(|(n, s, z)| {
            serde_json::json!({"name": n, "sha256": s, "size": z})
        }).collect::<Vec<_>>()});
        let v = self
            .json(
                self.api
                    .post(format!("{}/api/spaces/{id}/inputs:presign", self.base))
                    .json(&body),
            )
            .await?;
        let mut out = vec![];
        for u in v
            .get("uploads")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
        {
            let f = |k: &str| u.get(k).and_then(Value::as_str).map(str::to_string);
            match (f("name"), f("key"), f("url")) {
                (Some(name), Some(key), Some(url)) => out.push(Upload { name, key, url }),
                _ => {
                    return Err(HubErr::Transient(
                        "the hub's presign answer is missing name, key or url".into(),
                    ))
                }
            }
        }
        Ok(out)
    }

    /// PUT the object to its presigned URL, bound to its SHA-256. The
    /// presigned URL carries its own authority and may be another host, so
    /// the hub token is NOT sent.
    pub async fn put_object(
        &self,
        url: &str,
        sha256_hex: &str,
        bytes: Vec<u8>,
    ) -> Result<(), HubErr> {
        let raw = hex::decode(sha256_hex)
            .map_err(|_| HubErr::Transient("a recorded digest is not hex".into()))?;
        let resp = self
            .transfer
            .put(url)
            .header(
                "x-amz-checksum-sha256",
                base64::engine::general_purpose::STANDARD.encode(raw),
            )
            .body(bytes)
            .send()
            .await
            .map_err(|e| HubErr::Transient(format!("upload failed: {e}")))?;
        let status = resp.status().as_u16();
        if (200..300).contains(&status) {
            return Ok(());
        }
        let body = resp.text().await.unwrap_or_default();
        Err(classify(status, &body))
    }

    pub async fn add_batches(&self, id: &str, ndjson: String) -> Result<Value, HubErr> {
        self.json(
            self.api
                .post(format!("{}/api/spaces/{id}/batches", self.base))
                .header("content-type", "application/x-ndjson")
                .body(ndjson),
        )
        .await
    }

    pub async fn publish(&self, id: &str) -> Result<Value, HubErr> {
        self.json(
            self.api
                .post(format!("{}/api/spaces/{id}/publish", self.base)),
        )
        .await
    }

    pub async fn cancel(&self, id: &str) -> Result<Value, HubErr> {
        self.json(
            self.api
                .post(format!("{}/api/spaces/{id}/cancel", self.base)),
        )
        .await
    }

    /// One page of batches, with their presigned output links.
    pub async fn list_batches(
        &self,
        id: &str,
        status: Option<&str>,
        cursor: Option<&str>,
    ) -> Result<Value, HubErr> {
        let mut q: Vec<(&str, &str)> = vec![("limit", "100")];
        if let Some(s) = status {
            q.push(("status", s));
        }
        if let Some(c) = cursor {
            q.push(("cursor", c));
        }
        self.json(
            self.api
                .get(format!("{}/api/spaces/{id}/batches", self.base))
                .query(&q),
        )
        .await
    }

    /// Stream a presigned GET into `dest` (a temp file the caller renames),
    /// hashing as it goes. No hub token goes to the storage host.
    pub async fn download(&self, url: &str, dest: &Path) -> Result<(String, u64), HubErr> {
        use ring::digest::{Context, SHA256};
        use std::io::Write;
        let mut resp = self
            .transfer
            .get(url)
            .send()
            .await
            .map_err(|e| HubErr::Transient(format!("download failed: {e}")))?;
        let status = resp.status().as_u16();
        if !(200..300).contains(&status) {
            let body = resp.text().await.unwrap_or_default();
            return Err(classify(status, &body));
        }
        let local = |e: std::io::Error| HubErr::Transient(format!("{}: {e}", dest.display()));
        let mut file = std::fs::File::create(dest).map_err(local)?;
        let mut ctx = Context::new(&SHA256);
        let mut size = 0u64;
        while let Some(chunk) = resp
            .chunk()
            .await
            .map_err(|e| HubErr::Transient(format!("download interrupted: {e}")))?
        {
            ctx.update(&chunk);
            size += chunk.len() as u64;
            file.write_all(&chunk).map_err(local)?;
        }
        file.sync_all().map_err(local)?;
        Ok((hex::encode(ctx.finish().as_ref()), size))
    }
}

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

    #[test]
    fn only_a_4xx_other_than_408_and_429_is_permanent() {
        for s in [408, 429, 500, 502, 503, 504] {
            assert!(matches!(classify(s, "{}"), HubErr::Transient(_)), "{s}");
        }
        for s in [400, 401, 402, 403, 404, 409, 413, 422] {
            assert!(matches!(classify(s, "{}"), HubErr::Permanent { .. }), "{s}");
        }
    }

    #[test]
    fn the_hubs_detail_is_what_is_reported() {
        let e = classify(402, r#"{"detail":"insufficient   balance\nfor this hold"}"#);
        assert_eq!(
            e,
            HubErr::Permanent {
                status: 402,
                message: "insufficient balance for this hold".into()
            }
        );
        let e = classify(409, "plain text");
        assert!(matches!(e, HubErr::Permanent { message, .. } if message == "plain text"));
    }
}