8 var refreshGracePeriod = 30 * time.Second
10 // StateRefreshFunc is a function type used for StateChangeConf that is
11 // responsible for refreshing the item being watched for a state change.
13 // It returns three results. `result` is any object that will be returned
14 // as the final object after waiting for state change. This allows you to
15 // return the final updated object, for example an EC2 instance after refreshing
18 // `state` is the latest state of that object. And `err` is any error that
19 // may have happened while refreshing the state.
20 type StateRefreshFunc func() (result interface{}, state string, err error)
22 // StateChangeConf is the configuration struct used for `WaitForState`.
23 type StateChangeConf struct {
24 Delay time.Duration // Wait this time before starting checks
25 Pending []string // States that are "allowed" and will continue trying
26 Refresh StateRefreshFunc // Refreshes the current state
27 Target []string // Target state
28 Timeout time.Duration // The amount of time to wait before timeout
29 MinTimeout time.Duration // Smallest time to wait before refreshes
30 PollInterval time.Duration // Override MinTimeout/backoff and only poll this often
31 NotFoundChecks int // Number of times to allow not found
33 // This is to work around inconsistent APIs
34 ContinuousTargetOccurence int // Number of times the Target state has to occur continuously
37 // WaitForState watches an object and waits for it to achieve the state
38 // specified in the configuration using the specified Refresh() func,
39 // waiting the number of seconds specified in the timeout configuration.
41 // If the Refresh function returns an error, exit immediately with that error.
43 // If the Refresh function returns a state other than the Target state or one
44 // listed in Pending, return immediately with an error.
46 // If the Timeout is exceeded before reaching the Target state, return an
49 // Otherwise, the result is the result of the first call to the Refresh function to
50 // reach the target state.
51 func (conf *StateChangeConf) WaitForState() (interface{}, error) {
52 log.Printf("[DEBUG] Waiting for state to become: %s", conf.Target)
57 // Set a default for times to check for not found
58 if conf.NotFoundChecks == 0 {
59 conf.NotFoundChecks = 20
62 if conf.ContinuousTargetOccurence == 0 {
63 conf.ContinuousTargetOccurence = 1
73 // Read every result from the refresh loop, waiting for a positive result.Done.
74 resCh := make(chan Result, 1)
75 // cancellation channel for the refresh loop
76 cancelCh := make(chan struct{})
83 time.Sleep(conf.Delay)
85 // start with 0 delay for the first loop
86 var wait time.Duration
89 // store the last result
92 // wait and watch for cancellation
96 case <-time.After(wait):
97 // first round had no wait
99 wait = 100 * time.Millisecond
103 res, currentState, err := conf.Refresh()
115 // If we're waiting for the absence of a thing, then return
116 if res == nil && len(conf.Target) == 0 {
118 if conf.ContinuousTargetOccurence == targetOccurence {
127 // If we didn't find the resource, check if we have been
128 // not finding it for awhile, and if so, report an error.
130 if notfoundTick > conf.NotFoundChecks {
131 result.Error = &NotFoundError{
133 Retries: notfoundTick,
139 // Reset the counter for when a resource isn't found
143 for _, allowed := range conf.Target {
144 if currentState == allowed {
147 if conf.ContinuousTargetOccurence == targetOccurence {
156 for _, allowed := range conf.Pending {
157 if currentState == allowed {
164 if !found && len(conf.Pending) > 0 {
165 result.Error = &UnexpectedStateError{
168 ExpectedState: conf.Target,
175 // Wait between refreshes using exponential backoff, except when
176 // waiting for the target state to reoccur.
177 if targetOccurence == 0 {
181 // If a poll interval has been specified, choose that interval.
182 // Otherwise bound the default value.
183 if conf.PollInterval > 0 && conf.PollInterval < 180*time.Second {
184 wait = conf.PollInterval
186 if wait < conf.MinTimeout {
187 wait = conf.MinTimeout
188 } else if wait > 10*time.Second {
189 wait = 10 * time.Second
193 log.Printf("[TRACE] Waiting %s before next try", wait)
197 // store the last value result from the refresh loop
198 lastResult := Result{}
200 timeout := time.After(conf.Timeout)
203 case r, ok := <-resCh:
204 // channel closed, so return the last result
206 return lastResult.Result, lastResult.Error
209 // we reached the intended state
211 return r.Result, r.Error
214 // still waiting, store the last result
218 log.Printf("[WARN] WaitForState timeout after %s", conf.Timeout)
219 log.Printf("[WARN] WaitForState starting %s refresh grace period", refreshGracePeriod)
221 // cancel the goroutine and start our grace period timer
223 timeout := time.After(refreshGracePeriod)
225 // we need a for loop and a label to break on, because we may have
226 // an extra response value to read, but still want to wait for the
231 case r, ok := <-resCh:
233 // the last refresh loop reached the desired state
234 return r.Result, r.Error
238 // the goroutine returned
242 // target state not reached, save the result for the
243 // TimeoutError and wait for the channel to close
246 log.Println("[ERROR] WaitForState exceeded refresh grace period")
251 return nil, &TimeoutError{
252 LastError: lastResult.Error,
253 LastState: lastResult.State,
254 Timeout: conf.Timeout,
255 ExpectedState: conf.Target,