v3: Client introduce a wait timeout with different polling strategy (#…

…674)

Signed-off-by: Pierre-Emmanuel Jacquier <[email protected]>

CHANGELOG.md

@@ -3,6 +3,7 @@ Changelog
 
 Unrelease
 ----------
+- v3: Client introduce a wait timeout with different polling strategy #674
 - v3 generator: Findable return error on too many found #669
 
 3.1.7

v3/api.go

@@ -10,6 +10,7 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"math"
 	"net/http"
 	"net/http/httputil"
 	"os"
@@ -40,26 +41,46 @@ func ParseUUID(s string) (UUID, error) {
 // Final states are one of: failure, success, timeout.
 // If states argument are given, returns an error if the final state not match on of those.
 func (c Client) Wait(ctx context.Context, op *Operation, states ...OperationState) (*Operation, error) {
+	const abortErrorsCount = 5
+
 	if op == nil {
 		return nil, fmt.Errorf("operation is nil")
 	}
 
-	ticker := time.NewTicker(c.pollingInterval)
+	startTime := time.Now()
+
+	ticker := time.NewTicker(pollInterval(0))
 	defer ticker.Stop()
 
 	if op.State != OperationStatePending {
 		return op, nil
 	}
 
+	var subsequentErrors int
 	var operation *Operation
 polling:
 	for {
 		select {
 		case <-ticker.C:
+			runTime := time.Since(startTime)
+
+			if c.waitTimeout != 0 && runTime > c.waitTimeout {
+				return nil, fmt.Errorf("operation: %q: max wait timeout reached", op.ID)
+			}
+
+			newInterval := pollInterval(runTime)
+			ticker.Reset(newInterval)
+
 			o, err := c.GetOperation(ctx, op.ID)
 			if err != nil {
-				return nil, err
+				subsequentErrors++
+				if subsequentErrors >= abortErrorsCount {
+					return nil, err
+				}
+				continue
 			}
+			subsequentErrors = 0
+
 			if o.State == OperationStatePending {
 				continue
 			}
@@ -140,6 +161,28 @@ func (c Client) Validate(s any) error {
 	return err
 }
 
+// pollInterval returns the wait interval (as a time.Duration) before the next poll, based on the current runtime of a job.
+// The polling frequency is:
+//   - every 3 seconds for the first 30 seconds
+//   - then increases linearly to reach 1 minute at 15 minutes of runtime
+//   - after 15 minutes, it stays at 1 minute intervals
+func pollInterval(runTime time.Duration) time.Duration {
+	runTimeSeconds := runTime.Seconds()
+
+	// Coefficients for the linear equation y = a * x + b
+	a := 57.0 / 870.0
+	b := 3.0 - 30.0*a
+
+	minWait := 3.0
+	maxWait := 60.0
+
+	interval := a*runTimeSeconds + b
+	interval = math.Max(minWait, interval)
+	interval = math.Min(maxWait, interval)
+
+	return time.Duration(interval) * time.Second
+}
+
 func prepareJSONBody(body any) (*bytes.Reader, error) {
 	buf, err := json.Marshal(body)
 	if err != nil {

v3/api_test.go

@@ -0,0 +1,62 @@
+package v3
+
+import (
+	"testing"
+	"time"
+)
+
+func TestPollInterval(t *testing.T) {
+	tests := []struct {
+		runTime     time.Duration
+		expectedMin time.Duration
+		expectedMax time.Duration
+		description string
+	}{
+		{
+			runTime:     10 * time.Second,
+			expectedMin: 3 * time.Second,
+			expectedMax: 3 * time.Second,
+			description: "Polling at 10 seconds should return 3 seconds",
+		},
+		{
+			runTime:     30 * time.Second,
+			expectedMin: 3 * time.Second,
+			expectedMax: 3 * time.Second,
+			description: "Polling at 30 seconds should still return 3 seconds",
+		},
+		{
+			runTime:     60 * time.Second,
+			expectedMin: 3 * time.Second,
+			expectedMax: 7 * time.Second, // Expected range after 30s should increase linearly
+			description: "Polling at 60 seconds should return a value greater than 3 seconds but less than 7 seconds",
+		},
+		{
+			runTime:     300 * time.Second,
+			expectedMin: 3 * time.Second,
+			expectedMax: 24 * time.Second, // Interval keeps increasing linearly
+			description: "Polling at 5 minutes should return a value in the correct range (up to 24 seconds)",
+		},
+		{
+			runTime:     900 * time.Second, // 15 minutes
+			expectedMin: 60 * time.Second,
+			expectedMax: 60 * time.Second,
+			description: "Polling at 15 minutes should return exactly 60 seconds",
+		},
+		{
+			runTime:     1200 * time.Second, // 20 minutes
+			expectedMin: 60 * time.Second,
+			expectedMax: 60 * time.Second,
+			description: "Polling beyond 15 minutes should cap at 60 seconds",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.description, func(t *testing.T) {
+			interval := pollInterval(test.runTime)
+			if interval < test.expectedMin || interval > test.expectedMax {
+				t.Errorf("pollInterval(%v) = %v, expected between %v and %v",
+					test.runTime, interval, test.expectedMin, test.expectedMax)
+			}
+		})
+	}
+}

v3/generator/client/client.tmpl

@@ -35,14 +35,14 @@ func (c Client) GetZoneAPIEndpoint(ctx context.Context, zoneName ZoneName) (Endp
 
 // Client represents an Exoscale API client.
 type Client struct {
-	apiKey          string
-	apiSecret       string
-	userAgent       string
-	serverEndpoint  string
-	httpClient      *http.Client
-	pollingInterval time.Duration
-	validate        *validator.Validate
-	trace           bool
+	apiKey         string
+	apiSecret      string
+	userAgent      string
+	serverEndpoint string
+	httpClient     *http.Client
+	waitTimeout    time.Duration
+	validate       *validator.Validate
+	trace          bool
 
 	// A list of callbacks for modifying requests which are generated before sending over
 	// the network.
@@ -55,8 +55,6 @@ type RequestInterceptorFn func(ctx context.Context, req *http.Request) error
 // Deprecated: use ClientOptWithUserAgent instead.
 var UserAgent = getDefaultUserAgent()
 
-const pollingInterval = 3 * time.Second
-
 // ClientOpt represents a function setting Exoscale API client option.
 type ClientOpt func(*Client) error
 
@@ -92,6 +90,14 @@ func ClientOptWithEndpoint(endpoint Endpoint) ClientOpt {
 	}
 }
 
+// ClientOptWithWaitTimeout returns a ClientOpt With a given wait timeout.
+func ClientOptWithWaitTimeout(t time.Duration) ClientOpt {
+	return func(c *Client) error {
+		c.waitTimeout = t
+		return nil
+	}
+}
+
 // ClientOptWithRequestInterceptors returns a ClientOpt With given RequestInterceptors.
 func ClientOptWithRequestInterceptors(f ...RequestInterceptorFn) ClientOpt {
 	return func(c *Client) error {
@@ -131,14 +137,13 @@ func NewClient(credentials *credentials.Credentials, opts ...ClientOpt) (*Client
 	}
 
     client := &Client{
-    	apiKey:           values.APIKey,
-    	apiSecret:        values.APISecret,
-    	serverEndpoint:   string({{ .ServerEndpoint }}),
-    	httpClient:       http.DefaultClient,
-    	pollingInterval:  pollingInterval,
-    	validate:         validator.New(),
-    	userAgent:        getDefaultUserAgent(),
-    }
+		apiKey:         values.APIKey,
+		apiSecret:      values.APISecret,
+		serverEndpoint: string(CHGva2),
+		httpClient:     http.DefaultClient,
+		validate:       validator.New(),
+		userAgent:      getDefaultUserAgent(),
+	}
 
 	for _, opt := range opts {
 		if err := opt(client); err != nil {
@@ -173,6 +178,15 @@ func (c *Client) WithEndpoint(endpoint Endpoint) *Client {
 	return clone
 }
 
+// WithWaitTimeout returns a copy of Client with new wait timeout.
+func (c *Client) WithWaitTimeout(t time.Duration) *Client {
+	clone := cloneClient(c)
+
+	clone.waitTimeout = t
+
+	return clone
+}
+
 // WithUserAgent returns a copy of Client with new User-Agent.
 func (c *Client) WithUserAgent(ua string) *Client {
 	clone := cloneClient(c)
@@ -237,7 +251,7 @@ func cloneClient(c *Client) *Client {
 		serverEndpoint:      c.serverEndpoint,
 		httpClient:          c.httpClient,
 		requestInterceptors: c.requestInterceptors,
-		pollingInterval:     c.pollingInterval,
+		waitTimeout:         c.waitTimeout,
 		trace:               c.trace,
 		validate:            c.validate,
 	}