Documentation
¶
Overview ¶
Package core is the machinery the parameters packages share: the options of one read, the transforms, the conversion of a value into the Go type the caller names, the cache and the registry of default providers. It is internal so that every provider under parameters/ uses it without it becoming part of the public API.
Index ¶
- Constants
- Variables
- func ApplyStore[O any](options []StoreOption, target *O)
- func Convert[T any](v Value) (T, error)
- func DecodeBase64(raw []byte) ([]byte, error)
- func Fetch[V any](ctx context.Context, c *Cache, key Key, maxAge time.Duration, force bool, ...) (V, error)
- func Lookup[V any](c *Cache, key Key) (V, bool)
- func NormalizeTransform(t string) (string, error)
- func RegisterDefaults(reset func())
- func ResetDefaults()
- func ResolveTransform(name, transform string) string
- type Cache
- type CacheHolder
- type Defaults
- type Key
- type Kind
- type Options
- type StoreOption
- type Value
Constants ¶
const ( TransformNone = "" TransformJSON = "json" TransformBinary = "binary" TransformAuto = "auto" )
The transforms, by their Python names.
const DefaultMaxAge = 5 * time.Minute
DefaultMaxAge is how long a value stays cached when neither the read nor POWERTOOLS_PARAMETERS_MAX_AGE says otherwise, as in Powertools Python.
Variables ¶
var ( // ErrUnknownTransform reports a transform that is none of the above. ErrUnknownTransform = errors.New("unknown transform") // ErrInvalidJSON reports a value that is not a JSON document. ErrInvalidJSON = errors.New("value is not valid JSON") // ErrIncorrectPadding reports base64 data whose padding is missing. ErrIncorrectPadding = errors.New("incorrect base64 padding") // ErrUnsupportedType reports a Go type that cannot hold a value read // without the JSON transform. ErrUnsupportedType = errors.New("type cannot hold a text value, read it with the JSON transform") )
Errors of the transforms and of the conversion into a Go type.
var ErrCacheType = errors.New("cached value has an unexpected type")
ErrCacheType reports a cached value of another type than the one asked for: two readers used one key for different things, a bug.
Functions ¶
func ApplyStore ¶
func ApplyStore[O any](options []StoreOption, target *O)
ApplyStore applies to target, in order, every store option written for its type.
func Convert ¶
Convert turns v into a T. A JSON value is decoded into T; a text or binary value goes into a string, a []byte or an empty interface (a string for text, a []byte for binary, as Python returns str and bytes); a failed one gives the zero T.
func DecodeBase64 ¶
DecodeBase64 decodes standard base64 the way Python's base64.b64decode does without validation: characters outside the alphabet, whitespace included, are discarded, padding is required, and anything after the padding is ignored.
func Fetch ¶
func Fetch[V any](ctx context.Context, c *Cache, key Key, maxAge time.Duration, force bool, fetch func(context.Context) (V, error)) (V, error)
Fetch returns the value of type V cached under key or, when there is none, when it has expired, or when force is set, the value fetch returns, which it then caches for maxAge. Concurrent fetches of one key share a single call.
The shared call runs on a context detached from the cancellation of the caller that started it (it keeps that caller's deadline and values), and every caller waits only as long as its own context allows: invocations served by one process (Lambda Managed Instances) do not fail because another one ended.
func NormalizeTransform ¶
NormalizeTransform returns the canonical name of transform t, accepting the ".json" and ".binary" aliases Python accepts.
func RegisterDefaults ¶
func RegisterDefaults(reset func())
RegisterDefaults adds reset to what ResetDefaults calls.
func ResetDefaults ¶
func ResetDefaults()
ResetDefaults forgets every default provider, so that the next shortcut builds a new one, with a new SDK client and an empty cache.
func ResolveTransform ¶
ResolveTransform returns the transform that applies to the value named name: transform itself, or for TransformAuto the one the suffix after the last dot names (".json" or ".binary"), none for any other suffix. As in Python, a name without a dot is its own suffix.
Types ¶
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache keeps values for a time, safely for concurrent use, and makes concurrent reads of a missing value share one fetch.
func NewCache ¶
func NewCache() *Cache
NewCache returns an empty cache on the wall clock. time.Now carries a monotonic reading, so expiry is immune to clock changes.
func (*Cache) Lookup ¶
Lookup returns the value cached under key, if it has not expired. A value is valid up to and including its expiry instant, as in Python.
type CacheHolder ¶
type CacheHolder interface {
Cache() *Cache
}
CacheHolder is implemented by the stores of this module that read in batches (SSM by name, Secrets Manager by name): they bring the cache their provider must share with them. Only this module can implement it.
type Defaults ¶
type Defaults[K comparable, P any] struct { // contains filtered or unexported fields }
Defaults holds the default provider of a package, built on first use. Building it can fail (no AWS region, for one); a failure is not kept, the next use tries again.
type Key ¶
Key identifies a cached value: the name (or path, or joined names) it was read under, the transform applied to it, whether it holds several values, and the variant the store options made of it.
func MultipleKey ¶
MultipleKey is the key of the values under path read with o.
type Kind ¶
type Kind uint8
Kind says what a Value holds.
const ( // KindText is a value as the store returned it. KindText Kind = iota // KindBinary is the bytes a binary transform decoded. KindBinary // KindJSON is a JSON document, validated by the JSON transform. KindJSON // KindFailed is a value whose transform failed in a read of several // values that tolerates it: Python gives None, Go the zero value. KindFailed )
The kinds of Value.
type Options ¶
type Options struct {
MaxAge time.Duration
MaxAgeSet bool
ForceFetch bool
Transform string
RaiseOnTransformError bool
Store []StoreOption
}
Options are the options of one read, once applied.
func (*Options) ResolvedMaxAge ¶
ResolvedMaxAge returns the explicit max age, else POWERTOOLS_PARAMETERS_MAX_AGE, else DefaultMaxAge. The variable is read on every call, as Python does, so that changing it at runtime takes effect.
type StoreOption ¶
StoreOption is an option of one specific store, carried along with the common ones. Apply is a func(*O) for the store's option type O; Variant says how the option changes the value read ("" when it does not), so that the cache keeps values read with different options apart.
type Value ¶
type Value struct {
Data []byte
Kind Kind
// Err is why the transform of a KindFailed value failed.
Err error
}
Value is a value after its transform: what the cache keeps, and what is converted into the caller's type on every read, so that callers never share mutable state through the cache.
Source Files