configuration

Documentation

Overview

Package configuration is the FTL configuration and secret management API.

The full design is documented here.

A [Manager] is the high-level interface to storing, listing, and retrieving secrets and configuration. A [Resolver] is the next layer, mapping names to a storage location key such as environment variables, keychain, etc. The Provider is the final layer, responsible for actually storing and retrieving values in concrete storage.

A constructed [Manager] and its providers are parametric on either secrets or configuration and thus cannot be used interchangeably.

Index

• Variables
• type AsynchronousProvider
• type Configuration
  • func (Configuration) String() string
• type Entry
• type Obfuscator
  • func NewObfuscator(key []byte) Obfuscator
  • func (o Obfuscator) Obfuscate(input []byte) ([]byte, error)
  • func (o Obfuscator) Reveal(input []byte) ([]byte, error)
• type ObfuscatorProvider
• type Provider
• type ProviderKey
• type Ref
  • func NewRef(module, name string) Ref
  • func ParseRef(s string) (Ref, error)
  • func (k Ref) String() string
  • func (k *Ref) UnmarshalText(text []byte) error
• type Role
• type Router
• type Secrets
  • func (Secrets) Obfuscator() Obfuscator
  • func (Secrets) String() string
• type SyncedValue
• type SynchronousProvider
• type VersionToken

Variables

var ErrNotFound = errors.New("not found")

ErrNotFound is returned when a configuration entry is not found or cannot be resolved.

Types

type AsynchronousProvider

type AsynchronousProvider[R Role] interface {
	Provider[R]

	SyncInterval() time.Duration

	// Sync is called periodically to update the cache with the latest values.
	//
	// SyncInterval() provides the expected time between syncs.
	// If Sync() returns an error, sync will be retried with an exponential backoff.
	//
	// Values should be updated by Sync().
	// An array of known entries from the router is provided in case it is helpful, but the provider can store any values it wants.
	Sync(ctx context.Context, entries []Entry, values *xsync.MapOf[Ref, SyncedValue]) error
}

AsynchronousProvider is an interface for Provider's that support syncing values. This is recommended if the Provider allows batch access, or is expensive to load.

type Configuration

type Configuration struct{}

func (Configuration) String

func (Configuration) String() string

type Entry

type Entry struct {
	Ref
	Accessor *url.URL
}

Entry in the configuration store.

type Obfuscator

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

Obfuscator hides and reveals a value, but does not provide real security.

Instead, the aim of this Obfuscator is to make values not easily human-readable

Obfuscation is done by XOR-ing the input with the AES key. Length of key must be 16, 24 or 32 bytes (corresponding to AES-128, AES-192 or AES-256 keys).

func NewObfuscator

func NewObfuscator(key []byte) Obfuscator

func (Obfuscator) Obfuscate

func (o Obfuscator) Obfuscate(input []byte) ([]byte, error)

Obfuscate takes a value and returns an obfuscated value (encoded in base64)

func (Obfuscator) Reveal

func (o Obfuscator) Reveal(input []byte) ([]byte, error)

Reveal takes an obfuscated value and de-obfuscates the base64 encoded value

type ObfuscatorProvider

type ObfuscatorProvider interface {
	Obfuscator() Obfuscator
}

type Provider

type Provider[R Role] interface {
	Role() R
	Key() ProviderKey

	// Store a configuration value and return its key.
	Store(ctx context.Context, ref Ref, value []byte) (*url.URL, error)
	// Delete a configuration value.
	Delete(ctx context.Context, ref Ref) error
}

Provider is a generic interface for storing and retrieving configuration and secrets.

type ProviderKey

type ProviderKey string

type Ref

type Ref struct {
	Module optional.Option[string]
	Name   string
}

A Ref is a reference to a configuration value.

func NewRef

func NewRef(module, name string) Ref

NewRef creates a new Ref.

If [module] is empty, the Ref is considered to be a global configuration value.

func ParseRef

func ParseRef(s string) (Ref, error)

func (Ref) String

func (k Ref) String() string

func (*Ref) UnmarshalText

func (k *Ref) UnmarshalText(text []byte) error

type Role

type Role interface {
	Secrets | Configuration
}

Role of a Provider, Router or Manager. Either Secrets or Configuration.

type Router

type Router[R Role] interface {
	Role() R
	Get(ctx context.Context, ref Ref) (key *url.URL, err error)
	Set(ctx context.Context, ref Ref, key *url.URL) error
	Unset(ctx context.Context, ref Ref) error
	List(ctx context.Context) ([]Entry, error)
}

A Router resolves configuration names to keys that are then used to load values from a Provider.

This indirection allows for the storage of configuration values to be abstracted from the configuration itself. For example, the ftl-project.toml file contains per-module and global configuration maps, but the secrets themselves may be stored in a separate secret store such as a system keychain.

type Secrets

type Secrets struct{}

func (Secrets) Obfuscator

func (Secrets) Obfuscator() Obfuscator

func (Secrets) String

func (Secrets) String() string

type SyncedValue

type SyncedValue struct {
	Value []byte

	// VersionToken is a way of storing a version provided by the source of truth (eg: lastModified)
	// it is nil when:
	// - the owner of the cache is not using version tokens
	// - the cache is updated after writing
	VersionToken optional.Option[VersionToken]
}

type SynchronousProvider

type SynchronousProvider[R Role] interface {
	Provider[R]

	Load(ctx context.Context, ref Ref, key *url.URL) ([]byte, error)
}

SynchronousProvider is an interface for providers that can load values on-demand. This is recommended if the provider allows inexpensive loading of values.

type VersionToken

type VersionToken any