feat(core): add new waiter helper function (#5939)

relates to STACKITSDK-366

Author: marceljk

CHANGELOG.md

@@ -1,7 +1,9 @@
 ## Release (2026-DD-MM)
-
-- `core`: [v0.22.0](core/CHANGELOG.md#v0220) 
-  - **Feature:** Support Azure DevOps OIDC adapter
+- `core`:
+  - [v0.23.0](core/CHANGELOG.md#v0230)
+    - **New:** Add new `WaiterHelper` struct, which creates an `AsyncActionCheck` function based on the configuration
+  - [v0.22.0](core/CHANGELOG.md#v0220) 
+    - **Feature:** Support Azure DevOps OIDC adapter
 - `alb`: 
   - [v0.10.0](services/alb/CHANGELOG.md#v0100)
     - **Feature:** Add new field `AltPort` to `ActiveHealthCheck`

CONTRIBUTION.md

@@ -70,67 +70,58 @@ type APIClientInterface interface {
 }
 
 // CreateBarWaitHandler will wait for Bar creation
-func CreateBarWaitHandler(ctx context.Context, a APIClientInterface, BarId, projectId string) *wait.AsyncActionHandler[foo.GetBarResponse] {
-	handler := wait.New(func() (waitFinished bool, response *foo.GetBarResponse, err error) {
-		s, err := a.GetBarExecute(ctx, BarId, projectId)
-		if err != nil {
-			return false, nil, err
-		}
-		if s.Id == nil || s.Status == nil {
-			return false, nil, fmt.Errorf("could not get Bar id or status from response for project %s and Bar %s", projectId, BarId)
-		}
-		if *s.Id == BarId && *s.Status == CreateSuccess {
-			return true, s, nil
-		}
-		if *s.Id == BarId && *s.Status == CreateFail {
-			return true, s, fmt.Errorf("create failed for Bar with id %s", BarId)
-		}
-		return false, nil, nil
-	})
+func CreateBarWaitHandler(ctx context.Context, a APIClientInterface, projectId, barId string) *wait.AsyncActionHandler[foo.GetBarResponse] {
+    waitConfig := wait.WaiterHelper[foo.GetBarResponse, string]{
+      FetchInstance: a.GetBar(ctx, projectId, barId).Execute,
+      GetState: func(d *foo.GetBarResponse) (string, error) {
+        if d == nil {
+          return "", errors.New("could not get bar status from response")
+        }
+        return d.Status, nil
+      },
+      ActiveState: []string{CreateSuccess},
+      ErrorState:  []string{CreateFail},
+    }
+
+    handler := wait.New(waitConfig.Wait())
 	handler.SetTimeout(45 * time.Minute)
 	return handler
 }
 
 // UpdateBarWaitHandler will wait for Bar update
 func UpdateBarWaitHandler(ctx context.Context, a APIClientInterface, BarId, projectId string) *wait.AsyncActionHandler[foo.GetBarResponse] {
-	handler := wait.New(func() (waitFinished bool, response *foo.GetBarResponse, err error) {
-		s, err := a.GetBarExecute(ctx, BarId, projectId)
-		if err != nil {
-			return false, nil, err
-		}
-		if s.Id == nil || s.Status == nil {
-			return false, nil, fmt.Errorf("could not get Bar id or status from response for project %s and Bar %s", projectId, BarId)
-		}
-		if *s.Id == BarId && (*s.Status == UpdateSuccess) {
-			return true, s, nil
-		}
-		if *s.Id == BarId && (*s.Status == UpdateFail) {
-			return true, s, fmt.Errorf("update failed for Bar with id %s", BarId)
-		}
-		return false, nil, nil
-	})
+    waitConfig := wait.WaiterHelper[foo.GetBarResponse, string]{
+      FetchInstance: a.GetBar(ctx, projectId, barId).Execute,
+      GetState: func(d *foo.GetBarResponse) (string, error) {
+        if d == nil {
+          return "", errors.New("could not get bar status from response")
+        }
+        return d.Status, nil
+      },
+      ActiveState: []string{UpdateSuccess},
+      ErrorState:  []string{UpdateFail},
+    }
+
+    handler := wait.New(waitConfig.Wait())
 	handler.SetTimeout(30 * time.Minute)
 	return handler
 }
 
 // DeleteBarWaitHandler will wait for Bar deletion
 func DeleteBarWaitHandler(ctx context.Context, a APIClientInterface, BarId, projectId string) *wait.AsyncActionHandler[foo.GetBarResponse] {
-	handler := wait.New(func() (waitFinished bool, response *foo.GetBarResponse, err error) {
-		s, err := a.GetBarExecute(ctx, BarId, projectId)
-		if err != nil {
-			return false, nil, err
-		}
-		if s.Id == nil || s.Status == nil {
-			return false, nil, fmt.Errorf("could not get Bar id or status from response for project %s and Bar %s", projectId, BarId)
-		}
-		if *s.Id == BarId && *s.Status == DeleteSuccess {
-			return true, s, nil
-		}
-		if *s.Id == BarId && *s.Status == DeleteFail {
-			return true, s, fmt.Errorf("delete failed for Bar with id %s", BarId)
-		}
-		return false, nil, nil
-	})
+    waitConfig := wait.WaiterHelper[foo.GetBarResponse, string]{
+      FetchInstance: a.GetBar(ctx, projectId, barId).Execute,
+      GetState: func(d *foo.GetBarResponse) (string, error) {
+        if d == nil {
+          return "", errors.New("could not get bar status from response")
+        }
+        return d.Status, nil
+      },
+      ActiveState: []string{DeleteSuccess},
+      ErrorState:  []string{DeleteFail},
+    }
+
+    handler := wait.New(waitConfig.Wait())
 	handler.SetTimeout(20 * time.Minute)
 	return handler
 }
@@ -141,26 +132,29 @@ func DeleteBarWaitHandler(ctx context.Context, a APIClientInterface, BarId, proj
 - The success condition may vary from service to service. In the example above we wait for the field `Status` to match a successful or failed message, but other services may have different fields and/or values to represent the state of the create, update or delete operations
 - The `id` and the `state` might not be present on the root level of the API response, this also varies from service to service. You must always match the resource `id` and the resource `state` to what is expected
 - The timeout values included above are just for reference, each resource takes different amounts of time to finish the create, update or delete operations. You should account for some buffer, e.g. 15 minutes, on top of normal execution times
-- For some resources, after a successful delete operation the resource can't be found anymore, so a call to the `Get` method would result in an error. In those cases, the waiter can be implemented by calling the `List` method and check that the resource is not present, like in this example:
+- For some resources, after a successful delete operation the resource can't be found anymore, so a call to the `Get` method would result in an error. In those cases, the WaiterHelper should have no ActiveStates configured, like in this example:
 
   ```go
   // DeleteBarWaitHandler will wait for Bar deletion
   func DeleteBarWaitHandler(ctx context.Context, a APIClientInterface, barId, projectId string) *wait.AsyncActionHandler[foo.ListBarsResponse] {
-      handler := wait.New(func() (waitFinished bool, response *foo.ListBarsResponse, err error) {
-          s, err := a.ListBarsExecute(ctx, barId, projectId)
-          if err != nil {
-              return false, nil, err
+	  waitConfig := wait.WaiterHelper[foo.GetBarResponse, string]{
+        FetchInstance: a.GetBar(ctx, projectId, barId).Execute,
+        GetState: func(d *foo.GetBarResponse) (string, error) {
+          if d == nil {
+            return "", errors.New("could not get bar status from response")
           }
-          for i := range s {
-              if *s[i].Id == barId {
-                  return false, nil, nil
-              }
-          }
-          return true, s, nil
-      })
+          return d.Status, nil
+        },
+        ActiveState: nil,
+        ErrorState:  []string{DeleteFail},
+		DeleteHttpErrorStatusCodes: []int{http.StatusNotFound},
+	  }
+  
+      handler := wait.New(waitConfig.Wait())
       handler.SetTimeout(10 * time.Minute)
       return handler
   }
+
   ```
 
 - The main objective of the waiter functions is to make sure that the operation was successful, which means any other special cases such as intermediate error states should also be handled

core/CHANGELOG.md

@@ -1,3 +1,6 @@
+## v0.23.0
+- **New:** Add new `WaiterHelper` struct, which creates an `AsyncActionCheck` function based on the configuration 
+
 ## v0.22.0
 - **Feature:** Support Azure DevOps OIDC adapter
 

core/VERSION

@@ -1 +1 @@
-v0.22.0
+v0.23.0

core/wait/wait.go

@@ -74,7 +74,14 @@ func (h *AsyncActionHandler[T]) WaitWithContext(ctx context.Context) (res *T, er
 	defer cancel()
 
 	// Wait some seconds for the API to process the request
-	time.Sleep(h.sleepBeforeWait)
+	if h.sleepBeforeWait > 0 {
+		select {
+		case <-ctx.Done():
+			return nil, fmt.Errorf("context canceled during initial sleep: %w", ctx.Err())
+		case <-time.After(h.sleepBeforeWait):
+			// continue within the WaitForContext() function
+		}
+	}
 
 	ticker := time.NewTicker(h.throttle)
 	defer ticker.Stop()

core/wait/wait_test.go

@@ -270,7 +270,7 @@ func TestWaitWithContext(t *testing.T) {
 			handlerTimeout:                 100 * time.Millisecond,
 			handlerTempErrRetryLimit:       0,
 			contextTimeout:                 1000 * time.Millisecond,
-			wantCheckFnNumberCalls:         1,
+			wantCheckFnNumberCalls:         0,
 			wantErr:                        true,
 		},
 		{
@@ -283,7 +283,7 @@ func TestWaitWithContext(t *testing.T) {
 			handlerTimeout:                 1000 * time.Millisecond,
 			handlerTempErrRetryLimit:       0,
 			contextTimeout:                 100 * time.Millisecond,
-			wantCheckFnNumberCalls:         1,
+			wantCheckFnNumberCalls:         0,
 			wantErr:                        true,
 		},
 		{

core/wait/waiterhelper.go

@@ -0,0 +1,68 @@
+package wait
+
+import (
+	"errors"
+	"fmt"
+	"net/http"
+	"slices"
+
+	"github.com/stackitcloud/stackit-sdk-go/core/oapierror"
+)
+
+// WaiterHelper is a helper struct, which creates based on the configured attributes the AsyncActionCheck for wait.New
+type WaiterHelper[T any, S comparable] struct {
+	// FetchInstance is called periodically to get the latest resource data.
+	FetchInstance func() (*T, error)
+
+	// GetState extracts the status string from the API response.
+	GetState func(*T) (S, error)
+
+	// ActiveState represents the terminal "Happy Path" (e.g. ACTIVE, READY, CREATED).
+	ActiveState []S
+
+	// ErrorState represents the terminal "Error Path" (e.g. FAILED, ERROR).
+	ErrorState []S
+
+	// DeleteHttpErrorStatusCodes defines codes treated as a successful deletion (default: 403, 404, 410).
+	DeleteHttpErrorStatusCodes []int
+}
+
+var defaultHttpErrorStatusCodes = []int{http.StatusForbidden, http.StatusNotFound, http.StatusGone}
+
+func (w *WaiterHelper[T, S]) Wait() AsyncActionCheck[T] {
+	if len(w.DeleteHttpErrorStatusCodes) == 0 {
+		w.DeleteHttpErrorStatusCodes = append(w.DeleteHttpErrorStatusCodes, defaultHttpErrorStatusCodes...)
+	}
+
+	return func() (waitFinished bool, response *T, err error) {
+		instance, err := w.FetchInstance()
+		if err != nil {
+			var oapiErr *oapierror.GenericOpenAPIError
+			if errors.As(err, &oapiErr) {
+				// If no active states are defined and one of the "Delete HTTP Status codes" is returned, finish wait without an error
+				if len(w.ActiveState) == 0 && slices.Contains(w.DeleteHttpErrorStatusCodes, oapiErr.StatusCode) {
+					return true, nil, nil
+				}
+			}
+			return true, nil, err
+		}
+
+		state, err := w.GetState(instance)
+		if err != nil {
+			return true, nil, err
+		}
+
+		// 1. Check if the operation succeeded
+		if slices.Contains(w.ActiveState, state) {
+			return true, instance, nil
+		}
+
+		// 2. Check if the operation failed
+		if slices.Contains(w.ErrorState, state) {
+			return true, instance, fmt.Errorf("waiting failed. state is %v", state)
+		}
+
+		// 3. Default: Operation is pending
+		return false, nil, nil
+	}
+}