Add a store interface with default implementations

The store interface is a simplified version of client go store. If an
object can be cached there, it should be in our store implementations.

We also provide a default way to generate keys, but we allow users to
provide their own function. This should enable all needed levels of
isolation.

The provided implementations are an expiring cache and a LRU cache.

The cache is self-instrumented.

Signed-off-by: Soule BA <[email protected]>

cache/errors.go

@@ -0,0 +1,74 @@
+/*
+Copyright 2024 The Flux authors
+
+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 cache
+
+import (
+	"errors"
+	"fmt"
+)
+
+// CacheErrorReason is a type that represents the reason for a cache error.
+type CacheErrorReason struct {
+	reason string
+	msg    string
+}
+
+// Error gives a human-readable description of the error.
+func (e CacheErrorReason) Error() string {
+	return e.msg
+}
+
+type CacheError struct {
+	Reason CacheErrorReason
+	Err    error
+}
+
+// Error returns Err as a string, prefixed with the Reason to provide context.
+func (e *CacheError) Error() string {
+	if e.Reason.Error() == "" {
+		return e.Err.Error()
+	}
+	return fmt.Sprintf("%s: %s", e.Reason.Error(), e.Err.Error())
+}
+
+// Is returns true if the Reason or Err equals target.
+// It can be used to programmatically place an arbitrary Err in the
+// context of the Cache:
+//
+//	err := &CacheError{Reason: ErrCacheFull, Err: errors.New("arbitrary resize error")}
+//	errors.Is(err, ErrCacheFull)
+func (e *CacheError) Is(target error) bool {
+	if e.Reason == target {
+		return true
+	}
+	return errors.Is(e.Err, target)
+}
+
+// Unwrap returns the underlying Err.
+func (e *CacheError) Unwrap() error {
+	return e.Err
+}
+
+var (
+	ErrNotFound      = CacheErrorReason{"NotFound", "object not found"}
+	ErrAlreadyExists = CacheErrorReason{"AlreadyRxists", "object already exists"}
+	ErrCacheClosed   = CacheErrorReason{"CacheClosed", "cache is closed"}
+	ErrCacheFull     = CacheErrorReason{"CacheFull", "cache is full"}
+	ErrInvalidSize   = CacheErrorReason{"InvalidSize", "invalid size"}
+	ErrInvalidKey    = CacheErrorReason{"InvalidKey", "invalid key"}
+	ErrInvalidLabels = CacheErrorReason{"InvalidLabels", "invalid labels"}
+)

cache/go.mod

@@ -0,0 +1,67 @@
+module github.com/fluxcd/pkg/cache
+
+go 1.22.0
+
+require (
+	github.com/fluxcd/cli-utils v0.36.0-flux.7
+	github.com/onsi/gomega v1.32.0
+	github.com/prometheus/client_golang v1.19.0
+	k8s.io/apimachinery v0.30.0
+	k8s.io/client-go v0.30.0
+)
+
+require (
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/blang/semver/v4 v4.0.0 // indirect
+	github.com/cespare/xxhash/v2 v2.2.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/emicklei/go-restful/v3 v3.11.0 // indirect
+	github.com/go-errors/errors v1.5.1 // indirect
+	github.com/go-logr/logr v1.4.1 // indirect
+	github.com/go-openapi/jsonpointer v0.19.6 // indirect
+	github.com/go-openapi/jsonreference v0.20.2 // indirect
+	github.com/go-openapi/swag v0.22.4 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/protobuf v1.5.4 // indirect
+	github.com/google/gnostic-models v0.6.8 // indirect
+	github.com/google/go-cmp v0.6.0 // indirect
+	github.com/google/gofuzz v1.2.0 // indirect
+	github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/josharian/intern v1.0.0 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/mailru/easyjson v0.7.7 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	github.com/monochromegane/go-gitignore v0.0.0-20200626010858-205db1a8cc00 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/prometheus/client_model v0.5.0 // indirect
+	github.com/prometheus/common v0.48.0 // indirect
+	github.com/prometheus/procfs v0.12.0 // indirect
+	github.com/stretchr/objx v0.5.2 // indirect
+	github.com/xlab/treeprint v1.2.0 // indirect
+	go.starlark.net v0.0.0-20230525235612-a134d8f9ddca // indirect
+	golang.org/x/net v0.24.0 // indirect
+	golang.org/x/oauth2 v0.19.0 // indirect
+	golang.org/x/sync v0.7.0 // indirect
+	golang.org/x/sys v0.19.0 // indirect
+	golang.org/x/term v0.19.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
+	golang.org/x/time v0.5.0 // indirect
+	google.golang.org/protobuf v1.33.0 // indirect
+	gopkg.in/evanphx/json-patch.v4 v4.12.0 // indirect
+	gopkg.in/inf.v0 v0.9.1 // indirect
+	gopkg.in/yaml.v2 v2.4.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	k8s.io/api v0.30.0 // indirect
+	k8s.io/cli-runtime v0.30.0 // indirect
+	k8s.io/klog/v2 v2.120.1 // indirect
+	k8s.io/kube-openapi v0.0.0-20240228011516-70dd3763d340 // indirect
+	k8s.io/utils v0.0.0-20230726121419-3b25d923346b // indirect
+	sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
+	sigs.k8s.io/kustomize/api v0.17.1 // indirect
+	sigs.k8s.io/kustomize/kyaml v0.17.0 // indirect
+	sigs.k8s.io/structured-merge-diff/v4 v4.4.1 // indirect
+	sigs.k8s.io/yaml v1.4.0 // indirect
+)