feat(ctrl): encapsulates finalizer logic in reusable pkg (openshift-service-mesh#164)

We are going to leverage finalizers to ensure we properly release
any resources owned by our controllers. That includes resources we
cannot garbage collect using `ownerRef` but also things like gRPC
connections we are going to establish between meshes.

Providing consistent approach to deal with this scenario helps us write
cleaner and
maintainable code.

This change brings `finalizer` package to address this.

It has `finalizer.Handler` struct that:
- adds finalizer to a given object if it does not exists and then
persist it
- performs cleanup defined as `CleanupFn` if the object is marked for
deletion

Example usage in the controller reconcile loop:

```golang
finalizerHandler := finalizer.NewHandler(r.Client, "federation.openshift-service-mesh.io/mesh-federation")
if finalized, errFinalize := finalizerHandler.Finalize(ctx, meshFederation, func() error {
	// finalizer logic goes here
	return nil
}); finalized {
	return ctrl.Result{}, errFinalize
}

if finalizerAlreadyExists, errAdd := finalizerHandler.Add(ctx, meshFederation); !finalizerAlreadyExists {
	return ctrl.Result{}, errAdd
}
```

It seems to make sense to trigger another reconcile immediately after
adding finalizer, to ensure that the object the controller reconciles
gets it
as soon as possible.

### Additional changes

Together with `finalizer` a set of common `retry` functions has been
added, so that `finalizer.Handler` can retry updating the object when
the conflict occurs.

Signed-off-by: bartoszmajsak <[email protected]>

---------

Signed-off-by: bartoszmajsak <[email protected]>
Co-authored-by: Eoin Fennessy <[email protected]>

Author: bartoszmajsak

internal/controller/finalizer/types.go

@@ -0,0 +1,91 @@
+// Copyright Red Hat, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the License);
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an AS IS BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package finalizer
+
+import (
+	"context"
+
+	"sigs.k8s.io/controller-runtime/pkg/client"
+	"sigs.k8s.io/controller-runtime/pkg/controller/controllerutil"
+
+	"github.com/openshift-service-mesh/federation/internal/controller"
+)
+
+// CleanupFn is a closure which can be used in the reconciler to define finalizer logic just before
+// the object is removed from kube-apiserver.
+type CleanupFn func() error
+
+// Handler encapsulates finalizer handling. It can:
+// - add finalizer to a given object and persist it
+// - perform cleanup defined as CleanupFn if the object is marked for deletion
+//
+// Example usage in the controller reconcile loop:
+//
+//	finalizerHandler := finalizer.NewHandler(r.Client, "federation.openshift-service-mesh.io/mesh-federation")
+//	if finalized, errFinalize := finalizerHandler.Finalize(ctx, meshFederation, func() error {
+//		// finalizer logic
+//		return nil
+//	}); finalized {
+//		return ctrl.Result{}, errFinalize
+//	}
+//
+//	if finalizerAlreadyExists, errAdd := finalizerHandler.Add(ctx, meshFederation); !finalizerAlreadyExists {
+//		return ctrl.Result{}, errAdd
+//	}
+type Handler struct {
+	cl            client.Client
+	finalizerName string
+}
+
+func NewHandler(cl client.Client, finalizerName string) *Handler {
+	return &Handler{
+		cl:            cl,
+		finalizerName: finalizerName,
+	}
+}
+
+// Add adds the defined finalizer to the object and then persists it if the finalizer was not already present.
+// Returns true if the finalizer was already present.
+// Returns an error if updating the object failed.
+func (f *Handler) Add(ctx context.Context, obj client.Object) (bool, error) {
+	if finalizersUpdated := controllerutil.AddFinalizer(obj, f.finalizerName); !finalizersUpdated {
+		return true, nil // Finalizer already exists, no need to add it
+	}
+
+	_, errRetry := controller.RetryUpdate(ctx, f.cl, obj, func(saved client.Object) {
+		controllerutil.AddFinalizer(saved, f.finalizerName) // in case of conflict retry adding finalizer on the obj fetched from cluster
+	})
+
+	return false, errRetry
+}
+
+// Finalize executes cleanup logic defined in cleanupFn only if the object is marked for deletion.
+// Returns true if finalizer logic was attempted.
+// Returns an error if the cleanup function was unsuccessful or the removal of the finalizer failed.
+func (f *Handler) Finalize(ctx context.Context, obj client.Object, cleanupFn CleanupFn) (bool, error) {
+	if finalizeNeeded := !obj.GetDeletionTimestamp().IsZero() && controllerutil.ContainsFinalizer(obj, f.finalizerName); !finalizeNeeded {
+		return false, nil
+	}
+
+	if err := cleanupFn(); err != nil {
+		return true, err
+	}
+
+	_, errRetry := controller.RetryUpdate(ctx, f.cl, obj, func(saved client.Object) {
+		controllerutil.RemoveFinalizer(saved, f.finalizerName) // in case of conflict retry removing finalizer on the obj fetched from cluster
+	})
+
+	return true, errRetry
+}

internal/controller/retry.go

@@ -0,0 +1,75 @@
+// Copyright Red Hat, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the License);
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an AS IS BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package controller
+
+import (
+	"context"
+	"errors"
+
+	"k8s.io/client-go/util/retry"
+	"sigs.k8s.io/controller-runtime/pkg/client"
+)
+
+// MutateFn is a function that allows defining custom
+// logic for updating resource object.
+type MutateFn[T client.Object] func(saved T)
+
+// ClientCallFn defines what client.Client operation on a given object should be performed.
+type ClientCallFn[T client.Object] func(ctx context.Context, cli client.Client, obj T) error
+
+// RetryUpdate attempts to update a specified Kubernetes resource and retries on conflict.
+func RetryUpdate[T client.Object](ctx context.Context, cli client.Client, original T, mutate MutateFn[T], opts ...client.UpdateOption) (T, error) {
+	updateObjFn := func(ctx context.Context, cli client.Client, obj T) error {
+		return cli.Update(ctx, obj, opts...)
+	}
+
+	return retryCall[T](ctx, cli, original, mutate, updateObjFn)
+}
+
+// RetryStatusUpdate attempts to update status subresource of a specified Kubernetes resource and retries on conflict.
+func RetryStatusUpdate[T client.Object](ctx context.Context, cli client.Client, original T, mutate MutateFn[T], opts ...client.SubResourceUpdateOption) (T, error) {
+	updateStatusFn := func(ctx context.Context, cli client.Client, obj T) error {
+		return cli.Status().Update(ctx, obj, opts...)
+	}
+
+	return retryCall[T](ctx, cli, original, mutate, updateStatusFn)
+}
+
+func retryCall[T client.Object](
+	ctx context.Context,
+	cli client.Client,
+	original T,
+	mutate MutateFn[T],
+	updateFn ClientCallFn[T],
+) (T, error) {
+
+	current, ok := original.DeepCopyObject().(T)
+	if !ok {
+		var zero T
+		return zero, errors.New("failed to deep copy object")
+	}
+
+	err := retry.RetryOnConflict(retry.DefaultBackoff, func() error {
+		if err := cli.Get(ctx, client.ObjectKeyFromObject(original), current); err != nil {
+			return err
+		}
+		mutate(current)
+
+		// Return the mutate error directly so the RetryOnConflict logic can identify conflicts
+		return updateFn(ctx, cli, current)
+	})
+
+	return current, err
+}