Go SDK
Relevant source files
The following files were used as context for generating this wiki page:
The Go SDK is a natively generated client library for interacting with services modeled in Crucible. It provides type-safe models, a context-aware HTTP client, and a standard-library runtime. The SDK ensures high performance and concurrency safety by leveraging Go's native primitives, such as goroutines and the context package.
Sources: crates/crucible-codegen-go/src/lib.rs:1-5, crates/crucible-cli/src/main.rs:252-259
SDK Architecture
The Go SDK generator produces a complete Go module. This module includes generated models, a service client, and integrated runtime logic. The following diagram illustrates the relationship between the generated components.
The ServiceClient acts as the primary entry point, utilizing an internal clientRuntime to execute requests against the service endpoint.
Sources: crates/crucible-codegen-go/src/lib.rs:434-450, crates/crucible-codegen-go/src/lib.rs:520-535
Core Components
The SDK generation process creates several essential files within the output directory:
| File | Description |
|---|---|
go.mod | Defines the Go module path and version requirements. |
models.go | Contains type definitions for structures, unions, enums, and lists. |
client.go | Implements the main service client and operation methods. |
runtime.go | Provides internal logic for HTTP communication and model decoding. |
auth.go | Manages authentication mechanisms like bearer tokens. |
crucible.json | Stores generator provenance and schema hashes. |
Sources: crates/crucible-codegen-go/src/lib.rs:520-565
Type Mapping and Models
Crucible shapes map to native Go types. For complex types like structures and unions, the generator uses pointers to represent optionality and recursion.
Simple Kind Mapping
Crucible's fundamental types map to Go standard library types or specialized internal types.
| Crucible Type | Go Native Type |
|---|---|
| String | string |
| Boolean | bool |
| Integer | int32 |
| Long | int64 |
| Timestamp | time.Time |
| BigInteger | *big.Int |
| BigDecimal | Decimal |
| Blob | []byte |
| Document | any |
Sources: crates/crucible-codegen-go/src/lib.rs:81-100
Model Accessors
For structures and unions, the generator produces four standard accessor methods per member to handle optionality without exposing raw pointers directly to standard users.
Set[Member](https://github.com/Operation-Leyline/crucible/blob/cc7f65d1b39bf89df74c892a98a62ec57c51b8b7/value%20T): Sets the value and marks the field as present.Get[Member](https://github.com/Operation-Leyline/crucible/blob/cc7f65d1b39bf89df74c892a98a62ec57c51b8b7/Member) T: Returns the value or a zero value if the field is absent or null.Has[Member](https://github.com/Operation-Leyline/crucible/blob/cc7f65d1b39bf89df74c892a98a62ec57c51b8b7/Member) bool: Reports if the member is present (including explicit null).IsNull[Member](https://github.com/Operation-Leyline/crucible/blob/cc7f65d1b39bf89df74c892a98a62ec57c51b8b7/Member) bool: Reports if the member is explicitly set to null.
Sources: crates/crucible-codegen-go/src/lib.rs:149-165, crates/crucible-codegen-go/src/lib.rs:374-420
Client Operations
Service operations are generated as methods on the ServiceClient struct. Each method accepts a context.Context and an input model, returning an output model and an error.
The client manages the conversion between typed Go models and the underlying wire schema JSON.
Sources: crates/crucible-codegen-go/src/lib.rs:465-478
Pagination
Operations marked with @paginated receive additional paginator support. The SDK generates a <Operation>Pages method that returns a paginator object.
- You call
Pages(input)to receive a paginator. - You use
HasMorePages()to check for remaining data. - You call
NextPage(ctx)to fetch the next result set.
The paginator snapshots the initial input and prevents repeated tokens to avoid infinite loops.
Sources: crates/crucible-codegen-go/src/lib.rs:480-510
Client Configuration
The Config struct allows users to customize the SDK behavior during construction.
| Option | Type | Default | Description |
|---|---|---|---|
Endpoint | string | Model default | The base URL of the service. |
HTTPClient | HTTPClient | http.DefaultClient | Custom transport for requests. |
RetryMode | RetryMode | RetryModeStandard | Strategy for handling transient failures. |
TelemetryHook | TelemetryHook | NopTelemetryHook | Callbacks for operation lifecycle events. |
Sources: crates/crucible-codegen-go/src/lib.rs:248-278, crates/crucible-codegen-go/src/lib.rs:445-455
Error Handling
The Go SDK treats service-modeled errors as native Go errors. Modeled exceptions are generated as structs that implement the error interface.
- Every generated error includes a
Metadatafield of type*ServiceError. Unwrap()allows access to the underlying HTTP response metadata.Error()returns a redacted string representation of the error.
Sources: crates/crucible-codegen-go/src/lib.rs:421-428, crates/crucible-codegen-go/src/lib.rs:456-464
Summary
The Go SDK provides a high-fidelity mapping of Crucible services into the Go ecosystem. It prioritizes type safety through generated models and concurrency safety through context-awareness. By integrating pagination, retries, and comprehensive error handling into the generated client, it reduces the boilerplate required for robust service integration.
Sources: crates/crucible-codegen-go/src/lib.rs:1-10, crates/crucible-codegen-common/src/guide.rs:411-430