box_open_sdk/runtime/
mod.rs

1// Code generated by box-gantry (vendored from runtimes/rust/gantryruntime/src/lib.rs). DO NOT EDIT.
2
3//! The hand-written runtime the generated Box Rust SDK ships against
4//! (TR-Rust.5). It implements the machine-readable runtime contract
5//! (`gantry-contract` V1): generated code calls only these declarations, and
6//! this crate supplies the behavior — a retrying async network layer (jittered
7//! backoff, 401 refresh, Retry-After), auth-token threading, request builders,
8//! and response accessors.
9//!
10//! It is the real implementation the compilable stubs stand in for during
11//! generation-time verification (FR-5.3). Because it satisfies the same
12//! signatures — `async fn` network entry points returning `Result<T, Error>`,
13//! per the Rust manifest axes — the generated SDK compiles against it unchanged
14//! (FR-5.2), which `crates/gantry-backend-rust/tests` enforces.
15//!
16//! Async threads cancellation through the future itself (no context parameter);
17//! dropping a `fetch` future cancels the in-flight request.
18
19mod auth;
20mod jwt;
21
22pub use auth::{Auth, CcgConfig, OAuthConfig, RefreshTokenStore, TokenSource};
23pub use jwt::JwtConfig;
24
25use std::collections::HashMap;
26use std::time::Duration;
27
28/// The safety ceiling on any single retry sleep, so a pathological server-sent
29/// `Retry-After` (hours, years) can never suspend `fetch` far past the caller's
30/// intent.
31const MAX_RETRY_DELAY: Duration = Duration::from_secs(300);
32
33/// A runtime error: a failed request, auth acquisition, or body decode. Opaque
34/// by design — the message carries the detail, the type stays stable.
35#[derive(Debug)]
36pub struct Error(String);
37
38impl Error {
39    pub(crate) fn new(message: impl Into<String>) -> Error {
40        Error(message.into())
41    }
42}
43
44impl std::fmt::Display for Error {
45    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
46        write!(f, "{}", self.0)
47    }
48}
49
50impl std::error::Error for Error {}
51
52impl From<serde_json::Error> for Error {
53    fn from(err: serde_json::Error) -> Self {
54        Error(err.to_string())
55    }
56}
57
58impl From<reqwest::Error> for Error {
59    fn from(err: reqwest::Error) -> Self {
60        Error(err.to_string())
61    }
62}
63
64/// A body stream. Buffered by construction (the Rust manifest's streaming axis
65/// is satisfied by full buffering here): keeping the bytes in hand makes both
66/// request retries and response replay safe.
67pub struct Stream(Vec<u8>);
68
69impl Stream {
70    /// An empty stream (e.g. an absent multipart file part).
71    pub fn empty() -> Stream {
72        Stream(Vec::new())
73    }
74
75    /// A stream over already-buffered bytes.
76    pub fn from_bytes(bytes: Vec<u8>) -> Stream {
77        Stream(bytes)
78    }
79
80    /// The buffered bytes.
81    pub fn into_bytes(self) -> Vec<u8> {
82        self.0
83    }
84}
85
86/// The body assembled by the `with_*` builders before `fetch` executes it.
87enum Body {
88    /// A byte body with a fixed content type (JSON, form, buffered stream).
89    Bytes { content_type: String, data: Vec<u8> },
90    /// A Box-style multipart body: an `attributes` JSON part plus a file part.
91    Multipart {
92        attributes: Vec<u8>,
93        file_name: String,
94        file: Vec<u8>,
95    },
96}
97
98/// The runtime-owned HTTP request envelope, assembled by the `with_*` builders
99/// before `fetch` executes it.
100pub struct Request {
101    method: String,
102    url: String,
103    headers: Vec<(String, String)>,
104    query: Vec<(String, String)>,
105    body: Option<Body>,
106}
107
108/// The runtime-owned HTTP response envelope. The body is read fully so it can
109/// be replayed as bytes or a stream and so retries stay safe.
110pub struct Response {
111    status: i64,
112    headers: Vec<(String, String)>,
113    body: Vec<u8>,
114}
115
116/// The runtime session: it holds the auth flow, HTTP client, base-URL
117/// configuration, and retry policy shared by every manager.
118pub struct Client {
119    auth: Auth,
120    http: reqwest::Client,
121    base_urls: HashMap<String, String>,
122    max_retries: u32,
123    default_headers: Vec<(String, String)>,
124}
125
126impl Client {
127    /// Build a runtime session for an authentication flow, with the default
128    /// Box base URLs, a 60s HTTP timeout, and five retries.
129    pub fn new(auth: Auth) -> Client {
130        let http = reqwest::Client::builder()
131            .timeout(Duration::from_secs(60))
132            .build()
133            .unwrap_or_default();
134        Client {
135            auth,
136            http,
137            max_retries: 5,
138            base_urls: default_base_urls(),
139            default_headers: Vec::new(),
140        }
141    }
142
143    /// Override how many times a retriable failure is retried (fluent).
144    pub fn with_max_retries(mut self, n: u32) -> Client {
145        self.max_retries = n;
146        self
147    }
148
149    /// Override the `reqwest::Client` used for API requests (fluent) — e.g. to
150    /// inject an instrumented transport instead of the internally built default.
151    pub fn with_http_client(mut self, http: reqwest::Client) -> Client {
152        self.http = http;
153        self
154    }
155
156    /// Add a header sent with every request from this client (fluent) — e.g.
157    /// a tracing or `User-Agent` header an embedding application wants on
158    /// every call. Replaces any prior default with the same name
159    /// (case-insensitive). A header set on an individual `Request` (via the
160    /// free [`with_header`]) takes precedence over a same-named default.
161    pub fn with_header(mut self, name: &str, value: &str) -> Client {
162        self.default_headers
163            .retain(|(key, _)| !key.eq_ignore_ascii_case(name));
164        self.default_headers
165            .push((name.to_string(), value.to_string()));
166        self
167    }
168
169    /// Override one base-URL class for custom deployments (fluent).
170    pub fn with_base_url(mut self, name: &str, base: &str) -> Client {
171        self.base_urls
172            .insert(name.to_string(), base.trim_end_matches('/').to_string());
173        self
174    }
175
176    /// The configured base URL for a D-106 class, without a trailing slash.
177    pub fn base_url(&self, name: &str) -> String {
178        self.base_urls.get(name).cloned().unwrap_or_default()
179    }
180
181    /// A valid access token for the configured auth flow.
182    pub async fn access_token(&self) -> Result<String, Error> {
183        self.auth.access_token().await
184    }
185
186    /// Create a request envelope for a method and fully built URL.
187    pub fn new_request(&self, method: &str, url: &str) -> Request {
188        Request {
189            method: method.to_string(),
190            url: url.to_string(),
191            headers: Vec::new(),
192            query: Vec::new(),
193            body: None,
194        }
195    }
196
197    /// Execute the request with retries: exponential backoff + full jitter, a
198    /// single 401 token refresh, and Retry-After (as a floor) on 429/5xx.
199    ///
200    /// Retries are gated on idempotency: a 429 means the request was rate-limited
201    /// and never processed, so it retries for every method; a transport error or
202    /// 5xx may have already committed a write, so those retry only for idempotent
203    /// methods (GET/HEAD/PUT/DELETE/…). The 401 refresh applies to every method.
204    pub async fn fetch(&self, request: Request) -> Result<Response, Error> {
205        let method = reqwest::Method::from_bytes(request.method.as_bytes()).map_err(|_| {
206            Error::new(format!(
207                "gantryruntime: invalid method {:?}",
208                request.method
209            ))
210        })?;
211        let idempotent = method.is_idempotent();
212        let mut token = self.access_token().await?;
213        let mut refreshed = false;
214
215        for attempt in 0..=self.max_retries {
216            let mut builder = self
217                .http
218                .request(method.clone(), &request.url)
219                .query(&request.query)
220                .header("Authorization", format!("Bearer {token}"));
221            for (name, value) in &self.default_headers {
222                if !request
223                    .headers
224                    .iter()
225                    .any(|(n, _)| n.eq_ignore_ascii_case(name))
226                {
227                    builder = builder.header(name, value);
228                }
229            }
230            for (name, value) in &request.headers {
231                builder = builder.header(name, value);
232            }
233            builder = apply_body(builder, request.body.as_ref());
234
235            let response = match builder.send().await {
236                Ok(response) => response,
237                Err(err) => {
238                    // A transport error gives no response, so a non-idempotent
239                    // request may or may not have committed — don't replay it.
240                    if attempt == self.max_retries || !idempotent {
241                        return Err(err.into());
242                    }
243                    sleep(backoff(attempt)).await;
244                    continue;
245                }
246            };
247            let response = read_response(response).await?;
248
249            // A single force-refresh on 401: re-acquire past the token cache so
250            // the retry doesn't just resend the same rejected token.
251            if response.status == 401 && !refreshed && attempt < self.max_retries {
252                refreshed = true;
253                token = self.auth.force_refresh(&token).await?;
254                continue;
255            }
256            // Back off exponentially on rate-limit / server errors.
257            if should_retry(response.status, idempotent) && attempt < self.max_retries {
258                sleep(retry_delay(&response, attempt)).await;
259                continue;
260            }
261            return Ok(response);
262        }
263        Err(Error::new("gantryruntime: retries exhausted"))
264    }
265}
266
267/// The default Box base URLs by D-106 class (custom deployments override any
268/// via `with_base_url`).
269fn default_base_urls() -> HashMap<String, String> {
270    [
271        ("api", "https://api.box.com/2.0"),
272        ("api_root", "https://api.box.com"),
273        ("upload", "https://upload.box.com/api/2.0"),
274        ("upload_session", "https://upload.box.com/api/2.0"),
275        ("oauth_authorize", "https://account.box.com/api/oauth2"),
276        ("download", "https://api.box.com/2.0"),
277    ]
278    .iter()
279    .map(|(k, v)| (k.to_string(), v.to_string()))
280    .collect()
281}
282
283/// Attach the assembled body (and its content type) to the request builder.
284fn apply_body(builder: reqwest::RequestBuilder, body: Option<&Body>) -> reqwest::RequestBuilder {
285    match body {
286        None => builder,
287        Some(Body::Bytes { content_type, data }) => builder
288            .header("Content-Type", content_type)
289            .body(data.clone()),
290        Some(Body::Multipart {
291            attributes,
292            file_name,
293            file,
294        }) => {
295            // A boundary that provably does not occur in either part, so the
296            // payload's own bytes can never split the framing.
297            let boundary = multipart_boundary(attributes, file);
298            let payload = multipart_body(&boundary, attributes, file_name, file);
299            builder
300                .header(
301                    "Content-Type",
302                    format!("multipart/form-data; boundary={boundary}"),
303                )
304                .body(payload)
305        }
306    }
307}
308
309/// Build a Box-style multipart/form-data body: an `attributes` JSON field plus
310/// a `file` part (G-7). `file_name` is escaped for the quoted header value.
311fn multipart_body(boundary: &str, attributes: &[u8], file_name: &str, file: &[u8]) -> Vec<u8> {
312    let mut out = Vec::new();
313    out.extend_from_slice(format!("--{boundary}\r\n").as_bytes());
314    out.extend_from_slice(b"Content-Disposition: form-data; name=\"attributes\"\r\n");
315    out.extend_from_slice(b"Content-Type: application/json\r\n\r\n");
316    out.extend_from_slice(attributes);
317    out.extend_from_slice(b"\r\n");
318    out.extend_from_slice(format!("--{boundary}\r\n").as_bytes());
319    out.extend_from_slice(
320        format!(
321            "Content-Disposition: form-data; name=\"file\"; filename=\"{}\"\r\n",
322            escape_filename(file_name)
323        )
324        .as_bytes(),
325    );
326    out.extend_from_slice(b"Content-Type: application/octet-stream\r\n\r\n");
327    out.extend_from_slice(file);
328    out.extend_from_slice(b"\r\n");
329    out.extend_from_slice(format!("--{boundary}--\r\n").as_bytes());
330    out
331}
332
333/// A multipart boundary guaranteed not to appear in either part — so no file
334/// content can forge a delimiter and split the framing. Derived from a
335/// nanosecond-seeded counter, re-rolled until it is collision-free (`mime/
336/// multipart` gets this from a random boundary; we verify explicitly).
337fn multipart_boundary(attributes: &[u8], file: &[u8]) -> String {
338    let mut seed = std::time::SystemTime::now()
339        .duration_since(std::time::UNIX_EPOCH)
340        .map(|d| d.as_nanos() as u64)
341        .unwrap_or(0x9e37_79b9_7f4a_7c15);
342    loop {
343        let candidate = format!("gantryruntimeXboundaryX{seed:016x}");
344        let needle = candidate.as_bytes();
345        if !contains_subslice(attributes, needle) && !contains_subslice(file, needle) {
346            return candidate;
347        }
348        seed = seed
349            .wrapping_mul(6364136223846793005)
350            .wrapping_add(1442695040888963407);
351    }
352}
353
354/// Whether `haystack` contains `needle` as a contiguous subslice.
355fn contains_subslice(haystack: &[u8], needle: &[u8]) -> bool {
356    !needle.is_empty()
357        && haystack.len() >= needle.len()
358        && haystack
359            .windows(needle.len())
360            .any(|window| window == needle)
361}
362
363/// Escape a filename for a quoted `Content-Disposition` value (RFC 6266): strip
364/// CR/LF so it can never inject header lines or a boundary, and backslash-escape
365/// `\` and `"` so a quote can't close the value early.
366fn escape_filename(name: &str) -> String {
367    let mut out = String::with_capacity(name.len());
368    for ch in name.chars() {
369        match ch {
370            '\r' | '\n' => {}
371            '\\' | '"' => {
372                out.push('\\');
373                out.push(ch);
374            }
375            _ => out.push(ch),
376        }
377    }
378    out
379}
380
381/// Read a response fully into the owned envelope.
382async fn read_response(response: reqwest::Response) -> Result<Response, Error> {
383    let status = response.status().as_u16() as i64;
384    let headers = response
385        .headers()
386        .iter()
387        .map(|(name, value)| {
388            (
389                name.as_str().to_string(),
390                value.to_str().unwrap_or_default().to_string(),
391            )
392        })
393        .collect();
394    let body = response.bytes().await?.to_vec();
395    Ok(Response {
396        status,
397        headers,
398        body,
399    })
400}
401
402/// Whether a response status warrants a retry for a request of this idempotency.
403/// A 429 (rate-limited, never processed) retries for any method; a 5xx may have
404/// committed a write, so it retries only for idempotent methods.
405fn should_retry(status: i64, idempotent: bool) -> bool {
406    status == 429 || (status >= 500 && idempotent)
407}
408
409/// Exponential backoff capped at 30s, with full jitter.
410fn backoff(attempt: u32) -> Duration {
411    let base = (500u64.saturating_mul(1u64 << attempt.min(20))).min(30_000);
412    Duration::from_millis(jitter(base))
413}
414
415/// The delay before the next retry: exponential backoff (so repeated 429s/5xx
416/// escalate), raised to a server-sent `Retry-After` as a floor when present, and
417/// clamped to [`MAX_RETRY_DELAY`] so a hostile header can't stall the client.
418fn retry_delay(response: &Response, attempt: u32) -> Duration {
419    let mut delay = backoff(attempt);
420    if let Some(value) = header_value(&response.headers, "retry-after") {
421        if let Ok(secs) = value.trim().parse::<u64>() {
422            delay = delay.max(Duration::from_secs(secs));
423        }
424    }
425    delay.min(MAX_RETRY_DELAY)
426}
427
428/// A cheap, dependency-free full-jitter source: a uniform value in `[0, max]`
429/// from a nanosecond-seeded xorshift (jitter only needs to decorrelate retries,
430/// not be cryptographic).
431fn jitter(max: u64) -> u64 {
432    if max == 0 {
433        return 0;
434    }
435    let mut x = std::time::SystemTime::now()
436        .duration_since(std::time::UNIX_EPOCH)
437        .map(|d| d.as_nanos() as u64)
438        .unwrap_or(0x9e37_79b9_7f4a_7c15)
439        | 1;
440    x ^= x << 13;
441    x ^= x >> 7;
442    x ^= x << 17;
443    x % (max + 1)
444}
445
446async fn sleep(duration: Duration) {
447    tokio::time::sleep(duration).await;
448}
449
450/// Case-insensitive header lookup (HTTP header names are case-insensitive).
451fn header_value<'a>(headers: &'a [(String, String)], name: &str) -> Option<&'a str> {
452    headers
453        .iter()
454        .find(|(key, _)| key.eq_ignore_ascii_case(name))
455        .map(|(_, value)| value.as_str())
456}
457
458/// Return the request with the header set (replacing any prior value).
459pub fn with_header(mut request: Request, name: &str, value: &str) -> Request {
460    request
461        .headers
462        .retain(|(key, _)| !key.eq_ignore_ascii_case(name));
463    request.headers.push((name.to_string(), value.to_string()));
464    request
465}
466
467/// Return the request with the query parameter appended, encoded at send time.
468pub fn with_query(mut request: Request, name: &str, value: &str) -> Request {
469    request.query.push((name.to_string(), value.to_string()));
470    request
471}
472
473/// Return the request with the serialized JSON body and content type set.
474pub fn with_json_body(mut request: Request, body: &[u8]) -> Request {
475    request.body = Some(Body::Bytes {
476        content_type: "application/json".to_string(),
477        data: body.to_vec(),
478    });
479    request
480}
481
482/// Return the request with an application/x-www-form-urlencoded body (the
483/// OAuth2 token endpoints).
484pub fn with_form_body(mut request: Request, form: &[u8]) -> Request {
485    request.body = Some(Body::Bytes {
486        content_type: "application/x-www-form-urlencoded".to_string(),
487        data: form.to_vec(),
488    });
489    request
490}
491
492/// Return the request with a streaming body (buffered here).
493pub fn with_stream_body(mut request: Request, body: Stream, content_type: &str) -> Request {
494    request.body = Some(Body::Bytes {
495        content_type: content_type.to_string(),
496        data: body.into_bytes(),
497    });
498    request
499}
500
501/// Return the request with a Box-style multipart body: an `attributes` JSON
502/// part plus a file part (G-7).
503pub fn with_multipart_body(
504    mut request: Request,
505    attributes: &[u8],
506    file_name: &str,
507    file: Stream,
508) -> Request {
509    request.body = Some(Body::Multipart {
510        attributes: attributes.to_vec(),
511        file_name: file_name.to_string(),
512        file: file.into_bytes(),
513    });
514    request
515}
516
517/// Read the whole response body.
518pub fn response_bytes(response: &Response) -> Result<Vec<u8>, Error> {
519    Ok(response.body.clone())
520}
521
522/// The response body as a stream, for binary downloads (FR-7.4).
523pub fn response_stream(response: &Response) -> Stream {
524    Stream::from_bytes(response.body.clone())
525}
526
527/// A response header value, empty when absent (redirect Location, Retry-After
528/// surfacing).
529pub fn response_header(response: &Response, name: &str) -> String {
530    header_value(&response.headers, name)
531        .unwrap_or_default()
532        .to_string()
533}
534
535/// The response status code.
536pub fn status_code(response: &Response) -> i64 {
537    response.status
538}
box_open_sdk/runtime/mod.rs

box_open_sdk/runtime/
mod.rs
