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 Provider
• type ProviderKey
  • func (p ProviderKey) String() string
• 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) 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.
	Sync(ctx context.Context) (map[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 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

func (ProviderKey) String

func (p ProviderKey) String() 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) 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