customizations

package
v1.53.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 29, 2024 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package customizations provides customizations for the Amazon S3 API client.

This package provides support for following S3 customizations 

ProcessARN Middleware: processes an ARN if provided as input and updates the endpoint as per the arn type

UpdateEndpoint Middleware: resolves a custom endpoint as per s3 config options

RemoveBucket Middleware: removes a serialized bucket name from request url path

processResponseWith200Error Middleware: Deserializing response error with 200 status code

Virtual Host style url addressing

Since serializers serialize by default as path style url, we use customization to modify the endpoint url when `UsePathStyle` option on S3Client is unset or false. This flag will be ignored if `UseAccelerate` option is set to true.

If UseAccelerate is not enabled, and the bucket name is not a valid hostname label, they SDK will fallback to forcing the request to be made as if UsePathStyle was enabled. This behavior is also used if UseDualStackEndpoint is enabled.

https://docs.aws.amazon.com/AmazonS3/latest/dev/dual-stack-endpoints.html#dual-stack-endpoints-description

Transfer acceleration

By default S3 Transfer acceleration support is disabled. By enabling `UseAccelerate` option on S3Client, one can enable s3 transfer acceleration support. Transfer acceleration only works with Virtual Host style addressing, and thus `UsePathStyle` option if set is ignored. Transfer acceleration is not supported for S3 operations DeleteBucket, ListBuckets, and CreateBucket.

Dualstack support

By default dualstack support for s3 client is disabled. By enabling `UseDualstack` option on s3 client, you can enable dualstack endpoint support.

Endpoint customizations

Customizations to lookup ARN, process ARN needs to happen before request serialization. UpdateEndpoint middleware which mutates resources based on Options such as UseDualstack, UseAccelerate for modifying resolved endpoint are executed after request serialization. Remove bucket middleware is executed after an request is serialized, and removes the serialized bucket name from request path 

Middleware layering:

Initialize : HTTP Request -> ARN Lookup -> Input-Validation -> Serialize step

Serialize : HTTP Request -> Process ARN -> operation serializer -> Update-Endpoint customization -> Remove-Bucket -> next middleware

Customization options: 

UseARNRegion (Disabled by Default)

UsePathStyle (Disabled by Default)

UseAccelerate (Disabled by Default)

UseDualstack (Disabled by Default)

Handle Error response with 200 status code

S3 operations: CopyObject, CompleteMultipartUpload, UploadPartCopy can have an error Response with status code 2xx. The processResponseWith200Error middleware customizations enables SDK to check for an error within response body prior to deserialization.

As the check for 2xx response containing an error needs to be performed earlier than response deserialization. Since the behavior of Deserialization is in reverse order to the other stack steps its easier to consider that "after" means "before". 

Middleware layering:

HTTP Response -> handle 200 error customization -> deserialize

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddExpressDefaultChecksumMiddleware added in v1.46.0 

func AddExpressDefaultChecksumMiddleware(s *middleware.Stack) error

AddExpressDefaultChecksumMiddleware appends a step to default to CRC32 for S3Express requests. This should only be applied to operations where a checksum is required (e.g. DeleteObject).

func GetBucket added in v1.46.0 

func GetBucket(ctx context.Context) string

GetBucket retrieves a stored bucket name within a context.

func GetIdentityPropertiesBucket added in v1.46.0 

func GetIdentityPropertiesBucket(ip *smithy.Properties) (string, bool)

GetIdentityPropertiesBucket returns the S3 bucket from identity properties.

func GetPropertiesBackend added in v1.46.0 

func GetPropertiesBackend(p *smithy.Properties) string

GetPropertiesBackend returns a resolved endpoint backend from the property set.

func GetSignerVersion added in v1.15.0 

func GetSignerVersion(ctx context.Context) (v string)

GetSignerVersion retrieves the signer version to use for signing

Scoped to stack values. Use github.com/aws/smithy-go/middleware#ClearStackValues to clear all stack values.

func HandleResponseErrorWith200Status added in v0.27.0 

func HandleResponseErrorWith200Status(stack *middleware.Stack) error

HandleResponseErrorWith200Status check for S3 200 error response. If an s3 200 error is found, status code for the response is modified temporarily to 5xx response status code.

func RegisterPreSigningMiddleware added in v1.15.0 

func RegisterPreSigningMiddleware(stack *middleware.Stack, signingMiddleware *PresignHTTPRequestMiddleware) (err error)

RegisterPreSigningMiddleware registers the wrapper pre-signing middleware to the stack. If a pre-signing middleware is already present, this provided middleware will be swapped. Otherwise the middleware will be added at the tail of the finalize step.

func RegisterSigningMiddleware added in v1.15.0 

func RegisterSigningMiddleware(stack *middleware.Stack, signingMiddleware *SignHTTPRequestMiddleware) (err error)

RegisterSigningMiddleware registers the wrapper signing middleware to the stack. If a signing middleware is already present, this provided middleware will be swapped. Otherwise the middleware will be added at the tail of the finalize step.

func ResolveDisableExpressAuth added in v1.46.0 

func ResolveDisableExpressAuth(configs []interface{}) (value bool, exists bool)

ResolveDisableExpressAuth pulls S3DisableExpressAuth setting from config sources.

func SetBucket added in v1.46.0 

func SetBucket(ctx context.Context, bucket string) context.Context

SetBucket stores a bucket name within the request context, which is required for a variety of custom S3 behaviors.

func SetIdentityPropertiesBucket added in v1.46.0 

func SetIdentityPropertiesBucket(ip *smithy.Properties, bucket string)

SetIdentityPropertiesBucket sets the S3 bucket to identity properties.

func SetSignerVersion added in v1.15.0 

func SetSignerVersion(ctx context.Context, version string) context.Context

SetSignerVersion sets the signer version to be used for signing the request

Scoped to stack values. Use github.com/aws/smithy-go/middleware#ClearStackValues to clear all stack values.

func UpdateEndpoint 

func UpdateEndpoint(stack *middleware.Stack, options UpdateEndpointOptions) (err error)

UpdateEndpoint adds the middleware to the middleware stack based on the UpdateEndpointOptions.

Types

type AddExpiresOnPresignedURL added in v0.30.0 

type AddExpiresOnPresignedURL struct {

	// Expires is time.Duration within which presigned url should be expired.
	// This should be the duration in seconds the presigned URL should be considered valid for.
	// By default the S3 presigned url expires in 15 minutes ie. 900 seconds.
	Expires time.Duration
}

AddExpiresOnPresignedURL represents a build middleware used to assign expiration on a presigned URL.

func (*AddExpiresOnPresignedURL) HandleBuild added in v0.30.0 

func (m *AddExpiresOnPresignedURL) HandleBuild(ctx context.Context, in middleware.BuildInput, next middleware.BuildHandler) (
	out middleware.BuildOutput, metadata middleware.Metadata, err error,
)

HandleBuild handles the build step middleware behavior

func (*AddExpiresOnPresignedURL) ID added in v0.30.0 

func (*AddExpiresOnPresignedURL) ID() string

ID representing the middleware

type EndpointResolver added in v0.30.0 

type EndpointResolver interface {
	ResolveEndpoint(region string, options EndpointResolverOptions) (aws.Endpoint, error)
}

EndpointResolver interface for resolving service endpoints.

type EndpointResolverOptions added in v0.30.0 

type EndpointResolverOptions = internalendpoints.Options

EndpointResolverOptions is the service endpoint resolver options

type ExpressIdentityResolver added in v1.46.0 

type ExpressIdentityResolver struct {
	Provider S3ExpressCredentialsProvider
}

ExpressIdentityResolver retrieves identity for the S3Express storage class.

func (*ExpressIdentityResolver) GetIdentity added in v1.46.0 

func (v *ExpressIdentityResolver) GetIdentity(ctx context.Context, props smithy.Properties) (
	auth.Identity, error,
)

GetIdentity retrieves AWS credentials using the underlying provider.

type ExpressSigner added in v1.46.0 

type ExpressSigner struct {
	Signer     v4.HTTPSigner
	Logger     logging.Logger
	LogSigning bool
}

ExpressSigner signs requests for the sigv4-s3express auth scheme.

This signer respects the aws.auth#sigv4 properties for signing name and region.

func (*ExpressSigner) SignRequest added in v1.46.0 

func (v *ExpressSigner) SignRequest(ctx context.Context, r *smithyhttp.Request, identity auth.Identity, props smithy.Properties) error

SignRequest signs the request with the provided identity.

type PresignHTTPRequestMiddleware added in v1.15.0 

type PresignHTTPRequestMiddleware struct {
	// contains filtered or unexported fields
}

PresignHTTPRequestMiddleware provides the Finalize middleware for creating a presigned URL for an HTTP request.

Will short circuit the middleware stack and not forward onto the next Finalize handler.

func NewPresignHTTPRequestMiddleware added in v1.15.0 

func NewPresignHTTPRequestMiddleware(options PresignHTTPRequestMiddlewareOptions) *PresignHTTPRequestMiddleware

NewPresignHTTPRequestMiddleware constructs a PresignHTTPRequestMiddleware using the given Signer for signing requests

func (*PresignHTTPRequestMiddleware) HandleFinalize added in v1.15.0 

func (p *PresignHTTPRequestMiddleware) HandleFinalize(
	ctx context.Context, in middleware.FinalizeInput, next middleware.FinalizeHandler,
) (
	out middleware.FinalizeOutput, metadata middleware.Metadata, err error,
)

HandleFinalize will take the provided input and create a presigned url for the http request using the SigV4 or SigV4a presign authentication scheme.

Since the signed request is not a valid HTTP request

func (*PresignHTTPRequestMiddleware) ID added in v1.15.0 

func (*PresignHTTPRequestMiddleware) ID() string

ID provides the middleware ID.

type PresignHTTPRequestMiddlewareOptions added in v1.15.0 

type PresignHTTPRequestMiddlewareOptions struct {
	CredentialsProvider aws.CredentialsProvider
	ExpressCredentials  S3ExpressCredentialsProvider
	V4Presigner         v4.HTTPPresigner
	V4aPresigner        v4a.HTTPPresigner
	LogSigning          bool
}

PresignHTTPRequestMiddlewareOptions is the options for the PresignHTTPRequestMiddleware middleware.

type S3ExpressCredentialsProvider added in v1.46.0 

type S3ExpressCredentialsProvider interface {
	Retrieve(ctx context.Context, bucket string) (aws.Credentials, error)
}

S3ExpressCredentialsProvider retrieves credentials for the S3Express storage class.

type S3ExpressSignHTTPRequestMiddleware added in v1.46.0 

type S3ExpressSignHTTPRequestMiddleware struct {
	Credentials S3ExpressCredentialsProvider
	Signer      v4.HTTPSigner
	LogSigning  bool
}

S3ExpressSignHTTPRequestMiddleware signs S3 S3Express requests.

This is NOT mutually exclusive with existing v4 or v4a signer handling on the stack itself, but only one handler will actually perform signing based on the provided signing version in the context.

func (*S3ExpressSignHTTPRequestMiddleware) HandleFinalize added in v1.46.0 

func (m *S3ExpressSignHTTPRequestMiddleware) HandleFinalize(ctx context.Context, in middleware.FinalizeInput, next middleware.FinalizeHandler) (
	out middleware.FinalizeOutput, metadata middleware.Metadata, err error,
)

HandleFinalize will sign the request if the S3Express signer has been selected.

func (*S3ExpressSignHTTPRequestMiddleware) ID added in v1.46.0 

func (*S3ExpressSignHTTPRequestMiddleware) ID() string

ID identifies S3ExpressSignHTTPRequestMiddleware.

type SignHTTPRequestMiddleware added in v1.15.0 

type SignHTTPRequestMiddleware struct {
	// contains filtered or unexported fields
}

SignHTTPRequestMiddleware is a `FinalizeMiddleware` implementation to select HTTP Signing method

func NewSignHTTPRequestMiddleware added in v1.15.0 

func NewSignHTTPRequestMiddleware(options SignHTTPRequestMiddlewareOptions) *SignHTTPRequestMiddleware

NewSignHTTPRequestMiddleware constructs a SignHTTPRequestMiddleware using the given Signer for signing requests

func (*SignHTTPRequestMiddleware) HandleFinalize added in v1.15.0 

func (s *SignHTTPRequestMiddleware) HandleFinalize(ctx context.Context, in middleware.FinalizeInput, next middleware.FinalizeHandler) (
	out middleware.FinalizeOutput, metadata middleware.Metadata, err error,
)

HandleFinalize will take the provided input and handle signing for either SigV4 or SigV4A as called for.

func (*SignHTTPRequestMiddleware) ID added in v1.15.0 

func (s *SignHTTPRequestMiddleware) ID() string

ID is the SignHTTPRequestMiddleware identifier

type SignHTTPRequestMiddlewareOptions added in v1.15.0 

type SignHTTPRequestMiddlewareOptions struct {

	// credential provider
	CredentialsProvider aws.CredentialsProvider

	// log signing
	LogSigning bool

	// v4 signer
	V4Signer v4.HTTPSigner

	//v4a signer
	V4aSigner v4a.HTTPSigner
}

SignHTTPRequestMiddlewareOptions is the configuration options for the SignHTTPRequestMiddleware middleware.

type UpdateEndpointOptions 

type UpdateEndpointOptions struct {
	// Accessor are parameter accessors used by the middleware
	Accessor UpdateEndpointParameterAccessor

	// use path style
	UsePathStyle bool

	// use transfer acceleration
	UseAccelerate bool

	// indicates if an operation supports s3 transfer acceleration.
	SupportsAccelerate bool

	// use ARN region
	UseARNRegion bool

	// Indicates that the operation should target the s3-object-lambda endpoint.
	// Used to direct operations that do not route based on an input ARN.
	TargetS3ObjectLambda bool

	// EndpointResolver used to resolve endpoints. This may be a custom endpoint resolver
	EndpointResolver EndpointResolver

	// EndpointResolverOptions used by endpoint resolver
	EndpointResolverOptions EndpointResolverOptions

	// DisableMultiRegionAccessPoints indicates multi-region access point support is disabled
	DisableMultiRegionAccessPoints bool
}

UpdateEndpointOptions provides the options for the UpdateEndpoint middleware setup.

type UpdateEndpointParameterAccessor added in v0.30.0 

type UpdateEndpointParameterAccessor struct {
	// functional pointer to fetch bucket name from provided input.
	// The function is intended to take an input value, and
	// return a string pointer to value of string, and bool if
	// input has no bucket member.
	GetBucketFromInput func(interface{}) (*string, bool)
}

UpdateEndpointParameterAccessor represents accessor functions used by the middleware

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.