Vendor dependencies
This commit is contained in:
dwrz
+205
@@ -0,0 +1,205 @@
|
||||
# Smithy Go
|
||||
|
||||
[](https://github.com/aws/smithy-go/actions/workflows/go.yml)
|
||||
[](https://github.com/aws/smithy-go/actions/workflows/codegen.yml)
|
||||
[](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.
|
||||
Reference in New Issue
Block a user