Struct ClientConfig 

#[non_exhaustive]
pub struct ClientConfig {
    pub base_url: String,
    pub timeout: Duration,
    pub stream_idle_timeout: Duration,
    pub retry: RetryConfig,
    pub stream_reconnect: ReconnectConfig,
    pub require_tls: bool,
    pub pool_max_idle_per_host: usize,
    pub pool_idle_timeout: Option<Duration>,
    pub max_concurrent_requests: Option<usize>,
    pub internal_token_provider: Option<InternalTokenProvider>,
}

Base configuration for a generated REST client.

#[non_exhaustive]: construct via ClientConfig::new and the with_* chain rather than a struct literal, so future transport knobs can be added without a breaking change.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

base_url: String

Base URL prefix (e.g., https://billing.internal). Combined with the base path declared in the projection trait.

timeout: Duration

Deadline applied to a single unary attempt — NOT to the whole logical call. A #[retryable] method may make up to retry.max_attempts attempts, so the worst-case wall-clock for a logical call is bounded by max_attempts × (timeout + retry.max_delay) (the per-retry backoff is itself clamped to RetryConfig::max_delay, including a server-advised Retry-After). There is deliberately no separate whole-call budget field.

stream_idle_timeout: Duration

Per-item idle deadline for streams of any framing: the maximum gap between two received wire chunks before the stream is treated as timed out. A long-lived stream is NOT bounded by timeout (which would kill a healthy slow stream); it is bounded by this larger idle deadline instead. Defaults to 60s (> the unary default).

This is idle, not quiet: any wire chunk resets it, including ones that dispatch no item (an SSE keepalive comment, a multipart part header block arriving on its own).

retry: RetryConfig

Retry policy applied to methods marked #[retryable].

stream_reconnect: ReconnectConfig

Reconnect policy for streams of any framing. By default max_attempts: 0 — stream failures bubble up unchanged. Set explicitly to opt into transparent re-open on a transient failure.

Two limits are deliberate rather than accidental:

• It applies only to a method whose open is immediate (#[streaming] fn). A fallible open (#[streaming] async fn) carries domain semantics the client must not blindly repeat — a re-open can collide with an exclusion lease the first open acquired, and its failure would land as a stream item, past the caller’s open-time error handling. Generated code therefore passes ReconnectConfig::disabled for a fallible open regardless of this value.
• Resume via Last-Event-ID is SSE-only. A reconnected multipart/mixed stream re-issues the original request with no resume token, because the framing has none. The transport still reopens it, but that is a blind restart, not a resume: the server replays the body from its first part, so any items already delivered before the failure are delivered again (at-least-once, with no marker for the restart). Enable reconnect for a multipart stream only where the consumer tolerates duplicates; one needing exactly-once must instead leave reconnect disabled and run its own reopen loop with application-level dedup.

require_tls: bool

When true, the generated client refuses plaintext http:// and requires TLS (toolkit_http::TransportSecurity::TlsOnly) for every request — including the bearer-carrying Authorization header, which otherwise would ride whatever scheme base_url uses. Defaults to false, preserving the platform’s existing in-mesh service-to-service convention where plaintext HTTP inside a secured network boundary is an accepted, deliberate choice (see build_default_http_client). Set this when a resolved endpoint may cross an untrusted network. Read by both the REST and gRPC transports.

pool_max_idle_per_host: usize

Maximum idle keep-alive connections retained per upstream host (active in-flight requests are not capped). Defaults to 128; raise via ClientTuning for higher concurrency. REST transport only.

Keep it at or above the expected per-upstream concurrency: below that, hyper closes excess connections as they idle and reopens them per request, producing a connect(2) storm that dominates CPU. The 128 default clears the ~100-concurrent gear-to-gear traffic that motivated it (the old toolkit-http default of 32 did not).

pool_idle_timeout: Option<Duration>

How long an idle keep-alive connection is retained before it is closed — the companion of pool_max_idle_per_host (which bounds how many). Keep it above the gap between bursts to an upstream so connections stay warm. Defaults to 90s. REST transport only.

None does not mean “kept indefinitely”: it leaves the hyper-util setter unset, so hyper-util’s own default (~90s) applies. The default is an explicit Some(90s) for that reason.

max_concurrent_requests: Option<usize>

Maximum in-flight requests through this client at once (across all upstream hosts). None disables the limiter; Some(n) caps at n, with Some(0) clamped to 1 by the transport so the client can’t wedge shedding everything. Defaults to Some(128), aligned with pool_max_idle_per_host so the idle pool is fully reusable before load is shed. REST transport only.

The cap bounds requests waiting on response headers — the tower permit is released once headers arrive, so a long-lived SSE/multipart body holds no slot while it streams; size it against in-flight requests, not open streams. A shed request surfaces as TransportError::Overloaded, which is not transient, so a saturated client fails fast rather than retrying into its own overload.

internal_token_provider: Option<InternalTokenProvider>

Source of the platform-plane internal credential attached to methods whose plane marker is PlatformSecurityContext (carried as X-ToolKit-Internal-Token). None (the default) attaches nothing — legitimate for Profile 1 / in-process (InternalCredential::None); the requirement is enforced server-side. The bootstrap layer populates this from the process’s selected InternalCredential. Tenant-plane methods (SecurityContext) never consult it; they forward the caller’s bearer token from the argument.

Implementations

impl ClientConfig

pub fn new(base_url: impl Into<String>) -> ClientConfig

Create a new config with sensible defaults.

pub fn with_timeout(self, timeout: Duration) -> ClientConfig

Override the per-call (unary) timeout.

pub fn with_stream_idle_timeout(self, idle: Duration) -> ClientConfig

Override the per-item stream idle deadline (max gap between wire chunks). See Self::stream_idle_timeout.

pub fn with_retry(self, retry: RetryConfig) -> ClientConfig

Override the retry policy.

pub fn with_stream_reconnect( self, stream_reconnect: ReconnectConfig, ) -> ClientConfig

Override the stream reconnect policy. Use ReconnectConfig::disabled() to disable (the default) or ReconnectConfig::enabled() to opt in. See Self::stream_reconnect for what it does and does not govern.

pub fn with_require_tls(self, require_tls: bool) -> ClientConfig

Require TLS (reject plaintext http://) for this client. See Self::require_tls.

pub fn with_pool_max_idle_per_host(self, max: usize) -> ClientConfig

Override the max idle keep-alive connections per upstream host. See Self::pool_max_idle_per_host.

pub fn with_pool_idle_timeout(self, timeout: Option<Duration>) -> ClientConfig

Override how long idle keep-alive connections are retained (None uses hyper-util’s default). See Self::pool_idle_timeout.

pub fn with_max_concurrent_requests(self, max: Option<usize>) -> ClientConfig

Override the max concurrent in-flight requests (None disables the limiter). See Self::max_concurrent_requests.

pub fn with_internal_token_provider( self, provider: impl Into<Option<InternalTokenProvider>>, ) -> ClientConfig

Set (or clear) the platform-plane internal-credential provider. See Self::internal_token_provider. Accepts either an InternalTokenProvider or an Option<InternalTokenProvider>, so the bootstrap layer can pass through whatever the process selected without a branch.

Trait Implementations

impl Clone for ClientConfig

fn clone(&self) -> ClientConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ClientConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.