Documentation
¶
Overview ¶
Package smithy provides the core components for a Smithy SDK.
Index ¶
- func ReadList(d ShapeDeserializer, schema *Schema, memberFn func() error) error
- func ReadMap(d ShapeDeserializer, schema *Schema, memberFn func(string) error) error
- func ReadStruct(d ShapeDeserializer, schema *Schema, memberFn func(*Schema) error) error
- func ReadUnion(d ShapeDeserializer, schema *Schema, memberFn func(*Schema) error) error
- func SchemaDirectTrait[T Trait](s *Schema) (T, bool)
- func SchemaExtension[T any](s *Schema, id ExtensionID, build func(*Schema) *T) *T
- func SchemaTrait[T Trait](s *Schema) (T, bool)
- type APIError
- type CanceledError
- type Deserializable
- type DeserializableError
- type DeserializationError
- type Documentdeprecated
- type ErrorFault
- type ExtensionID
- type GenericAPIError
- type IndexableTrait
- type InvalidParamError
- type InvalidParamsError
- type OperationError
- type OperationSchema
- type ParamRequiredError
- type Properties
- type PropertiesReader
- type Schema
- func (s *Schema) AddMember(name string, target *Schema, ts ...Trait) *Schema
- func (s *Schema) ID() ShapeID
- func (s *Schema) ListMember() *Schema
- func (s *Schema) MapKey() *Schema
- func (s *Schema) MapValue() *Schema
- func (s *Schema) Member(name string) *Schema
- func (s *Schema) MemberName() string
- func (s *Schema) Members() map[string]*Schema
- func (s *Schema) TargetID() ShapeID
- func (s *Schema) Type() ShapeType
- type Serializable
- type SerializationError
- type ServiceSchema
- type ShapeDeserializer
- type ShapeID
- type ShapeSerializer
- type ShapeType
- type StreamingInput
- type StreamingOutput
- type Trait
- type TypeRegistry
- type TypeRegistryEntry
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ReadList ¶ added in v1.27.0
func ReadList(d ShapeDeserializer, schema *Schema, memberFn func() error) error
ReadList is a utility API for generated clients.
func ReadMap ¶ added in v1.27.0
func ReadMap(d ShapeDeserializer, schema *Schema, memberFn func(string) error) error
ReadMap is a utility API for generated clients.
func ReadStruct ¶ added in v1.27.0
func ReadStruct(d ShapeDeserializer, schema *Schema, memberFn func(*Schema) error) error
ReadStruct is a utility API for generated clients.
func ReadUnion ¶ added in v1.27.0
func ReadUnion(d ShapeDeserializer, schema *Schema, memberFn func(*Schema) error) error
ReadUnion is a utility API for generated clients.
func SchemaDirectTrait ¶ added in v1.27.0
SchemaDirectTrait returns the target trait on the schema if it was declared directly on the schema.
For member schemas this returns the trait only if it was declared on the member itself, ignoring any trait inherited from the target shape. For non-member schemas this is equivalent to SchemaTrait.
func SchemaExtension ¶ added in v1.27.0
func SchemaExtension[T any](s *Schema, id ExtensionID, build func(*Schema) *T) *T
SchemaExtension retrieves or lazily computes the extension for the given slot. build is called on first access for a schema and the result is cached. The build function must return a pointer to an immutable value.
func SchemaTrait ¶ added in v1.27.0
SchemaTrait returns the target trait on the schema if it exists.
For member schemas this returns the effective trait, which is the trait declared directly on the member if present, else the trait inherited from the target shape.
Types ¶
type APIError ¶
type APIError interface {
error
// ErrorCode returns the error code for the API exception.
ErrorCode() string
// ErrorMessage returns the error message for the API exception.
ErrorMessage() string
// ErrorFault returns the fault for the API exception.
ErrorFault() ErrorFault
}
APIError provides the generic API and protocol agnostic error type all SDK generated exception types will implement.
type CanceledError ¶
type CanceledError struct {
Err error
}
CanceledError is the error that will be returned by an API request that was canceled. API operations given a Context may return this error when canceled.
func (*CanceledError) CanceledError ¶
func (*CanceledError) CanceledError() bool
CanceledError returns true to satisfy interfaces checking for canceled errors.
func (*CanceledError) Error ¶
func (e *CanceledError) Error() string
func (*CanceledError) Unwrap ¶
func (e *CanceledError) Unwrap() error
Unwrap returns the underlying error, if there was one.
type Deserializable ¶ added in v1.27.0
type Deserializable interface {
Deserialize(ShapeDeserializer) error
}
Deserializable is an entity that can unmarshal itself from a ShapeDeserializer.
type DeserializableError ¶ added in v1.27.0
type DeserializableError interface {
Deserializable
error
}
DeserializableError is implemented by modeled error types for a service.
type DeserializationError ¶
DeserializationError provides a wrapper for an error that occurs during deserialization.
func (*DeserializationError) Error ¶
func (e *DeserializationError) Error() string
Error returns a formatted error for DeserializationError
func (*DeserializationError) Unwrap ¶
func (e *DeserializationError) Unwrap() error
Unwrap returns the underlying Error in DeserializationError
type ErrorFault ¶
type ErrorFault int
ErrorFault provides the type for a Smithy API error fault.
const ( FaultUnknown ErrorFault = iota FaultServer FaultClient )
ErrorFault enumeration values
func (ErrorFault) String ¶
func (f ErrorFault) String() string
type ExtensionID ¶ added in v1.27.0
type ExtensionID int
ExtensionID identifies a schema extension slot. Each codec family (JSON, CBOR, etc.) uses a distinct slot to cache precomputed data.
const ( ExtJSON ExtensionID = iota // transport/http/protocol/internal/json ExtCBOR // transport/http/protocol/internal/cbor ExtXML // transport/http/protocol/internal/xml ExtQuery // transport/http/protocol/internal/query )
type GenericAPIError ¶
type GenericAPIError struct {
Code string
Message string
Fault ErrorFault
}
GenericAPIError provides a generic concrete API error type that SDKs can use to deserialize error responses into. Should be used for unmodeled or untyped errors.
func (*GenericAPIError) Error ¶
func (e *GenericAPIError) Error() string
func (*GenericAPIError) ErrorCode ¶
func (e *GenericAPIError) ErrorCode() string
ErrorCode returns the error code for the API exception.
func (*GenericAPIError) ErrorFault ¶
func (e *GenericAPIError) ErrorFault() ErrorFault
ErrorFault returns the fault for the API exception.
func (*GenericAPIError) ErrorMessage ¶
func (e *GenericAPIError) ErrorMessage() string
ErrorMessage returns the error message for the API exception.
type IndexableTrait ¶ added in v1.27.0
IndexableTrait is optionally implemented by Trait values that have a reserved index in Schema's indexed trait slice. All traits defined in the traits package implement this interface.
You SHOULD NOT implement this outside of a smithy-go trait unless you know what you are doing. If you implement this and return a value that collides with one of the primary serde-based indexed traits (see index.go) you will probably break something.
type InvalidParamError ¶
type InvalidParamError interface {
error
// Field name the error occurred on.
Field() string
// SetContext updates the context of the error.
SetContext(string)
// AddNestedContext updates the error's context to include a nested level.
AddNestedContext(string)
}
An InvalidParamError represents an invalid parameter error type.
type InvalidParamsError ¶
type InvalidParamsError struct {
// Context is the base context of the invalid parameter group.
Context string
// contains filtered or unexported fields
}
An InvalidParamsError provides wrapping of invalid parameter errors found when validating API operation input parameters.
func (*InvalidParamsError) Add ¶
func (e *InvalidParamsError) Add(err InvalidParamError)
Add adds a new invalid parameter error to the collection of invalid parameters. The context of the invalid parameter will be updated to reflect this collection.
func (*InvalidParamsError) AddNested ¶
func (e *InvalidParamsError) AddNested(nestedCtx string, nested InvalidParamsError)
AddNested adds the invalid parameter errors from another InvalidParamsError value into this collection. The nested errors will have their nested context updated and base context to reflect the merging.
Use for nested validations errors.
func (InvalidParamsError) Error ¶
func (e InvalidParamsError) Error() string
Error returns the string formatted form of the invalid parameters.
func (InvalidParamsError) Errs ¶
func (e InvalidParamsError) Errs() []error
Errs returns a slice of the invalid parameters
func (*InvalidParamsError) Len ¶
func (e *InvalidParamsError) Len() int
Len returns the number of invalid parameter errors
type OperationError ¶
OperationError decorates an underlying error which occurred while invoking an operation with names of the operation and API.
func (*OperationError) Error ¶
func (e *OperationError) Error() string
func (*OperationError) Operation ¶
func (e *OperationError) Operation() string
Operation returns the name of the API operation the error occurred with.
func (*OperationError) Service ¶
func (e *OperationError) Service() string
Service returns the name of the API service the error occurred with.
func (*OperationError) Unwrap ¶
func (e *OperationError) Unwrap() error
Unwrap returns the nested error if any, or nil.
type OperationSchema ¶ added in v1.27.0
type OperationSchema struct {
*Schema
Input, Output *Schema
// contains filtered or unexported fields
}
OperationSchema describes an operation, which is essentially its own schema with additional pointers to its input and output.
func NewOperationSchema ¶ added in v1.27.0
func NewOperationSchema(op, input, output *Schema) *OperationSchema
NewOperationSchema returns an OperationSchema for (input, output).
func (*OperationSchema) IsInputEventStream ¶ added in v1.27.0
func (s *OperationSchema) IsInputEventStream() bool
IsInputEventStream reports whether this is an input event stream.
func (*OperationSchema) IsOutputEventStream ¶ added in v1.27.0
func (s *OperationSchema) IsOutputEventStream() bool
IsOutputEventStream reports whether this is an output event stream.
type ParamRequiredError ¶
type ParamRequiredError struct {
// contains filtered or unexported fields
}
An ParamRequiredError represents an required parameter error.
func NewErrParamRequired ¶
func NewErrParamRequired(field string) *ParamRequiredError
NewErrParamRequired creates a new required parameter error.
func (*ParamRequiredError) AddNestedContext ¶
func (e *ParamRequiredError) AddNestedContext(ctx string)
AddNestedContext prepends a context to the field's path.
func (ParamRequiredError) Error ¶
func (e ParamRequiredError) Error() string
Error returns the string version of the invalid parameter error.
func (ParamRequiredError) Field ¶
func (e ParamRequiredError) Field() string
Field Returns the field and context the error occurred.
func (*ParamRequiredError) SetContext ¶
func (e *ParamRequiredError) SetContext(ctx string)
SetContext updates the base context of the error.
type Properties ¶ added in v1.14.0
type Properties struct {
// contains filtered or unexported fields
}
Properties provides storing and reading metadata values. Keys may be any comparable value type. Get and Set will panic if a key is not comparable.
The zero value for a Properties instance is ready for reads/writes without any additional initialization.
func (*Properties) Get ¶ added in v1.14.0
func (m *Properties) Get(key any) any
Get attempts to retrieve the value the key points to. Returns nil if the key was not found.
Panics if key type is not comparable.
func (*Properties) Has ¶ added in v1.14.0
func (m *Properties) Has(key any) bool
Has returns whether the key exists in the metadata.
Panics if the key type is not comparable.
func (*Properties) Set ¶ added in v1.14.0
func (m *Properties) Set(key, value any)
Set stores the value pointed to by the key. If a value already exists at that key it will be replaced with the new value.
Panics if the key type is not comparable.
func (*Properties) SetAll ¶ added in v1.17.0
func (m *Properties) SetAll(other *Properties)
SetAll accepts all of the given Properties into the receiver, overwriting any existing keys in the case of conflicts.
func (*Properties) Values ¶ added in v1.21.0
func (m *Properties) Values() map[any]any
Values returns a shallow clone of the property set's values.
type PropertiesReader ¶ added in v1.14.0
PropertiesReader provides an interface for reading metadata from the underlying metadata container.
type Schema ¶ added in v1.27.0
type Schema struct {
// contains filtered or unexported fields
}
Schema encodes information about a shape from a Smithy model.
Generated clients use schemas at runtime to dynamically (de)serialize request/responses.
func NewSchema ¶ added in v1.27.0
NewSchema creates a new Schema with the given shape ID and traits.
func (*Schema) AddMember ¶ added in v1.27.0
AddMember adds a member to the schema derived from the target, with optional trait overrides. The member schema is returned for caller reference.
The member schema's effective trait view (accessed via SchemaTrait) inherits all of the target's traits, then applies the overrides. The member's direct trait view (accessed via SchemaDirectTrait) contains only the overrides, i.e. the traits declared directly on the member.
func (*Schema) ListMember ¶ added in v1.27.0
ListMember returns the "member" schema for list types.
func (*Schema) Member ¶ added in v1.27.0
Member returns the member schema for the given name, or nil.
func (*Schema) MemberName ¶ added in v1.27.0
MemberName returns the member component of the schema's shape ID.
func (*Schema) Members ¶ added in v1.27.0
Members returns the schema's members as a map of name to schema.
type Serializable ¶ added in v1.27.0
type Serializable interface {
Serialize(ShapeSerializer)
}
Serializable is an entity that can describe itself to a ShapeSerializer to be encoded to some format.
Unlike the standard library marshaler interfaces, which idiomatically encode to []byte, the output format and data type here is not specified at all. This is because Smithy shapes need to encode to a variety of formats or data carriers. For example, HTTP-binding JSON protocols need to serialize some members to bytes (the HTTP request body) and others directly to fields on the HTTP request itself (e.g. headers).
type SerializationError ¶
type SerializationError struct {
Err error // original error
}
SerializationError represents an error that occurred while attempting to serialize a request
func (*SerializationError) Error ¶
func (e *SerializationError) Error() string
Error returns a formatted error for SerializationError
func (*SerializationError) Unwrap ¶
func (e *SerializationError) Unwrap() error
Unwrap returns the underlying Error in SerializationError
type ServiceSchema ¶ added in v1.27.0
ServiceSchema describes a service shape.
func NewServiceSchema ¶ added in v1.27.0
func NewServiceSchema(schema *Schema, version string) *ServiceSchema
NewServiceSchema returns a ServiceSchema for the given service shape.
type ShapeDeserializer ¶ added in v1.27.0
type ShapeDeserializer interface {
ReadInt8(*Schema, *int8) error
ReadInt16(*Schema, *int16) error
ReadInt32(*Schema, *int32) error
ReadInt64(*Schema, *int64) error
ReadFloat32(*Schema, *float32) error
ReadFloat64(*Schema, *float64) error
ReadBool(*Schema, *bool) error
ReadString(*Schema, *string) error
ReadBlob(*Schema, *[]byte) error
ReadTime(*Schema, *time.Time) error
ReadBigInt(*Schema, *big.Int) error
ReadBigFloat(*Schema, *big.Float) error
ReadNil(*Schema) (bool, error)
ReadStruct(*Schema) error
ReadStructMember() (*Schema, error)
ReadUnion(*Schema) (*Schema, error)
ReadDocument(*Schema, *document.Value) error
ReadList(*Schema) error
ReadListItem(*Schema) (hasMoreElements bool, err error)
ReadMap(*Schema) error
ReadMapKey(*Schema) (key string, hasMoreElements bool, err error)
}
ShapeDeserializer implements the unmarshaling from some unspecified data format to an in-code representation of a shape, which is determined by the implementation.
type ShapeID ¶ added in v1.27.0
type ShapeID struct {
Namespace, Name, Member string
}
ShapeID fields of a Smithy shape ID.
type ShapeSerializer ¶ added in v1.27.0
type ShapeSerializer interface {
Bytes() []byte
WriteInt8(*Schema, int8)
WriteInt16(*Schema, int16)
WriteInt32(*Schema, int32)
WriteInt64(*Schema, int64)
WriteFloat32(*Schema, float32)
WriteFloat64(*Schema, float64)
WriteBool(*Schema, bool)
WriteString(*Schema, string)
WriteBigInt(*Schema, *big.Int)
WriteBigFloat(*Schema, *big.Float)
WriteBlob(*Schema, []byte)
WriteTime(*Schema, time.Time)
WriteUnion(schema, variant *Schema)
CloseUnion()
WriteDocument(*Schema, document.Value)
WriteNil(*Schema)
WriteStruct(*Schema)
CloseStruct()
WriteList(*Schema)
CloseList()
WriteMap(*Schema)
WriteKey(*Schema, string)
CloseMap()
}
ShapeSerializer implements the marshaling of an in-code representation of a shape to an unspecified data format, which is determined by the implementation.
A ShapeSerializer is consumed by the **code-generated** Serialize() method of a modeled structure. For example:
func (v *PutItemInput) Serialize(s smithy.ShapeSerializer) {
s.WriteStruct(schemas.PutItemInput)
v.SerializeMembers(s)
s.CloseStruct()
}
func (v *PutItemInput) SerializeMembers(s smithy.ShapeSerializer) {
if v.TableName != nil {
s.WriteString(schemas.PutItemInput_TableName, *v.TableName)
}
if v.Item != nil {
serializeAttributeMap(s, schemas.PutItemInput_Item, v.Item)
}
// ...
}
type ShapeType ¶ added in v1.27.0
type ShapeType int
ShapeType is a type of Smithy shape. See https://smithy.io/2.0/spec/idl.html#defining-shapes.
const ( ShapeTypeBlob ShapeType = iota ShapeTypeBoolean ShapeTypeString ShapeTypeTimestamp ShapeTypeByte ShapeTypeShort ShapeTypeInteger ShapeTypeLong ShapeTypeFloat ShapeTypeDocument ShapeTypeDouble ShapeTypeBigDecimal ShapeTypeBigInteger ShapeTypeEnum ShapeTypeIntEnum ShapeTypeList ShapeTypeSet ShapeTypeMap ShapeTypeStructure ShapeTypeUnion ShapeTypeMember ShapeTypeService ShapeTypeResource ShapeTypeOperation )
Enumerates ShapeType per the Smithy IDL.
type StreamingInput ¶ added in v1.27.0
StreamingInput is implemented by input types that have a streaming blob payload (an io.Reader member with @httpPayload + @streaming).
type StreamingOutput ¶ added in v1.27.0
type StreamingOutput interface {
SetPayloadStream(io.ReadCloser)
}
StreamingOutput is implemented by output types that have a streaming blob payload (an io.ReadCloser member with @httpPayload + @streaming).
type Trait ¶ added in v1.27.0
type Trait interface {
TraitID() ShapeID
}
Trait represents a trait applied to a shape in a Smithy model. Traits related to (de)serialization are included in code-generated Schemas for the client.
type TypeRegistry ¶ added in v1.27.0
type TypeRegistry struct {
Entries map[string]*TypeRegistryEntry
}
TypeRegistry creates an instance of a type based on its Smithy IDL shape ID.
Generated clients have an exported package-level registry (named TypeRegistry) that holds all structure types for the service.
func (*TypeRegistry) DeserializableError ¶ added in v1.27.0
func (t *TypeRegistry) DeserializableError(id string) (DeserializableError, bool)
DeserializableError provides an instance of a deserializable error structure for a given shape ID.
The ID is given as a string here since this will be called in a context where a shape ID is a discriminator read in from some wire payload.
func (*TypeRegistry) LookupEntry ¶ added in v1.27.0
func (t *TypeRegistry) LookupEntry(id string) (*TypeRegistryEntry, bool)
LookupEntry returns the registry entry for the given shape ID.
type TypeRegistryEntry ¶ added in v1.27.0
TypeRegistryEntry holds the schema and constructor for a registered shape.
func RegistryEntry ¶ added in v1.27.0
func RegistryEntry[T any](schema *Schema) *TypeRegistryEntry
RegistryEntry creates a type registry entry.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package auth defines protocol-agnostic authentication types for smithy clients.
|
Package auth defines protocol-agnostic authentication types for smithy clients. |
|
bearer
Package bearer provides middleware and utilities for authenticating API operation calls with a Bearer Token.
|
Package bearer provides middleware and utilities for authenticating API operation calls with a Bearer Token. |
|
aws-http-auth
module
|
|
|
codegen
module
|
|
|
container
|
|
|
private/cache
Package cache defines the interface for a key-based data store.
|
Package cache defines the interface for a key-based data store. |
|
private/cache/lru
Package lru implements cache.Cache with an LRU eviction policy.
|
Package lru implements cache.Cache with an LRU eviction policy. |
|
Package document provides interface definitions and error types for document types.
|
Package document provides interface definitions and error types for document types. |
|
cbor
Package cbor implements reflective encoding of Smithy documents for CBOR-based protocols.
|
Package cbor implements reflective encoding of Smithy documents for CBOR-based protocols. |
|
json
Package json provides a document Encoder and Decoder implementation that is used to implement Smithy document types for JSON based protocols.
|
Package json provides a document Encoder and Decoder implementation that is used to implement Smithy document types for JSON based protocols. |
|
cbor
Package cbor implements partial encoding/decoding of concise binary object representation (CBOR) described in [RFC 8949].
|
Package cbor implements partial encoding/decoding of concise binary object representation (CBOR) described in [RFC 8949]. |
|
xml
Package xml holds the XMl encoder utility.
|
Package xml holds the XMl encoder utility. |
|
internal
|
|
|
Package io provides utilities for Smithy generated API clients.
|
Package io provides utilities for Smithy generated API clients. |
|
Package metrics defines the metrics APIs used by Smithy clients.
|
Package metrics defines the metrics APIs used by Smithy clients. |
|
smithyotelmetrics
module
|
|
|
Package middleware provides transport agnostic middleware for decorating SDK handlers.
|
Package middleware provides transport agnostic middleware for decorating SDK handlers. |
|
Package prelude defines schemas for the Smithy prelude shapes.
|
Package prelude defines schemas for the Smithy prelude shapes. |
|
private
|
|
|
requestcompression
Package requestcompression implements runtime support for smithy-modeled request compression.
|
Package requestcompression implements runtime support for smithy-modeled request compression. |
|
Package ptr provides utilities for converting scalar literal type values to and from pointers inline.
|
Package ptr provides utilities for converting scalar literal type values to and from pointers inline. |
|
Package rand provides utilities for creating and working with random value generators.
|
Package rand provides utilities for creating and working with random value generators. |
|
Package testing provides utilities for testing smith clients and protocols.
|
Package testing provides utilities for testing smith clients and protocols. |
|
xml
package xml is xml testing package that supports xml comparison utility.
|
package xml is xml testing package that supports xml comparison utility. |
|
Package tracing defines tracing APIs to be used by Smithy clients.
|
Package tracing defines tracing APIs to be used by Smithy clients. |
|
smithy-otel-tracing
module
|
|
|
smithyoteltracing
module
|
|
|
Package traits defines representations of Smithy IDL traits that appear in code-generated schemas.
|
Package traits defines representations of Smithy IDL traits that appear in code-generated schemas. |
|
transport
|
|
|
http
Package http provides the HTTP transport client and request/response types needed to round trip API operation calls with an service.
|
Package http provides the HTTP transport client and request/response types needed to round trip API operation calls with an service. |
|
http/protocol/internal/json/internal/stdlib
Package stdlib contains code copied from the Go standard library's encoding/json package (Go 1.24).
|
Package stdlib contains code copied from the Go standard library's encoding/json package (Go 1.24). |