awsclient

awsclient

Resolve the AWS configuration a service client is built from — once and shared, or afresh per operation, as the caller chooses.

import "gitlab.com/phpboyscout/go/awsclient"

src := awsclient.Ambient()          // resolved lazily, once, on first use

cfg, err := src.AWSConfig(ctx)
client := ssm.NewFromConfig(cfg)     // pure; no I/O, no error, nothing to close

Why it exists

Building an AWS service client is two steps with very different costs. ssm.NewFromConfig(cfg) is pure — no I/O, no error, nothing to close. Getting the aws.Config is the part that walks a credential chain, may hit an SSO redirect or the instance metadata endpoint, and may fail.

Every adapter that needs a client faces the same problem, so it is solved once here instead of thirteen times downstream.

The rungs

All three return the same Source, so switching posture is a one-word change.

PerCall is not a slower Ambient. A signing backend that resolves credentials inside each operation does so deliberately — "it avoids holding AWS credentials longer than the operation requires" — and adopting a memoising source would quietly change that. It also does not collapse concurrent calls into one attempt, because sharing a resolution between callers who asked not to share one is the thing the rung exists to avoid.

Ambient resolves at most once concurrently and — unlike sync.OnceValues — never caches a failure, so a flap at startup does not wedge the process.

This module never guesses a region

There is no default region here, and there will not be one. A config that names no region names a key in an account nobody chose, so an empty region is ErrNoRegion from the accessor rather than a confusing failure several calls later.

Two shipped modules already disagree about this, each deliberately: encryption-aws-kms sets no default and errors on an empty region; signing-aws-kms defaults eu-west-2 to match its Terraform module. A general-purpose module cannot hold both opinions and should hold neither. A caller that has a region passes it:

awsclient.Ambient(
    awsclient.WithRegion("eu-west-2"),                                   // the common case
    awsclient.WithLoadOptions(config.WithSharedConfigProfile("build")),  // the rest
)

A caller whose region is a user-facing default — a CLI flag, say — keeps that default in its own layer, where the choice has a reason.

Sharing is explicit

Two adapters that each call Ambient() get two independent sources and resolve the chain twice. That is correct: they may deliberately want different profiles, and a hidden process-wide cache would make the first one's transient failure everybody's, invisibly. A caller who wants one chain says so:

src := awsclient.Ambient()

ssmBackend := configawsssm.FromSource(src, "/app")
s3fs       := configawss3.FSFromSource(src, "my-bucket")

Options

Logging

Off unless you pass a logger. Records carry only non-secret identifiers — the region, how long resolution took, and the credential provider's type, which is the most useful thing a wedged chain can tell you because it says which link actually won. Credentials are never logged, at any level, and nothing is logged above DEBUG. Both claims have tests.

What it costs

This module carries the AWS credential-resolution graph — that is its entire job, and it is why it exists as a module rather than in each adapter. The exact set is asserted by depfootprint_test.go. An adapter that takes an aws.Config through a narrow interface it declares itself pays none of it.

Specification

org 0003 — provider client modules (P-2, P-3, P-12, P-13, P-14), which applies the connection lifecycle of org 0002 across the estate. The state machine beneath Ambient is clientlifecycle.

Licence

MIT. See LICENSE.