github.com/aws/aws-sdk-go-v2 v1.47.0: aws.CredentialsCacheOptions

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify github.com/aws/aws-sdk-go-v2/aws.CredentialsCacheOptions in pkg:golang/github.com/aws/aws-sdk-go-v2@v1.47.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/aws/aws-sdk-go-v2@v1.47.0
Demonstrate these symbols/APIs:
  - github.com/aws/aws-sdk-go-v2/aws.CredentialsCacheOptions

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:11097489f78d6b28731ddd7263ee4dc5dbd654c80476becf3b394c78647a33e6","contract":["CredentialsCacheOptions struct allows configuring ExpiryWindow and ExpiryWindowJitterFrac","NewCredentialsCache accepts option functions to configure CredentialsCacheOptions","CredentialsCache caches unexpired credentials when outside ExpiryWindow","CredentialsCache triggers credential refresh when within ExpiryWindow","CredentialsCache Invalidate forces immediate credential refresh on next Retrieve","NewCredentialsCache operates with default options when no option functions are provided"],"goal":"verify github.com/aws/aws-sdk-go-v2/aws.CredentialsCacheOptions in pkg:golang/github.com/aws/aws-sdk-go-v2@v1.47.0","kind":"HOW","packages":["pkg:golang/github.com/aws/aws-sdk-go-v2@v1.47.0"],"schemaVersion":1,"symbols":["github.com/aws/aws-sdk-go-v2/aws.CredentialsCacheOptions"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/aws/aws-sdk-go-v2@v1.47.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/aws/aws-sdk-go-v2@v1.47.0","symbols":["github.com/aws/aws-sdk-go-v2/aws.CredentialsCacheOptions"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require github.com/aws/aws-sdk-go-v2 v1.47.0

require github.com/aws/smithy-go v1.28.5 // indirect

github.com/aws/aws-sdk-go-v2 v1.47.0 h1:0jsHallhJCeaU0Ko48c/3FK1ctOQ7NpzggxriJOQ8MQ=
github.com/aws/aws-sdk-go-v2 v1.47.0/go.mod h1:bttEH6JqnUL8LepvDVfdrds/fZ5bCIxzpe3abyUrhDU=
github.com/aws/aws-sdk-go-v2 v1.47.3 h1:HRoT/MkNi3bjO5xF4dCzLzvVmkvRGHj3/cLINDnJejk=
github.com/aws/aws-sdk-go-v2 v1.47.3/go.mod h1:xSl+OSI5ZUw6bSMupWc218zE5Pl+65MCCu3ySWFY99A=
github.com/aws/smithy-go v1.28.5 h1:OqbqKtzY9NUnr2yAe9+hiTdFb20tNaK/lI0PMOGXX9k=
github.com/aws/smithy-go v1.28.5/go.mod h1:YE2RhdIuDbA5E5bTdciG9KrW3+TiEONeUWCqxX9i1Fc=

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/aws/aws-sdk-go-v2/aws"
)

type staticProvider struct {
	creds aws.Credentials
}

func (p staticProvider) Retrieve(ctx context.Context) (aws.Credentials, error) {
	return p.creds, nil
}

func main() {
	ctx := context.Background()

	provider := staticProvider{
		creds: aws.Credentials{
			AccessKeyID:     "mock-access-key-id",
			SecretAccessKey: "mock-secret-access-key",
			SessionToken:    "mock-session-token",
			Source:          "StaticProvider",
			CanExpire:       true,
			Expires:         time.Now().Add(1 * time.Hour),
		},
	}

	cache := aws.NewCredentialsCache(provider, func(options *aws.CredentialsCacheOptions) {
		options.ExpiryWindow = 5 * time.Minute
		options.ExpiryWindowJitterFrac = 0.0
	})

	creds, err := cache.Retrieve(ctx)
	if err != nil {
		fmt.Printf("failed to retrieve credentials: %v\n", err)
		return
	}

	fmt.Printf("Retrieved credentials from source %s (hasKeys: %t, expired: %t)\n",
		creds.Source, creds.HasKeys(), creds.Expired())
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/aws/aws-sdk-go-v2/aws.CredentialsCacheOptions in pkg:golang/github.com/aws/aws-sdk-go-v2@v1.47.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/aws/aws-sdk-go-v2@v1.47.0"
  ],
  "symbols": [
    "github.com/aws/aws-sdk-go-v2/aws.CredentialsCacheOptions"
  ]
}

package main

import (
	"context"
	"fmt"
	"os"
	"sync/atomic"
	"time"

	"github.com/aws/aws-sdk-go-v2/aws"
)

func main() {
	if err := runContract(); err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: %v\n", err)
		os.Exit(1)
	}
	fmt.Println("PASS: all contract assertions satisfied")
}

type countingProvider struct {
	count atomic.Int64
	creds aws.Credentials
}

func (c *countingProvider) Retrieve(ctx context.Context) (aws.Credentials, error) {
	c.count.Add(1)
	return c.creds, nil
}

func runContract() error {
	ctx := context.Background()

	// 1. CredentialsCacheOptions struct allows configuring ExpiryWindow and ExpiryWindowJitterFrac
	opts := aws.CredentialsCacheOptions{
		ExpiryWindow:           15 * time.Minute,
		ExpiryWindowJitterFrac: 0.25,
	}
	if opts.ExpiryWindow != 15*time.Minute {
		return fmt.Errorf("expected ExpiryWindow to be 15m, got %v", opts.ExpiryWindow)
	}
	if opts.ExpiryWindowJitterFrac != 0.25 {
		return fmt.Errorf("expected ExpiryWindowJitterFrac to be 0.25, got %v", opts.ExpiryWindowJitterFrac)
	}

	// 2. NewCredentialsCache accepts option functions to configure CredentialsCacheOptions
	optConfigured := false
	dummyProvider := &countingProvider{
		creds: aws.Credentials{
			AccessKeyID:     "opt-key",
			SecretAccessKey: "opt-secret",
			CanExpire:       false,
		},
	}
	cacheWithOpt := aws.NewCredentialsCache(dummyProvider, func(options *aws.CredentialsCacheOptions) {
		optConfigured = true
		options.ExpiryWindow = 5 * time.Minute
		options.ExpiryWindowJitterFrac = 0.0
	})
	if cacheWithOpt == nil {
		return fmt.Errorf("NewCredentialsCache returned nil")
	}
	if !optConfigured {
		return fmt.Errorf("option function was not invoked during NewCredentialsCache")
	}

	// 3. CredentialsCache caches unexpired credentials when outside ExpiryWindow
	longLivedProvider := &countingProvider{
		creds: aws.Credentials{
			AccessKeyID:     "cached-key",
			SecretAccessKey: "cached-secret",
			Source:          "LongLivedProvider",
			CanExpire:       true,
			Expires:         time.Now().Add(2 * time.Hour),
		},
	}
	cache1 := aws.NewCredentialsCache(longLivedProvider, func(options *aws.CredentialsCacheOptions) {
		options.ExpiryWindow = 10 * time.Minute
		options.ExpiryWindowJitterFrac = 0.0
	})
	c1, err := cache1.Retrieve(ctx)
	if err != nil {
		return fmt.Errorf("first retrieve failed: %w", err)
	}
	c2, err := cache1.Retrieve(ctx)
	if err != nil {
		return fmt.Errorf("second retrieve failed: %w", err)
	}
	if c1.AccessKeyID != c2.AccessKeyID || c1.SecretAccessKey != c2.SecretAccessKey {
		return fmt.Errorf("cached credentials mismatch: %+v vs %+v", c1, c2)
	}
	if calls := longLivedProvider.count.Load(); calls != 1 {
		return fmt.Errorf("expected exactly 1 provider invocation outside ExpiryWindow, got %d", calls)
	}

	// 4. CredentialsCache triggers credential refresh when within ExpiryWindow
	nearExpiryProvider := &countingProvider{
		creds: aws.Credentials{
			AccessKeyID:     "refresh-key",
			SecretAccessKey: "refresh-secret",
			Source:          "NearExpiryProvider",
			CanExpire:       true,
			Expires:         time.Now().Add(5 * time.Second),
		},
	}
	cache2 := aws.NewCredentialsCache(nearExpiryProvider, func(options *aws.CredentialsCacheOptions) {
		options.ExpiryWindow = 30 * time.Second
		options.ExpiryWindowJitterFrac = 0.0
	})
	_, err = cache2.Retrieve(ctx)
	if err != nil {
		return fmt.Errorf("retrieve failed on near-expiry cache: %w", err)
	}
	_, err = cache2.Retrieve(ctx)
	if err != nil {
		return fmt.Errorf("subsequent retrieve failed on near-expiry cache: %w", err)
	}
	if calls := nearExpiryProvider.count.Load(); calls != 2 {
		return fmt.Errorf("expected 2 provider invocations due to ExpiryWindow refresh, got %d", calls)
	}

	// 5. CredentialsCache Invalidate forces immediate credential refresh on next Retrieve
	cache1.Invalidate()
	_, err = cache1.Retrieve(ctx)
	if err != nil {
		return fmt.Errorf("retrieve after invalidate failed: %w", err)
	}
	if calls := longLivedProvider.count.Load(); calls != 2 {
		return fmt.Errorf("expected provider invocation after Invalidate(), got count %d", calls)
	}

	// 6. NewCredentialsCache operates with default options when no option functions are provided
	defaultProvider := &countingProvider{
		creds: aws.Credentials{
			AccessKeyID:     "default-key",
			SecretAccessKey: "default-secret",
			Source:          "DefaultProvider",
			CanExpire:       false,
		},
	}
	defaultCache := aws.NewCredentialsCache(defaultProvider)
	defCreds, err := defaultCache.Retrieve(ctx)
	if err != nil {
		return fmt.Errorf("defaultCache retrieve failed: %w", err)
	}
	if defCreds.AccessKeyID != "default-key" {
		return fmt.Errorf("unexpected default credentials: %+v", defCreds)
	}

	return nil
}