awsopt

Documentation

Overview

Package awsopt solves the repetitive wiring problem of configuring the aws-sdk-go-v2 library consistently across multiple AWS service clients. Rather than scattering config.LoadOptionsFunc calls throughout every package that talks to AWS, awsopt centralizes those options into a single composable Options slice that can be built once and handed to any AWS-based package in this library.

Problem

Every aws-sdk-go-v2 client requires a loaded aws.Config, and every project ends up writing the same region-detection boilerplate: check a hardcoded value, fall back to an environment variable, fall back to a default. When several packages (secrets, S3, SQS, …) each duplicate this logic, configuration drift and inconsistent behavior are inevitable. awsopt provides one canonical implementation shared by all of them.

How It Works

Options is a typed slice of config.LoadOptionsFunc values. Options are accumulated with method calls and then materialized into an aws.Config via Options.LoadDefaultConfig, which delegates to the standard config.LoadDefaultConfig from the SDK:

1. Create an Options value (zero value is ready to use).
2. Append options with Options.WithAWSOption, Options.WithRegion, or Options.WithRegionFromURL.
3. Call Options.LoadDefaultConfig to obtain an aws.Config that can be passed directly to any aws-sdk-go-v2 service constructor.

Key Features

• Composable options: Options is an append-friendly slice; options from multiple sources can be merged before the config is loaded.
• Automatic region resolution: Options.WithRegionFromURL extracts the AWS region from a service endpoint URL by taking the right-most region-shaped host label. This is partition-agnostic — standard, dual-stack (api.aws), China, GovCloud, ISO, and VPC-endpoint URLs all work, as do future partitions, with no code changes. When the URL encodes no region, it uses the caller-supplied default if given, and otherwise adds no region option — deferring to the SDK's canonical resolution (AWS_REGION, AWS_DEFAULT_REGION, the shared config file, then IMDS) instead of forcing a hardcoded default. This single function eliminates an entire class of misconfiguration bugs.
• Escape hatch: Options.WithAWSOption accepts any config.LoadOptionsFunc, so every SDK option remains accessible without leaving the awsopt pattern.
• Zero dependencies beyond aws-sdk-go-v2: the package adds no third-party dependencies of its own.

Integrated Packages

awsopt is used as the AWS configuration layer by:

• github.com/tecnickcom/nurago/pkg/awssecretcache
• github.com/tecnickcom/nurago/pkg/s3
• github.com/tecnickcom/nurago/pkg/sqs

Usage

var opts awsopt.Options
opts.WithRegionFromURL("https://s3.eu-west-1.amazonaws.com", "")

awsCfg, err := opts.LoadDefaultConfig(ctx)
if err != nil {
    return err
}

// awsCfg is ready for any aws-sdk-go-v2 service client:
// s3.NewFromConfig(awsCfg), secretsmanager.NewFromConfig(awsCfg), …

When consuming an awsopt-based package, pass additional options via the package's own WithAWSOptions helper so all AWS clients in the process share consistent configuration.

Index

• type Options
  • func (c *Options) LoadDefaultConfig(ctx context.Context) (aws.Config, error)
  • func (c *Options) WithAWSOption(opt config.LoadOptionsFunc)
  • func (c *Options) WithRegion(region string)
  • func (c *Options) WithRegionFromURL(rawURL, defaultRegion string)

Types

type Options

type Options []config.LoadOptionsFunc

Options is a set of all AWS options to apply.

An Options value is not safe for concurrent modification: build it from a single goroutine with the With* methods, then share the finished value read-only (for example by passing it to a consuming package's WithAWSOptions).

func (*Options) LoadDefaultConfig

func (c *Options) LoadDefaultConfig(ctx context.Context) (aws.Config, error)

LoadDefaultConfig builds an aws.Config from the accumulated options.

It solves the "repeat config wiring in every AWS client" problem by turning one shared Options value into a concrete SDK configuration in a single call. This keeps region, credentials, and any custom SDK loaders consistent across packages that consume awsopt.

func (*Options) WithAWSOption

func (c *Options) WithAWSOption(opt config.LoadOptionsFunc)

WithAWSOption appends any raw aws-sdk-go-v2 load option.

Use this as the escape hatch when you need an SDK feature that does not have a dedicated helper in this package. The main benefit is flexibility without giving up the shared Options composition pattern.

func (*Options) WithRegion

func (c *Options) WithRegion(region string)

WithRegion appends an explicit AWS region option.

This is the direct choice when the region is already known, and it ensures every downstream AWS client built from the same Options value uses the same target region.

func (*Options) WithRegionFromURL

func (c *Options) WithRegionFromURL(rawURL, defaultRegion string)

WithRegionFromURL appends a region derived from an AWS endpoint URL.

It removes common endpoint-parsing boilerplate by extracting the region from AWS endpoint URLs. The region is the right-most host label that looks like an AWS region code. This is partition-agnostic — it does not depend on the DNS suffix — so every endpoint form works, including future partitions, with no code changes:

https://sqs.eu-west-1.amazonaws.com                -> eu-west-1     (standard)
https://ec2.us-west-2.api.aws                      -> us-west-2     (dual-stack)
https://sqs.cn-north-1.amazonaws.com.cn            -> cn-north-1    (China)
https://sqs.us-iso-east-1.c2s.ic.gov               -> us-iso-east-1 (ISO)
https://vpce-0abc.sqs.us-east-1.vpce.amazonaws.com -> us-east-1     (VPC endpoint)

The scheme is optional, matching is case-insensitive, and userinfo, port, and path are ignored (only the host is inspected). Scanning right-to-left means a region-shaped label further left — such as a bucket named like a region in "bucket.s3.eu-west-1.amazonaws.com" — does not shadow the real region.

The region must be its own dot-separated host label. Endpoints that fold the region into a larger label are not recognized and fall back — notably the dash-style S3 website endpoint "bucket.s3-website-us-east-1.amazonaws.com" (the dot-style "bucket.s3-website.us-east-1.amazonaws.com" works).

Note the flip side of being partition-agnostic: the host is not verified to be AWS-owned, so a non-AWS URL that happens to carry a region-shaped label yields that region. Pass a genuine AWS endpoint.

When the URL carries no region, defaultRegion is used if it is non-empty. Otherwise no region option is added at all: region resolution is left to the SDK's config.LoadDefaultConfig, which applies AWS's canonical precedence — AWS_REGION, then AWS_DEFAULT_REGION, then the shared config file (~/.aws/config), then EC2 IMDS. In other words this is a thin override: it only pins a region when it has an explicit one (from the URL or defaultRegion) and otherwise stays out of the SDK's way rather than substituting a hardcoded default.