Documentation
¶
Overview ¶
Package wait provides reusable polling infrastructure shared by the `--wait` flag (block until a resource reaches a target state) and the `events list --follow` stream. It owns three concerns: a context-aware polling loop with bounded backoff, the `--wait`/`--timeout` flag pair, and a signal-derived context so Ctrl+C exits cleanly (no traceback).
Index ¶
- Variables
- func AddFlags(cmd *cobra.Command)
- func ForKubernetesClusterPhase(ctx context.Context, client *sdk.Latitudesh, clusterID string, ...) (components.KubernetesClusterDataPhase, error)
- func ForServerState(ctx context.Context, client *sdk.Latitudesh, serverID string, ...) (components.ServerDataStatus, error)
- func ForVirtualMachineState(ctx context.Context, client *sdk.Latitudesh, vmID string, ...) (components.VirtualMachineAttributesStatus, error)
- func Poll(ctx context.Context, b Backoff, ...) error
- func SignalContext(parent context.Context) (context.Context, context.CancelFunc)
- type Backoff
- type Options
Constants ¶
This section is empty.
Variables ¶
var ( ErrTimeout = errors.New("timed out waiting for the resource to reach its target state") ErrCanceled = errors.New("wait canceled") )
Sentinel errors returned by Poll and its callers. Commands map ErrTimeout to a non-zero exit code; ErrCanceled is the clean Ctrl+C path.
var ErrClusterFailed = errors.New("kubernetes cluster entered a failed phase")
ErrClusterFailed is returned when a cluster enters its Failed phase instead of reaching a target phase.
var ErrFailedState = errors.New("server entered a failed state")
ErrFailedState is returned when a server reaches a state the caller declared as terminal-failure (e.g. failed_deployment) instead of its target state.
Functions ¶
func ForKubernetesClusterPhase ¶ added in v1.7.0
func ForKubernetesClusterPhase( ctx context.Context, client *sdk.Latitudesh, clusterID string, want, fail []components.KubernetesClusterDataPhase, o Options, opts ...operations.Option, ) (components.KubernetesClusterDataPhase, error)
ForKubernetesClusterPhase polls GET /kubernetes_clusters/{id} until the cluster's phase is one of want (success), one of fail (ErrClusterFailed), o.Timeout elapses (ErrTimeout), or the user cancels (ErrCanceled). It returns the last phase observed.
Transient API errors are swallowed and retried until the timeout, at which point the last error is attached to ErrTimeout so the failure is diagnosable.
func ForServerState ¶
func ForServerState( ctx context.Context, client *sdk.Latitudesh, serverID string, want, fail []components.ServerDataStatus, requireTransition bool, o Options, onStatus func(components.ServerDataStatus), opts ...operations.Option, ) (components.ServerDataStatus, error)
ForServerState polls GET /servers/{id} until the server's status is one of want (success), one of fail (returns ErrFailedState), o.Timeout elapses (ErrTimeout), or the user cancels (ErrCanceled). It returns the last status observed and invokes onStatus (when non-nil) on every successful poll.
When requireTransition is true, a terminal state is only accepted after the server has first been observed in some other (transition) state. This guards operations that act on a server already sitting in a target state — e.g. a reinstall on a powered-on server, or a create whose POST response optimistically reports "on" — from returning before the operation has actually begun.
Transient errors from the API (the platform occasionally 5xxs mid-provision) are not fatal: they are swallowed and retried until the timeout, at which point the last error is attached to ErrTimeout so the failure is diagnosable.
func ForVirtualMachineState ¶ added in v1.7.0
func ForVirtualMachineState( ctx context.Context, client *sdk.Latitudesh, vmID string, want []components.VirtualMachineAttributesStatus, o Options, opts ...operations.Option, ) (components.VirtualMachineAttributesStatus, error)
ForVirtualMachineState polls GET /virtual_machines/{id} until the VM's status is one of want (success), o.Timeout elapses (ErrTimeout), or the user cancels (ErrCanceled). It returns the last status observed.
The virtual machine schema does not expose a distinct failure status, so there is no fail set: a stuck provision surfaces as an ErrTimeout instead. Transient API errors are swallowed and retried until the timeout, at which point the last error is attached to ErrTimeout so the failure is diagnosable.
func Poll ¶
Poll calls probe immediately, then repeatedly with a backoff delay between attempts, until probe reports done, probe returns an error, or ctx is cancelled/expired. A (false, nil) result means "not there yet — keep waiting". Context cancellation is normalized to ErrCanceled/ErrTimeout so callers get a stable, friendly error regardless of where it was observed.
func SignalContext ¶
SignalContext derives a context that is cancelled on SIGINT (Ctrl+C) or SIGTERM, so long-running waits and the --follow stream stop cleanly. The returned cancel func must be called to release the signal handler.
Types ¶
type Backoff ¶
Backoff controls the delay between polls. The delay grows geometrically from Initial by Factor, capped at Max, and is never shorter than pollFloor.
func DefaultBackoff ¶
func DefaultBackoff() Backoff
DefaultBackoff is tuned for resource-state waiters: a quick first re-check that eases off so a long provision doesn't hammer the API.
Source Files