parameters

Documentation

Overview

Package parameters shares caching, transforms and errors for configuration providers.

The ssm, secrets, dynamodb, appconfig and appconfigagent subpackages retrieve configuration from their respective services. Construct service providers with application-owned clients and reuse them across Lambda invocations.

Cache and transform policy

Options controls age, refresh, missing-value and transform behavior. Use Age for an explicit lifetime; nonpositive lifetimes bypass lookup and storage, while ForceFetch bypasses lookup. Service adapters isolate entries by effective request options. Cache also supports application-owned retrieval callbacks.

TransformValue applies JSON or Base64 decoding. Retrieval and transform errors preserve underlying failures for errors.Is and errors.As. Provider ClearCache methods invalidate local entries; they do not change the remote configuration.

For usage and compatibility details, see the user guide.

Index

• func Age(d time.Duration) *time.Duration
• func ClearCaches()
• func GetError(name string, err error) error
• func TransformValue(name string, value any, transform Transform) (any, error)
• type Cache
  • func NewCache(clock func() time.Time) *Cache
  • func (c *Cache) ClearCache()
  • func (c *Cache) Get(ctx context.Context, name string, options Options, ...) (any, error)
  • func (c *Cache) GetMultiple(ctx context.Context, path string, options Options, ...) (map[string]any, error)
  • func (c *Cache) Lookup(name string, options Options) (any, bool)
  • func (c *Cache) Store(name string, value any, options Options)
• type GetParameterError
  • func (e *GetParameterError) Error() string
  • func (e *GetParameterError) Unwrap() error
• type Options
  • func (o Options) Lifetime() time.Duration
• type ParameterNotFoundError
  • func (e *ParameterNotFoundError) Error() string
• type SetParameterError
  • func (e *SetParameterError) Error() string
  • func (e *SetParameterError) Unwrap() error
• type Transform
• type TransformParameterError
  • func (e *TransformParameterError) Error() string
  • func (e *TransformParameterError) Unwrap() error

Examples

• Cache.Get

Functions

func Age

func Age(d time.Duration) *time.Duration

Age returns a duration pointer for an explicit cache lifetime, including zero.

func ClearCaches

func ClearCaches()

ClearCaches clears all initialized default providers. Explicit providers have their own ClearCache methods. Default AWS configuration and AppConfig sessions are retained.

func GetError

func GetError(name string, err error) error

GetError normalizes retrieval errors without losing typed library errors.

func TransformValue

func TransformValue(name string, value any, transform Transform) (any, error)

TransformValue decodes JSON or base64 text. Auto selects by the name suffix. Binary returns UTF-8 text; raw byte values stay bytes when no transform is used.

Types

type Cache

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

Cache is safe for concurrent retrievals. Construct one per provider, not per invocation. RequestKey isolates value-affecting request options within each operation. Concurrent misses may fetch independently, matching the reference provider.

func NewCache

func NewCache(clock func() time.Time) *Cache

NewCache accepts an optional clock for deterministic expiry tests.

func (*Cache) ClearCache

func (c *Cache) ClearCache()

ClearCache also prevents in-flight Get/GetMultiple callbacks from repopulating entries.

func (*Cache) Get

func (c *Cache) Get(ctx context.Context, name string, options Options, fetch func(context.Context) (any, error)) (any, error)

Get fetches and transforms a value on a cache miss. A nil value means missing.

Example

package main

import (
	"context"
	"fmt"
	"time"

	"github.com/rambow-cloud/powertools-lambda-go/parameters"
)

func main() {
	cache := parameters.NewCache(nil)
	options := parameters.Options{MaxAge: parameters.Age(time.Minute)}
	fetches := 0
	fetch := func(context.Context) (any, error) {
		fetches++
		return "enabled", nil
	}
	for range 2 {
		value, err := cache.Get(context.Background(), "feature", options, fetch)
		fmt.Println(value, err)
	}
	fmt.Println("fetches:", fetches)
}

Output:
enabled <nil>
enabled <nil>
fetches: 1

func (*Cache) GetMultiple

func (c *Cache) GetMultiple(ctx context.Context, path string, options Options, fetch func(context.Context) (map[string]any, error)) (map[string]any, error)

func (*Cache) Lookup

func (c *Cache) Lookup(name string, options Options) (any, bool)

Lookup and Store share single-value entries with batched provider operations.

func (*Cache) Store

func (c *Cache) Store(name string, value any, options Options)

Store caches an already transformed value returned by a batched operation.

type GetParameterError

type GetParameterError struct {
	Name string
	Err  error
}

GetParameterError preserves the underlying SDK or context error for errors.Is/As.

func (*GetParameterError) Error

func (e *GetParameterError) Error() string

func (*GetParameterError) Unwrap

func (e *GetParameterError) Unwrap() error

type Options

type Options struct {
	// RequestKey isolates effective provider request options. Providers set it automatically.
	RequestKey            string
	MaxAge                *time.Duration
	ForceFetch            bool
	Transform             Transform
	ThrowOnMissing        bool
	ThrowOnTransformError bool
}

Options controls one retrieval. A nil MaxAge reads the environment on each call. Nonpositive MaxAge bypasses lookup and storage; ForceFetch bypasses lookup.

func (Options) Lifetime

func (o Options) Lifetime() time.Duration

type ParameterNotFoundError

type ParameterNotFoundError struct{ Name string }

func (*ParameterNotFoundError) Error

func (e *ParameterNotFoundError) Error() string

type SetParameterError

type SetParameterError struct {
	Name string
	Err  error
}

func (*SetParameterError) Error

func (e *SetParameterError) Error() string

func (*SetParameterError) Unwrap

func (e *SetParameterError) Unwrap() error

type Transform

type Transform string

const (
	JSON   Transform = "json"
	Binary Transform = "binary"
	Auto   Transform = "auto"
)

type TransformParameterError

type TransformParameterError struct {
	Transform Transform
	Err       error
}

func (*TransformParameterError) Error

func (e *TransformParameterError) Error() string

func (*TransformParameterError) Unwrap

func (e *TransformParameterError) Unwrap() error