wavekat_platform_client/
client.rs

1//! `Client` — reqwest-backed bearer-auth HTTP against `platform.wavekat.com`.
2//!
3//! Ported from `wavekat-cli/src/client.rs`. Two intentional changes vs.
4//! the CLI:
5//!
6//!   1. Storage-agnostic constructor: `Client::new(base_url, token)`
7//!      instead of `Client::from_config()`. Reading auth.json belongs in
8//!      the consumer (see this crate's `CLAUDE.md`).
9//!   2. Typed errors via [`crate::Error`] instead of `anyhow::Result`.
10//!      Consumers that prefer `anyhow` can `?` straight through.
11//!
12//! Surface stays close to the CLI so the CLI's eventual migration is
13//! mechanical.
14
15use futures_util::StreamExt;
16use reqwest::header::{HeaderMap, HeaderValue, AUTHORIZATION};
17use serde::de::DeserializeOwned;
18use serde::Serialize;
19use tokio::io::AsyncWriteExt;
20
21use crate::error::{Error, Result};
22use crate::token::Token;
23
24/// HTTP client with the bearer token baked into its default headers.
25///
26/// Cheap to clone (it's a thin wrapper around `reqwest::Client`, which is
27/// itself an `Arc` internally), so prefer cloning over re-building.
28#[derive(Clone)]
29pub struct Client {
30    inner: reqwest::Client,
31    base_url: String,
32}
33
34impl Client {
35    /// Build a client for the given platform base URL, authenticated with
36    /// `token`. The base URL's trailing slash (if any) is stripped.
37    pub fn new(base_url: impl Into<String>, token: Token) -> Result<Self> {
38        let mut headers = HeaderMap::new();
39        let value = format!("Bearer {}", token.as_str());
40        let header = HeaderValue::from_str(&value)
41            .map_err(|_| Error::BadRequest("token contained invalid bytes".into()))?;
42        headers.insert(AUTHORIZATION, header);
43
44        let inner = reqwest::Client::builder()
45            .default_headers(headers)
46            .user_agent(concat!(
47                "wavekat-platform-client/",
48                env!("CARGO_PKG_VERSION")
49            ))
50            .build()?;
51        Ok(Self {
52            inner,
53            base_url: base_url.into().trim_end_matches('/').to_string(),
54        })
55    }
56
57    /// Base URL the client was configured with, with any trailing slash
58    /// stripped. Useful for callers that want to print a clickable link
59    /// alongside an API result (`{base_url}/projects/…`).
60    pub fn base_url(&self) -> &str {
61        &self.base_url
62    }
63
64    fn url(&self, path: &str) -> String {
65        format!("{}{}", self.base_url, path)
66    }
67
68    /// `GET {path}` and decode the JSON response.
69    pub async fn get_json<T: DeserializeOwned>(&self, path: &str) -> Result<T> {
70        let url = self.url(path);
71        let resp = self.inner.get(&url).send().await?;
72        decode(url, resp).await
73    }
74
75    /// `GET {path}?query` and decode the JSON response. `query` is any
76    /// `serde::Serialize` — typically a `&[(K, V)]` or a struct.
77    pub async fn get_json_query<T: DeserializeOwned, Q: Serialize + ?Sized>(
78        &self,
79        path: &str,
80        query: &Q,
81    ) -> Result<T> {
82        let url = self.url(path);
83        let resp = self.inner.get(&url).query(query).send().await?;
84        decode(url, resp).await
85    }
86
87    /// `POST {path}` with `body` serialized as JSON, decode the JSON
88    /// response.
89    pub async fn post_json<T: DeserializeOwned, B: Serialize + ?Sized>(
90        &self,
91        path: &str,
92        body: &B,
93    ) -> Result<T> {
94        let url = self.url(path);
95        let resp = self.inner.post(&url).json(body).send().await?;
96        decode(url, resp).await
97    }
98
99    /// `POST {path}` with no body, expecting an empty/ignored response.
100    pub async fn post_empty(&self, path: &str) -> Result<()> {
101        let url = self.url(path);
102        let resp = self.inner.post(&url).send().await?;
103        ensure_success(url, resp).await
104    }
105
106    /// `POST {path}` with no body, decoding the JSON response. The CLI
107    /// uses this for `…/finalize` endpoints that take no body but return
108    /// the updated row.
109    pub async fn post_empty_returning_json<T: DeserializeOwned>(&self, path: &str) -> Result<T> {
110        let url = self.url(path);
111        let resp = self.inner.post(&url).send().await?;
112        decode(url, resp).await
113    }
114
115    /// `DELETE {path}`.
116    pub async fn delete(&self, path: &str) -> Result<()> {
117        let url = self.url(path);
118        let resp = self.inner.delete(&url).send().await?;
119        ensure_success(url, resp).await
120    }
121
122    /// `PUT {path}` with `body` as `application/octet-stream`. Used by
123    /// the CLI's `models push` to ship bytes through the platform's
124    /// proxy upload route when R2 isn't directly reachable.
125    pub async fn put_proxy_bytes(&self, path: &str, body: Vec<u8>) -> Result<()> {
126        let url = self.url(path);
127        let resp = self
128            .inner
129            .put(&url)
130            .header(reqwest::header::CONTENT_TYPE, "application/octet-stream")
131            .body(body)
132            .send()
133            .await?;
134        ensure_success(url, resp).await
135    }
136
137    /// `PUT` raw bytes to a presigned URL. Deliberately uses a *fresh*
138    /// `reqwest::Client` (no auth headers) — adding `Authorization:
139    /// Bearer …` would make S3/R2 reject the request because it's not
140    /// part of the SigV4 query-string signature.
141    pub async fn put_presigned_bytes(presigned_url: &str, body: Vec<u8>) -> Result<()> {
142        let resp = reqwest::Client::new()
143            .put(presigned_url)
144            .body(body)
145            .send()
146            .await?;
147        ensure_success(presigned_url.to_string(), resp).await
148    }
149
150    /// Stream a `GET` response body into `sink`. Returns the number of
151    /// bytes written. Used for big payloads (manifests, audio clips)
152    /// where holding the whole body in memory would be wasteful.
153    pub async fn get_stream_to<W: AsyncWriteExt + Unpin>(
154        &self,
155        path: &str,
156        sink: &mut W,
157    ) -> Result<u64> {
158        let url = self.url(path);
159        let resp = self.inner.get(&url).send().await?;
160        let status = resp.status();
161        if !status.is_success() {
162            let body = resp.text().await.unwrap_or_default();
163            return Err(Error::Http {
164                status: status.as_u16(),
165                url,
166                body: truncate(&body, 500).to_string(),
167            });
168        }
169        let mut stream = resp.bytes_stream();
170        let mut written: u64 = 0;
171        while let Some(chunk) = stream.next().await {
172            let bytes = chunk?;
173            sink.write_all(&bytes).await?;
174            written += bytes.len() as u64;
175        }
176        sink.flush().await?;
177        Ok(written)
178    }
179}
180
181async fn decode<T: DeserializeOwned>(url: String, resp: reqwest::Response) -> Result<T> {
182    let status = resp.status();
183    let text = resp.text().await?;
184    if !status.is_success() {
185        return Err(Error::Http {
186            status: status.as_u16(),
187            url,
188            body: truncate(&text, 500).to_string(),
189        });
190    }
191    serde_json::from_str(&text).map_err(|source| Error::Decode { url, source })
192}
193
194async fn ensure_success(url: String, resp: reqwest::Response) -> Result<()> {
195    let status = resp.status();
196    if status.is_success() {
197        return Ok(());
198    }
199    let body = resp.text().await.unwrap_or_default();
200    Err(Error::Http {
201        status: status.as_u16(),
202        url,
203        body: truncate(&body, 500).to_string(),
204    })
205}
206
207fn truncate(s: &str, n: usize) -> &str {
208    if s.len() > n {
209        // Walk back to the previous char boundary so we don't slice a
210        // multibyte UTF-8 sequence (the CLI's version of this used a
211        // raw byte slice, which is a panic waiting for a non-ASCII
212        // error body).
213        let mut end = n;
214        while end > 0 && !s.is_char_boundary(end) {
215            end -= 1;
216        }
217        &s[..end]
218    } else {
219        s
220    }
221}
222
223#[cfg(test)]
224mod tests {
225    use super::*;
226
227    #[test]
228    fn http_error_format_matches_cli_shape() {
229        // Regression guard: `Display` for `Error::Http` should format
230        // "{status} {url}: {body}" — matches what the CLI's old `decode`
231        // produced via `anyhow!`. Consumers (and grep-driven debugging)
232        // depend on the shape.
233        let e = Error::Http {
234            status: 401,
235            url: "https://platform.wavekat.com/api/me".into(),
236            body: "unauthorized".into(),
237        };
238        let s = e.to_string();
239        assert!(s.contains("401"), "{s}");
240        assert!(s.contains("https://platform.wavekat.com/api/me"), "{s}");
241        assert!(s.contains("unauthorized"), "{s}");
242    }
243
244    #[test]
245    fn truncate_respects_char_boundaries() {
246        // Multi-byte char straddling the cap shouldn't panic.
247        let s = "a".repeat(498) + "é"; // 'é' is 2 bytes in UTF-8.
248        let t = truncate(&s, 499);
249        assert!(s.starts_with(t));
250    }
251}
wavekat_platform_client/client.rs

wavekat_platform_client/
client.rs
