Documentation
¶
Index ¶
- Constants
- type ExponentialBackoffStrategy
- type FixedIntervalStrategy
- type LinearBackoffStrategy
- type OperationWaiter
- func (w *OperationWaiter) Wait(ctx context.Context, client *nirvana.Client, operationID string) error
- func (w *OperationWaiter) WithExponentialBackoff(baseInterval time.Duration, multiplier float64, maxInterval time.Duration) *OperationWaiter
- func (w *OperationWaiter) WithLinearBackoff(baseInterval, increment, maxInterval time.Duration) *OperationWaiter
- func (w *OperationWaiter) WithPollInterval(interval time.Duration) *OperationWaiter
- func (w *OperationWaiter) WithStrategy(strategy WaitStrategy) *OperationWaiter
- func (w *OperationWaiter) WithTimeout(timeout time.Duration) *OperationWaiter
- type WaitStrategy
Constants ¶
const ( // DefaultTimeout is the default maximum time to wait for an operation to complete. // Used by NewOperationWaiter() when no custom timeout is specified. DefaultTimeout = 10 * time.Minute // DefaultPollInterval is the default interval between operation status checks. // Used by NewOperationWaiter() when no custom polling strategy is specified. DefaultPollInterval = 1 * time.Second )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ExponentialBackoffStrategy ¶ added in v1.11.1
type ExponentialBackoffStrategy struct {
// contains filtered or unexported fields
}
ExponentialBackoffStrategy implements WaitStrategy with exponentially increasing intervals. Each successive poll waits exponentially longer, which is ideal for operations that might take a long time and where you want to quickly back off to avoid overwhelming the service while still eventually checking for completion.
Formula: interval = baseInterval * multiplier * attempt, capped at maxInterval
func NewExponentialBackoffStrategy ¶ added in v1.11.1
func NewExponentialBackoffStrategy(baseInterval time.Duration, multiplier float64, maxInterval time.Duration) *ExponentialBackoffStrategy
NewExponentialBackoffStrategy creates a strategy with exponential backoff. The baseInterval is used in calculations, multiplier determines growth rate, and maxInterval caps the maximum wait time.
Example - start calculations with 100ms base, 2x multiplier, max 30s:
strategy := NewExponentialBackoffStrategy(100*time.Millisecond, 2.0, 30*time.Second) // Attempt 0: 0ms, Attempt 1: 200ms, Attempt 2: 400ms, Attempt 3: 600ms, etc.
func (*ExponentialBackoffStrategy) NextInterval ¶ added in v1.11.1
func (s *ExponentialBackoffStrategy) NextInterval(attempt int) time.Duration
NextInterval calculates the next polling interval using exponential backoff. Returns baseInterval * multiplier * attempt, capped at maxInterval. This implements the WaitStrategy interface.
func (*ExponentialBackoffStrategy) Reset ¶ added in v1.11.1
func (s *ExponentialBackoffStrategy) Reset()
Reset is a no-op for exponential backoff strategy as there's no state to reset. This implements the WaitStrategy interface.
type FixedIntervalStrategy ¶ added in v1.11.1
type FixedIntervalStrategy struct {
// contains filtered or unexported fields
}
FixedIntervalStrategy implements WaitStrategy with constant polling intervals. This is the simplest strategy that polls at regular, unchanging intervals. It's ideal when you want consistent polling frequency regardless of how long the operation has been running.
func NewFixedIntervalStrategy ¶ added in v1.11.1
func NewFixedIntervalStrategy(interval time.Duration) *FixedIntervalStrategy
NewFixedIntervalStrategy creates a strategy that polls at fixed intervals. The interval parameter determines how long to wait between each poll attempt.
Example:
strategy := NewFixedIntervalStrategy(2 * time.Second) waiter := NewOperationWaiter().WithStrategy(strategy)
func (*FixedIntervalStrategy) NextInterval ¶ added in v1.11.1
func (s *FixedIntervalStrategy) NextInterval(attempt int) time.Duration
NextInterval returns the fixed interval regardless of attempt number. This implements the WaitStrategy interface.
func (*FixedIntervalStrategy) Reset ¶ added in v1.11.1
func (s *FixedIntervalStrategy) Reset()
Reset is a no-op for fixed interval strategy as there's no state to reset. This implements the WaitStrategy interface.
type LinearBackoffStrategy ¶ added in v1.11.1
type LinearBackoffStrategy struct {
// contains filtered or unexported fields
}
LinearBackoffStrategy implements WaitStrategy with linearly increasing intervals. Each successive poll waits longer by a fixed increment, up to a maximum interval. This is useful when you want to gradually reduce polling frequency to avoid overwhelming the service while still getting reasonably quick updates initially.
Formula: interval = baseInterval + (attempt * increment), capped at maxInterval
func NewLinearBackoffStrategy ¶ added in v1.11.1
func NewLinearBackoffStrategy(baseInterval, increment, maxInterval time.Duration) *LinearBackoffStrategy
NewLinearBackoffStrategy creates a strategy with linear backoff. The baseInterval is the starting poll interval, increment is added for each subsequent attempt, and maxInterval caps the maximum wait time.
Example - start at 1s, increase by 500ms each attempt, max 5s:
strategy := NewLinearBackoffStrategy(1*time.Second, 500*time.Millisecond, 5*time.Second) // Attempt 0: 1s, Attempt 1: 1.5s, Attempt 2: 2s, ..., Attempt 8+: 5s
func (*LinearBackoffStrategy) NextInterval ¶ added in v1.11.1
func (s *LinearBackoffStrategy) NextInterval(attempt int) time.Duration
NextInterval calculates the next polling interval using linear backoff. Returns baseInterval + (attempt * increment), capped at maxInterval. This implements the WaitStrategy interface.
func (*LinearBackoffStrategy) Reset ¶ added in v1.11.1
func (s *LinearBackoffStrategy) Reset()
Reset is a no-op for linear backoff strategy as there's no state to reset. This implements the WaitStrategy interface.
type OperationWaiter ¶ added in v1.11.1
type OperationWaiter struct {
// contains filtered or unexported fields
}
OperationWaiter provides configurable waiting for operations with support for different polling strategies. It allows you to customize timeout duration and polling behavior (fixed intervals, linear backoff, exponential backoff, etc.).
Example usage:
// Default: 10-minute timeout with 1-second fixed intervals waiter := NewOperationWaiter() // Custom timeout with linear backoff waiter := NewOperationWaiter(). WithTimeout(5*time.Minute). WithLinearBackoff(1*time.Second, 500*time.Millisecond, 10*time.Second) err := waiter.Wait(ctx, client, "operation-id")
func NewOperationWaiter ¶ added in v1.11.1
func NewOperationWaiter() *OperationWaiter
NewOperationWaiter creates a new OperationWaiter with default settings. Default configuration:
- Timeout: 10 minutes (DefaultTimeout)
- Strategy: Fixed 1-second intervals (DefaultPollInterval)
The returned waiter can be customized using the With* methods before calling Wait.
Example with exponential backoff:
waiter := NewOperationWaiter(). WithTimeout(5*time.Minute). WithExponentialBackoff(100*time.Millisecond, 2.0, 30*time.Second) err := waiter.Wait(ctx, client, operationID)
func (*OperationWaiter) Wait ¶ added in v1.11.1
func (w *OperationWaiter) Wait(ctx context.Context, client *nirvana.Client, operationID string) error
Wait polls the operation status until it completes, fails, times out, or the context is cancelled. It uses the configured polling strategy to determine wait intervals between status checks.
The method will:
- Poll the operation status at intervals determined by the WaitStrategy
- Return nil when the operation status becomes 'done'
- Return an error if the operation fails, times out, or context is cancelled
- Return an error if any API call fails
Parameters:
- ctx: Context for cancellation and deadlines
- client: Nirvana client for API calls
- operationID: ID of the operation to wait for
Returns an error if the operation fails, times out, is cancelled, or if API calls fail.
func (*OperationWaiter) WithExponentialBackoff ¶ added in v1.11.1
func (w *OperationWaiter) WithExponentialBackoff(baseInterval time.Duration, multiplier float64, maxInterval time.Duration) *OperationWaiter
WithExponentialBackoff sets an exponential backoff strategy where polling intervals grow exponentially with each attempt. This is ideal for long-running operations where you want to quickly back off to avoid overwhelming the service.
Parameters:
- baseInterval: Base interval used in calculations
- multiplier: Growth factor for each attempt
- maxInterval: Maximum interval to prevent excessive delays
Example:
waiter := NewOperationWaiter().WithExponentialBackoff(100*time.Millisecond, 2.0, 30*time.Second) // Polls at: 0ms, 200ms, 400ms, 600ms, ..., up to 30s
func (*OperationWaiter) WithLinearBackoff ¶ added in v1.11.1
func (w *OperationWaiter) WithLinearBackoff(baseInterval, increment, maxInterval time.Duration) *OperationWaiter
WithLinearBackoff sets a linear backoff strategy where polling intervals increase linearly with each attempt. This is useful when you want to gradually reduce polling frequency while still getting reasonably quick updates.
Parameters:
- baseInterval: Starting polling interval
- increment: Amount to increase each attempt
- maxInterval: Maximum interval to prevent infinite growth
Example:
waiter := NewOperationWaiter().WithLinearBackoff(1*time.Second, 500*time.Millisecond, 10*time.Second) // Polls at: 1s, 1.5s, 2s, 2.5s, ..., up to 10s
func (*OperationWaiter) WithPollInterval ¶ added in v1.11.1
func (w *OperationWaiter) WithPollInterval(interval time.Duration) *OperationWaiter
WithPollInterval sets the polling interval using a fixed interval strategy. This is a convenience method that replaces the current strategy with a fixed interval. For more advanced polling strategies, use WithStrategy, WithLinearBackoff, or WithExponentialBackoff.
Example:
waiter := NewOperationWaiter().WithPollInterval(2 * time.Second)
func (*OperationWaiter) WithStrategy ¶ added in v1.11.1
func (w *OperationWaiter) WithStrategy(strategy WaitStrategy) *OperationWaiter
WithStrategy sets a custom wait strategy that implements the WaitStrategy interface. This allows you to provide your own polling logic or use pre-built strategies.
Example:
customStrategy := NewLinearBackoffStrategy(500*time.Millisecond, 100*time.Millisecond, 5*time.Second) waiter := NewOperationWaiter().WithStrategy(customStrategy)
func (*OperationWaiter) WithTimeout ¶ added in v1.11.1
func (w *OperationWaiter) WithTimeout(timeout time.Duration) *OperationWaiter
WithTimeout sets the maximum duration to wait for operation completion. If the operation doesn't complete within this timeout, Wait() will return a timeout error.
Example:
waiter := NewOperationWaiter().WithTimeout(5 * time.Minute)
type WaitStrategy ¶ added in v1.11.1
type WaitStrategy interface {
// NextInterval returns the next polling interval given the current attempt number (0-based).
// The attempt parameter starts at 0 for the first retry after the initial poll.
NextInterval(attempt int) time.Duration
// Reset is called when starting a new wait operation to allow strategies
// to reset any internal state if needed.
Reset()
}
WaitStrategy defines how polling intervals are calculated for operation waiting. This interface allows for different backoff strategies like fixed intervals, linear backoff, exponential backoff, or custom implementations.
Example usage:
strategy := NewLinearBackoffStrategy(1*time.Second, 500*time.Millisecond, 5*time.Second) waiter := NewOperationWaiter().WithStrategy(strategy)
Source Files