S3 Client Configuration

import (
    "context"
    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

package main

import (
    "context"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
    // Load default AWS configuration
    cfg, err := config.LoadDefaultConfig(context.TODO())
    if err != nil {
        panic(err)
    }

    // Create S3 client from config
    client := s3.NewFromConfig(cfg)

    // Use client for operations
    // ...
}

func NewFromConfig(cfg aws.Config, optFns ...func(*Options)) *Client

cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithRegion("us-west-2"),
)
if err != nil {
    panic(err)
}

// Create client with additional options
client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.UsePathStyle = true
    o.UseAccelerate = true
})

func New(options Options, optFns ...func(*Options)) *Client

client := s3.New(s3.Options{
    Region: "us-west-2",
    Credentials: aws.NewCredentialsCache(
        credentials.NewStaticCredentialsProvider("AKID", "SECRET", "TOKEN"),
    ),
    UsePathStyle: true,
})

type Options struct {
    // Set of options to modify how an operation is invoked. These apply to all
    // operations invoked for this client. Use functional options on operation call to
    // modify this list for per operation behavior.
    APIOptions []func(*middleware.Stack) error

    // The optional application specific identifier appended to the User-Agent header.
    AppID string

    // This endpoint will be given as input to an EndpointResolverV2. It is used for
    // providing a custom base endpoint that is subject to modifications by the
    // processing EndpointResolverV2.
    BaseEndpoint *string

    // Configures the events that will be sent to the configured logger.
    ClientLogMode aws.ClientLogMode

    // The threshold ContentLength in bytes for HTTP PUT request to receive {Expect:
    // 100-continue} header. Setting to -1 will disable adding the Expect header to
    // requests; setting to 0 will set the threshold to default 2MB
    ContinueHeaderThresholdBytes int64

    // The credentials object to use when signing requests.
    Credentials aws.CredentialsProvider

    // The configuration DefaultsMode that the SDK should use when constructing the
    // clients initial default settings.
    DefaultsMode aws.DefaultsMode

    // Disables logging when the client skips output checksum validation due to lack
    // of algorithm support.
    DisableLogOutputChecksumValidationSkipped bool

    // Allows you to disable S3 Multi-Region access points feature.
    DisableMultiRegionAccessPoints bool

    // Disables this client's usage of Session Auth for S3Express buckets and reverts
    // to using conventional SigV4 for those.
    DisableS3ExpressSessionAuth *bool

    // The endpoint options to be used when attempting to resolve an endpoint.
    EndpointOptions EndpointResolverOptions

    // The service endpoint resolver.
    // Deprecated: Use EndpointResolverV2 and BaseEndpoint instead.
    EndpointResolver EndpointResolver

    // Resolves the endpoint used for a particular service operation. This should be
    // used over the deprecated EndpointResolver.
    EndpointResolverV2 EndpointResolverV2

    // The credentials provider for S3Express requests.
    ExpressCredentials ExpressCredentialsProvider

    // Signature Version 4 (SigV4) Signer
    HTTPSignerV4 HTTPSignerV4

    // Provides idempotency tokens values that will be automatically populated into
    // idempotent API operations.
    IdempotencyTokenProvider IdempotencyTokenProvider

    // The logger writer interface to write logging messages to.
    Logger logging.Logger

    // The client meter provider.
    MeterProvider metrics.MeterProvider

    // The region to send requests to. (Required)
    Region string

    // Indicates how user opt-in/out request checksum calculation
    RequestChecksumCalculation aws.RequestChecksumCalculation

    // Indicates how user opt-in/out response checksum validation
    ResponseChecksumValidation aws.ResponseChecksumValidation

    // RetryMaxAttempts specifies the maximum number attempts an API client will call
    // an operation that fails with a retryable error. A value of 0 is ignored, and
    // will not be used to configure the API client created default retryer, or modify
    // per operation call's retry max attempts.
    RetryMaxAttempts int

    // RetryMode specifies the retry mode the API client will be created with, if
    // Retryer option is not also specified.
    RetryMode aws.RetryMode

    // Retryer guides how HTTP requests should be retried in case of recoverable
    // failures. When nil the API client will use a default retryer.
    Retryer aws.Retryer

    // The RuntimeEnvironment configuration, only populated if the DefaultsMode is set
    // to DefaultsModeAuto and is initialized using config.LoadDefaultConfig.
    RuntimeEnvironment aws.RuntimeEnvironment

    // The client tracer provider.
    TracerProvider tracing.TracerProvider

    // Allows you to enable arn region support for the service.
    UseARNRegion bool

    // Allows you to enable S3 Accelerate feature. All operations compatible with S3
    // Accelerate will use the accelerate endpoint for requests.
    UseAccelerate bool

    // Allows you to enable dual-stack endpoint support for the service.
    // Deprecated: Set dual-stack by setting UseDualStackEndpoint on EndpointResolverOptions.
    UseDualstack bool

    // Allows you to enable the client to use path-style addressing.
    UsePathStyle bool

    // The HTTP client to invoke API calls with. Defaults to client's default HTTP
    // implementation if nil.
    HTTPClient HTTPClient

    // Client registry of operation interceptors.
    Interceptors smithyhttp.InterceptorRegistry

    // The auth scheme resolver which determines how to authenticate for each operation.
    AuthSchemeResolver AuthSchemeResolver

    // The list of auth schemes supported by the client.
    AuthSchemes []smithyhttp.AuthScheme

    // Priority list of preferred auth scheme names (e.g. sigv4a).
    AuthSchemePreference []string
}

func (o Options) Copy() Options
func (o Options) GetIdentityResolver(schemeID string) smithyauth.IdentityResolver

func WithAPIOptions(optFns ...func(*middleware.Stack) error) func(*Options)

client := s3.NewFromConfig(cfg,
    s3.WithAPIOptions(func(stack *middleware.Stack) error {
        // Add custom middleware
        return stack.Finalize.Add(myCustomMiddleware, middleware.After)
    }),
)

func WithEndpointResolverV2(v EndpointResolverV2) func(*Options)

type customResolver struct{}

func (r *customResolver) ResolveEndpoint(ctx context.Context, params s3.EndpointParameters) (
    smithyendpoints.Endpoint, error,
) {
    // Custom endpoint resolution logic
    return smithyendpoints.Endpoint{
        URI: url.URL{
            Scheme: "https",
            Host:   "custom-s3-endpoint.example.com",
        },
    }, nil
}

client := s3.NewFromConfig(cfg,
    s3.WithEndpointResolverV2(&customResolver{}),
)

func WithEndpointResolver(v EndpointResolver) func(*Options)

func WithSigV4SigningRegion(region string) func(*Options)

client := s3.NewFromConfig(cfg,
    s3.WithSigV4SigningRegion("us-east-1"),
)

func WithSigV4SigningName(name string) func(*Options)

client := s3.NewFromConfig(cfg,
    s3.WithSigV4SigningName("s3"),
)

func WithSigV4ASigningRegions(regions []string) func(*Options)

client := s3.NewFromConfig(cfg,
    s3.WithSigV4ASigningRegions([]string{"us-west-2", "us-east-1"}),
)

type EndpointResolverV2 interface {
    // ResolveEndpoint attempts to resolve the endpoint with the provided options,
    // returning the endpoint if found. Otherwise an error is returned.
    ResolveEndpoint(ctx context.Context, params EndpointParameters) (
        smithyendpoints.Endpoint, error,
    )
}

func NewDefaultEndpointResolverV2() EndpointResolverV2

resolver := s3.NewDefaultEndpointResolverV2()

type EndpointParameters struct {
    // The S3 bucket used to send the request. This is an optional parameter that will
    // be set automatically for operations that are scoped to an S3 bucket.
    Bucket *string

    // The AWS region used to dispatch the request.
    Region *string

    // When true, send this request to the FIPS-compliant regional endpoint.
    UseFIPS *bool

    // When true, use the dual-stack endpoint.
    UseDualStack *bool

    // Override the endpoint used to send this request
    Endpoint *string

    // When true, force a path-style endpoint to be used where the bucket name is part
    // of the path.
    ForcePathStyle *bool

    // When true, use S3 Accelerate. NOTE: Not all regions support S3 accelerate.
    Accelerate *bool

    // Whether the global endpoint should be used, rather than the regional endpoint
    // for us-east-1.
    UseGlobalEndpoint *bool

    // Internal parameter to use object lambda endpoint for an operation
    UseObjectLambdaEndpoint *bool

    // The S3 Key used to send the request.
    Key *string

    // The S3 Prefix used to send the request.
    Prefix *string

    // The Copy Source used for Copy Object request.
    CopySource *string

    // Internal parameter to disable Access Point Buckets
    DisableAccessPoints *bool

    // Whether multi-region access points (MRAP) should be disabled.
    DisableMultiRegionAccessPoints *bool

    // When an Access Point ARN is provided and this flag is enabled, the SDK MUST use
    // the ARN's region when constructing the endpoint instead of the client's
    // configured region.
    UseArnRegion *bool

    // Internal parameter to indicate whether S3Express operation should use control
    // plane endpoint
    UseS3ExpressControlEndpoint *bool

    // Parameter to indicate whether S3Express session auth should be disabled
    DisableS3ExpressSessionAuth *bool
}

func (p EndpointParameters) ValidateRequired() error
func (p EndpointParameters) WithDefaults() EndpointParameters

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

type EndpointResolverFunc func(region string, options EndpointResolverOptions) (aws.Endpoint, error)

func (fn EndpointResolverFunc) ResolveEndpoint(region string, options EndpointResolverOptions) (
    endpoint aws.Endpoint, err error,
)

resolver := s3.EndpointResolverFunc(func(region string, options s3.EndpointResolverOptions) (aws.Endpoint, error) {
    return aws.Endpoint{
        URL:           "https://custom-endpoint.example.com",
        SigningRegion: region,
    }, nil
})

client := s3.NewFromConfig(cfg, s3.WithEndpointResolver(resolver))

func EndpointResolverFromURL(url string, optFns ...func(*aws.Endpoint)) EndpointResolver

resolver := s3.EndpointResolverFromURL("https://s3.custom-domain.com")
client := s3.NewFromConfig(cfg, s3.WithEndpointResolver(resolver))

type EndpointResolverOptions struct {
    // Logger is a logging implementation that log events should be sent to.
    Logger logging.Logger

    // LogDeprecated indicates that deprecated endpoints should be logged to the
    // provided logger.
    LogDeprecated bool

    // ResolvedRegion is used to override the region to be resolved.
    ResolvedRegion string

    // DisableHTTPS informs the resolver to return an endpoint that does not use the
    // HTTPS scheme.
    DisableHTTPS bool

    // UseDualStackEndpoint specifies the resolver must resolve a dual-stack endpoint.
    UseDualStackEndpoint aws.DualStackEndpointState

    // UseFIPSEndpoint specifies the resolver must resolve a FIPS endpoint.
    UseFIPSEndpoint aws.FIPSEndpointState
}

func (o EndpointResolverOptions) GetResolvedRegion() string
func (o EndpointResolverOptions) GetDisableHTTPS() bool
func (o EndpointResolverOptions) GetUseDualStackEndpoint() aws.DualStackEndpointState
func (o EndpointResolverOptions) GetUseFIPSEndpoint() aws.FIPSEndpointState

func NewDefaultEndpointResolver() *internalendpoints.Resolver

type AuthSchemeResolver interface {
    ResolveAuthSchemes(context.Context, *AuthResolverParameters) ([]*smithyauth.Option, error)
}

type AuthResolverParameters struct {
    // The name of the operation being invoked.
    Operation string

    // The region in which the operation is being invoked.
    Region string
}

type HTTPClient interface {
    Do(*http.Request) (*http.Response, error)
}

import "net/http"

customHTTPClient := &http.Client{
    Timeout: 30 * time.Second,
}

client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.HTTPClient = customHTTPClient
})

type HTTPSignerV4 interface {
    SignHTTP(ctx context.Context, credentials aws.Credentials, r *http.Request,
        payloadHash string, service string, region string, signingTime time.Time,
        optFns ...func(*v4.SignerOptions)) error
}

type HTTPPresignerV4 interface {
    PresignHTTP(ctx context.Context, credentials aws.Credentials, r *http.Request,
        payloadHash string, service string, region string, signingTime time.Time,
        optFns ...func(*v4.SignerOptions)) (url string, signedHeader http.Header, err error)
}

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

func GetHostIDMetadata(metadata middleware.Metadata) (string, bool)

output, err := client.GetObject(ctx, &s3.GetObjectInput{
    Bucket: aws.String("my-bucket"),
    Key:    aws.String("my-key"),
})
if err != nil {
    // Get host ID for troubleshooting
    if hostID, ok := s3.GetHostIDMetadata(output.ResultMetadata); ok {
        fmt.Printf("S3 Host ID: %s\n", hostID)
    }
}

cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    log.Fatal(err)
}

client := s3.NewFromConfig(cfg)

cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithRegion("us-west-2"),
)
if err != nil {
    log.Fatal(err)
}

client := s3.NewFromConfig(cfg)

client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.UsePathStyle = true
})

client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.UseAccelerate = true
})

cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithUseDualStackEndpoint(aws.DualStackEndpointStateEnabled),
)
if err != nil {
    log.Fatal(err)
}

client := s3.NewFromConfig(cfg)

cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithUseFIPSEndpoint(aws.FIPSEndpointStateEnabled),
)
if err != nil {
    log.Fatal(err)
}

client := s3.NewFromConfig(cfg)

client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.BaseEndpoint = aws.String("http://localhost:9000")
    o.UsePathStyle = true
})

import (
    "github.com/aws/aws-sdk-go-v2/credentials"
)

cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithCredentialsProvider(
        credentials.NewStaticCredentialsProvider("AKID", "SECRET", ""),
    ),
)
if err != nil {
    log.Fatal(err)
}

client := s3.NewFromConfig(cfg)

import "github.com/aws/aws-sdk-go-v2/aws/retry"

cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithRetryMaxAttempts(5),
    config.WithRetryMode(aws.RetryModeAdaptive),
)
if err != nil {
    log.Fatal(err)
}

client := s3.NewFromConfig(cfg)

import "github.com/aws/aws-sdk-go-v2/aws/retry"

client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.Retryer = retry.NewStandard(func(opts *retry.StandardOptions) {
        opts.MaxAttempts = 10
        opts.MaxBackoff = 30 * time.Second
    })
})

import "log"

cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithClientLogMode(aws.LogRequestWithBody | aws.LogResponseWithBody),
)
if err != nil {
    log.Fatal(err)
}

client := s3.NewFromConfig(cfg)

client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.DisableMultiRegionAccessPoints = true
})

client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.UseARNRegion = true
})

client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.DisableS3ExpressSessionAuth = aws.Bool(true)
})

client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.Region = "us-west-2"
    o.UsePathStyle = true
    o.UseAccelerate = false
    o.RetryMaxAttempts = 5
    o.RetryMode = aws.RetryModeStandard
})

// Client-level configuration
client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.UsePathStyle = true
})

// Override for specific operation
output, err := client.GetObject(ctx, &s3.GetObjectInput{
    Bucket: aws.String("my-bucket"),
    Key:    aws.String("my-key"),
}, func(o *s3.Options) {
    // This operation will use virtual-hosted style
    o.UsePathStyle = false
})

import "github.com/aws/smithy-go/middleware"

customMiddleware := middleware.FinalizeMiddlewareFunc(
    "CustomMiddleware",
    func(ctx context.Context, in middleware.FinalizeInput, next middleware.FinalizeHandler) (
        middleware.FinalizeOutput, middleware.Metadata, error,
    ) {
        // Modify request or add custom logic
        fmt.Println("Custom middleware executed")
        return next.HandleFinalize(ctx, in)
    },
)

client := s3.NewFromConfig(cfg,
    s3.WithAPIOptions(func(stack *middleware.Stack) error {
        return stack.Finalize.Add(customMiddleware, middleware.Before)
    }),
)

type customEndpointResolver struct {
    baseURL string
}

func (r *customEndpointResolver) ResolveEndpoint(
    ctx context.Context,
    params s3.EndpointParameters,
) (smithyendpoints.Endpoint, error) {
    // Custom logic based on bucket name, region, etc.
    uri := url.URL{
        Scheme: "https",
        Host:   r.baseURL,
    }

    if params.Bucket != nil {
        // Custom bucket routing logic
        uri.Host = fmt.Sprintf("%s.%s", *params.Bucket, r.baseURL)
    }

    return smithyendpoints.Endpoint{
        URI: uri,
    }, nil
}

client := s3.NewFromConfig(cfg,
    s3.WithEndpointResolverV2(&customEndpointResolver{
        baseURL: "custom-s3.example.com",
    }),
)

client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    // Enable automatic checksum calculation for requests
    o.RequestChecksumCalculation = aws.RequestChecksumCalculationWhenSupported

    // Enable automatic checksum validation for responses
    o.ResponseChecksumValidation = aws.ResponseChecksumValidationWhenSupported
})

type ResponseError interface {
    error

    ServiceHostID() string
    ServiceRequestID() string
}

package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func handleS3Error() {
    cfg, err := config.LoadDefaultConfig(context.TODO())
    if err != nil {
        log.Fatal(err)
    }

    client := s3.NewFromConfig(cfg)

    _, err = client.GetObject(context.TODO(), &s3.GetObjectInput{
        Bucket: aws.String("my-bucket"),
        Key:    aws.String("nonexistent-key"),
    })

    if err != nil {
        // Check if error implements ResponseError
        var respErr s3.ResponseError
        if errors.As(err, &respErr) {
            fmt.Printf("S3 Error: %v\n", err)
            fmt.Printf("Request ID: %s\n", respErr.ServiceRequestID())
            fmt.Printf("Host ID: %s\n", respErr.ServiceHostID())
        } else {
            fmt.Printf("Non-response error: %v\n", err)
        }
    }
}

type UnknownEventMessageError struct {
    Type    string
    Message *eventstream.Message
}

func (e *UnknownEventMessageError) Error() string

package main

import (
    "context"
    "errors"
    "fmt"
    "log"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/aws/aws-sdk-go-v2/service/s3/types"
)

func handleSelectObjectContentErrors() error {
    cfg, err := config.LoadDefaultConfig(context.TODO())
    if err != nil {
        return err
    }

    client := s3.NewFromConfig(cfg)

    result, err := client.SelectObjectContent(context.TODO(), &s3.SelectObjectContentInput{
        Bucket:         aws.String("my-bucket"),
        Key:            aws.String("data.csv"),
        ExpressionType: types.ExpressionTypeSql,
        Expression:     aws.String("SELECT * FROM S3Object"),
        InputSerialization: &types.InputSerialization{
            CSV: &types.CSVInput{
                FileHeaderInfo: types.FileHeaderInfoUse,
            },
        },
        OutputSerialization: &types.OutputSerialization{
            CSV: &types.CSVOutput{},
        },
    })
    if err != nil {
        return err
    }

    stream := result.GetStream()
    defer stream.Close()

    for event := range stream.Events() {
        // Process events...
        _ = event
    }

    // Check for stream errors
    if err := stream.Err(); err != nil {
        var unknownEventErr *s3.UnknownEventMessageError
        if errors.As(err, &unknownEventErr) {
            fmt.Printf("Unknown event type: %s\n", unknownEventErr.Type)
            log.Printf("Unexpected event in stream: %v", unknownEventErr)
            // Handle gracefully or report for investigation
        }
        return err
    }

    return nil
}

func GetChecksumValidationMetadata(m middleware.Metadata) (ChecksumValidationMetadata, bool)

package main

import (
    "context"
    "fmt"
    "io"
    "log"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func downloadWithChecksumValidation() error {
    cfg, err := config.LoadDefaultConfig(context.TODO())
    if err != nil {
        return err
    }

    client := s3.NewFromConfig(cfg)

    output, err := client.GetObject(context.TODO(), &s3.GetObjectInput{
        Bucket:       aws.String("my-bucket"),
        Key:          aws.String("my-object"),
        ChecksumMode: types.ChecksumModeEnabled,
    })
    if err != nil {
        return err
    }
    defer output.Body.Close()

    // Check which checksum algorithms will be used for validation
    if checksumMeta, ok := s3.GetChecksumValidationMetadata(output.ResultMetadata); ok {
        fmt.Printf("Checksum validation metadata: %+v\n", checksumMeta)
    }

    // Read the entire body to trigger checksum validation
    data, err := io.ReadAll(output.Body)
    if err != nil {
        // Checksum validation errors will be returned here
        return fmt.Errorf("failed to read object (checksum may have failed): %w", err)
    }

    fmt.Printf("Downloaded %d bytes with checksum validation\n", len(data))
    return nil
}

type ChecksumValidationMetadata struct {
    // Contains information about which checksum algorithms
    // are being used to validate the response
}

func GetComputedInputChecksumsMetadata(m middleware.Metadata) (ComputedInputChecksumsMetadata, bool)

package main

import (
    "context"
    "fmt"
    "log"
    "strings"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/aws/aws-sdk-go-v2/service/s3/types"
)

func uploadWithChecksumTracking() error {
    cfg, err := config.LoadDefaultConfig(context.TODO())
    if err != nil {
        return err
    }

    client := s3.NewFromConfig(cfg)

    output, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
        Bucket:            aws.String("my-bucket"),
        Key:               aws.String("my-object"),
        Body:              strings.NewReader("Hello, World!"),
        ChecksumAlgorithm: types.ChecksumAlgorithmSha256,
    })
    if err != nil {
        return err
    }

    // Retrieve computed checksums from metadata
    if checksums, ok := s3.GetComputedInputChecksumsMetadata(output.ResultMetadata); ok {
        fmt.Println("Computed input checksums:")
        for algo, value := range checksums {
            fmt.Printf("  %s: %s\n", algo, value)
        }
    }

    fmt.Printf("Object uploaded with ETag: %s\n", *output.ETag)
    return nil
}

type ComputedInputChecksumsMetadata map[string]string
// Maps checksum algorithm names to their computed base64-encoded values

const ServiceID = "S3"
const ServiceAPIVersion = "2006-03-01"