Crate polyoxide_core 

polyoxide-core

Core utilities and shared types for the polyoxide venue clients.

This crate provides the venue-neutral machinery every venue crate builds its HTTP clients on, and names no venue:

• Shared error types and error handling
• HTTP client configuration
• The transport seam, HttpTransport, with the Response it answers with and the TransportError it fails with, so the send loop names no HTTP library
• Request builder utilities
• One send loop, HttpClient::send, with the hooks a venue supplies (Throttle, RetryPolicy, Authenticator), and one health ping on it, HttpClient::health
• Per-endpoint window quotas (WindowQuotaTable, which builds a RateLimiter), token-cost buckets (CapacityBucket), the Hold their layers share, and the retry schedule (RetryConfig)
• Optional OS keychain credential storage (behind the keychain feature)

HTTP Client

Use HttpClientBuilder to create configured HTTP clients:

use polyoxide_core::HttpClientBuilder;

let client = HttpClientBuilder::new("https://api.example.com")
    .timeout_ms(60_000)
    .build()
    .unwrap();

Error Handling

An unsuccessful response is ApiError::Response, carrying an ErrorResponse: its status, headers, body, message and Retry-After. A venue’s error type wraps ApiError, and its From<ApiError> is its one decode, so a ? on core’s error anywhere reads the venue’s body.

Re-exports

pub use capacity::CapacityBucket;

pub use client::retry_after_header;

pub use client::HttpClient;

pub use client::HttpClientBuilder;

pub use client::DEFAULT_POOL_SIZE;

pub use client::DEFAULT_TIMEOUT_MS;

pub use config::ClientConfig;

pub use error::ApiError;

pub use error::ErrorResponse;

pub use health::Pong;

pub use hold::Hold;

pub use hooks::AttemptInfo;

pub use hooks::Authenticator;

pub use hooks::Charge;

pub use hooks::Cost;

pub use hooks::Decision;

pub use hooks::DefaultRetryPolicy;

pub use hooks::DynAuthenticator;

pub use hooks::DynRetryPolicy;

pub use hooks::DynThrottle;

pub use hooks::LayerCharge;

pub use hooks::LayerId;

pub use hooks::NoThrottle;

pub use hooks::Outcome;

pub use hooks::Refused;

pub use hooks::RequestMeta;

pub use hooks::RequestParts;

pub use hooks::ResponseMeta;

pub use hooks::RetryPolicy;

pub use hooks::Throttle;

pub use rate_limit::BucketId;

pub use rate_limit::EffectiveQuota;

pub use rate_limit::Matching;

pub use rate_limit::QuotaRow;

pub use rate_limit::RateLimiter;

pub use rate_limit::RetryConfig;

pub use rate_limit::WindowQuotaTable;

pub use request::QueryBuilder;

pub use request::Request;

pub use request::RequestError;

pub use response::Response;

pub use send::decode_json;

pub use transport::ReqwestTransport;

pub use transport::HttpRequest;

pub use transport::HttpTransport;

pub use transport::TransportError;

pub use transport::TransportKind;

pub use http;

pub use reqwest;

Modules

capacity

CapacityBucket: a token bucket that holds a published burst, charges integer costs, and can be resized in place.

client

config

The transport settings every client builder holds.

error

health

One health ping, on the send loop.

hold

Hold: what the server said, shared by every layer of a throttle.

hooks

The hooks a venue gives HttpClient::send.

macros

Macros for reducing boilerplate in API client implementations

rate_limit

Window quotas: WindowQuotaTable builds a RateLimiter, which counts requests against the buckets a request’s method and path resolve to.

request

response

The response an HttpTransport hands the send loop: an owned head and a lazy body.

send

HttpClient::send: core’s one send loop.

transport

The seam between the send loop and the network.

Macros

client_config_setters

Generates a client builder’s transport setters over a ClientConfig field: base_url, timeout_ms, pool_size, with_retry_config, max_concurrent, runtime and http_transport.

namespaces

Generates a client’s namespace accessors: each clones the listed client fields into the same-named fields of its namespace struct.

query_setters

Generates a request builder’s query-parameter setters.

Functions

csv

Comma-joins a multi-value query parameter; None when the joined value is empty, so the parameter is omitted rather than sent empty.

truncate_for_log

Truncate a string for safe inclusion in log output.