Smithy Go

Smithy code generators for Go, and the runtime package the generated code depends on.

[!WARNING] All interfaces in this repository are subject to change. The client code generator in particular powers aws-sdk-go-v2, but arbitrary client generation is in an early stage of development:

• Generated clients are missing certain features that were originally implemented SDK-side (e.g. retries)
• There may be bugs
• The public APIs of generated clients may be unstable

If you are interested in using the client code generators, we encourage you to experiment and share any feedback with us in an issue.

---

This repository contains two major components:

1. Codegen (codegen/): A Java/Gradle-based Smithy build plugin that generates Go client, server, and shape code from Smithy models.
2. Runtime (this module, github.com/aws/smithy-go): The Go packages that code generated by the plugins above depends on.

[!NOTE] This repository does not contain any generated clients, such as for S3 or other AWS services. Rather, these are the tools that facilitate generating those clients (and non-AWS Smithy clients) from a Smithy model.

Getting started

If this is your first time using Smithy, follow the Smithy Quickstart guide to learn the basics and create a simple Smithy model.

The smithy-go runtime requires a minimum version of Go 1.24.

Codegen

To generate a Go client from a Smithy model, apply the go-codegen plugin in your smithy-build.json:

{
  "version": "1.0",
  "sources": [
    "models"
  ],
  "maven": {
    "dependencies": [
      "software.amazon.smithy.go:smithy-go-codegen:[0.1.0,2.0)"
    ]
  },
  "plugins": {
    "go-codegen": {
      "service": "example.weather#Weather",
      "module": "github.com/example/weather",
      "generateGoMod": true,
      "goDirective": "1.24"
    }
  }
}

This repository implements the following Smithy build plugins:

ID	GAV prefix	Description
go-codegen	software.amazon.smithy.go:smithy-go-codegen	Go client code generation for Smithy models.
go-server-codegen	software.amazon.smithy.go:smithy-go-codegen	Go server code generation for Smithy models (work-in-progress, undocumented).
go-shape-codegen	software.amazon.smithy.go:smithy-go-codegen	Go shape code generation (types only) for Smithy models (work-in-progress, undocumented).

go-codegen settings

GoSettings contains all of the settings enabled from smithy-build.json. The up-to-date list of top-level properties enabled for go-codegen can be found in GoSettings::from().

Setting	Type	Required	Description
service	string	yes	The Shape ID of the service for which to generate the client.
module	string	yes	Name of the module in generated.json (and go.mod if generateGoMod is enabled) and doc.go.
generateGoMod	boolean		Whether to generate a default go.mod file. The default value is false.
goDirective	string		Go directive of the module. The default value is the minimum supported Go version.

Supported protocols

The protocol a generated client uses is configured by the Protocol field on the client’s Options. The SDK configures a default based on the protocol traits applied to the modeled service.

Each protocol is implemented as its own package under transport/http/protocol. Serialization for these protocols is handled by internal codecs under protocol/internal (e.g. protocol/internal/json, protocol/internal/cbor, protocol/internal/xml); these largely supersede the top-level encoding/ packages of the same name; see Encoding below.

Protocol	Package	Notes
smithy.protocols#rpcv2Cbor	protocol/rpcv2
aws.protocols#restJson1	protocol/restjson1
aws.protocols#restXml	protocol/restxml
aws.protocols#awsJson1_0	protocol/awsjson	awsjson.New10
aws.protocols#awsJson1_1	protocol/awsjson	awsjson.New11
aws.protocols#awsQuery	protocol/awsquery
aws.protocols#ec2Query	protocol/ec2query

These packages are client-only; smithy-go does not currently implement server-side protocol support.

Building and testing the codegen plugins is done via Gradle from the codegen/ directory:

# Build and test codegen
cd codegen && ./gradlew build

# Publish to local Maven for downstream use
cd codegen && ./gradlew publishToMavenLocal

See codegen/README.md for local setup instructions.

Runtime packages

All generated clients depend on this module (github.com/aws/smithy-go) at runtime. It also includes a few standalone submodules published separately.

Core

• middleware: The middleware stack that drives the operation pipeline.
• transport/http: HTTP request/response types and middleware.
• auth: Auth identity and scheme interfaces.
  • auth/bearer: Bearer token auth.
• endpoints: Endpoint resolution types.
• context: Context helpers.
• logging: Logging interfaces.
• tracing: Tracing interfaces.
• metrics: Metrics interfaces.

Encoding

Wire format encoders/decoders under encoding/.

[!NOTE] Most of these packages are effectively legacy. The protocol implementations under transport/http/protocol (used by current client codegen) have their own internal codecs under protocol/internal/* and generally do not build on these packages. The encoding/json, encoding/xml, and encoding/cbor packages otherwise remain in use by document/json/document/cbor and eventstream, and by existing generated SDK code that predates the newer protocol implementations.

• encoding/json: JSON encoding/decoding.
• encoding/xml: XML encoding/decoding.
• encoding/cbor: CBOR encoding/decoding (used by rpcv2Cbor).
• encoding/httpbinding: HTTP binding serde helpers.

Document

• document: Smithy document type abstraction.
  • document/json: JSON document codec.

Utilities

• container: Generic container types.
• io: I/O helpers.
• ptr: Pointer-to/from-value helpers.
• time: Smithy timestamp format helpers.
• rand: UUID/randomness helpers.
• testing: Test assertion helpers for generated protocol tests.

Standalone modules

These are published as separate Go modules, each with its own go.mod.

• aws-http-auth: AWS SigV4/SigV4A HTTP signing.
• tracing/smithyoteltracing: OpenTelemetry tracing adapter.
• metrics/smithyotelmetrics: OpenTelemetry metrics adapter.

Development

See CONTRIBUTING for more information on contributing to this project, including the changelog process for runtime changes.

License

This project is licensed under the Apache-2.0 License.