1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
|
// experiment package contains helper functions for tracking experimental
// features throughout Terraform.
//
// This package should be used for creating, enabling, querying, and deleting
// experimental features. By unifying all of that onto a single interface,
// we can have the Go compiler help us by enforcing every place we touch
// an experimental feature.
//
// To create a new experiment:
//
// 1. Add the experiment to the global vars list below, prefixed with X_
//
// 2. Add the experiment variable to the All listin the init() function
//
// 3. Use it!
//
// To remove an experiment:
//
// 1. Delete the experiment global var.
//
// 2. Try to compile and fix all the places where the var was referenced.
//
// To use an experiment:
//
// 1. Use Flag() if you want the experiment to be available from the CLI.
//
// 2. Use Enabled() to check whether it is enabled.
//
// As a general user:
//
// 1. The `-Xexperiment-name` flag
// 2. The `TF_X_<experiment-name>` env var.
// 3. The `TF_X_FORCE` env var can be set to force an experimental feature
// without human verifications.
//
package experiment
import (
"flag"
"fmt"
"os"
"strconv"
"strings"
"sync"
)
// The experiments that are available are listed below. Any package in
// Terraform defining an experiment should define the experiments below.
// By keeping them all within the experiment package we force a single point
// of definition and use. This allows the compiler to enforce references
// so it becomes easy to remove the features.
var (
// Shadow graph. This is already on by default. Disabling it will be
// allowed for awhile in order for it to not block operations.
X_shadow = newBasicID("shadow", "SHADOW", false)
)
// Global variables this package uses because we are a package
// with global state.
var (
// all is the list of all experiements. Do not modify this.
All []ID
// enabled keeps track of what flags have been enabled
enabled map[string]bool
enabledLock sync.Mutex
// Hidden "experiment" that forces all others to be on without verification
x_force = newBasicID("force", "FORCE", false)
)
func init() {
// The list of all experiments, update this when an experiment is added.
All = []ID{
X_shadow,
x_force,
}
// Load
reload()
}
// reload is used by tests to reload the global state. This is called by
// init publicly.
func reload() {
// Initialize
enabledLock.Lock()
enabled = make(map[string]bool)
enabledLock.Unlock()
// Set defaults and check env vars
for _, id := range All {
// Get the default value
def := id.Default()
// If we set it in the env var, default it to true
key := fmt.Sprintf("TF_X_%s", strings.ToUpper(id.Env()))
if v := os.Getenv(key); v != "" {
def = v != "0"
}
// Set the default
SetEnabled(id, def)
}
}
// Enabled returns whether an experiment has been enabled or not.
func Enabled(id ID) bool {
enabledLock.Lock()
defer enabledLock.Unlock()
return enabled[id.Flag()]
}
// SetEnabled sets an experiment to enabled/disabled. Please check with
// the experiment docs for when calling this actually affects the experiment.
func SetEnabled(id ID, v bool) {
enabledLock.Lock()
defer enabledLock.Unlock()
enabled[id.Flag()] = v
}
// Force returns true if the -Xforce of TF_X_FORCE flag is present, which
// advises users of this package to not verify with the user that they want
// experimental behavior and to just continue with it.
func Force() bool {
return Enabled(x_force)
}
// Flag configures the given FlagSet with the flags to configure
// all active experiments.
func Flag(fs *flag.FlagSet) {
for _, id := range All {
desc := id.Flag()
key := fmt.Sprintf("X%s", id.Flag())
fs.Var(&idValue{X: id}, key, desc)
}
}
// idValue implements flag.Value for setting the enabled/disabled state
// of an experiment from the CLI.
type idValue struct {
X ID
}
func (v *idValue) IsBoolFlag() bool { return true }
func (v *idValue) String() string { return strconv.FormatBool(Enabled(v.X)) }
func (v *idValue) Set(raw string) error {
b, err := strconv.ParseBool(raw)
if err == nil {
SetEnabled(v.X, b)
}
return err
}
|
