feat: add collection utility functions

[Diaphteiros]

What this PR does / why we need it:
When implementing preemptive scheduling, I needed a few utility functions which I put into this repo.
Mostly related to collections.

See release notes for more details.

Which issue(s) this PR fixes:
None

Special notes for your reviewer:
Prerequisite for openmcp-project/openmcp-operator#67

As requested, I split this PR into smaller ones, the new ones are:

• add retrying k8s client implementation #79
• extend testing library #80

Release note:

The `pkg/collections/maps` package now has a `GetAny` functions to get an arbitrary element from a map.

The `pkg/collections` package now has projection (`ProjectSlice`, `ProjectMapToSlice`, `ProjectMapToMap`) and aggregation (`AggregateSlice`, `AggregateMap`) functions to perform operations for each entry of a slice or map.

The `pkg/controller` package has a new `RemoveFinalizerWithPrefix` function that removes the first finalizer from the object with the given prefix.

[Copilot]

Pull Request Overview

This PR adds several utility functions and enhancements to support preemptive scheduling, testing, and general collection operations.

• Introduces UID injection support in testing environments (WithUIDs and InjectUIDOnObjectCreation).
• Implements a retrying Kubernetes client wrapper with configurable backoff, timeout, and attempt parameters.
• Adds generic projection, aggregation, and map‐related helpers (e.g., ProjectSlice, GetAny) plus a RemoveFinalizersWithPrefix utility.

Reviewed Changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
pkg/testing/environment.go	Added WithUIDs to inject random UIDs on object creation.
pkg/testing/complex_environment.go	Extended complex builder for per-cluster UID injection; added InjectUIDOnObjectCreation.
pkg/retry/retry.go	New Client wrapper implementing retry logic for Kubernetes API calls.
pkg/retry/retry_test.go	Comprehensive tests for the retrying client behavior.
pkg/collections/utils.go	Added projection and aggregation helpers for slices and maps.
pkg/collections/maps/utils.go	Added GetAny to return an arbitrary key-value pair.
pkg/controller/utils.go	Introduced RemoveFinalizersWithPrefix to strip object finalizers by prefix.
pkg/controller/utils_test.go	Converted tests to Ginkgo/Gomega style and added coverage for new utilities.
pkg/clusters/cluster.go	Added Retry() method returning the retrying client.
docs/libs/retry.md	Documentation for the retrying client.
docs/README.md	Added retry docs to the table of contents.

Comments suppressed due to low confidence (5)

pkg/retry/retry.go:61

• [nitpick] The getter MaxRetries doesn’t align with the setter WithMaxAttempts. Consider renaming one of them for consistency (e.g., MaxAttempts).

func (rc *Client) MaxRetries() int {

pkg/controller/utils.go:69

• Ranging over an integer is invalid. Replace with an index-based loop, e.g., for i := 0; i < length; i++, or iterate directly over the slice with for i := range fins.

	for i := range length {

pkg/controller/utils.go:70

• The code uses strings.HasPrefix but the strings package isn’t imported. Add import "strings" at the top of the file.

		if (removeAll || !found) && strings.HasPrefix(fins[i], prefix) {

pkg/retry/retry.go:152

• Ranging over an integer is invalid. Use a classic for-loop like for i := 0; i < argCountVariadic; i++ to index into the variadic arguments.

		for i := range argCountVariadic {

pkg/testing/complex_environment.go:432

• This function signature references context.Context but the context package isn’t imported. Add import "context" to the imports.

func InjectUIDOnObjectCreation(additionalLogic func(ctx context.Context, client client.WithWatch, obj client.Object, opts ...client.CreateOption) error) func(ctx context.Context, client client.WithWatch, obj client.Object, opts ...client.CreateOption) error {

[maximiliantech]

@Diaphteiros Could you have a look on the review from Copilot please? There might be some things that need your attention. And also please don't forget to update the PR description 🙏

[Diaphteiros]

@maximiliantech CoPilot actually noticed one function that I forgot to rename, the other suggestions were humbug.
I adapted the PR description.

[Diaphteiros]

I added another small function and adapted the Release Notes in the PR info.