Module runtime 

The hand-written runtime the generated Box Rust SDK ships against (TR-Rust.5). It implements the machine-readable runtime contract (gantry-contract V1): generated code calls only these declarations, and this crate supplies the behavior — a retrying async network layer (jittered backoff, 401 refresh, Retry-After), auth-token threading, request builders, and response accessors.

It is the real implementation the compilable stubs stand in for during generation-time verification (FR-5.3). Because it satisfies the same signatures — async fn network entry points returning Result<T, Error>, per the Rust manifest axes — the generated SDK compiles against it unchanged (FR-5.2), which crates/gantry-backend-rust/tests enforces.

Async threads cancellation through the future itself (no context parameter); dropping a fetch future cancels the in-flight request.

Structs

Auth

The configured authentication flow. Build one with Auth::developer_token, Auth::client_credentials, or Auth::oauth, then pass it to Client::new.

CcgConfig

The Client Credentials Grant config: server-to-server auth with no signing key. Set exactly one subject — enterprise_id for the service account, or user_id to act as a managed user. Derives Default so the optional user_id/token_url can be elided with ..Default::default().

Client

The runtime session: it holds the auth flow, HTTP client, base-URL configuration, and retry policy shared by every manager.

Error

A runtime error: a failed request, auth acquisition, or body decode. Opaque by design — the message carries the detail, the type stays stable.

JwtConfig

JWT server auth config — the fields Box’s box_config.json carries. Set exactly one subject: enterprise_id for the service account, or user_id to act as a managed user.

OAuthConfig

The OAuth 2.0 authorization-code config. Use OAuthConfig::authorize_url to build the redirect, OAuthConfig::exchange_code to turn the returned code into an Auth, or Auth::oauth to resume from a stored refresh token.

Request

The runtime-owned HTTP request envelope, assembled by the with_* builders before fetch executes it.

Response

The runtime-owned HTTP response envelope. The body is read fully so it can be replayed as bytes or a stream and so retries stay safe.

Stream

A body stream. Buffered by construction (the Rust manifest’s streaming axis is satisfied by full buffering here): keeping the bytes in hand makes both request retries and response replay safe.

Traits

RefreshTokenStore

A durable store for the rotating OAuth refresh token. Box invalidates the previous refresh token on each exchange, so an app that restarts must reload the newest one — implement this to persist each rotation (a file, a DB row, a secret manager).

TokenSource

A custom access-token source, for callers that need to own token acquisition and refresh outside the built-in flows — e.g. an engine-owned token cache with proactive refresh and per-identity fan-out. Build an Auth from one with Auth::custom.

Functions

response_bytes

Read the whole response body.

response_header

A response header value, empty when absent (redirect Location, Retry-After surfacing).

response_stream

The response body as a stream, for binary downloads (FR-7.4).

status_code

The response status code.

with_form_body

Return the request with an application/x-www-form-urlencoded body (the OAuth2 token endpoints).

with_header

Return the request with the header set (replacing any prior value).

with_json_body

Return the request with the serialized JSON body and content type set.

with_multipart_body

Return the request with a Box-style multipart body: an attributes JSON part plus a file part (G-7).

with_query

Return the request with the query parameter appended, encoded at send time.

with_stream_body

Return the request with a streaming body (buffered here).