experiments

Documentation

Overview

Package experiments contains the models and logic for opt-in experiments that can be activated for a particular Terraform module.

We use experiments to get feedback on new configuration language features in a way that permits breaking changes without waiting for a future minor release. Any feature behind an experiment flag is subject to change in any way in even a patch release, until we have enough confidence about the design of the feature to make compatibility commitments about it.

Index

• Constants
• func OverrideForTesting(t *testing.T, current Set, concluded map[Experiment]string) func()
• type ConcludedError
  • func (e ConcludedError) Error() string
• type Experiment
  • func GetCurrent(name string) (Experiment, error)
  • func (e Experiment) IsConcluded() bool
  • func (e Experiment) IsCurrent() bool
  • func (e Experiment) Keyword() string
• type Set
  • func NewSet(exps ...Experiment) Set
  • func SetUnion(sets ...Set) Set
  • func (s Set) Add(exp Experiment)
  • func (s Set) Has(exp Experiment) bool
  • func (s Set) Remove(exp Experiment)
• type UnavailableError
  • func (e UnavailableError) Error() string

Constants

const (
	VariableValidation = Experiment("variable_validation")
)

All active and defunct experiments must be represented by constants whose internal string values are unique.

Each of these declared constants must also be registered as either a current or a defunct experiment in the init() function below.

Each experiment is represented by a string that must be a valid HCL identifier so that it can be specified in configuration.

Functions

func OverrideForTesting

func OverrideForTesting(t *testing.T, current Set, concluded map[Experiment]string) func()

OverrideForTesting temporarily overrides the global tables of experiments in order to allow for a predictable set when unit testing the experiments infrastructure code.

The correct way to use this function is to defer a call to its result so that the original tables can be restored at the conclusion of the calling test:

defer experiments.OverrideForTesting(t, current, concluded)()

This function modifies global variables that are normally fixed throughout our execution, so this function must not be called from non-test code and any test using it cannot safely run concurrently with other tests.

Types

type ConcludedError

type ConcludedError struct {
	ExperimentName string
	Message        string
}

ConcludedError is the error type returned by GetCurrent when the requested experiment is recognized as concluded.

func (ConcludedError) Error

func (e ConcludedError) Error() string

type Experiment

type Experiment string

Experiment represents a particular experiment, which can be activated independently of all other experiments.

func GetCurrent

func GetCurrent(name string) (Experiment, error)

GetCurrent takes an experiment name and returns the experiment value representing that expression if and only if it is a current experiment.

If the selected experiment is concluded, GetCurrent will return an error of type ConcludedError whose message hopefully includes some guidance for users of the experiment on how to migrate to a stable feature that succeeded it.

If the selected experiment is not known at all, GetCurrent will return an error of type UnavailableError.

func (Experiment) IsConcluded

func (e Experiment) IsConcluded() bool

IsConcluded returns true if the receiver is a concluded experiment.

func (Experiment) IsCurrent

func (e Experiment) IsCurrent() bool

IsCurrent returns true if the receiver is considered a currently-selectable experiment.

func (Experiment) Keyword

func (e Experiment) Keyword() string

Keyword returns the keyword that would be used to activate this experiment in the configuration.

type Set

type Set map[Experiment]struct{}

Set is a collection of experiments where every experiment is either a member or not.

func NewSet

func NewSet(exps ...Experiment) Set

NewSet constructs a new Set with the given experiments as its initial members.

func SetUnion

func SetUnion(sets ...Set) Set

SetUnion constructs a new Set containing the members of all of the given sets.

func (Set) Add

func (s Set) Add(exp Experiment)

Add inserts the given experiment into the set.

If the given experiment is already present then this is a no-op.

func (Set) Has

func (s Set) Has(exp Experiment) bool

Has tests whether the given experiment is in the receiving set.

func (Set) Remove

func (s Set) Remove(exp Experiment)

Remove takes the given experiment out of the set.

If the given experiment not already present then this is a no-op.

type UnavailableError

type UnavailableError struct {
	ExperimentName string
}

UnavailableError is the error type returned by GetCurrent when the requested experiment is not recognized at all.

func (UnavailableError) Error

func (e UnavailableError) Error() string