cratestack-client-rust

Rust HTTP client runtime for CrateStack services.

Overview

cratestack-client-rust provides the typed client runtime that include_client_schema! builds its generated client::Client surface on top of. It owns the HTTP transport, codec negotiation, request authorization hook, and optional offline state journaling.

The CBOR and JSON codecs are re-exported as CborCodec and JsonCodec.

Installation

[dependencies]
cratestack-client-rust = "0.2.2"
tokio = { version = "1", features = ["rt-multi-thread"] }
url = "2"

Usage

use cratestack::include_client_schema;
use cratestack_client_rust::{CborCodec, ClientConfig, CratestackClient};

include_client_schema!("../schemas/api.cstack");

let base_url = url::Url::parse("https://api.example.com")?;
let runtime = CratestackClient::new(ClientConfig::new(base_url), CborCodec);
let client = cratestack_schema::client::Client::new(runtime);

Codecs

use cratestack_client_rust::{CborCodec, JsonCodec};

let cbor_client = CratestackClient::new(config.clone(), CborCodec);
let json_client = CratestackClient::new(config, JsonCodec);

Request Authorization

with_request_authorizer attaches an implementation of RequestAuthorizer that returns extra headers per call. The trait gets a canonical-request string the implementer can sign:

use std::sync::Arc;
use cratestack_client_rust::{AuthorizationRequest, ClientError, RequestAuthorizer};

struct HmacAuthorizer { key: Vec<u8> }

impl RequestAuthorizer for HmacAuthorizer {
    fn authorize(
        &self,
        request: &AuthorizationRequest,
    ) -> Result<Vec<(String, String)>, ClientError> {
        let sig = sign(&self.key, &request.canonical_request_string());
        Ok(vec![(
            "authorization".to_owned(),
            format!("Signature {}", hex::encode(sig)),
        )])
    }
}

let client = runtime.with_request_authorizer(Arc::new(HmacAuthorizer { key }));

State Persistence

Journal requests for replay or offline recovery. The bundled implementations are InMemoryStateStore and JsonFileStateStore; the trait is ClientStateStore.

use std::sync::Arc;
use cratestack_client_rust::{ClientStateStore, JsonFileStateStore};

let store: Arc<dyn ClientStateStore> = Arc::new(JsonFileStateStore::new("./client_state.json"));
let runtime = runtime.with_state_store(store);

with_optional_state_store(None) is a no-op convenience for configuration-driven setup.

For a Redis-backed store, see cratestack-client-store-redis. For a SQLite-backed store, see cratestack-client-store-sqlite.

License

MIT

cratestack-client-rust 0.4.13