Smithy Go

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

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.

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.

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:

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

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.

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

• 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.

Wire format encoders/decoders under encoding/.

• 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: Smithy document type abstraction.
  • document/json: JSON document codec.

• 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.

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.

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

This project is licensed under the Apache-2.0 License.