Struct CratestackClient 

pub struct CratestackClient<C = CborCodec> { /* private fields */ }

Implementations

impl<C> CratestackClient<C>

where C: HttpClientCodec,

pub fn with_compact_keys(self, tables: KeyTables) -> Self

Turn compact wire keys on, with tables holding one entry per op (the client’s own contracts). Off by default.

pub fn with_compact_key_bytes( self, tables: &[u8], contracts: OpContracts, ) -> Result<Self, ClientError>

Compact wire keys from the generated KEY_TABLES bytes, keeping the entries whose digest is the op’s current one in contracts (the generated OP_CONTRACTS). Called by the generated Client::with_compact_keys.

impl CratestackClient<CborCodec>

pub fn cbor(config: ClientConfig) -> Self

impl<C> CratestackClient<C>

where C: HttpClientCodec,

pub fn new(config: ClientConfig, codec: C) -> Self

pub fn with_http_client(config: ClientConfig, codec: C, http: Client) -> Self

Build a client on a caller-supplied reqwest::Client — a custom timeout, proxy, or mTLS identity.

Install a rustls crypto provider (e.g. via ensure_crypto_provider) before constructing http: unlike Self::new, this constructor is handed an already-built client, so the #440 panic fires in the caller, not here.

pub fn with_state_store(self, state_store: Arc<dyn ClientStateStore>) -> Self

pub fn with_optional_state_store( self, state_store: Option<Arc<dyn ClientStateStore>>, ) -> Self

pub fn with_request_authorizer( self, request_authorizer: Arc<dyn RequestAuthorizer>, ) -> Self

pub fn with_schema_sha(self, schema_sha: &'static str) -> Self

Stamps the generating schema’s SCHEMA_SHA256 onto this client, so every subsequent request carries x-cratestack-schema-sha (issue #178). Called by the schema-generated Client::new wrapper, not meant to be called directly by schema authors — public because the generated code lives in a downstream crate.

pub fn state(&self) -> Result<PersistedClientState, ClientError>

impl<C> CratestackClient<C>

where C: HttpClientCodec,

pub async fn get<Output>( &self, path: &str, query: &[QueryPair<'_>], headers: &[HeaderPair<'_>], ) -> Result<Output, ClientError>

where Output: DeserializeOwned,

pub async fn get_with_response<Output>( &self, path: &str, query: &[QueryPair<'_>], headers: &[HeaderPair<'_>], ) -> Result<TypedResponse<Output>, ClientError>

where Output: DeserializeOwned,

Same request as Self::get, but returns the status and headers alongside the decoded body (issue #493) — the way a caller reads the ETag off an @version model’s GET before sending it back as If-Match on patch_with_response/patch.

pub async fn post<Input, Output>( &self, path: &str, input: &Input, headers: &[HeaderPair<'_>], ) -> Result<Output, ClientError>

where Input: Serialize, Output: DeserializeOwned,

pub async fn post_with_response<Input, Output>( &self, path: &str, input: &Input, headers: &[HeaderPair<'_>], ) -> Result<TypedResponse<Output>, ClientError>

where Input: Serialize, Output: DeserializeOwned,

Same request as Self::post, but returns the status and headers alongside the decoded body (issue #493) — e.g. to read Idempotency-Replayed off a create sent through an idempotency-key-aware server.

pub async fn patch<Input, Output>( &self, path: &str, input: &Input, headers: &[HeaderPair<'_>], ) -> Result<Output, ClientError>

where Input: Serialize, Output: DeserializeOwned,

pub async fn patch_with_response<Input, Output>( &self, path: &str, input: &Input, headers: &[HeaderPair<'_>], ) -> Result<TypedResponse<Output>, ClientError>

where Input: Serialize, Output: DeserializeOwned,

Same request as Self::patch, but returns the status and headers alongside the decoded body (issue #493) — the response carries the new ETag after a successful @version update, which a caller chaining further updates needs to read back out.

pub async fn delete<Output>( &self, path: &str, headers: &[HeaderPair<'_>], ) -> Result<Output, ClientError>

where Output: DeserializeOwned,

pub async fn delete_with_response<Output>( &self, path: &str, headers: &[HeaderPair<'_>], ) -> Result<TypedResponse<Output>, ClientError>

where Output: DeserializeOwned,

Same request as Self::delete, but returns the status and headers alongside the decoded body (issue #493) — e.g. to read a Retry-After on a 429, or any other out-of-band signal a server sends on a delete response.

Part of the @version optimistic-locking round trip since cratestack#519: on an @version model the server requires an If-Match header here exactly as it does on patch_with_response, and returns 412 on a stale or missing value. Pass the ETag learned from a prior Self::get_with_response (or from a previous *_with_response call’s TypedResponse::header("etag")) as If-Match in headers.

impl<C: HttpClientCodec> CratestackClient<C>

pub fn prepare_call<Input: Serialize>( &self, method: &str, route: RouteRef<'_>, path: &str, input: &Input, query: &[QueryPair<'_>], headers: &[HeaderPair<'_>], ) -> Result<PreparedCall, ClientError>

Encode and freeze one keyed unary mutation before any network I/O. Requires compact key tables, even when this first payload stays named. Persist the descriptor before calling execute_prepared; the framework does not enqueue it. Credentials come from the authorizer on each attempt.

pub async fn execute_prepared( &self, call: &PreparedCall, ) -> Result<RuntimeResponseWire, ClientError>

Send original inner bytes, reauthorizing and (when configured) resealing with fresh COSE claims. No compact negotiation or request transcoding runs. A changed service, codec, seal mode, or op contract fails before sending.

pub async fn execute_prepared_typed<Output: DeserializeOwned>( &self, call: &PreparedCall, ) -> Result<TypedResponse<Output>, ClientError>

Typed equivalent of execute_prepared, retaining replay/status headers.

impl<C> CratestackClient<C>

where C: HttpClientCodec,

pub fn at(&self, route: RouteRef<'_>) -> Self

A copy of this client that knows which route its next call is for, so a sealed call can bind the route template (see RouteRef).

Generated code calls it before every REST operation (runtime.at(RouteRef::new("/widgets/{id}", &[&id])).get(..)) and the RPC client before every op. It is a copy rather than a *_at twin of each of the twelve request methods, the same shape as with_idempotency; it does nothing unless an envelope is set.

impl<C> CratestackClient<C>

where C: HttpClientCodec,

This impl block contains no public items.

Without the feature the generated Client::new still calls this, and it does nothing.

impl<C> CratestackClient<C>

where C: HttpClientCodec,

pub async fn post_list<Input, Output>( &self, path: &str, input: &Input, headers: &[HeaderPair<'_>], ) -> Result<Vec<Output>, ClientError>

where Input: Serialize, Output: DeserializeOwned,

pub async fn post_list_streamed<Input, Output>( &self, path: &str, input: &Input, headers: &[HeaderPair<'_>], ) -> Result<Receiver<Result<Output, ClientError>>, ClientError>

where Input: Serialize, Output: DeserializeOwned + Send + 'static,

Streaming variant of Self::post_list. Returns an mpsc::Receiver that yields decoded items as they arrive over the network — first-item latency drops from “buffer the whole body” to “decode one chunk.” Useful on mobile / flaky links where time-to-first-byte matters more than total throughput.

The receiver yields Result<Output, ClientError> per item. Transport / decode errors are terminal — the next call to .recv() returns None after one. A clean end-of-stream (server closed cleanly after the last item) also surfaces as None from the next .recv().

Ideally the server returns application/cbor-seq, decoded incrementally as bytes arrive. If content negotiation instead picks a buffered application/cbor or application/json response, this still works — the body is buffered in full and forwarded item-by-item through the same Receiver — but loses the time-to-first-byte win, so prefer Self::post_list when you already know the server won’t stream. A Content-Type the codec can’t decode at all becomes a terminal Err on the receiver naming what was received.

pub async fn execute_raw_transport( &self, request: RuntimeRequestWire, ) -> Result<RuntimeResponseWire, ClientError>

impl<C> CratestackClient<C>

where C: HttpClientCodec,

pub async fn get_view<P>( &self, path: &str, projection: &P, headers: &[HeaderPair<'_>], ) -> Result<P::Output, ClientError>

where P: ProjectionDecoder,

pub async fn list_view<P>( &self, path: &str, projection: &P, extra_query: &[QueryPair<'_>], headers: &[HeaderPair<'_>], ) -> Result<Vec<P::Output>, ClientError>

where P: ProjectionDecoder,

pub async fn list_view_paged<P>( &self, path: &str, projection: &P, extra_query: &[QueryPair<'_>], headers: &[HeaderPair<'_>], ) -> Result<Page<P::Output>, ClientError>

where P: ProjectionDecoder,

impl<C> CratestackClient<C>

pub fn with_idempotency(self, idempotency: RequestIdempotency) -> Self

Pin every request this client sends to idempotency, overriding the method-derived default.

CratestackClient is cheap to clone (the reqwest client, the state store and the authorizer are all reference-counted), so the intended shape is a per-call clone rather than a second long-lived client:

use cratestack_client_rust::{
    CborCodec, ClientConfig, CratestackClient, RequestIdempotency,
};

let client = CratestackClient::cbor(ClientConfig::new(
    "https://api.example.com".parse()?,
));

// A `@query` procedure is a POST on the wire but is safe to
// replay — say so, and a retry middleware will retry it.
let readonly = client.clone().with_idempotency(RequestIdempotency::IDEMPOTENT);

This is the REST half of the per-call override; the RPC half is RpcClient::with_idempotency, which forwards to this method.

impl<C: HttpClientCodec> CratestackClient<C>

pub async fn subscribe<T>( &self, target: SubscriptionTarget, ) -> Result<ClientSubscription<T>, ClientError>

where T: DeserializeOwned + Send + 'static,

Opens target, resolving once the server says Ready.

Trait Implementations

impl<C: Clone> Clone for CratestackClient<C>

fn clone(&self) -> CratestackClient<C>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.