# Smithy Go

[![Go Build Status](https://github.com/aws/smithy-go/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/aws/smithy-go/actions/workflows/go.yml)
[![Codegen Build Status](https://github.com/aws/smithy-go/actions/workflows/codegen.yml/badge.svg?branch=main)](https://github.com/aws/smithy-go/actions/workflows/codegen.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

[Smithy](https://smithy.io/) code generators for [Go](https://go.dev/), 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](https://github.com/aws/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/`](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](https://smithy.io/2.0/quickstart.html) 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`:

```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`](codegen/smithy-go-codegen/src/main/java/software/amazon/smithy/go/codegen/GoSettings.java)
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](https://go.dev/ref/mod#go-mod-file-go) 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`](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/`](encoding) packages of the same name; see
[Encoding](#encoding) below.

| Protocol | Package | Notes |
|----------|---------|-------|
| [`smithy.protocols#rpcv2Cbor`](https://smithy.io/2.0/additional-specs/protocols/smithy-rpc-v2.html) | [`protocol/rpcv2`](transport/http/protocol/rpcv2) | |
| [`aws.protocols#restJson1`](https://smithy.io/2.0/aws/protocols/aws-restjson1-protocol.html) | [`protocol/restjson1`](transport/http/protocol/restjson1) | |
| [`aws.protocols#restXml`](https://smithy.io/2.0/aws/protocols/aws-restxml-protocol.html) | [`protocol/restxml`](transport/http/protocol/restxml) | |
| [`aws.protocols#awsJson1_0`](https://smithy.io/2.0/aws/protocols/aws-json-1_0-protocol.html) | [`protocol/awsjson`](transport/http/protocol/awsjson) | `awsjson.New10` |
| [`aws.protocols#awsJson1_1`](https://smithy.io/2.0/aws/protocols/aws-json-1_1-protocol.html) | [`protocol/awsjson`](transport/http/protocol/awsjson) | `awsjson.New11` |
| [`aws.protocols#awsQuery`](https://smithy.io/2.0/aws/protocols/aws-query-protocol.html) | [`protocol/awsquery`](transport/http/protocol/awsquery) | |
| [`aws.protocols#ec2Query`](https://smithy.io/2.0/aws/protocols/aws-ec2-query-protocol.html) | [`protocol/ec2query`](transport/http/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:

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

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

See [`codegen/README.md`](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`](middleware): The middleware stack that drives the operation
  pipeline.
- [`transport/http`](transport/http): HTTP request/response types and
  middleware.
- [`auth`](auth): Auth identity and scheme interfaces.
  - [`auth/bearer`](auth/bearer): Bearer token auth.
- [`endpoints`](endpoints): Endpoint resolution types.
- [`context`](context): Context helpers.
- [`logging`](logging): Logging interfaces.
- [`tracing`](tracing): Tracing interfaces.
- [`metrics`](metrics): Metrics interfaces.

### Encoding

Wire format encoders/decoders under [`encoding/`](encoding).

> [!NOTE]
> Most of these packages are effectively legacy. The protocol
> implementations under [`transport/http/protocol`](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/json)/[`document/cbor`](document/cbor)
> and [`eventstream`](eventstream), and by existing generated SDK code that
> predates the newer protocol implementations.

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

### Document

- [`document`](document): Smithy document type abstraction.
  - [`document/json`](document/json): JSON document codec.

### Utilities

- [`container`](container): Generic container types.
- [`io`](io): I/O helpers.
- [`ptr`](ptr): Pointer-to/from-value helpers.
- [`time`](time): Smithy timestamp format helpers.
- [`rand`](rand): UUID/randomness helpers.
- [`testing`](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-http-auth): AWS SigV4/SigV4A HTTP signing.
- [`tracing/smithyoteltracing`](tracing/smithyoteltracing): OpenTelemetry
  tracing adapter.
- [`metrics/smithyotelmetrics`](metrics/smithyotelmetrics): OpenTelemetry
  metrics adapter.

## Development

See [CONTRIBUTING](CONTRIBUTING.md) 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.