feat: add new WithPollOpts client option (#493)

- Improve consistency with the pattern used with `WithRetryOpts`,
- Use the `PollOpts` struct, which is more future-proof than function
arguments (properties can be added without breaking),
- Update docs to use the latest `WithPollOpts` instead of the deprecated
alternative.

Since we already changed the way to configure the retry options, I think
it is a good time to also change the pattern for the poll opts, even if
this does not really bring a new feature.

Author: jooola

hcloud/action_waiter.go

@@ -16,7 +16,7 @@ type ActionWaiter interface {
 var _ ActionWaiter = (*ActionClient)(nil)
 
 // WaitForFunc waits until all actions are completed by polling the API at the interval
-// defined by [WithPollBackoffFunc]. An action is considered as complete when its status is
+// defined by [WithPollOpts]. An action is considered as complete when its status is
 // either [ActionStatusSuccess] or [ActionStatusError].
 //
 // The handleUpdate callback is called every time an action is updated.
@@ -98,7 +98,7 @@ func (c *ActionClient) WaitForFunc(ctx context.Context, handleUpdate func(update
 }
 
 // WaitFor waits until all actions succeed by polling the API at the interval defined by
-// [WithPollBackoffFunc]. An action is considered as succeeded when its status is either
+// [WithPollOpts]. An action is considered as succeeded when its status is either
 // [ActionStatusSuccess].
 //
 // If a single action fails, the function will stop waiting and the error set in the

hcloud/action_watch.go

@@ -21,7 +21,7 @@ import (
 // timeout, use the [context.Context]. Once the method has stopped watching,
 // both returned channels are closed.
 //
-// WatchOverallProgress uses the [WithPollBackoffFunc] of the [Client] to wait
+// WatchOverallProgress uses the [WithPollOpts] of the [Client] to wait
 // until sending the next request.
 //
 // Deprecated: WatchOverallProgress is deprecated, use [WaitForFunc] instead.
@@ -86,7 +86,7 @@ func (c *ActionClient) WatchOverallProgress(ctx context.Context, actions []*Acti
 // timeout, use the [context.Context]. Once the method has stopped watching,
 // both returned channels are closed.
 //
-// WatchProgress uses the [WithPollBackoffFunc] of the [Client] to wait until
+// WatchProgress uses the [WithPollOpts] of the [Client] to wait until
 // sending the next request.
 //
 // Deprecated: WatchProgress is deprecated, use [WaitForFunc] instead.

hcloud/client.go

@@ -140,22 +140,40 @@ func WithToken(token string) ClientOption {
 // polling from the API.
 //
 // Deprecated: Setting the poll interval is deprecated, you can now configure
-// [WithPollBackoffFunc] with a [ConstantBackoff] to get the same results. To
+// [WithPollOpts] with a [ConstantBackoff] to get the same results. To
 // migrate your code, replace your usage like this:
 //
 //	// before
 //	hcloud.WithPollInterval(2 * time.Second)
 //	// now
-//	hcloud.WithPollBackoffFunc(hcloud.ConstantBackoff(2 * time.Second))
+//	hcloud.WithPollOpts(hcloud.PollOpts{
+//		BackoffFunc: hcloud.ConstantBackoff(2 * time.Second),
+//	})
 func WithPollInterval(pollInterval time.Duration) ClientOption {
-	return WithPollBackoffFunc(ConstantBackoff(pollInterval))
+	return WithPollOpts(PollOpts{
+		BackoffFunc: ConstantBackoff(pollInterval),
+	})
 }
 
 // WithPollBackoffFunc configures a Client to use the specified backoff
 // function when polling from the API.
+//
+// Deprecated: WithPollBackoffFunc is deprecated, use [WithPollOpts] instead.
 func WithPollBackoffFunc(f BackoffFunc) ClientOption {
+	return WithPollOpts(PollOpts{
+		BackoffFunc: f,
+	})
+}
+
+// PollOpts defines the options used by [WithPollOpts].
+type PollOpts struct {
+	BackoffFunc BackoffFunc
+}
+
+// WithPollOpts configures a Client to use the specified options when polling from the API.
+func WithPollOpts(opts PollOpts) ClientOption {
 	return func(client *Client) {
-		client.pollBackoffFunc = f
+		client.pollBackoffFunc = opts.BackoffFunc
 	}
 }
 

hcloud/client_test.go

@@ -42,10 +42,12 @@ func newTestEnvWithServer(server *httptest.Server, mux *http.ServeMux) testEnv {
 		WithEndpoint(server.URL),
 		WithToken("token"),
 		WithRetryOpts(RetryOpts{
-			BackoffFunc: func(_ int) time.Duration { return 0 },
+			BackoffFunc: ConstantBackoff(0),
 			MaxRetries:  5,
 		}),
-		WithPollBackoffFunc(func(r int) time.Duration { return 0 }),
+		WithPollOpts(PollOpts{
+			BackoffFunc: ConstantBackoff(0),
+		}),
 	)
 	return testEnv{
 		Server: server,