Client Runtime Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Client Runtime provides the execution layer for native SDKs generated from Crucible models. It manages low-level concerns including HTTP transport, request authentication, automatic retries with backoff, and pagination logic. The architecture ensures that generated clients remain thin while delegating complex behavior to a language-specific runtime library.
Sources: README.md:1-12, AGENTS.md:52-54
Core Components
The client runtime architecture consists of several standardized components across all supported languages.
Client Configuration (ClientConfig)
The ClientConfig structure stores operational parameters for the client instance. You use it to define:
- Service endpoints and base URLs.
- Authentication providers (e.g., Bearer tokens).
- Timeout durations for the entire call budget.
- Retry strategy parameters (max attempts, base delay, max delay).
- Custom HTTP transports and request middleware.
Sources: crates/crucible-codegen-r/src/lib.rs:565-575, crates/crucible-codegen-ruby/src/lib.rs:25-30
Client Runtime (ClientRuntime)
The orchestrator component manages the lifecycle of a service call. It coordinates between the generated operation methods and the low-level transport. It maintains connection pools and shared retry quotas across multiple threads or coroutines.
Sources: crates/crucible-codegen-kotlin/src/lib.rs:434-440, crates/crucible-codegen-ruby/src/lib.rs:343-345
Wire Codec and Schema
The WireCodec handles the conversion between native language models and the wire format (Crucible JSON). It uses a schema.json file generated from the IR to validate data types and redact fields marked as @sensitive.
Sources: crates/crucible-codegen-common/src/guide.rs:18-28, crates/crucible-codegen-go/src/lib.rs:396-402
Request Orchestration Flow
Every operation call follows a phased pipeline managed by the runtime.
The runtime coordinates the sequence from encoding native objects to handling transport responses.
Sources: crates/crucible-codegen-common/src/guide.rs:326-331, crates/crucible-codegen-go/src/lib.rs:420-435
Error Handling and Retries
The runtime implements standardized retry logic to handle transient failures.
| Feature | Behavior |
|---|---|
| Retry Quota | Shared budget across calls to prevent overloading the service. |
| Throttling | Always retried for any operation. |
| Transport Failures | Retried for read-only or idempotent operations. |
| Backoff | Full-jitter exponential backoff using base_delay and max_delay. |
| Idempotency | Automatically fills idempotency tokens if unset by the caller. |
Sources: crates/crucible-codegen-common/src/guide.rs:326-331, crates/crucible-codegen-kotlin/src/lib.rs:528-545
Exception Hierarchy
Failure modes are categorized into specific types:
- ServiceException: Modelled errors defined in the
.crufile. - NetworkError: No response arrived from the transport.
- DeadlineError: The call exceeded the configured timeout.
- CancelledError: The caller cancelled the operation via a cancellation token.
Sources: crates/crucible-codegen-ruby/src/lib.rs:27-31, crates/crucible-codegen-r/src/lib.rs:555-564
Pagination Architecture
Paginated operations provide a high-level API to walk through result sets lazily.
The paginator advanced the input token based on the service's previous response until the token is absent or empty.
Sources: crates/crucible-codegen-go/src/lib.rs:440-455, crates/crucible-codegen-ruby/src/lib.rs:360-363
Language-Specific Implementations
Each language generator bundles a runtime tailored to that ecosystem's concurrency model.
| Language | Concurrency Model | Primary Transport |
|---|---|---|
| Kotlin | Coroutines (suspend) | Ktor / OkHttp |
| Python | Sync and Async (httpx) | HTTPX |
| Go | Context-aware (net/http) | Standard Library |
| Ruby | Thread-safe blocking | net-http |
| Dart | Futures and Streams | http package |
Sources: crates/crucible-codegen-kotlin/src/lib.rs:1-10, crates/crucible-codegen-python/src/lib.rs:1-10, crates/crucible-codegen-go/src/lib.rs:1-10
Summary
The Client Runtime Architecture decouples service-specific logic from generic communication patterns. It uses a shared wire contract and schema-based validation to ensure consistency across languages. By centralizing retries, authentication, and pagination, the runtime provides a robust and conformant interface for interacting with Crucible-based services.
Sources: README.md:5-10, AGENTS.md:52-54