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:

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().

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.

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.