working commit

vendor/k8s.io/client-go/tools/cache/OWNERS

@@ -0,0 +1,27 @@
+# See the OWNERS docs at https://go.k8s.io/owners
+
+approvers:
+  - thockin
+  - smarterclayton
+  - wojtek-t
+  - deads2k
+  - caesarxuchao
+  - liggitt
+reviewers:
+  - thockin
+  - smarterclayton
+  - wojtek-t
+  - deads2k
+  - derekwaynecarr
+  - caesarxuchao
+  - mikedanese
+  - liggitt
+  - janetkuo
+  - justinsb
+  - soltysh
+  - jsafrane
+  - dims
+  - ingvagabund
+emeritus_approvers:
+  - lavalamp
+  - ncdc

vendor/k8s.io/client-go/tools/cache/controller.go

@@ -0,0 +1,747 @@
+/*
+Copyright 2015 The Kubernetes 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 (
+	"context"
+	"errors"
+	"fmt"
+	"sync"
+	"time"
+
+	"k8s.io/apimachinery/pkg/runtime"
+	utilruntime "k8s.io/apimachinery/pkg/util/runtime"
+	"k8s.io/apimachinery/pkg/util/wait"
+	clientgofeaturegate "k8s.io/client-go/features"
+	"k8s.io/utils/clock"
+)
+
+// This file implements a low-level controller that is used in
+// sharedIndexInformer, which is an implementation of
+// SharedIndexInformer.  Such informers, in turn, are key components
+// in the high level controllers that form the backbone of the
+// Kubernetes control plane.  Look at those for examples, or the
+// example in
+// https://github.com/kubernetes/client-go/tree/master/examples/workqueue
+// .
+
+// Config contains all the settings for one of these low-level controllers.
+type Config struct {
+	// The queue for your objects - has to be a DeltaFIFO due to
+	// assumptions in the implementation. Your Process() function
+	// should accept the output of this Queue's Pop() method.
+	Queue
+
+	// Something that can list and watch your objects.
+	ListerWatcher
+
+	// Process can process a popped Deltas.
+	Process ProcessFunc
+
+	// ProcessBatch can process a batch of popped Deltas, which should return `TransactionError` if not all items
+	// in the batch were successfully processed.
+	//
+	// For batch processing to be used:
+	// * ProcessBatch must be non-nil
+	// * Queue must implement QueueWithBatch
+	// * The client InOrderInformersBatchProcess feature gate must be enabled
+	//
+	// If any of those are false, Process is used and no batch processing is done.
+	ProcessBatch ProcessBatchFunc
+
+	// ObjectType is an example object of the type this controller is
+	// expected to handle.
+	ObjectType runtime.Object
+
+	// ObjectDescription is the description to use when logging type-specific information about this controller.
+	ObjectDescription string
+
+	// FullResyncPeriod is the period at which ShouldResync is considered.
+	FullResyncPeriod time.Duration
+
+	// MinWatchTimeout, if set, will define the minimum timeout for watch requests send
+	// to kube-apiserver. However, values lower than 5m will not be honored to avoid
+	// negative performance impact on controlplane.
+	// Optional - if unset a default value of 5m will be used.
+	MinWatchTimeout time.Duration
+
+	// ShouldResync is periodically used by the reflector to determine
+	// whether to Resync the Queue. If ShouldResync is `nil` or
+	// returns true, it means the reflector should proceed with the
+	// resync.
+	ShouldResync ShouldResyncFunc
+
+	// Called whenever the ListAndWatch drops the connection with an error.
+	//
+	// Contextual logging: WatchErrorHandlerWithContext should be used instead of WatchErrorHandler in code which supports contextual logging.
+	WatchErrorHandler WatchErrorHandler
+
+	// Called whenever the ListAndWatch drops the connection with an error
+	// and WatchErrorHandler is not set.
+	WatchErrorHandlerWithContext WatchErrorHandlerWithContext
+
+	// WatchListPageSize is the requested chunk size of initial and relist watch lists.
+	WatchListPageSize int64
+}
+
+// ShouldResyncFunc is a type of function that indicates if a reflector should perform a
+// resync or not. It can be used by a shared informer to support multiple event handlers with custom
+// resync periods.
+type ShouldResyncFunc func() bool
+
+// ProcessFunc processes a single object.
+type ProcessFunc func(obj interface{}, isInInitialList bool) error
+
+// ProcessBatchFunc processes multiple objects in batch.
+// The deltas must not contain multiple entries for the same object.
+type ProcessBatchFunc func(deltas []Delta, isInInitialList bool) error
+
+// `*controller` implements Controller
+type controller struct {
+	config         Config
+	reflector      *Reflector
+	reflectorMutex sync.RWMutex
+	clock          clock.Clock
+}
+
+// Controller is a low-level controller that is parameterized by a
+// Config and used in sharedIndexInformer.
+type Controller interface {
+	// RunWithContext does two things.  One is to construct and run a Reflector
+	// to pump objects/notifications from the Config's ListerWatcher
+	// to the Config's Queue and possibly invoke the occasional Resync
+	// on that Queue.  The other is to repeatedly Pop from the Queue
+	// and process with the Config's ProcessFunc.  Both of these
+	// continue until the context is canceled.
+	//
+	// It's an error to call RunWithContext more than once.
+	// RunWithContext blocks; call via go.
+	RunWithContext(ctx context.Context)
+
+	// Run does the same as RunWithContext with a stop channel instead of
+	// a context.
+	//
+	// Contextual logging: RunWithcontext should be used instead of Run in code which supports contextual logging.
+	Run(stopCh <-chan struct{})
+
+	// HasSynced delegates to the Config's Queue
+	HasSynced() bool
+
+	// LastSyncResourceVersion delegates to the Reflector when there
+	// is one, otherwise returns the empty string
+	LastSyncResourceVersion() string
+}
+
+// New makes a new Controller from the given Config.
+func New(c *Config) Controller {
+	ctlr := &controller{
+		config: *c,
+		clock:  &clock.RealClock{},
+	}
+	return ctlr
+}
+
+// Run implements [Controller.Run].
+func (c *controller) Run(stopCh <-chan struct{}) {
+	c.RunWithContext(wait.ContextForChannel(stopCh))
+}
+
+// RunWithContext implements [Controller.RunWithContext].
+func (c *controller) RunWithContext(ctx context.Context) {
+	defer utilruntime.HandleCrashWithContext(ctx)
+	go func() {
+		<-ctx.Done()
+		c.config.Queue.Close()
+	}()
+	r := NewReflectorWithOptions(
+		c.config.ListerWatcher,
+		c.config.ObjectType,
+		c.config.Queue,
+		ReflectorOptions{
+			ResyncPeriod:    c.config.FullResyncPeriod,
+			MinWatchTimeout: c.config.MinWatchTimeout,
+			TypeDescription: c.config.ObjectDescription,
+			Clock:           c.clock,
+		},
+	)
+	r.ShouldResync = c.config.ShouldResync
+	r.WatchListPageSize = c.config.WatchListPageSize
+	if c.config.WatchErrorHandler != nil {
+		r.watchErrorHandler = func(_ context.Context, r *Reflector, err error) {
+			c.config.WatchErrorHandler(r, err)
+		}
+	} else if c.config.WatchErrorHandlerWithContext != nil {
+		r.watchErrorHandler = c.config.WatchErrorHandlerWithContext
+	}
+
+	c.reflectorMutex.Lock()
+	c.reflector = r
+	c.reflectorMutex.Unlock()
+
+	var wg wait.Group
+
+	wg.StartWithContext(ctx, r.RunWithContext)
+
+	wait.UntilWithContext(ctx, c.processLoop, time.Second)
+	wg.Wait()
+}
+
+// Returns true once this controller has completed an initial resource listing
+func (c *controller) HasSynced() bool {
+	return c.config.Queue.HasSynced()
+}
+
+func (c *controller) LastSyncResourceVersion() string {
+	c.reflectorMutex.RLock()
+	defer c.reflectorMutex.RUnlock()
+	if c.reflector == nil {
+		return ""
+	}
+	return c.reflector.LastSyncResourceVersion()
+}
+
+// processLoop drains the work queue.
+// TODO: Consider doing the processing in parallel. This will require a little thought
+// to make sure that we don't end up processing the same object multiple times
+// concurrently.
+func (c *controller) processLoop(ctx context.Context) {
+	useBatchProcess := false
+	batchQueue, ok := c.config.Queue.(QueueWithBatch)
+	if ok && c.config.ProcessBatch != nil && clientgofeaturegate.FeatureGates().Enabled(clientgofeaturegate.InOrderInformersBatchProcess) {
+		useBatchProcess = true
+	}
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		default:
+			var err error
+			if useBatchProcess {
+				err = batchQueue.PopBatch(c.config.ProcessBatch)
+			} else {
+				// otherwise fallback to non-batch process behavior
+				_, err = c.config.Pop(PopProcessFunc(c.config.Process))
+			}
+			if err != nil {
+				if errors.Is(err, ErrFIFOClosed) {
+					return
+				}
+			}
+		}
+	}
+}
+
+// ResourceEventHandler can handle notifications for events that
+// happen to a resource. The events are informational only, so you
+// can't return an error.  The handlers MUST NOT modify the objects
+// received; this concerns not only the top level of structure but all
+// the data structures reachable from it.
+//   - OnAdd is called when an object is added.
+//   - OnUpdate is called when an object is modified. Note that oldObj is the
+//     last known state of the object-- it is possible that several changes
+//     were combined together, so you can't use this to see every single
+//     change. OnUpdate is also called when a re-list happens, and it will
+//     get called even if nothing changed. This is useful for periodically
+//     evaluating or syncing something.
+//   - OnDelete will get the final state of the item if it is known, otherwise
+//     it will get an object of type DeletedFinalStateUnknown. This can
+//     happen if the watch is closed and misses the delete event and we don't
+//     notice the deletion until the subsequent re-list.
+type ResourceEventHandler interface {
+	OnAdd(obj interface{}, isInInitialList bool)
+	OnUpdate(oldObj, newObj interface{})
+	OnDelete(obj interface{})
+}
+
+// ResourceEventHandlerFuncs is an adaptor to let you easily specify as many or
+// as few of the notification functions as you want while still implementing
+// ResourceEventHandler.  This adapter does not remove the prohibition against
+// modifying the objects.
+//
+// See ResourceEventHandlerDetailedFuncs if your use needs to propagate
+// HasSynced.
+type ResourceEventHandlerFuncs struct {
+	AddFunc    func(obj interface{})
+	UpdateFunc func(oldObj, newObj interface{})
+	DeleteFunc func(obj interface{})
+}
+
+// OnAdd calls AddFunc if it's not nil.
+func (r ResourceEventHandlerFuncs) OnAdd(obj interface{}, isInInitialList bool) {
+	if r.AddFunc != nil {
+		r.AddFunc(obj)
+	}
+}
+
+// OnUpdate calls UpdateFunc if it's not nil.
+func (r ResourceEventHandlerFuncs) OnUpdate(oldObj, newObj interface{}) {
+	if r.UpdateFunc != nil {
+		r.UpdateFunc(oldObj, newObj)
+	}
+}
+
+// OnDelete calls DeleteFunc if it's not nil.
+func (r ResourceEventHandlerFuncs) OnDelete(obj interface{}) {
+	if r.DeleteFunc != nil {
+		r.DeleteFunc(obj)
+	}
+}
+
+// ResourceEventHandlerDetailedFuncs is exactly like ResourceEventHandlerFuncs
+// except its AddFunc accepts the isInInitialList parameter, for propagating
+// HasSynced.
+type ResourceEventHandlerDetailedFuncs struct {
+	AddFunc    func(obj interface{}, isInInitialList bool)
+	UpdateFunc func(oldObj, newObj interface{})
+	DeleteFunc func(obj interface{})
+}
+
+// OnAdd calls AddFunc if it's not nil.
+func (r ResourceEventHandlerDetailedFuncs) OnAdd(obj interface{}, isInInitialList bool) {
+	if r.AddFunc != nil {
+		r.AddFunc(obj, isInInitialList)
+	}
+}
+
+// OnUpdate calls UpdateFunc if it's not nil.
+func (r ResourceEventHandlerDetailedFuncs) OnUpdate(oldObj, newObj interface{}) {
+	if r.UpdateFunc != nil {
+		r.UpdateFunc(oldObj, newObj)
+	}
+}
+
+// OnDelete calls DeleteFunc if it's not nil.
+func (r ResourceEventHandlerDetailedFuncs) OnDelete(obj interface{}) {
+	if r.DeleteFunc != nil {
+		r.DeleteFunc(obj)
+	}
+}
+
+// FilteringResourceEventHandler applies the provided filter to all events coming
+// in, ensuring the appropriate nested handler method is invoked. An object
+// that starts passing the filter after an update is considered an add, and an
+// object that stops passing the filter after an update is considered a delete.
+// Like the handlers, the filter MUST NOT modify the objects it is given.
+type FilteringResourceEventHandler struct {
+	FilterFunc func(obj interface{}) bool
+	Handler    ResourceEventHandler
+}
+
+// OnAdd calls the nested handler only if the filter succeeds
+func (r FilteringResourceEventHandler) OnAdd(obj interface{}, isInInitialList bool) {
+	if !r.FilterFunc(obj) {
+		return
+	}
+	r.Handler.OnAdd(obj, isInInitialList)
+}
+
+// OnUpdate ensures the proper handler is called depending on whether the filter matches
+func (r FilteringResourceEventHandler) OnUpdate(oldObj, newObj interface{}) {
+	newer := r.FilterFunc(newObj)
+	older := r.FilterFunc(oldObj)
+	switch {
+	case newer && older:
+		r.Handler.OnUpdate(oldObj, newObj)
+	case newer && !older:
+		r.Handler.OnAdd(newObj, false)
+	case !newer && older:
+		r.Handler.OnDelete(oldObj)
+	default:
+		// do nothing
+	}
+}
+
+// OnDelete calls the nested handler only if the filter succeeds
+func (r FilteringResourceEventHandler) OnDelete(obj interface{}) {
+	if !r.FilterFunc(obj) {
+		return
+	}
+	r.Handler.OnDelete(obj)
+}
+
+// DeletionHandlingMetaNamespaceKeyFunc checks for
+// DeletedFinalStateUnknown objects before calling
+// MetaNamespaceKeyFunc.
+func DeletionHandlingMetaNamespaceKeyFunc(obj interface{}) (string, error) {
+	if d, ok := obj.(DeletedFinalStateUnknown); ok {
+		return d.Key, nil
+	}
+	return MetaNamespaceKeyFunc(obj)
+}
+
+// DeletionHandlingObjectToName checks for
+// DeletedFinalStateUnknown objects before calling
+// ObjectToName.
+func DeletionHandlingObjectToName(obj interface{}) (ObjectName, error) {
+	if d, ok := obj.(DeletedFinalStateUnknown); ok {
+		return ParseObjectName(d.Key)
+	}
+	return ObjectToName(obj)
+}
+
+// InformerOptions configure a Reflector.
+type InformerOptions struct {
+	// ListerWatcher implements List and Watch functions for the source of the resource
+	// the informer will be informing about.
+	ListerWatcher ListerWatcher
+
+	// ObjectType is an object of the type that informer is expected to receive.
+	ObjectType runtime.Object
+
+	// Handler defines functions that should called on object mutations.
+	Handler ResourceEventHandler
+
+	// ResyncPeriod is the underlying Reflector's resync period. If non-zero, the store
+	// is re-synced with that frequency - Modify events are delivered even if objects
+	// didn't change.
+	// This is useful for synchronizing objects that configure external resources
+	// (e.g. configure cloud provider functionalities).
+	// Optional - if unset, store resyncing is not happening periodically.
+	ResyncPeriod time.Duration
+
+	// MinWatchTimeout, if set, will define the minimum timeout for watch requests send
+	// to kube-apiserver. However, values lower than 5m will not be honored to avoid
+	// negative performance impact on controlplane.
+	// Optional - if unset a default value of 5m will be used.
+	MinWatchTimeout time.Duration
+
+	// Indexers, if set, are the indexers for the received objects to optimize
+	// certain queries.
+	// Optional - if unset no indexes are maintained.
+	Indexers Indexers
+
+	// Transform function, if set, will be called on all objects before they will be
+	// put into the Store and corresponding Add/Modify/Delete handlers will be invoked
+	// for them.
+	// Optional - if unset no additional transforming is happening.
+	Transform TransformFunc
+}
+
+// NewInformerWithOptions returns a Store and a controller for populating the store
+// while also providing event notifications. You should only used the returned
+// Store for Get/List operations; Add/Modify/Deletes will cause the event
+// notifications to be faulty.
+func NewInformerWithOptions(options InformerOptions) (Store, Controller) {
+	var clientState Store
+	if options.Indexers == nil {
+		clientState = NewStore(DeletionHandlingMetaNamespaceKeyFunc)
+	} else {
+		clientState = NewIndexer(DeletionHandlingMetaNamespaceKeyFunc, options.Indexers)
+	}
+	return clientState, newInformer(clientState, options)
+}
+
+// NewInformer returns a Store and a controller for populating the store
+// while also providing event notifications. You should only used the returned
+// Store for Get/List operations; Add/Modify/Deletes will cause the event
+// notifications to be faulty.
+//
+// Parameters:
+//   - lw is list and watch functions for the source of the resource you want to
+//     be informed of.
+//   - objType is an object of the type that you expect to receive.
+//   - resyncPeriod: if non-zero, will re-list this often (you will get OnUpdate
+//     calls, even if nothing changed). Otherwise, re-list will be delayed as
+//     long as possible (until the upstream source closes the watch or times out,
+//     or you stop the controller).
+//   - h is the object you want notifications sent to.
+//
+// Deprecated: Use NewInformerWithOptions instead.
+func NewInformer(
+	lw ListerWatcher,
+	objType runtime.Object,
+	resyncPeriod time.Duration,
+	h ResourceEventHandler,
+) (Store, Controller) {
+	// This will hold the client state, as we know it.
+	clientState := NewStore(DeletionHandlingMetaNamespaceKeyFunc)
+
+	options := InformerOptions{
+		ListerWatcher: lw,
+		ObjectType:    objType,
+		Handler:       h,
+		ResyncPeriod:  resyncPeriod,
+	}
+	return clientState, newInformer(clientState, options)
+}
+
+// NewIndexerInformer returns an Indexer and a Controller for populating the index
+// while also providing event notifications. You should only used the returned
+// Index for Get/List operations; Add/Modify/Deletes will cause the event
+// notifications to be faulty.
+//
+// Parameters:
+//   - lw is list and watch functions for the source of the resource you want to
+//     be informed of.
+//   - objType is an object of the type that you expect to receive.
+//   - resyncPeriod: if non-zero, will re-list this often (you will get OnUpdate
+//     calls, even if nothing changed). Otherwise, re-list will be delayed as
+//     long as possible (until the upstream source closes the watch or times out,
+//     or you stop the controller).
+//   - h is the object you want notifications sent to.
+//   - indexers is the indexer for the received object type.
+//
+// Deprecated: Use NewInformerWithOptions instead.
+func NewIndexerInformer(
+	lw ListerWatcher,
+	objType runtime.Object,
+	resyncPeriod time.Duration,
+	h ResourceEventHandler,
+	indexers Indexers,
+) (Indexer, Controller) {
+	// This will hold the client state, as we know it.
+	clientState := NewIndexer(DeletionHandlingMetaNamespaceKeyFunc, indexers)
+
+	options := InformerOptions{
+		ListerWatcher: lw,
+		ObjectType:    objType,
+		Handler:       h,
+		ResyncPeriod:  resyncPeriod,
+		Indexers:      indexers,
+	}
+	return clientState, newInformer(clientState, options)
+}
+
+// NewTransformingInformer returns a Store and a controller for populating
+// the store while also providing event notifications. You should only used
+// the returned Store for Get/List operations; Add/Modify/Deletes will cause
+// the event notifications to be faulty.
+// The given transform function will be called on all objects before they will
+// put into the Store and corresponding Add/Modify/Delete handlers will
+// be invoked for them.
+//
+// Deprecated: Use NewInformerWithOptions instead.
+func NewTransformingInformer(
+	lw ListerWatcher,
+	objType runtime.Object,
+	resyncPeriod time.Duration,
+	h ResourceEventHandler,
+	transformer TransformFunc,
+) (Store, Controller) {
+	// This will hold the client state, as we know it.
+	clientState := NewStore(DeletionHandlingMetaNamespaceKeyFunc)
+
+	options := InformerOptions{
+		ListerWatcher: lw,
+		ObjectType:    objType,
+		Handler:       h,
+		ResyncPeriod:  resyncPeriod,
+		Transform:     transformer,
+	}
+	return clientState, newInformer(clientState, options)
+}
+
+// NewTransformingIndexerInformer returns an Indexer and a controller for
+// populating the index while also providing event notifications. You should
+// only used the returned Index for Get/List operations; Add/Modify/Deletes
+// will cause the event notifications to be faulty.
+// The given transform function will be called on all objects before they will
+// be put into the Index and corresponding Add/Modify/Delete handlers will
+// be invoked for them.
+//
+// Deprecated: Use NewInformerWithOptions instead.
+func NewTransformingIndexerInformer(
+	lw ListerWatcher,
+	objType runtime.Object,
+	resyncPeriod time.Duration,
+	h ResourceEventHandler,
+	indexers Indexers,
+	transformer TransformFunc,
+) (Indexer, Controller) {
+	// This will hold the client state, as we know it.
+	clientState := NewIndexer(DeletionHandlingMetaNamespaceKeyFunc, indexers)
+
+	options := InformerOptions{
+		ListerWatcher: lw,
+		ObjectType:    objType,
+		Handler:       h,
+		ResyncPeriod:  resyncPeriod,
+		Indexers:      indexers,
+		Transform:     transformer,
+	}
+	return clientState, newInformer(clientState, options)
+}
+
+// Multiplexes updates in the form of a list of Deltas into a Store, and informs
+// a given handler of events OnUpdate, OnAdd, OnDelete
+func processDeltas(
+	// Object which receives event notifications from the given deltas
+	handler ResourceEventHandler,
+	clientState Store,
+	deltas Deltas,
+	isInInitialList bool,
+) error {
+	// from oldest to newest
+	for _, d := range deltas {
+		obj := d.Object
+
+		switch d.Type {
+		case Sync, Replaced, Added, Updated:
+			if old, exists, err := clientState.Get(obj); err == nil && exists {
+				if err := clientState.Update(obj); err != nil {
+					return err
+				}
+				handler.OnUpdate(old, obj)
+			} else {
+				if err := clientState.Add(obj); err != nil {
+					return err
+				}
+				handler.OnAdd(obj, isInInitialList)
+			}
+		case Deleted:
+			if err := clientState.Delete(obj); err != nil {
+				return err
+			}
+			handler.OnDelete(obj)
+		}
+	}
+	return nil
+}
+
+// processDeltasInBatch applies a batch of Delta objects to the given Store and
+// notifies the ResourceEventHandler of add, update, or delete events.
+//
+// If the Store supports transactions (TransactionStore), all Deltas are applied
+// atomically in a single transaction and corresponding handler callbacks are
+// executed afterward. Otherwise, each Delta is processed individually.
+//
+// Returns an error if any Delta or transaction fails. For TransactionError,
+// only successful operations trigger callbacks.
+func processDeltasInBatch(
+	handler ResourceEventHandler,
+	clientState Store,
+	deltas []Delta,
+	isInInitialList bool,
+) error {
+	// from oldest to newest
+	txns := make([]Transaction, 0)
+	callbacks := make([]func(), 0)
+	txnStore, txnSupported := clientState.(TransactionStore)
+	if !txnSupported {
+		var errs []error
+		for _, delta := range deltas {
+			if err := processDeltas(handler, clientState, Deltas{delta}, isInInitialList); err != nil {
+				errs = append(errs, err)
+			}
+		}
+		if len(errs) > 0 {
+			return fmt.Errorf("unexpected error when handling deltas: %v", errs)
+		}
+		return nil
+	}
+	// deltasList is a list of unique objects
+	for _, d := range deltas {
+		obj := d.Object
+		switch d.Type {
+		case Sync, Replaced, Added, Updated:
+			// it will only return one old object for each because items are unique
+			if old, exists, err := clientState.Get(obj); err == nil && exists {
+				txn := Transaction{
+					Type:   TransactionTypeUpdate,
+					Object: obj,
+				}
+				txns = append(txns, txn)
+				callbacks = append(callbacks, func() {
+					handler.OnUpdate(old, obj)
+				})
+			} else {
+				txn := Transaction{
+					Type:   TransactionTypeAdd,
+					Object: obj,
+				}
+				txns = append(txns, txn)
+				callbacks = append(callbacks, func() {
+					handler.OnAdd(obj, isInInitialList)
+				})
+			}
+		case Deleted:
+			txn := Transaction{
+				Type:   TransactionTypeDelete,
+				Object: obj,
+			}
+			txns = append(txns, txn)
+			callbacks = append(callbacks, func() {
+				handler.OnDelete(obj)
+			})
+		}
+	}
+
+	err := txnStore.Transaction(txns...)
+	if err != nil {
+		// if txn had error, only execute the callbacks for the successful ones
+		for _, i := range err.SuccessfulIndices {
+			if i < len(callbacks) {
+				callbacks[i]()
+			}
+		}
+		// formatting the error so txns doesn't escape and keeps allocated in the stack.
+		return fmt.Errorf("not all items in the batch successfully processed: %s", err.Error())
+	}
+	for _, callback := range callbacks {
+		callback()
+	}
+	return nil
+}
+
+// newInformer returns a controller for populating the store while also
+// providing event notifications.
+//
+// Parameters
+//   - clientState is the store you want to populate
+//   - options contain the options to configure the controller
+func newInformer(clientState Store, options InformerOptions) Controller {
+	// This will hold incoming changes. Note how we pass clientState in as a
+	// KeyLister, that way resync operations will result in the correct set
+	// of update/delete deltas.
+
+	fifo := newQueueFIFO(clientState, options.Transform)
+
+	cfg := &Config{
+		Queue:            fifo,
+		ListerWatcher:    options.ListerWatcher,
+		ObjectType:       options.ObjectType,
+		FullResyncPeriod: options.ResyncPeriod,
+		MinWatchTimeout:  options.MinWatchTimeout,
+
+		Process: func(obj interface{}, isInInitialList bool) error {
+			if deltas, ok := obj.(Deltas); ok {
+				return processDeltas(options.Handler, clientState, deltas, isInInitialList)
+			}
+			return errors.New("object given as Process argument is not Deltas")
+		},
+		ProcessBatch: func(deltaList []Delta, isInInitialList bool) error {
+			return processDeltasInBatch(options.Handler, clientState, deltaList, isInInitialList)
+		},
+	}
+	return New(cfg)
+}
+
+func newQueueFIFO(clientState Store, transform TransformFunc) Queue {
+	if clientgofeaturegate.FeatureGates().Enabled(clientgofeaturegate.InOrderInformers) {
+		return NewRealFIFOWithOptions(RealFIFOOptions{
+			KeyFunction:  MetaNamespaceKeyFunc,
+			KnownObjects: clientState,
+			Transformer:  transform,
+		})
+	} else {
+		return NewDeltaFIFOWithOptions(DeltaFIFOOptions{
+			KnownObjects:          clientState,
+			EmitDeltaTypeReplaced: true,
+			Transformer:           transform,
+		})
+	}
+}

vendor/k8s.io/client-go/tools/cache/delta_fifo.go

@@ -0,0 +1,735 @@
+/*
+Copyright 2014 The Kubernetes 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"
+	"sync"
+	"time"
+
+	"k8s.io/apimachinery/pkg/util/sets"
+
+	"k8s.io/klog/v2"
+	utiltrace "k8s.io/utils/trace"
+)
+
+// DeltaFIFOOptions is the configuration parameters for DeltaFIFO. All are
+// optional.
+type DeltaFIFOOptions struct {
+
+	// KeyFunction is used to figure out what key an object should have. (It's
+	// exposed in the returned DeltaFIFO's KeyOf() method, with additional
+	// handling around deleted objects and queue state).
+	// Optional, the default is MetaNamespaceKeyFunc.
+	KeyFunction KeyFunc
+
+	// KnownObjects is expected to return a list of keys that the consumer of
+	// this queue "knows about". It is used to decide which items are missing
+	// when Replace() is called; 'Deleted' deltas are produced for the missing items.
+	// KnownObjects may be nil if you can tolerate missing deletions on Replace().
+	KnownObjects KeyListerGetter
+
+	// EmitDeltaTypeReplaced indicates that the queue consumer
+	// understands the Replaced DeltaType. Before the `Replaced` event type was
+	// added, calls to Replace() were handled the same as Sync(). For
+	// backwards-compatibility purposes, this is false by default.
+	// When true, `Replaced` events will be sent for items passed to a Replace() call.
+	// When false, `Sync` events will be sent instead.
+	EmitDeltaTypeReplaced bool
+
+	// If set, will be called for objects before enqueueing them. Please
+	// see the comment on TransformFunc for details.
+	Transformer TransformFunc
+
+	// If set, log output will go to this logger instead of klog.Background().
+	Logger *klog.Logger
+}
+
+// DeltaFIFO is like FIFO, but differs in two ways.  One is that the
+// accumulator associated with a given object's key is not that object
+// but rather a Deltas, which is a slice of Delta values for that
+// object.  Applying an object to a Deltas means to append a Delta
+// except when the potentially appended Delta is a Deleted and the
+// Deltas already ends with a Deleted.  In that case the Deltas does
+// not grow, although the terminal Deleted will be replaced by the new
+// Deleted if the older Deleted's object is a
+// DeletedFinalStateUnknown.
+//
+// The other difference is that DeltaFIFO has two additional ways that
+// an object can be applied to an accumulator: Replaced and Sync.
+// If EmitDeltaTypeReplaced is not set to true, Sync will be used in
+// replace events for backwards compatibility.  Sync is used for periodic
+// resync events.
+//
+// DeltaFIFO is a producer-consumer queue, where a Reflector is
+// intended to be the producer, and the consumer is whatever calls
+// the Pop() method.
+//
+// DeltaFIFO solves this use case:
+//   - You want to process every object change (delta) at most once.
+//   - When you process an object, you want to see everything
+//     that's happened to it since you last processed it.
+//   - You want to process the deletion of some of the objects.
+//   - You might want to periodically reprocess objects.
+//
+// DeltaFIFO's Pop(), Get(), and GetByKey() methods return
+// interface{} to satisfy the Store/Queue interfaces, but they
+// will always return an object of type Deltas. List() returns
+// the newest object from each accumulator in the FIFO.
+//
+// A DeltaFIFO's knownObjects KeyListerGetter provides the abilities
+// to list Store keys and to get objects by Store key.  The objects in
+// question are called "known objects" and this set of objects
+// modifies the behavior of the Delete, Replace, and Resync methods
+// (each in a different way).
+//
+// A note on threading: If you call Pop() in parallel from multiple
+// threads, you could end up with multiple threads processing slightly
+// different versions of the same object.
+type DeltaFIFO struct {
+	// lock/cond protects access to 'items' and 'queue'.
+	lock sync.RWMutex
+	cond sync.Cond
+
+	// `items` maps a key to a Deltas.
+	// Each such Deltas has at least one Delta.
+	items map[string]Deltas
+
+	// `queue` maintains FIFO order of keys for consumption in Pop().
+	// There are no duplicates in `queue`.
+	// A key is in `queue` if and only if it is in `items`.
+	queue []string
+
+	// populated is true if the first batch of items inserted by Replace() has been populated
+	// or Delete/Add/Update/AddIfNotPresent was called first.
+	populated bool
+	// initialPopulationCount is the number of items inserted by the first call of Replace()
+	initialPopulationCount int
+
+	// keyFunc is used to make the key used for queued item
+	// insertion and retrieval, and should be deterministic.
+	keyFunc KeyFunc
+
+	// knownObjects list keys that are "known" --- affecting Delete(),
+	// Replace(), and Resync()
+	knownObjects KeyListerGetter
+
+	// Used to indicate a queue is closed so a control loop can exit when a queue is empty.
+	// Currently, not used to gate any of CRUD operations.
+	closed bool
+
+	// emitDeltaTypeReplaced is whether to emit the Replaced or Sync
+	// DeltaType when Replace() is called (to preserve backwards compat).
+	emitDeltaTypeReplaced bool
+
+	// Called with every object if non-nil.
+	transformer TransformFunc
+
+	// logger is a per-instance logger. This gets chosen when constructing
+	// the instance, with klog.Background() as default.
+	logger klog.Logger
+}
+
+// TransformFunc allows for transforming an object before it will be processed.
+//
+// The most common usage pattern is to clean-up some parts of the object to
+// reduce component memory usage if a given component doesn't care about them.
+//
+// New in v1.27: TransformFunc sees the object before any other actor, and it
+// is now safe to mutate the object in place instead of making a copy.
+//
+// It's recommended for the TransformFunc to be idempotent.
+// It MUST be idempotent if objects already present in the cache are passed to
+// the Replace() to avoid re-mutating them. Default informers do not pass
+// existing objects to Replace though.
+//
+// Note that TransformFunc is called while inserting objects into the
+// notification queue and is therefore extremely performance sensitive; please
+// do not do anything that will take a long time.
+type TransformFunc func(interface{}) (interface{}, error)
+
+// DeltaType is the type of a change (addition, deletion, etc)
+type DeltaType string
+
+// Change type definition
+const (
+	Added   DeltaType = "Added"
+	Updated DeltaType = "Updated"
+	Deleted DeltaType = "Deleted"
+	// Replaced is emitted when we encountered watch errors and had to do a
+	// relist. We don't know if the replaced object has changed.
+	//
+	// NOTE: Previous versions of DeltaFIFO would use Sync for Replace events
+	// as well. Hence, Replaced is only emitted when the option
+	// EmitDeltaTypeReplaced is true.
+	Replaced DeltaType = "Replaced"
+	// Sync is for synthetic events during a periodic resync.
+	Sync DeltaType = "Sync"
+)
+
+// Delta is a member of Deltas (a list of Delta objects) which
+// in its turn is the type stored by a DeltaFIFO. It tells you what
+// change happened, and the object's state after* that change.
+//
+// [*] Unless the change is a deletion, and then you'll get the final
+// state of the object before it was deleted.
+type Delta struct {
+	Type   DeltaType
+	Object interface{}
+}
+
+// Deltas is a list of one or more 'Delta's to an individual object.
+// The oldest delta is at index 0, the newest delta is the last one.
+type Deltas []Delta
+
+// NewDeltaFIFO returns a Queue which can be used to process changes to items.
+//
+// keyFunc is used to figure out what key an object should have. (It is
+// exposed in the returned DeltaFIFO's KeyOf() method, with additional handling
+// around deleted objects and queue state).
+//
+// 'knownObjects' may be supplied to modify the behavior of Delete,
+// Replace, and Resync.  It may be nil if you do not need those
+// modifications.
+//
+// TODO: consider merging keyLister with this object, tracking a list of
+// "known" keys when Pop() is called. Have to think about how that
+// affects error retrying.
+//
+//	NOTE: It is possible to misuse this and cause a race when using an
+//	external known object source.
+//	Whether there is a potential race depends on how the consumer
+//	modifies knownObjects. In Pop(), process function is called under
+//	lock, so it is safe to update data structures in it that need to be
+//	in sync with the queue (e.g. knownObjects).
+//
+//	Example:
+//	In case of sharedIndexInformer being a consumer
+//	(https://github.com/kubernetes/kubernetes/blob/0cdd940f/staging/src/k8s.io/client-go/tools/cache/shared_informer.go#L192),
+//	there is no race as knownObjects (s.indexer) is modified safely
+//	under DeltaFIFO's lock. The only exceptions are GetStore() and
+//	GetIndexer() methods, which expose ways to modify the underlying
+//	storage. Currently these two methods are used for creating Lister
+//	and internal tests.
+//
+// Also see the comment on DeltaFIFO.
+//
+// Warning: This constructs a DeltaFIFO that does not differentiate between
+// events caused by a call to Replace (e.g., from a relist, which may
+// contain object updates), and synthetic events caused by a periodic resync
+// (which just emit the existing object). See https://issue.k8s.io/86015 for details.
+//
+// Use `NewDeltaFIFOWithOptions(DeltaFIFOOptions{..., EmitDeltaTypeReplaced: true})`
+// instead to receive a `Replaced` event depending on the type.
+//
+// Deprecated: Equivalent to NewDeltaFIFOWithOptions(DeltaFIFOOptions{KeyFunction: keyFunc, KnownObjects: knownObjects})
+func NewDeltaFIFO(keyFunc KeyFunc, knownObjects KeyListerGetter) *DeltaFIFO {
+	return NewDeltaFIFOWithOptions(DeltaFIFOOptions{
+		KeyFunction:  keyFunc,
+		KnownObjects: knownObjects,
+	})
+}
+
+// NewDeltaFIFOWithOptions returns a Queue which can be used to process changes to
+// items. See also the comment on DeltaFIFO.
+func NewDeltaFIFOWithOptions(opts DeltaFIFOOptions) *DeltaFIFO {
+	if opts.KeyFunction == nil {
+		opts.KeyFunction = MetaNamespaceKeyFunc
+	}
+
+	f := &DeltaFIFO{
+		items:        map[string]Deltas{},
+		queue:        []string{},
+		keyFunc:      opts.KeyFunction,
+		knownObjects: opts.KnownObjects,
+
+		emitDeltaTypeReplaced: opts.EmitDeltaTypeReplaced,
+		transformer:           opts.Transformer,
+		logger:                klog.Background(),
+	}
+	if opts.Logger != nil {
+		f.logger = *opts.Logger
+	}
+	f.cond.L = &f.lock
+	return f
+}
+
+var (
+	_ = Queue(&DeltaFIFO{})             // DeltaFIFO is a Queue
+	_ = TransformingStore(&DeltaFIFO{}) // DeltaFIFO implements TransformingStore to allow memory optimizations
+)
+
+var (
+	// ErrZeroLengthDeltasObject is returned in a KeyError if a Deltas
+	// object with zero length is encountered (should be impossible,
+	// but included for completeness).
+	ErrZeroLengthDeltasObject = errors.New("0 length Deltas object; can't get key")
+)
+
+// Close the queue.
+func (f *DeltaFIFO) Close() {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	f.closed = true
+	f.cond.Broadcast()
+}
+
+// KeyOf exposes f's keyFunc, but also detects the key of a Deltas object or
+// DeletedFinalStateUnknown objects.
+func (f *DeltaFIFO) KeyOf(obj interface{}) (string, error) {
+	if d, ok := obj.(Deltas); ok {
+		if len(d) == 0 {
+			return "", KeyError{obj, ErrZeroLengthDeltasObject}
+		}
+		obj = d.Newest().Object
+	}
+	if d, ok := obj.(DeletedFinalStateUnknown); ok {
+		return d.Key, nil
+	}
+	return f.keyFunc(obj)
+}
+
+// Transformer implements the TransformingStore interface.
+func (f *DeltaFIFO) Transformer() TransformFunc {
+	return f.transformer
+}
+
+// HasSynced returns true if an Add/Update/Delete/AddIfNotPresent are called first,
+// or the first batch of items inserted by Replace() has been popped.
+func (f *DeltaFIFO) HasSynced() bool {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	return f.hasSynced_locked()
+}
+
+func (f *DeltaFIFO) hasSynced_locked() bool {
+	return f.populated && f.initialPopulationCount == 0
+}
+
+// Add inserts an item, and puts it in the queue. The item is only enqueued
+// if it doesn't already exist in the set.
+func (f *DeltaFIFO) Add(obj interface{}) error {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	f.populated = true
+	return f.queueActionLocked(Added, obj)
+}
+
+// Update is just like Add, but makes an Updated Delta.
+func (f *DeltaFIFO) Update(obj interface{}) error {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	f.populated = true
+	return f.queueActionLocked(Updated, obj)
+}
+
+// Delete is just like Add, but makes a Deleted Delta. If the given
+// object does not already exist, it will be ignored. (It may have
+// already been deleted by a Replace (re-list), for example.)  In this
+// method `f.knownObjects`, if not nil, provides (via GetByKey)
+// _additional_ objects that are considered to already exist.
+func (f *DeltaFIFO) Delete(obj interface{}) error {
+	id, err := f.KeyOf(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	f.populated = true
+	if f.knownObjects == nil {
+		if _, exists := f.items[id]; !exists {
+			// Presumably, this was deleted when a relist happened.
+			// Don't provide a second report of the same deletion.
+			return nil
+		}
+	} else {
+		// We only want to skip the "deletion" action if the object doesn't
+		// exist in knownObjects and it doesn't have corresponding item in items.
+		// Note that even if there is a "deletion" action in items, we can ignore it,
+		// because it will be deduped automatically in "queueActionLocked"
+		_, exists, err := f.knownObjects.GetByKey(id)
+		_, itemsExist := f.items[id]
+		if err == nil && !exists && !itemsExist {
+			// Presumably, this was deleted when a relist happened.
+			// Don't provide a second report of the same deletion.
+			return nil
+		}
+	}
+
+	// exist in items and/or KnownObjects
+	return f.queueActionLocked(Deleted, obj)
+}
+
+// re-listing and watching can deliver the same update multiple times in any
+// order. This will combine the most recent two deltas if they are the same.
+func dedupDeltas(deltas Deltas) Deltas {
+	n := len(deltas)
+	if n < 2 {
+		return deltas
+	}
+	a := &deltas[n-1]
+	b := &deltas[n-2]
+	if out := isDup(a, b); out != nil {
+		deltas[n-2] = *out
+		return deltas[:n-1]
+	}
+	return deltas
+}
+
+// If a & b represent the same event, returns the delta that ought to be kept.
+// Otherwise, returns nil.
+// TODO: is there anything other than deletions that need deduping?
+func isDup(a, b *Delta) *Delta {
+	if out := isDeletionDup(a, b); out != nil {
+		return out
+	}
+	// TODO: Detect other duplicate situations? Are there any?
+	return nil
+}
+
+// keep the one with the most information if both are deletions.
+func isDeletionDup(a, b *Delta) *Delta {
+	if b.Type != Deleted || a.Type != Deleted {
+		return nil
+	}
+	// Do more sophisticated checks, or is this sufficient?
+	if _, ok := b.Object.(DeletedFinalStateUnknown); ok {
+		return a
+	}
+	return b
+}
+
+// queueActionLocked appends to the delta list for the object.
+// Caller must lock first.
+func (f *DeltaFIFO) queueActionLocked(actionType DeltaType, obj interface{}) error {
+	return f.queueActionInternalLocked(actionType, actionType, obj)
+}
+
+// queueActionInternalLocked appends to the delta list for the object.
+// The actionType is emitted and must honor emitDeltaTypeReplaced.
+// The internalActionType is only used within this function and must
+// ignore emitDeltaTypeReplaced.
+// Caller must lock first.
+func (f *DeltaFIFO) queueActionInternalLocked(actionType, internalActionType DeltaType, obj interface{}) error {
+	id, err := f.KeyOf(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+
+	// Every object comes through this code path once, so this is a good
+	// place to call the transform func.
+	//
+	// If obj is a DeletedFinalStateUnknown tombstone or the action is a Sync,
+	// then the object have already gone through the transformer.
+	//
+	// If the objects already present in the cache are passed to Replace(),
+	// the transformer must be idempotent to avoid re-mutating them,
+	// or coordinate with all readers from the cache to avoid data races.
+	// Default informers do not pass existing objects to Replace.
+	if f.transformer != nil {
+		_, isTombstone := obj.(DeletedFinalStateUnknown)
+		if !isTombstone && internalActionType != Sync {
+			var err error
+			obj, err = f.transformer(obj)
+			if err != nil {
+				return err
+			}
+		}
+	}
+
+	oldDeltas := f.items[id]
+	newDeltas := append(oldDeltas, Delta{actionType, obj})
+	newDeltas = dedupDeltas(newDeltas)
+
+	if len(newDeltas) > 0 {
+		if _, exists := f.items[id]; !exists {
+			f.queue = append(f.queue, id)
+		}
+		f.items[id] = newDeltas
+		f.cond.Broadcast()
+	} else {
+		// This never happens, because dedupDeltas never returns an empty list
+		// when given a non-empty list (as it is here).
+		// If somehow it happens anyway, deal with it but complain.
+		if oldDeltas == nil {
+			f.logger.Error(nil, "Impossible dedupDeltas, ignoring", "id", id, "oldDeltas", oldDeltas, "obj", obj)
+			return nil
+		}
+		f.logger.Error(nil, "Impossible dedupDeltas, breaking invariant by storing empty Deltas", "id", id, "oldDeltas", oldDeltas, "obj", obj)
+		f.items[id] = newDeltas
+		return fmt.Errorf("Impossible dedupDeltas for id=%q: oldDeltas=%#+v, obj=%#+v; broke DeltaFIFO invariant by storing empty Deltas", id, oldDeltas, obj)
+	}
+	return nil
+}
+
+// IsClosed checks if the queue is closed
+func (f *DeltaFIFO) IsClosed() bool {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	return f.closed
+}
+
+// Pop blocks until the queue has some items, and then returns one.  If
+// multiple items are ready, they are returned in the order in which they were
+// added/updated. The item is removed from the queue (and the store) before it
+// is returned, so if you don't successfully process it, you need to add it back
+// with AddIfNotPresent().
+// process function is called under lock, so it is safe to update data structures
+// in it that need to be in sync with the queue (e.g. knownKeys).
+// process should avoid expensive I/O operation so that other queue operations, i.e.
+// Add() and Get(), won't be blocked for too long.
+//
+// Pop returns a 'Deltas', which has a complete list of all the things
+// that happened to the object (deltas) while it was sitting in the queue.
+func (f *DeltaFIFO) Pop(process PopProcessFunc) (interface{}, error) {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	for {
+		for len(f.queue) == 0 {
+			// When the queue is empty, invocation of Pop() is blocked until new item is enqueued.
+			// When Close() is called, the f.closed is set and the condition is broadcasted.
+			// Which causes this loop to continue and return from the Pop().
+			if f.closed {
+				return nil, ErrFIFOClosed
+			}
+
+			f.cond.Wait()
+		}
+		isInInitialList := !f.hasSynced_locked()
+		id := f.queue[0]
+		f.queue = f.queue[1:]
+		depth := len(f.queue)
+		if f.initialPopulationCount > 0 {
+			f.initialPopulationCount--
+		}
+		item, ok := f.items[id]
+		if !ok {
+			// This should never happen
+			f.logger.Error(nil, "Inconceivable! Item was in f.queue but not f.items; ignoring", "id", id)
+			continue
+		}
+		delete(f.items, id)
+		// Only log traces if the queue depth is greater than 10 and it takes more than
+		// 100 milliseconds to process one item from the queue.
+		// Queue depth never goes high because processing an item is locking the queue,
+		// and new items can't be added until processing finish.
+		// https://github.com/kubernetes/kubernetes/issues/103789
+		if depth > 10 {
+			trace := utiltrace.New("DeltaFIFO Pop Process",
+				utiltrace.Field{Key: "ID", Value: id},
+				utiltrace.Field{Key: "Depth", Value: depth},
+				utiltrace.Field{Key: "Reason", Value: "slow event handlers blocking the queue"})
+			defer trace.LogIfLong(100 * time.Millisecond)
+		}
+		err := process(item, isInInitialList)
+		// Don't need to copyDeltas here, because we're transferring
+		// ownership to the caller.
+		return item, err
+	}
+}
+
+// Replace atomically does two things: (1) it adds the given objects
+// using the Sync or Replace DeltaType and then (2) it does some deletions.
+// In particular: for every pre-existing key K that is not the key of
+// an object in `list` there is the effect of
+// `Delete(DeletedFinalStateUnknown{K, O})` where O is the latest known
+// object of K. The pre-existing keys are those in the union set of the keys in
+// `f.items` and `f.knownObjects` (if not nil). The last known object for key K is
+// the one present in the last delta in `f.items`. If there is no delta for K
+// in `f.items`, it is the object in `f.knownObjects`
+func (f *DeltaFIFO) Replace(list []interface{}, _ string) error {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	keys := make(sets.Set[string], len(list))
+
+	// keep backwards compat for old clients
+	action := Sync
+	if f.emitDeltaTypeReplaced {
+		action = Replaced
+	}
+
+	// Add Sync/Replaced action for each new item.
+	for _, item := range list {
+		key, err := f.KeyOf(item)
+		if err != nil {
+			return KeyError{item, err}
+		}
+		keys.Insert(key)
+		if err := f.queueActionInternalLocked(action, Replaced, item); err != nil {
+			return fmt.Errorf("couldn't enqueue object: %v", err)
+		}
+	}
+
+	// Do deletion detection against objects in the queue
+	queuedDeletions := 0
+	for k, oldItem := range f.items {
+		if keys.Has(k) {
+			continue
+		}
+		// Delete pre-existing items not in the new list.
+		// This could happen if watch deletion event was missed while
+		// disconnected from apiserver.
+		var deletedObj interface{}
+		if n := oldItem.Newest(); n != nil {
+			deletedObj = n.Object
+
+			// if the previous object is a DeletedFinalStateUnknown, we have to extract the actual Object
+			if d, ok := deletedObj.(DeletedFinalStateUnknown); ok {
+				deletedObj = d.Obj
+			}
+		}
+		queuedDeletions++
+		if err := f.queueActionLocked(Deleted, DeletedFinalStateUnknown{k, deletedObj}); err != nil {
+			return err
+		}
+	}
+
+	if f.knownObjects != nil {
+		// Detect deletions for objects not present in the queue, but present in KnownObjects
+		knownKeys := f.knownObjects.ListKeys()
+		for _, k := range knownKeys {
+			if keys.Has(k) {
+				continue
+			}
+			if len(f.items[k]) > 0 {
+				continue
+			}
+
+			deletedObj, exists, err := f.knownObjects.GetByKey(k)
+			if err != nil {
+				deletedObj = nil
+				f.logger.Error(err, "Unexpected error during lookup, placing DeleteFinalStateUnknown marker without object", "key", k)
+			} else if !exists {
+				deletedObj = nil
+				f.logger.Info("Key does not exist in known objects store, placing DeleteFinalStateUnknown marker without object", "key", k)
+			}
+			queuedDeletions++
+			if err := f.queueActionLocked(Deleted, DeletedFinalStateUnknown{k, deletedObj}); err != nil {
+				return err
+			}
+		}
+	}
+
+	if !f.populated {
+		f.populated = true
+		f.initialPopulationCount = keys.Len() + queuedDeletions
+	}
+
+	return nil
+}
+
+// Resync adds, with a Sync type of Delta, every object listed by
+// `f.knownObjects` whose key is not already queued for processing.
+// If `f.knownObjects` is `nil` then Resync does nothing.
+func (f *DeltaFIFO) Resync() error {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+
+	if f.knownObjects == nil {
+		return nil
+	}
+
+	keys := f.knownObjects.ListKeys()
+	for _, k := range keys {
+		if err := f.syncKeyLocked(k); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func (f *DeltaFIFO) syncKeyLocked(key string) error {
+	obj, exists, err := f.knownObjects.GetByKey(key)
+	if err != nil {
+		f.logger.Error(err, "Unexpected error during lookup, unable to queue object for sync", "key", key)
+		return nil
+	} else if !exists {
+		f.logger.Info("Key does not exist in known objects store, unable to queue object for sync", "key", key)
+		return nil
+	}
+
+	// If we are doing Resync() and there is already an event queued for that object,
+	// we ignore the Resync for it. This is to avoid the race, in which the resync
+	// comes with the previous value of object (since queueing an event for the object
+	// doesn't trigger changing the underlying store <knownObjects>.
+	id, err := f.KeyOf(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+	if len(f.items[id]) > 0 {
+		return nil
+	}
+
+	if err := f.queueActionLocked(Sync, obj); err != nil {
+		return fmt.Errorf("couldn't queue object: %v", err)
+	}
+	return nil
+}
+
+// A KeyListerGetter is anything that knows how to list its keys and look up by key.
+type KeyListerGetter interface {
+	KeyLister
+	KeyGetter
+}
+
+// A KeyLister is anything that knows how to list its keys.
+type KeyLister interface {
+	ListKeys() []string
+}
+
+// A KeyGetter is anything that knows how to get the value stored under a given key.
+type KeyGetter interface {
+	// GetByKey returns the value associated with the key, or sets exists=false.
+	GetByKey(key string) (value interface{}, exists bool, err error)
+}
+
+// Oldest is a convenience function that returns the oldest delta, or
+// nil if there are no deltas.
+func (d Deltas) Oldest() *Delta {
+	if len(d) > 0 {
+		return &d[0]
+	}
+	return nil
+}
+
+// Newest is a convenience function that returns the newest delta, or
+// nil if there are no deltas.
+func (d Deltas) Newest() *Delta {
+	if n := len(d); n > 0 {
+		return &d[n-1]
+	}
+	return nil
+}
+
+// copyDeltas returns a shallow copy of d; that is, it copies the slice but not
+// the objects in the slice. This allows Get/List to return an object that we
+// know won't be clobbered by a subsequent modifications.
+func copyDeltas(d Deltas) Deltas {
+	d2 := make(Deltas, len(d))
+	copy(d2, d)
+	return d2
+}
+
+// DeletedFinalStateUnknown is placed into a DeltaFIFO in the case where an object
+// was deleted but the watch deletion event was missed while disconnected from
+// apiserver. In this case we don't know the final "resting" state of the object, so
+// there's a chance the included `Obj` is stale.
+type DeletedFinalStateUnknown struct {
+	Key string
+	Obj interface{}
+}

vendor/k8s.io/client-go/tools/cache/doc.go

@@ -0,0 +1,24 @@
+/*
+Copyright 2014 The Kubernetes 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 is a client-side caching mechanism. It is useful for
+// reducing the number of server calls you'd otherwise need to make.
+// Reflector watches a server and updates a Store. Two stores are provided;
+// one that simply caches objects (for example, to allow a scheduler to
+// list currently available nodes), and one that additionally acts as
+// a FIFO queue (for example, to allow a scheduler to process incoming
+// pods).
+package cache

vendor/k8s.io/client-go/tools/cache/expiration_cache.go

@@ -0,0 +1,214 @@
+/*
+Copyright 2014 The Kubernetes 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 (
+	"sync"
+	"time"
+
+	"k8s.io/utils/clock"
+)
+
+// ExpirationCache implements the store interface
+//  1. All entries are automatically time stamped on insert
+//     a. The key is computed based off the original item/keyFunc
+//     b. The value inserted under that key is the timestamped item
+//  2. Expiration happens lazily on read based on the expiration policy
+//     a. No item can be inserted into the store while we're expiring
+//     *any* item in the cache.
+//  3. Time-stamps are stripped off unexpired entries before return
+//
+// Note that the ExpirationCache is inherently slower than a normal
+// threadSafeStore because it takes a write lock every time it checks if
+// an item has expired.
+type ExpirationCache struct {
+	cacheStorage     ThreadSafeStore
+	keyFunc          KeyFunc
+	clock            clock.Clock
+	expirationPolicy ExpirationPolicy
+	// expirationLock is a write lock used to guarantee that we don't clobber
+	// newly inserted objects because of a stale expiration timestamp comparison
+	expirationLock sync.Mutex
+}
+
+// ExpirationPolicy dictates when an object expires. Currently only abstracted out
+// so unittests don't rely on the system clock.
+type ExpirationPolicy interface {
+	IsExpired(obj *TimestampedEntry) bool
+}
+
+// TTLPolicy implements a ttl based ExpirationPolicy.
+type TTLPolicy struct {
+	//	 >0: Expire entries with an age > ttl
+	//	<=0: Don't expire any entry
+	TTL time.Duration
+
+	// Clock used to calculate ttl expiration
+	Clock clock.Clock
+}
+
+// IsExpired returns true if the given object is older than the ttl, or it can't
+// determine its age.
+func (p *TTLPolicy) IsExpired(obj *TimestampedEntry) bool {
+	return p.TTL > 0 && p.Clock.Since(obj.Timestamp) > p.TTL
+}
+
+// TimestampedEntry is the only type allowed in a ExpirationCache.
+// Keep in mind that it is not safe to share timestamps between computers.
+// Behavior may be inconsistent if you get a timestamp from the API Server and
+// use it on the client machine as part of your ExpirationCache.
+type TimestampedEntry struct {
+	Obj       interface{}
+	Timestamp time.Time
+	key       string
+}
+
+// getTimestampedEntry returns the TimestampedEntry stored under the given key.
+func (c *ExpirationCache) getTimestampedEntry(key string) (*TimestampedEntry, bool) {
+	item, _ := c.cacheStorage.Get(key)
+	if tsEntry, ok := item.(*TimestampedEntry); ok {
+		return tsEntry, true
+	}
+	return nil, false
+}
+
+// getOrExpire retrieves the object from the TimestampedEntry if and only if it hasn't
+// already expired. It holds a write lock across deletion.
+func (c *ExpirationCache) getOrExpire(key string) (interface{}, bool) {
+	// Prevent all inserts from the time we deem an item as "expired" to when we
+	// delete it, so an un-expired item doesn't sneak in under the same key, just
+	// before the Delete.
+	c.expirationLock.Lock()
+	defer c.expirationLock.Unlock()
+	timestampedItem, exists := c.getTimestampedEntry(key)
+	if !exists {
+		return nil, false
+	}
+	if c.expirationPolicy.IsExpired(timestampedItem) {
+		c.cacheStorage.Delete(key)
+		return nil, false
+	}
+	return timestampedItem.Obj, true
+}
+
+// GetByKey returns the item stored under the key, or sets exists=false.
+func (c *ExpirationCache) GetByKey(key string) (interface{}, bool, error) {
+	obj, exists := c.getOrExpire(key)
+	return obj, exists, nil
+}
+
+// Get returns unexpired items. It purges the cache of expired items in the
+// process.
+func (c *ExpirationCache) Get(obj interface{}) (interface{}, bool, error) {
+	key, err := c.keyFunc(obj)
+	if err != nil {
+		return nil, false, KeyError{obj, err}
+	}
+	obj, exists := c.getOrExpire(key)
+	return obj, exists, nil
+}
+
+// List retrieves a list of unexpired items. It purges the cache of expired
+// items in the process.
+func (c *ExpirationCache) List() []interface{} {
+	items := c.cacheStorage.List()
+
+	list := make([]interface{}, 0, len(items))
+	for _, item := range items {
+		key := item.(*TimestampedEntry).key
+		if obj, exists := c.getOrExpire(key); exists {
+			list = append(list, obj)
+		}
+	}
+	return list
+}
+
+// ListKeys returns a list of all keys in the expiration cache.
+func (c *ExpirationCache) ListKeys() []string {
+	return c.cacheStorage.ListKeys()
+}
+
+// Add timestamps an item and inserts it into the cache, overwriting entries
+// that might exist under the same key.
+func (c *ExpirationCache) Add(obj interface{}) error {
+	key, err := c.keyFunc(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+	c.expirationLock.Lock()
+	defer c.expirationLock.Unlock()
+
+	c.cacheStorage.Add(key, &TimestampedEntry{obj, c.clock.Now(), key})
+	return nil
+}
+
+// Update has not been implemented yet for lack of a use case, so this method
+// simply calls `Add`. This effectively refreshes the timestamp.
+func (c *ExpirationCache) Update(obj interface{}) error {
+	return c.Add(obj)
+}
+
+// Delete removes an item from the cache.
+func (c *ExpirationCache) Delete(obj interface{}) error {
+	key, err := c.keyFunc(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+	c.expirationLock.Lock()
+	defer c.expirationLock.Unlock()
+	c.cacheStorage.Delete(key)
+	return nil
+}
+
+// Replace will convert all items in the given list to TimestampedEntries
+// before attempting the replace operation. The replace operation will
+// delete the contents of the ExpirationCache `c`.
+func (c *ExpirationCache) Replace(list []interface{}, resourceVersion string) error {
+	items := make(map[string]interface{}, len(list))
+	ts := c.clock.Now()
+	for _, item := range list {
+		key, err := c.keyFunc(item)
+		if err != nil {
+			return KeyError{item, err}
+		}
+		items[key] = &TimestampedEntry{item, ts, key}
+	}
+	c.expirationLock.Lock()
+	defer c.expirationLock.Unlock()
+	c.cacheStorage.Replace(items, resourceVersion)
+	return nil
+}
+
+// Resync is a no-op for one of these
+func (c *ExpirationCache) Resync() error {
+	return nil
+}
+
+// NewTTLStore creates and returns a ExpirationCache with a TTLPolicy
+func NewTTLStore(keyFunc KeyFunc, ttl time.Duration) Store {
+	return NewExpirationStore(keyFunc, &TTLPolicy{ttl, clock.RealClock{}})
+}
+
+// NewExpirationStore creates and returns a ExpirationCache for a given policy
+func NewExpirationStore(keyFunc KeyFunc, expirationPolicy ExpirationPolicy) Store {
+	return &ExpirationCache{
+		cacheStorage:     NewThreadSafeStore(Indexers{}, Indices{}),
+		keyFunc:          keyFunc,
+		clock:            clock.RealClock{},
+		expirationPolicy: expirationPolicy,
+	}
+}

vendor/k8s.io/client-go/tools/cache/expiration_cache_fakes.go

@@ -0,0 +1,57 @@
+/*
+Copyright 2014 The Kubernetes 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 (
+	"k8s.io/apimachinery/pkg/util/sets"
+	"k8s.io/utils/clock"
+)
+
+type fakeThreadSafeMap struct {
+	ThreadSafeStore
+	deletedKeys chan<- string
+}
+
+func (c *fakeThreadSafeMap) Delete(key string) {
+	if c.deletedKeys != nil {
+		c.ThreadSafeStore.Delete(key)
+		c.deletedKeys <- key
+	}
+}
+
+// FakeExpirationPolicy keeps the list for keys which never expires.
+type FakeExpirationPolicy struct {
+	NeverExpire     sets.Set[string]
+	RetrieveKeyFunc KeyFunc
+}
+
+// IsExpired used to check if object is expired.
+func (p *FakeExpirationPolicy) IsExpired(obj *TimestampedEntry) bool {
+	key, _ := p.RetrieveKeyFunc(obj)
+	return !p.NeverExpire.Has(key)
+}
+
+// NewFakeExpirationStore creates a new instance for the ExpirationCache.
+func NewFakeExpirationStore(keyFunc KeyFunc, deletedKeys chan<- string, expirationPolicy ExpirationPolicy, cacheClock clock.Clock) Store {
+	cacheStorage := NewThreadSafeStore(Indexers{}, Indices{})
+	return &ExpirationCache{
+		cacheStorage:     &fakeThreadSafeMap{cacheStorage, deletedKeys},
+		keyFunc:          keyFunc,
+		clock:            cacheClock,
+		expirationPolicy: expirationPolicy,
+	}
+}

vendor/k8s.io/client-go/tools/cache/fake_custom_store.go

@@ -0,0 +1,102 @@
+/*
+Copyright 2016 The Kubernetes 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
+
+// FakeCustomStore lets you define custom functions for store operations.
+type FakeCustomStore struct {
+	AddFunc      func(obj interface{}) error
+	UpdateFunc   func(obj interface{}) error
+	DeleteFunc   func(obj interface{}) error
+	ListFunc     func() []interface{}
+	ListKeysFunc func() []string
+	GetFunc      func(obj interface{}) (item interface{}, exists bool, err error)
+	GetByKeyFunc func(key string) (item interface{}, exists bool, err error)
+	ReplaceFunc  func(list []interface{}, resourceVersion string) error
+	ResyncFunc   func() error
+}
+
+// Add calls the custom Add function if defined
+func (f *FakeCustomStore) Add(obj interface{}) error {
+	if f.AddFunc != nil {
+		return f.AddFunc(obj)
+	}
+	return nil
+}
+
+// Update calls the custom Update function if defined
+func (f *FakeCustomStore) Update(obj interface{}) error {
+	if f.UpdateFunc != nil {
+		return f.UpdateFunc(obj)
+	}
+	return nil
+}
+
+// Delete calls the custom Delete function if defined
+func (f *FakeCustomStore) Delete(obj interface{}) error {
+	if f.DeleteFunc != nil {
+		return f.DeleteFunc(obj)
+	}
+	return nil
+}
+
+// List calls the custom List function if defined
+func (f *FakeCustomStore) List() []interface{} {
+	if f.ListFunc != nil {
+		return f.ListFunc()
+	}
+	return nil
+}
+
+// ListKeys calls the custom ListKeys function if defined
+func (f *FakeCustomStore) ListKeys() []string {
+	if f.ListKeysFunc != nil {
+		return f.ListKeysFunc()
+	}
+	return nil
+}
+
+// Get calls the custom Get function if defined
+func (f *FakeCustomStore) Get(obj interface{}) (item interface{}, exists bool, err error) {
+	if f.GetFunc != nil {
+		return f.GetFunc(obj)
+	}
+	return nil, false, nil
+}
+
+// GetByKey calls the custom GetByKey function if defined
+func (f *FakeCustomStore) GetByKey(key string) (item interface{}, exists bool, err error) {
+	if f.GetByKeyFunc != nil {
+		return f.GetByKeyFunc(key)
+	}
+	return nil, false, nil
+}
+
+// Replace calls the custom Replace function if defined
+func (f *FakeCustomStore) Replace(list []interface{}, resourceVersion string) error {
+	if f.ReplaceFunc != nil {
+		return f.ReplaceFunc(list, resourceVersion)
+	}
+	return nil
+}
+
+// Resync calls the custom Resync function if defined
+func (f *FakeCustomStore) Resync() error {
+	if f.ResyncFunc != nil {
+		return f.ResyncFunc()
+	}
+	return nil
+}

vendor/k8s.io/client-go/tools/cache/fifo.go

@@ -0,0 +1,306 @@
+/*
+Copyright 2014 The Kubernetes 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"
+	"sync"
+
+	"k8s.io/apimachinery/pkg/util/sets"
+)
+
+// PopProcessFunc is passed to Pop() method of Queue interface.
+// It is supposed to process the accumulator popped from the queue.
+type PopProcessFunc func(obj interface{}, isInInitialList bool) error
+
+// ErrFIFOClosed used when FIFO is closed
+var ErrFIFOClosed = errors.New("DeltaFIFO: manipulating with closed queue")
+
+// Queue extends ReflectorStore with a collection of Store keys to "process".
+// Every Add, Update, or Delete may put the object's key in that collection.
+// A Queue has a way to derive the corresponding key given an accumulator.
+// A Queue can be accessed concurrently from multiple goroutines.
+// A Queue can be "closed", after which Pop operations return an error.
+type Queue interface {
+	ReflectorStore
+
+	// Pop blocks until there is at least one key to process or the
+	// Queue is closed.  In the latter case Pop returns with an error.
+	// In the former case Pop atomically picks one key to process,
+	// removes that (key, accumulator) association from the Store, and
+	// processes the accumulator.  Pop returns the accumulator that
+	// was processed and the result of processing.  The PopProcessFunc
+	// may return an ErrRequeue{inner} and in this case Pop will (a)
+	// return that (key, accumulator) association to the Queue as part
+	// of the atomic processing and (b) return the inner error from
+	// Pop.
+	Pop(PopProcessFunc) (interface{}, error)
+
+	// HasSynced returns true if the first batch of keys have all been
+	// popped.  The first batch of keys are those of the first Replace
+	// operation if that happened before any Add, AddIfNotPresent,
+	// Update, or Delete; otherwise the first batch is empty.
+	HasSynced() bool
+
+	// Close the queue
+	Close()
+}
+
+// QueueWithBatch extends the Queue interface with support for batch processing.
+//
+// In addition to the standard single-item Pop method, QueueWithBatch provides
+// PopBatch, which allows multiple items to be popped and processed together as
+// a batch. This can be used to improve processing efficiency when it is
+// beneficial to handle multiple queued keys or accumulators in a single
+// operation.
+// TODO: Consider merging this interface into Queue after feature gate GA
+type QueueWithBatch interface {
+	Queue
+
+	// PopBatch behaves similarly to Queue#Pop, but processes multiple keys
+	// as a batch. The implementation determines the batching strategy,
+	// such as the number of keys to include per batch.
+	PopBatch(ProcessBatchFunc) error
+}
+
+// Pop is helper function for popping from Queue.
+// WARNING: Do NOT use this function in non-test code to avoid races
+// unless you really really really really know what you are doing.
+//
+// NOTE: This function is deprecated and may be removed in the future without
+// additional warning.
+func Pop(queue Queue) interface{} {
+	var result interface{}
+	queue.Pop(func(obj interface{}, isInInitialList bool) error {
+		result = obj
+		return nil
+	})
+	return result
+}
+
+// FIFO is a Queue in which (a) each accumulator is simply the most
+// recently provided object and (b) the collection of keys to process
+// is a FIFO.  The accumulators all start out empty, and deleting an
+// object from its accumulator empties the accumulator.  The Resync
+// operation is a no-op.
+//
+// Thus: if multiple adds/updates of a single object happen while that
+// object's key is in the queue before it has been processed then it
+// will only be processed once, and when it is processed the most
+// recent version will be processed. This can't be done with a channel
+//
+// FIFO solves this use case:
+//   - You want to process every object (exactly) once.
+//   - You want to process the most recent version of the object when you process it.
+//   - You do not want to process deleted objects, they should be removed from the queue.
+//   - You do not want to periodically reprocess objects.
+//
+// Compare with DeltaFIFO for other use cases.
+type FIFO struct {
+	lock sync.RWMutex
+	cond sync.Cond
+	// We depend on the property that every key in `items` is also in `queue`
+	items map[string]interface{}
+	queue []string
+
+	// populated is true if the first batch of items inserted by Replace() has been populated
+	// or Delete/Add/Update was called first.
+	populated bool
+	// initialPopulationCount is the number of items inserted by the first call of Replace()
+	initialPopulationCount int
+
+	// keyFunc is used to make the key used for queued item insertion and retrieval, and
+	// should be deterministic.
+	keyFunc KeyFunc
+
+	// Indication the queue is closed.
+	// Used to indicate a queue is closed so a control loop can exit when a queue is empty.
+	// Currently, not used to gate any of CRUD operations.
+	closed bool
+}
+
+var (
+	_ = Queue(&FIFO{}) // FIFO is a Queue
+)
+
+// Close the queue.
+func (f *FIFO) Close() {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	f.closed = true
+	f.cond.Broadcast()
+}
+
+// HasSynced returns true if an Add/Update/Delete/AddIfNotPresent are called first,
+// or the first batch of items inserted by Replace() has been popped.
+func (f *FIFO) HasSynced() bool {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	return f.hasSynced_locked()
+}
+
+func (f *FIFO) hasSynced_locked() bool {
+	return f.populated && f.initialPopulationCount == 0
+}
+
+// Add inserts an item, and puts it in the queue. The item is only enqueued
+// if it doesn't already exist in the set.
+func (f *FIFO) Add(obj interface{}) error {
+	id, err := f.keyFunc(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	f.populated = true
+	if _, exists := f.items[id]; !exists {
+		f.queue = append(f.queue, id)
+	}
+	f.items[id] = obj
+	f.cond.Broadcast()
+	return nil
+}
+
+// Update is the same as Add in this implementation.
+func (f *FIFO) Update(obj interface{}) error {
+	return f.Add(obj)
+}
+
+// Delete removes an item. It doesn't add it to the queue, because
+// this implementation assumes the consumer only cares about the objects,
+// not the order in which they were created/added.
+func (f *FIFO) Delete(obj interface{}) error {
+	id, err := f.keyFunc(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	f.populated = true
+	delete(f.items, id)
+	return err
+}
+
+// IsClosed checks if the queue is closed
+func (f *FIFO) IsClosed() bool {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	return f.closed
+}
+
+// Pop waits until an item is ready and processes it. If multiple items are
+// ready, they are returned in the order in which they were added/updated.
+// The item is removed from the queue (and the store) before it is processed,
+// so if you don't successfully process it, it should be added back with
+// AddIfNotPresent(). process function is called under lock, so it is safe
+// update data structures in it that need to be in sync with the queue.
+func (f *FIFO) Pop(process PopProcessFunc) (interface{}, error) {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	for {
+		for len(f.queue) == 0 {
+			// When the queue is empty, invocation of Pop() is blocked until new item is enqueued.
+			// When Close() is called, the f.closed is set and the condition is broadcasted.
+			// Which causes this loop to continue and return from the Pop().
+			if f.closed {
+				return nil, ErrFIFOClosed
+			}
+
+			f.cond.Wait()
+		}
+		isInInitialList := !f.hasSynced_locked()
+		id := f.queue[0]
+		f.queue = f.queue[1:]
+		if f.initialPopulationCount > 0 {
+			f.initialPopulationCount--
+		}
+		item, ok := f.items[id]
+		if !ok {
+			// Item may have been deleted subsequently.
+			continue
+		}
+		delete(f.items, id)
+		err := process(item, isInInitialList)
+		return item, err
+	}
+}
+
+// Replace will delete the contents of 'f', using instead the given map.
+// 'f' takes ownership of the map, you should not reference the map again
+// after calling this function. f's queue is reset, too; upon return, it
+// will contain the items in the map, in no particular order.
+func (f *FIFO) Replace(list []interface{}, resourceVersion string) error {
+	items := make(map[string]interface{}, len(list))
+	for _, item := range list {
+		key, err := f.keyFunc(item)
+		if err != nil {
+			return KeyError{item, err}
+		}
+		items[key] = item
+	}
+
+	f.lock.Lock()
+	defer f.lock.Unlock()
+
+	if !f.populated {
+		f.populated = true
+		f.initialPopulationCount = len(items)
+	}
+
+	f.items = items
+	f.queue = f.queue[:0]
+	for id := range items {
+		f.queue = append(f.queue, id)
+	}
+	if len(f.queue) > 0 {
+		f.cond.Broadcast()
+	}
+	return nil
+}
+
+// Resync will ensure that every object in the Store has its key in the queue.
+// This should be a no-op, because that property is maintained by all operations.
+func (f *FIFO) Resync() error {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+
+	inQueue := sets.NewString()
+	for _, id := range f.queue {
+		inQueue.Insert(id)
+	}
+	for id := range f.items {
+		if !inQueue.Has(id) {
+			f.queue = append(f.queue, id)
+		}
+	}
+	if len(f.queue) > 0 {
+		f.cond.Broadcast()
+	}
+	return nil
+}
+
+// NewFIFO returns a Store which can be used to queue up items to
+// process.
+func NewFIFO(keyFunc KeyFunc) *FIFO {
+	f := &FIFO{
+		items:   map[string]interface{}{},
+		queue:   []string{},
+		keyFunc: keyFunc,
+	}
+	f.cond.L = &f.lock
+	return f
+}

vendor/k8s.io/client-go/tools/cache/heap.go

@@ -0,0 +1,322 @@
+/*
+Copyright 2017 The Kubernetes 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.
+*/
+
+// This file implements a heap data structure.
+
+package cache
+
+import (
+	"container/heap"
+	"fmt"
+	"sync"
+)
+
+const (
+	closedMsg = "heap is closed"
+)
+
+// LessFunc is used to compare two objects in the heap.
+type LessFunc func(interface{}, interface{}) bool
+
+type heapItem struct {
+	obj   interface{} // The object which is stored in the heap.
+	index int         // The index of the object's key in the Heap.queue.
+}
+
+type itemKeyValue struct {
+	key string
+	obj interface{}
+}
+
+// heapData is an internal struct that implements the standard heap interface
+// and keeps the data stored in the heap.
+type heapData struct {
+	// items is a map from key of the objects to the objects and their index.
+	// We depend on the property that items in the map are in the queue and vice versa.
+	items map[string]*heapItem
+	// queue implements a heap data structure and keeps the order of elements
+	// according to the heap invariant. The queue keeps the keys of objects stored
+	// in "items".
+	queue []string
+
+	// keyFunc is used to make the key used for queued item insertion and retrieval, and
+	// should be deterministic.
+	keyFunc KeyFunc
+	// lessFunc is used to compare two objects in the heap.
+	lessFunc LessFunc
+}
+
+var (
+	_ = heap.Interface(&heapData{}) // heapData is a standard heap
+)
+
+// Less compares two objects and returns true if the first one should go
+// in front of the second one in the heap.
+func (h *heapData) Less(i, j int) bool {
+	if i > len(h.queue) || j > len(h.queue) {
+		return false
+	}
+	itemi, ok := h.items[h.queue[i]]
+	if !ok {
+		return false
+	}
+	itemj, ok := h.items[h.queue[j]]
+	if !ok {
+		return false
+	}
+	return h.lessFunc(itemi.obj, itemj.obj)
+}
+
+// Len returns the number of items in the Heap.
+func (h *heapData) Len() int { return len(h.queue) }
+
+// Swap implements swapping of two elements in the heap. This is a part of standard
+// heap interface and should never be called directly.
+func (h *heapData) Swap(i, j int) {
+	h.queue[i], h.queue[j] = h.queue[j], h.queue[i]
+	item := h.items[h.queue[i]]
+	item.index = i
+	item = h.items[h.queue[j]]
+	item.index = j
+}
+
+// Push is supposed to be called by heap.Push only.
+func (h *heapData) Push(kv interface{}) {
+	keyValue := kv.(*itemKeyValue)
+	n := len(h.queue)
+	h.items[keyValue.key] = &heapItem{keyValue.obj, n}
+	h.queue = append(h.queue, keyValue.key)
+}
+
+// Pop is supposed to be called by heap.Pop only.
+func (h *heapData) Pop() interface{} {
+	key := h.queue[len(h.queue)-1]
+	h.queue = h.queue[0 : len(h.queue)-1]
+	item, ok := h.items[key]
+	if !ok {
+		// This is an error
+		return nil
+	}
+	delete(h.items, key)
+	return item.obj
+}
+
+// Heap is a thread-safe producer/consumer queue that implements a heap data structure.
+// It can be used to implement priority queues and similar data structures.
+type Heap struct {
+	lock sync.RWMutex
+	cond sync.Cond
+
+	// data stores objects and has a queue that keeps their ordering according
+	// to the heap invariant.
+	data *heapData
+
+	// closed indicates that the queue is closed.
+	// It is mainly used to let Pop() exit its control loop while waiting for an item.
+	closed bool
+}
+
+// Close the Heap and signals condition variables that may be waiting to pop
+// items from the heap.
+func (h *Heap) Close() {
+	h.lock.Lock()
+	defer h.lock.Unlock()
+	h.closed = true
+	h.cond.Broadcast()
+}
+
+// Add inserts an item, and puts it in the queue. The item is updated if it
+// already exists.
+func (h *Heap) Add(obj interface{}) error {
+	key, err := h.data.keyFunc(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+	h.lock.Lock()
+	defer h.lock.Unlock()
+	if h.closed {
+		return fmt.Errorf(closedMsg)
+	}
+	if _, exists := h.data.items[key]; exists {
+		h.data.items[key].obj = obj
+		heap.Fix(h.data, h.data.items[key].index)
+	} else {
+		h.addIfNotPresentLocked(key, obj)
+	}
+	h.cond.Broadcast()
+	return nil
+}
+
+// BulkAdd adds all the items in the list to the queue and then signals the condition
+// variable. It is useful when the caller would like to add all of the items
+// to the queue before consumer starts processing them.
+func (h *Heap) BulkAdd(list []interface{}) error {
+	h.lock.Lock()
+	defer h.lock.Unlock()
+	if h.closed {
+		return fmt.Errorf(closedMsg)
+	}
+	for _, obj := range list {
+		key, err := h.data.keyFunc(obj)
+		if err != nil {
+			return KeyError{obj, err}
+		}
+		if _, exists := h.data.items[key]; exists {
+			h.data.items[key].obj = obj
+			heap.Fix(h.data, h.data.items[key].index)
+		} else {
+			h.addIfNotPresentLocked(key, obj)
+		}
+	}
+	h.cond.Broadcast()
+	return nil
+}
+
+// AddIfNotPresent inserts an item, and puts it in the queue. If an item with
+// the key is present in the map, no changes is made to the item.
+//
+// This is useful in a single producer/consumer scenario so that the consumer can
+// safely retry items without contending with the producer and potentially enqueueing
+// stale items.
+func (h *Heap) AddIfNotPresent(obj interface{}) error {
+	id, err := h.data.keyFunc(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+	h.lock.Lock()
+	defer h.lock.Unlock()
+	if h.closed {
+		return fmt.Errorf(closedMsg)
+	}
+	h.addIfNotPresentLocked(id, obj)
+	h.cond.Broadcast()
+	return nil
+}
+
+// addIfNotPresentLocked assumes the lock is already held and adds the provided
+// item to the queue if it does not already exist.
+func (h *Heap) addIfNotPresentLocked(key string, obj interface{}) {
+	if _, exists := h.data.items[key]; exists {
+		return
+	}
+	heap.Push(h.data, &itemKeyValue{key, obj})
+}
+
+// Update is the same as Add in this implementation. When the item does not
+// exist, it is added.
+func (h *Heap) Update(obj interface{}) error {
+	return h.Add(obj)
+}
+
+// Delete removes an item.
+func (h *Heap) Delete(obj interface{}) error {
+	key, err := h.data.keyFunc(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+	h.lock.Lock()
+	defer h.lock.Unlock()
+	if item, ok := h.data.items[key]; ok {
+		heap.Remove(h.data, item.index)
+		return nil
+	}
+	return fmt.Errorf("object not found")
+}
+
+// Pop waits until an item is ready. If multiple items are
+// ready, they are returned in the order given by Heap.data.lessFunc.
+func (h *Heap) Pop() (interface{}, error) {
+	h.lock.Lock()
+	defer h.lock.Unlock()
+	for len(h.data.queue) == 0 {
+		// When the queue is empty, invocation of Pop() is blocked until new item is enqueued.
+		// When Close() is called, the h.closed is set and the condition is broadcast,
+		// which causes this loop to continue and return from the Pop().
+		if h.closed {
+			return nil, fmt.Errorf("heap is closed")
+		}
+		h.cond.Wait()
+	}
+	obj := heap.Pop(h.data)
+	if obj == nil {
+		return nil, fmt.Errorf("object was removed from heap data")
+	}
+
+	return obj, nil
+}
+
+// List returns a list of all the items.
+func (h *Heap) List() []interface{} {
+	h.lock.RLock()
+	defer h.lock.RUnlock()
+	list := make([]interface{}, 0, len(h.data.items))
+	for _, item := range h.data.items {
+		list = append(list, item.obj)
+	}
+	return list
+}
+
+// ListKeys returns a list of all the keys of the objects currently in the Heap.
+func (h *Heap) ListKeys() []string {
+	h.lock.RLock()
+	defer h.lock.RUnlock()
+	list := make([]string, 0, len(h.data.items))
+	for key := range h.data.items {
+		list = append(list, key)
+	}
+	return list
+}
+
+// Get returns the requested item, or sets exists=false.
+func (h *Heap) Get(obj interface{}) (interface{}, bool, error) {
+	key, err := h.data.keyFunc(obj)
+	if err != nil {
+		return nil, false, KeyError{obj, err}
+	}
+	return h.GetByKey(key)
+}
+
+// GetByKey returns the requested item, or sets exists=false.
+func (h *Heap) GetByKey(key string) (interface{}, bool, error) {
+	h.lock.RLock()
+	defer h.lock.RUnlock()
+	item, exists := h.data.items[key]
+	if !exists {
+		return nil, false, nil
+	}
+	return item.obj, true, nil
+}
+
+// IsClosed returns true if the queue is closed.
+func (h *Heap) IsClosed() bool {
+	h.lock.RLock()
+	defer h.lock.RUnlock()
+	return h.closed
+}
+
+// NewHeap returns a Heap which can be used to queue up items to process.
+func NewHeap(keyFn KeyFunc, lessFn LessFunc) *Heap {
+	h := &Heap{
+		data: &heapData{
+			items:    map[string]*heapItem{},
+			queue:    []string{},
+			keyFunc:  keyFn,
+			lessFunc: lessFn,
+		},
+	}
+	h.cond.L = &h.lock
+	return h
+}

vendor/k8s.io/client-go/tools/cache/index.go

@@ -0,0 +1,100 @@
+/*
+Copyright 2014 The Kubernetes 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 (
+	"fmt"
+
+	"k8s.io/apimachinery/pkg/api/meta"
+	"k8s.io/apimachinery/pkg/util/sets"
+)
+
+// Indexer extends Store with multiple indices and restricts each
+// accumulator to simply hold the current object (and be empty after
+// Delete).
+//
+// There are three kinds of strings here:
+//  1. a storage key, as defined in the Store interface,
+//  2. a name of an index, and
+//  3. an "indexed value", which is produced by an IndexFunc and
+//     can be a field value or any other string computed from the object.
+type Indexer interface {
+	Store
+	// Index returns the stored objects whose set of indexed values
+	// intersects the set of indexed values of the given object, for
+	// the named index
+	Index(indexName string, obj interface{}) ([]interface{}, error)
+	// IndexKeys returns the storage keys of the stored objects whose
+	// set of indexed values for the named index includes the given
+	// indexed value
+	IndexKeys(indexName, indexedValue string) ([]string, error)
+	// ListIndexFuncValues returns all the indexed values of the given index
+	ListIndexFuncValues(indexName string) []string
+	// ByIndex returns the stored objects whose set of indexed values
+	// for the named index includes the given indexed value
+	ByIndex(indexName, indexedValue string) ([]interface{}, error)
+	// GetIndexers return the indexers
+	GetIndexers() Indexers
+
+	// AddIndexers adds more indexers to this store. This supports adding indexes after the store already has items.
+	AddIndexers(newIndexers Indexers) error
+}
+
+// IndexFunc knows how to compute the set of indexed values for an object.
+type IndexFunc func(obj interface{}) ([]string, error)
+
+// IndexFuncToKeyFuncAdapter adapts an indexFunc to a keyFunc.  This is only useful if your index function returns
+// unique values for every object.  This conversion can create errors when more than one key is found.  You
+// should prefer to make proper key and index functions.
+func IndexFuncToKeyFuncAdapter(indexFunc IndexFunc) KeyFunc {
+	return func(obj interface{}) (string, error) {
+		indexKeys, err := indexFunc(obj)
+		if err != nil {
+			return "", err
+		}
+		if len(indexKeys) > 1 {
+			return "", fmt.Errorf("too many keys: %v", indexKeys)
+		}
+		if len(indexKeys) == 0 {
+			return "", fmt.Errorf("unexpected empty indexKeys")
+		}
+		return indexKeys[0], nil
+	}
+}
+
+const (
+	// NamespaceIndex is the lookup name for the most common index function, which is to index by the namespace field.
+	NamespaceIndex string = "namespace"
+)
+
+// MetaNamespaceIndexFunc is a default index function that indexes based on an object's namespace
+func MetaNamespaceIndexFunc(obj interface{}) ([]string, error) {
+	meta, err := meta.Accessor(obj)
+	if err != nil {
+		return []string{""}, fmt.Errorf("object has no meta: %v", err)
+	}
+	return []string{meta.GetNamespace()}, nil
+}
+
+// Index maps the indexed value to a set of keys in the store that match on that value
+type index map[string]sets.Set[string]
+
+// Indexers maps a name to an IndexFunc
+type Indexers map[string]IndexFunc
+
+// Indices maps a name to an Index
+type Indices map[string]index

vendor/k8s.io/client-go/tools/cache/listers.go

@@ -0,0 +1,184 @@
+/*
+Copyright 2014 The Kubernetes 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 (
+	"k8s.io/klog/v2"
+
+	"k8s.io/apimachinery/pkg/api/errors"
+	"k8s.io/apimachinery/pkg/api/meta"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/labels"
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/runtime/schema"
+)
+
+// AppendFunc is used to add a matching item to whatever list the caller is using
+type AppendFunc func(interface{})
+
+// ListAll lists items in the store matching the given selector, calling appendFn on each one.
+func ListAll(store Store, selector labels.Selector, appendFn AppendFunc) error {
+	if labels.MatchesNothing(selector) {
+		return nil
+	}
+
+	selectAll := selector.Empty()
+	for _, m := range store.List() {
+		if selectAll {
+			// Avoid computing labels of the objects to speed up common flows
+			// of listing all objects.
+			appendFn(m)
+			continue
+		}
+		metadata, err := meta.Accessor(m)
+		if err != nil {
+			return err
+		}
+		if selector.Matches(labels.Set(metadata.GetLabels())) {
+			appendFn(m)
+		}
+	}
+	return nil
+}
+
+// ListAllByNamespace lists items in the given namespace in the store matching the given selector,
+// calling appendFn on each one.
+// If a blank namespace (NamespaceAll) is specified, this delegates to ListAll().
+func ListAllByNamespace(indexer Indexer, namespace string, selector labels.Selector, appendFn AppendFunc) error {
+	if labels.MatchesNothing(selector) {
+		return nil
+	}
+
+	if namespace == metav1.NamespaceAll {
+		return ListAll(indexer, selector, appendFn)
+	}
+
+	items, err := indexer.Index(NamespaceIndex, &metav1.ObjectMeta{Namespace: namespace})
+	if err != nil {
+		// Ignore error; do slow search without index.
+		//
+		// ListAllByNamespace is called by generated code
+		// (k8s.io/client-go/listers) and probably not worth converting
+		// to contextual logging, which would require changing all of
+		// those APIs.
+		klog.TODO().Info("Warning: can not retrieve list of objects using index", "err", err)
+		for _, m := range indexer.List() {
+			metadata, err := meta.Accessor(m)
+			if err != nil {
+				return err
+			}
+			if metadata.GetNamespace() == namespace && selector.Matches(labels.Set(metadata.GetLabels())) {
+				appendFn(m)
+			}
+
+		}
+		return nil
+	}
+
+	selectAll := selector.Empty()
+	for _, m := range items {
+		if selectAll {
+			// Avoid computing labels of the objects to speed up common flows
+			// of listing all objects.
+			appendFn(m)
+			continue
+		}
+		metadata, err := meta.Accessor(m)
+		if err != nil {
+			return err
+		}
+		if selector.Matches(labels.Set(metadata.GetLabels())) {
+			appendFn(m)
+		}
+	}
+
+	return nil
+}
+
+// GenericLister is a lister skin on a generic Indexer
+type GenericLister interface {
+	// List will return all objects across namespaces
+	List(selector labels.Selector) (ret []runtime.Object, err error)
+	// Get will attempt to retrieve assuming that name==key
+	Get(name string) (runtime.Object, error)
+	// ByNamespace will give you a GenericNamespaceLister for one namespace
+	ByNamespace(namespace string) GenericNamespaceLister
+}
+
+// GenericNamespaceLister is a lister skin on a generic Indexer
+type GenericNamespaceLister interface {
+	// List will return all objects in this namespace
+	List(selector labels.Selector) (ret []runtime.Object, err error)
+	// Get will attempt to retrieve by namespace and name
+	Get(name string) (runtime.Object, error)
+}
+
+// NewGenericLister creates a new instance for the genericLister.
+func NewGenericLister(indexer Indexer, resource schema.GroupResource) GenericLister {
+	return &genericLister{indexer: indexer, resource: resource}
+}
+
+type genericLister struct {
+	indexer  Indexer
+	resource schema.GroupResource
+}
+
+func (s *genericLister) List(selector labels.Selector) (ret []runtime.Object, err error) {
+	err = ListAll(s.indexer, selector, func(m interface{}) {
+		ret = append(ret, m.(runtime.Object))
+	})
+	return ret, err
+}
+
+func (s *genericLister) ByNamespace(namespace string) GenericNamespaceLister {
+	return &genericNamespaceLister{indexer: s.indexer, namespace: namespace, resource: s.resource}
+}
+
+func (s *genericLister) Get(name string) (runtime.Object, error) {
+	obj, exists, err := s.indexer.GetByKey(name)
+	if err != nil {
+		return nil, err
+	}
+	if !exists {
+		return nil, errors.NewNotFound(s.resource, name)
+	}
+	return obj.(runtime.Object), nil
+}
+
+type genericNamespaceLister struct {
+	indexer   Indexer
+	namespace string
+	resource  schema.GroupResource
+}
+
+func (s *genericNamespaceLister) List(selector labels.Selector) (ret []runtime.Object, err error) {
+	err = ListAllByNamespace(s.indexer, s.namespace, selector, func(m interface{}) {
+		ret = append(ret, m.(runtime.Object))
+	})
+	return ret, err
+}
+
+func (s *genericNamespaceLister) Get(name string) (runtime.Object, error) {
+	obj, exists, err := s.indexer.GetByKey(s.namespace + "/" + name)
+	if err != nil {
+		return nil, err
+	}
+	if !exists {
+		return nil, errors.NewNotFound(s.resource, name)
+	}
+	return obj.(runtime.Object), nil
+}

vendor/k8s.io/client-go/tools/cache/listwatch.go

@@ -0,0 +1,312 @@
+/*
+Copyright 2015 The Kubernetes 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 (
+	"context"
+
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/fields"
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/watch"
+	restclient "k8s.io/client-go/rest"
+	"k8s.io/client-go/util/watchlist"
+)
+
+// Lister is any object that knows how to perform an initial list.
+//
+// Ideally, all implementations of Lister should also implement ListerWithContext.
+type Lister interface {
+	// List should return a list type object; the Items field will be extracted, and the
+	// ResourceVersion field will be used to start the watch in the right place.
+	//
+	// Deprecated: use ListerWithContext.ListWithContext instead.
+	List(options metav1.ListOptions) (runtime.Object, error)
+}
+
+// ListerWithContext is any object that knows how to perform an initial list.
+type ListerWithContext interface {
+	// ListWithContext should return a list type object; the Items field will be extracted, and the
+	// ResourceVersion field will be used to start the watch in the right place.
+	ListWithContext(ctx context.Context, options metav1.ListOptions) (runtime.Object, error)
+}
+
+func ToListerWithContext(l Lister) ListerWithContext {
+	if l, ok := l.(ListerWithContext); ok {
+		return l
+	}
+	return listerWrapper{
+		parent: l,
+	}
+}
+
+type listerWrapper struct {
+	parent Lister
+}
+
+func (l listerWrapper) ListWithContext(ctx context.Context, options metav1.ListOptions) (runtime.Object, error) {
+	return l.parent.List(options)
+}
+
+// Watcher is any object that knows how to start a watch on a resource.
+//
+// Ideally, all implementations of Watcher should also implement WatcherWithContext.
+type Watcher interface {
+	// Watch should begin a watch at the specified version.
+	//
+	// If Watch returns an error, it should handle its own cleanup, including
+	// but not limited to calling Stop() on the watch, if one was constructed.
+	// This allows the caller to ignore the watch, if the error is non-nil.
+	//
+	// Deprecated: use WatcherWithContext.WatchWithContext instead.
+	Watch(options metav1.ListOptions) (watch.Interface, error)
+}
+
+// WatcherWithContext is any object that knows how to start a watch on a resource.
+type WatcherWithContext interface {
+	// WatchWithContext should begin a watch at the specified version.
+	//
+	// If Watch returns an error, it should handle its own cleanup, including
+	// but not limited to calling Stop() on the watch, if one was constructed.
+	// This allows the caller to ignore the watch, if the error is non-nil.
+	WatchWithContext(ctx context.Context, options metav1.ListOptions) (watch.Interface, error)
+}
+
+func ToWatcherWithContext(w Watcher) WatcherWithContext {
+	if w, ok := w.(WatcherWithContext); ok {
+		return w
+	}
+	return watcherWrapper{
+		parent: w,
+	}
+}
+
+type watcherWrapper struct {
+	parent Watcher
+}
+
+func (l watcherWrapper) WatchWithContext(ctx context.Context, options metav1.ListOptions) (watch.Interface, error) {
+	return l.parent.Watch(options)
+}
+
+// ListerWatcher is any object that knows how to perform an initial list and start a watch on a resource.
+//
+// Ideally, all implementations of ListerWatcher should also implement ListerWatcherWithContext.
+type ListerWatcher interface {
+	Lister
+	Watcher
+}
+
+// ListerWatcherWithContext is any object that knows how to perform an initial list and start a watch on a resource.
+type ListerWatcherWithContext interface {
+	ListerWithContext
+	WatcherWithContext
+}
+
+func ToListerWatcherWithContext(lw ListerWatcher) ListerWatcherWithContext {
+	if lw, ok := lw.(ListerWatcherWithContext); ok {
+		return lw
+	}
+	return listerWatcherWrapper{
+		ListerWithContext:  ToListerWithContext(lw),
+		WatcherWithContext: ToWatcherWithContext(lw),
+	}
+}
+
+type listerWatcherWrapper struct {
+	ListerWithContext
+	WatcherWithContext
+}
+type listWatcherWithWatchListSemanticsWrapper struct {
+	*ListWatch
+
+	// unsupportedWatchListSemantics indicates whether a client explicitly does NOT support
+	// WatchList semantics.
+	//
+	// Over the years, unit tests in kube have been written in many different ways.
+	// After enabling the WatchListClient feature by default, existing tests started failing.
+	// To avoid breaking lots of existing client-go users after upgrade,
+	// we introduced this field as an opt-in.
+	//
+	// When true, the reflector disables WatchList even if the feature gate is enabled.
+	unsupportedWatchListSemantics bool
+}
+
+func (lw *listWatcherWithWatchListSemanticsWrapper) IsWatchListSemanticsUnSupported() bool {
+	return lw.unsupportedWatchListSemantics
+}
+
+// ToListWatcherWithWatchListSemantics returns a ListerWatcher
+// that knows whether the provided client explicitly
+// does NOT support the WatchList semantics. This allows Reflectors
+// to adapt their behavior based on client capabilities.
+func ToListWatcherWithWatchListSemantics(lw *ListWatch, client any) ListerWatcher {
+	return &listWatcherWithWatchListSemanticsWrapper{
+		lw,
+		watchlist.DoesClientNotSupportWatchListSemantics(client),
+	}
+}
+
+// ListFunc knows how to list resources
+//
+// Deprecated: use ListWithContextFunc instead.
+type ListFunc func(options metav1.ListOptions) (runtime.Object, error)
+
+// ListWithContextFunc knows how to list resources
+type ListWithContextFunc func(ctx context.Context, options metav1.ListOptions) (runtime.Object, error)
+
+// WatchFunc knows how to watch resources
+//
+// Deprecated: use WatchFuncWithContext instead.
+type WatchFunc func(options metav1.ListOptions) (watch.Interface, error)
+
+// WatchFuncWithContext knows how to watch resources
+type WatchFuncWithContext func(ctx context.Context, options metav1.ListOptions) (watch.Interface, error)
+
+// ListWatch knows how to list and watch a set of apiserver resources.
+// It satisfies the ListerWatcher and ListerWatcherWithContext interfaces.
+// It is a convenience function for users of NewReflector, etc.
+// ListFunc or ListWithContextFunc must be set. Same for WatchFunc and WatchFuncWithContext.
+// ListWithContextFunc and WatchFuncWithContext are preferred if
+// a context is available, otherwise ListFunc and WatchFunc.
+//
+// Beware of the inconsistent naming of the two WithContext methods.
+// This was unintentional, but fixing it now would force the ecosystem
+// to go through a breaking Go API change and was deemed not worth it.
+//
+// NewFilteredListWatchFromClient sets all of the functions to ensure that callers
+// which only know about ListFunc and WatchFunc continue to work.
+type ListWatch struct {
+	// Deprecated: use ListWithContext instead.
+	ListFunc ListFunc
+	// Deprecated: use WatchWithContext instead.
+	WatchFunc WatchFunc
+
+	ListWithContextFunc  ListWithContextFunc
+	WatchFuncWithContext WatchFuncWithContext
+
+	// DisableChunking requests no chunking for this list watcher.
+	DisableChunking bool
+}
+
+var (
+	_ ListerWatcher            = &ListWatch{}
+	_ ListerWatcherWithContext = &ListWatch{}
+)
+
+// Getter interface knows how to access Get method from RESTClient.
+type Getter interface {
+	Get() *restclient.Request
+}
+
+// NewListWatchFromClient creates a new ListWatch from the specified client, resource, namespace and field selector.
+// For backward compatibility, all function fields are populated.
+func NewListWatchFromClient(c Getter, resource string, namespace string, fieldSelector fields.Selector) *ListWatch {
+	optionsModifier := func(options *metav1.ListOptions) {
+		options.FieldSelector = fieldSelector.String()
+	}
+	return NewFilteredListWatchFromClient(c, resource, namespace, optionsModifier)
+}
+
+// NewFilteredListWatchFromClient creates a new ListWatch from the specified client, resource, namespace, and option modifier.
+// Option modifier is a function takes a ListOptions and modifies the consumed ListOptions. Provide customized modifier function
+// to apply modification to ListOptions with a field selector, a label selector, or any other desired options.
+// For backward compatibility, all function fields are populated.
+func NewFilteredListWatchFromClient(c Getter, resource string, namespace string, optionsModifier func(options *metav1.ListOptions)) *ListWatch {
+	listFunc := func(options metav1.ListOptions) (runtime.Object, error) {
+		optionsModifier(&options)
+		return c.Get().
+			Namespace(namespace).
+			Resource(resource).
+			VersionedParams(&options, metav1.ParameterCodec).
+			Do(context.Background()).
+			Get()
+	}
+	watchFunc := func(options metav1.ListOptions) (watch.Interface, error) {
+		options.Watch = true
+		optionsModifier(&options)
+		return c.Get().
+			Namespace(namespace).
+			Resource(resource).
+			VersionedParams(&options, metav1.ParameterCodec).
+			Watch(context.Background())
+	}
+	listFuncWithContext := func(ctx context.Context, options metav1.ListOptions) (runtime.Object, error) {
+		optionsModifier(&options)
+		return c.Get().
+			Namespace(namespace).
+			Resource(resource).
+			VersionedParams(&options, metav1.ParameterCodec).
+			Do(ctx).
+			Get()
+	}
+	watchFuncWithContext := func(ctx context.Context, options metav1.ListOptions) (watch.Interface, error) {
+		options.Watch = true
+		optionsModifier(&options)
+		return c.Get().
+			Namespace(namespace).
+			Resource(resource).
+			VersionedParams(&options, metav1.ParameterCodec).
+			Watch(ctx)
+	}
+	return &ListWatch{
+		ListFunc:             listFunc,
+		WatchFunc:            watchFunc,
+		ListWithContextFunc:  listFuncWithContext,
+		WatchFuncWithContext: watchFuncWithContext,
+	}
+}
+
+// List a set of apiserver resources
+//
+// Deprecated: use ListWatchWithContext.ListWithContext instead.
+func (lw *ListWatch) List(options metav1.ListOptions) (runtime.Object, error) {
+	// ListWatch is used in Reflector, which already supports pagination.
+	// Don't paginate here to avoid duplication.
+	if lw.ListFunc != nil {
+		return lw.ListFunc(options)
+	}
+	return lw.ListWithContextFunc(context.Background(), options)
+}
+
+// List a set of apiserver resources
+func (lw *ListWatch) ListWithContext(ctx context.Context, options metav1.ListOptions) (runtime.Object, error) {
+	// ListWatch is used in Reflector, which already supports pagination.
+	// Don't paginate here to avoid duplication.
+	if lw.ListWithContextFunc != nil {
+		return lw.ListWithContextFunc(ctx, options)
+	}
+	return lw.ListFunc(options)
+}
+
+// Watch a set of apiserver resources
+//
+// Deprecated: use ListWatchWithContext.WatchWithContext instead.
+func (lw *ListWatch) Watch(options metav1.ListOptions) (watch.Interface, error) {
+	if lw.WatchFunc != nil {
+		return lw.WatchFunc(options)
+	}
+	return lw.WatchFuncWithContext(context.Background(), options)
+}
+
+// Watch a set of apiserver resources
+func (lw *ListWatch) WatchWithContext(ctx context.Context, options metav1.ListOptions) (watch.Interface, error) {
+	if lw.WatchFuncWithContext != nil {
+		return lw.WatchFuncWithContext(ctx, options)
+	}
+	return lw.WatchFunc(options)
+}

vendor/k8s.io/client-go/tools/cache/mutation_cache.go

@@ -0,0 +1,264 @@
+/*
+Copyright 2017 The Kubernetes 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 (
+	"fmt"
+	"strconv"
+	"sync"
+	"time"
+
+	"k8s.io/klog/v2"
+
+	"k8s.io/apimachinery/pkg/api/meta"
+	"k8s.io/apimachinery/pkg/runtime"
+	utilcache "k8s.io/apimachinery/pkg/util/cache"
+	utilruntime "k8s.io/apimachinery/pkg/util/runtime"
+	"k8s.io/apimachinery/pkg/util/sets"
+)
+
+// MutationCache is able to take the result of update operations and stores them in an LRU
+// that can be used to provide a more current view of a requested object.  It requires interpreting
+// resourceVersions for comparisons.
+// Implementations must be thread-safe.
+// TODO find a way to layer this into an informer/lister
+type MutationCache interface {
+	GetByKey(key string) (interface{}, bool, error)
+	ByIndex(indexName, indexKey string) ([]interface{}, error)
+	Mutation(interface{})
+}
+
+// ResourceVersionComparator is able to compare object versions.
+type ResourceVersionComparator interface {
+	CompareResourceVersion(lhs, rhs runtime.Object) int
+}
+
+// NewIntegerResourceVersionMutationCache returns a MutationCache that understands how to
+// deal with objects that have a resource version that:
+//
+//   - is an integer
+//   - increases when updated
+//   - is comparable across the same resource in a namespace
+//
+// Most backends will have these semantics. Indexer may be nil. ttl controls how long an item
+// remains in the mutation cache before it is removed.
+//
+// If includeAdds is true, objects in the mutation cache will be returned even if they don't exist
+// in the underlying store. This is only safe if your use of the cache can handle mutation entries
+// remaining in the cache for up to ttl when mutations and deletes occur very closely in time.
+func NewIntegerResourceVersionMutationCache(logger klog.Logger, backingCache Store, indexer Indexer, ttl time.Duration, includeAdds bool) MutationCache {
+	return &mutationCache{
+		backingCache:  backingCache,
+		indexer:       indexer,
+		mutationCache: utilcache.NewLRUExpireCache(100),
+		comparator:    etcdObjectVersioner{},
+		ttl:           ttl,
+		includeAdds:   includeAdds,
+		logger:        logger,
+	}
+}
+
+// mutationCache doesn't guarantee that it returns values added via Mutation since they can page out and
+// since you can't distinguish between, "didn't observe create" and "was deleted after create",
+// if the key is missing from the backing cache, we always return it as missing
+type mutationCache struct {
+	logger        klog.Logger
+	lock          sync.Mutex
+	backingCache  Store
+	indexer       Indexer
+	mutationCache *utilcache.LRUExpireCache
+	includeAdds   bool
+	ttl           time.Duration
+
+	comparator ResourceVersionComparator
+}
+
+// GetByKey is never guaranteed to return back the value set in Mutation.  It could be paged out, it could
+// be older than another copy, the backingCache may be more recent or, you might have written twice into the same key.
+// You get a value that was valid at some snapshot of time and will always return the newer of backingCache and mutationCache.
+func (c *mutationCache) GetByKey(key string) (interface{}, bool, error) {
+	c.lock.Lock()
+	defer c.lock.Unlock()
+
+	obj, exists, err := c.backingCache.GetByKey(key)
+	if err != nil {
+		return nil, false, err
+	}
+	if !exists {
+		if !c.includeAdds {
+			// we can't distinguish between, "didn't observe create" and "was deleted after create", so
+			// if the key is missing, we always return it as missing
+			return nil, false, nil
+		}
+		obj, exists = c.mutationCache.Get(key)
+		if !exists {
+			return nil, false, nil
+		}
+	}
+	objRuntime, ok := obj.(runtime.Object)
+	if !ok {
+		return obj, true, nil
+	}
+	return c.newerObject(key, objRuntime), true, nil
+}
+
+// ByIndex returns the newer objects that match the provided index and indexer key.
+// Will return an error if no indexer was provided.
+func (c *mutationCache) ByIndex(name string, indexKey string) ([]interface{}, error) {
+	c.lock.Lock()
+	defer c.lock.Unlock()
+	if c.indexer == nil {
+		return nil, fmt.Errorf("no indexer has been provided to the mutation cache")
+	}
+	keys, err := c.indexer.IndexKeys(name, indexKey)
+	if err != nil {
+		return nil, err
+	}
+	var items []interface{}
+	keySet := sets.NewString()
+	for _, key := range keys {
+		keySet.Insert(key)
+		obj, exists, err := c.indexer.GetByKey(key)
+		if err != nil {
+			return nil, err
+		}
+		if !exists {
+			continue
+		}
+		if objRuntime, ok := obj.(runtime.Object); ok {
+			items = append(items, c.newerObject(key, objRuntime))
+		} else {
+			items = append(items, obj)
+		}
+	}
+
+	if c.includeAdds {
+		fn := c.indexer.GetIndexers()[name]
+		// Keys() is returned oldest to newest, so full traversal does not alter the LRU behavior
+		for _, key := range c.mutationCache.Keys() {
+			updated, ok := c.mutationCache.Get(key)
+			if !ok {
+				continue
+			}
+			if keySet.Has(key.(string)) {
+				continue
+			}
+			elements, err := fn(updated)
+			if err != nil {
+				c.logger.V(4).Info("Unable to calculate an index entry for mutation cache entry", "key", key, "err", err)
+				continue
+			}
+			for _, inIndex := range elements {
+				if inIndex != indexKey {
+					continue
+				}
+				items = append(items, updated)
+				break
+			}
+		}
+	}
+
+	return items, nil
+}
+
+// newerObject checks the mutation cache for a newer object and returns one if found. If the
+// mutated object is older than the backing object, it is removed from the  Must be
+// called while the lock is held.
+func (c *mutationCache) newerObject(key string, backing runtime.Object) runtime.Object {
+	mutatedObj, exists := c.mutationCache.Get(key)
+	if !exists {
+		return backing
+	}
+	mutatedObjRuntime, ok := mutatedObj.(runtime.Object)
+	if !ok {
+		return backing
+	}
+	if c.comparator.CompareResourceVersion(backing, mutatedObjRuntime) >= 0 {
+		c.mutationCache.Remove(key)
+		return backing
+	}
+	return mutatedObjRuntime
+}
+
+// Mutation adds a change to the cache that can be returned in GetByKey if it is newer than the backingCache
+// copy.  If you call Mutation twice with the same object on different threads, one will win, but its not defined
+// which one.  This doesn't affect correctness, since the GetByKey guaranteed of "later of these two caches" is
+// preserved, but you may not get the version of the object you want.  The object you get is only guaranteed to
+// "one that was valid at some point in time", not "the one that I want".
+func (c *mutationCache) Mutation(obj interface{}) {
+	c.lock.Lock()
+	defer c.lock.Unlock()
+
+	key, err := DeletionHandlingMetaNamespaceKeyFunc(obj)
+	if err != nil {
+		// this is a "nice to have", so failures shouldn't do anything weird
+		utilruntime.HandleErrorWithLogger(c.logger, err, "DeletionHandlingMetaNamespaceKeyFunc")
+		return
+	}
+
+	if objRuntime, ok := obj.(runtime.Object); ok {
+		if mutatedObj, exists := c.mutationCache.Get(key); exists {
+			if mutatedObjRuntime, ok := mutatedObj.(runtime.Object); ok {
+				if c.comparator.CompareResourceVersion(objRuntime, mutatedObjRuntime) < 0 {
+					return
+				}
+			}
+		}
+	}
+	c.mutationCache.Add(key, obj, c.ttl)
+}
+
+// etcdObjectVersioner implements versioning and extracting etcd node information
+// for objects that have an embedded ObjectMeta or ListMeta field.
+type etcdObjectVersioner struct{}
+
+// ObjectResourceVersion implements Versioner
+func (a etcdObjectVersioner) ObjectResourceVersion(obj runtime.Object) (uint64, error) {
+	accessor, err := meta.Accessor(obj)
+	if err != nil {
+		return 0, err
+	}
+	version := accessor.GetResourceVersion()
+	if len(version) == 0 {
+		return 0, nil
+	}
+	return strconv.ParseUint(version, 10, 64)
+}
+
+// CompareResourceVersion compares etcd resource versions.  Outside this API they are all strings,
+// but etcd resource versions are special, they're actually ints, so we can easily compare them.
+func (a etcdObjectVersioner) CompareResourceVersion(lhs, rhs runtime.Object) int {
+	lhsVersion, err := a.ObjectResourceVersion(lhs)
+	if err != nil {
+		// coder error
+		panic(err)
+	}
+	rhsVersion, err := a.ObjectResourceVersion(rhs)
+	if err != nil {
+		// coder error
+		panic(err)
+	}
+
+	if lhsVersion == rhsVersion {
+		return 0
+	}
+	if lhsVersion < rhsVersion {
+		return -1
+	}
+
+	return 1
+}

vendor/k8s.io/client-go/tools/cache/mutation_detector.go

@@ -0,0 +1,167 @@
+/*
+Copyright 2016 The Kubernetes 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 (
+	"fmt"
+	"os"
+	"reflect"
+	"strconv"
+	"sync"
+	"time"
+
+	"k8s.io/klog/v2"
+
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/util/diff"
+)
+
+var mutationDetectionEnabled = false
+
+func init() {
+	mutationDetectionEnabled, _ = strconv.ParseBool(os.Getenv("KUBE_CACHE_MUTATION_DETECTOR"))
+}
+
+// MutationDetector is able to monitor objects for mutation within a limited window of time
+type MutationDetector interface {
+	// AddObject adds the given object to the set being monitored for a while from now
+	AddObject(obj interface{})
+
+	// Run starts the monitoring and does not return until the monitoring is stopped.
+	Run(stopCh <-chan struct{})
+}
+
+// NewCacheMutationDetector creates a new instance for the defaultCacheMutationDetector.
+func NewCacheMutationDetector(name string) MutationDetector {
+	if !mutationDetectionEnabled {
+		return dummyMutationDetector{}
+	}
+	//nolint:logcheck // This code shouldn't be used in production.
+	klog.Warningln("Mutation detector is enabled, this will result in memory leakage.")
+	return &defaultCacheMutationDetector{name: name, period: 1 * time.Second, retainDuration: 2 * time.Minute}
+}
+
+type dummyMutationDetector struct{}
+
+func (dummyMutationDetector) Run(stopCh <-chan struct{}) {
+}
+func (dummyMutationDetector) AddObject(obj interface{}) {
+}
+
+// defaultCacheMutationDetector gives a way to detect if a cached object has been mutated
+// It has a list of cached objects and their copies.  I haven't thought of a way
+// to see WHO is mutating it, just that it's getting mutated.
+type defaultCacheMutationDetector struct {
+	name   string
+	period time.Duration
+
+	// compareLock ensures only a single call to CompareObjects runs at a time
+	compareObjectsLock sync.Mutex
+
+	// addLock guards addedObjs between AddObject and CompareObjects
+	addedObjsLock sync.Mutex
+	addedObjs     []cacheObj
+
+	cachedObjs []cacheObj
+
+	retainDuration     time.Duration
+	lastRotated        time.Time
+	retainedCachedObjs []cacheObj
+
+	// failureFunc is injectable for unit testing.  If you don't have it, the process will panic.
+	// This panic is intentional, since turning on this detection indicates you want a strong
+	// failure signal.  This failure is effectively a p0 bug and you can't trust process results
+	// after a mutation anyway.
+	failureFunc func(message string)
+}
+
+// cacheObj holds the actual object and a copy
+type cacheObj struct {
+	cached interface{}
+	copied interface{}
+}
+
+func (d *defaultCacheMutationDetector) Run(stopCh <-chan struct{}) {
+	// we DON'T want protection from panics.  If we're running this code, we want to die
+	for {
+		if d.lastRotated.IsZero() {
+			d.lastRotated = time.Now()
+		} else if time.Since(d.lastRotated) > d.retainDuration {
+			d.retainedCachedObjs = d.cachedObjs
+			d.cachedObjs = nil
+			d.lastRotated = time.Now()
+		}
+
+		d.CompareObjects()
+
+		select {
+		case <-stopCh:
+			return
+		case <-time.After(d.period):
+		}
+	}
+}
+
+// AddObject makes a deep copy of the object for later comparison.  It only works on runtime.Object
+// but that covers the vast majority of our cached objects
+func (d *defaultCacheMutationDetector) AddObject(obj interface{}) {
+	if _, ok := obj.(DeletedFinalStateUnknown); ok {
+		return
+	}
+	if obj, ok := obj.(runtime.Object); ok {
+		copiedObj := obj.DeepCopyObject()
+
+		d.addedObjsLock.Lock()
+		defer d.addedObjsLock.Unlock()
+		d.addedObjs = append(d.addedObjs, cacheObj{cached: obj, copied: copiedObj})
+	}
+}
+
+func (d *defaultCacheMutationDetector) CompareObjects() {
+	d.compareObjectsLock.Lock()
+	defer d.compareObjectsLock.Unlock()
+
+	// move addedObjs into cachedObjs under lock
+	// this keeps the critical section small to avoid blocking AddObject while we compare cachedObjs
+	d.addedObjsLock.Lock()
+	d.cachedObjs = append(d.cachedObjs, d.addedObjs...)
+	d.addedObjs = nil
+	d.addedObjsLock.Unlock()
+
+	altered := false
+	for i, obj := range d.cachedObjs {
+		if !reflect.DeepEqual(obj.cached, obj.copied) {
+			fmt.Printf("CACHE %s[%d] ALTERED!\n%v\n", d.name, i, diff.ObjectGoPrintSideBySide(obj.cached, obj.copied))
+			altered = true
+		}
+	}
+	for i, obj := range d.retainedCachedObjs {
+		if !reflect.DeepEqual(obj.cached, obj.copied) {
+			fmt.Printf("CACHE %s[%d] ALTERED!\n%v\n", d.name, i, diff.ObjectGoPrintSideBySide(obj.cached, obj.copied))
+			altered = true
+		}
+	}
+
+	if altered {
+		msg := fmt.Sprintf("cache %s modified", d.name)
+		if d.failureFunc != nil {
+			d.failureFunc(msg)
+			return
+		}
+		panic(msg)
+	}
+}

vendor/k8s.io/client-go/tools/cache/object-names.go

@@ -0,0 +1,65 @@
+/*
+Copyright 2023 The Kubernetes 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 (
+	"k8s.io/apimachinery/pkg/types"
+)
+
+// ObjectName is a reference to an object of some implicit kind
+type ObjectName struct {
+	Namespace string
+	Name      string
+}
+
+// NewObjectName constructs a new one
+func NewObjectName(namespace, name string) ObjectName {
+	return ObjectName{Namespace: namespace, Name: name}
+}
+
+// Parts is the inverse of the constructor
+func (objName ObjectName) Parts() (namespace, name string) {
+	return objName.Namespace, objName.Name
+}
+
+// String returns the standard string encoding,
+// which is designed to match the historical behavior of MetaNamespaceKeyFunc.
+// Note this behavior is different from the String method of types.NamespacedName.
+func (objName ObjectName) String() string {
+	if len(objName.Namespace) > 0 {
+		return objName.Namespace + "/" + objName.Name
+	}
+	return objName.Name
+}
+
+// ParseObjectName tries to parse the standard encoding
+func ParseObjectName(str string) (ObjectName, error) {
+	var objName ObjectName
+	var err error
+	objName.Namespace, objName.Name, err = SplitMetaNamespaceKey(str)
+	return objName, err
+}
+
+// NamespacedNameAsObjectName rebrands the given NamespacedName as an ObjectName
+func NamespacedNameAsObjectName(nn types.NamespacedName) ObjectName {
+	return NewObjectName(nn.Namespace, nn.Name)
+}
+
+// AsNamespacedName rebrands as a NamespacedName
+func (objName ObjectName) AsNamespacedName() types.NamespacedName {
+	return types.NamespacedName{Namespace: objName.Namespace, Name: objName.Name}
+}

vendor/k8s.io/client-go/tools/cache/reflector_data_consistency_detector.go

@@ -0,0 +1,43 @@
+/*
+Copyright 2024 The Kubernetes 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 (
+	"context"
+
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/client-go/util/consistencydetector"
+)
+
+// checkWatchListDataConsistencyIfRequested performs a data consistency check only when
+// the KUBE_WATCHLIST_INCONSISTENCY_DETECTOR environment variable was set during a binary startup.
+//
+// The consistency check is meant to be enforced only in the CI, not in production.
+// The check ensures that data retrieved by the watch-list api call
+// is exactly the same as data received by the standard list api call against etcd.
+//
+// Note that this function will panic when data inconsistency is detected.
+// This is intentional because we want to catch it in the CI.
+func checkWatchListDataConsistencyIfRequested[T runtime.Object, U any](ctx context.Context, identity string, lastSyncedResourceVersion string, listFn consistencydetector.ListFunc[T], listItemTransformFunc func(interface{}) (interface{}, error), retrieveItemsFn consistencydetector.RetrieveItemsFunc[U]) {
+	if !consistencydetector.IsDataConsistencyDetectionForWatchListEnabled() {
+		return
+	}
+	// for informers we pass an empty ListOptions because
+	// listFn might be wrapped for filtering during informer construction.
+	consistencydetector.CheckDataConsistency(ctx, identity, lastSyncedResourceVersion, listFn, listItemTransformFunc, metav1.ListOptions{}, retrieveItemsFn)
+}

vendor/k8s.io/client-go/tools/cache/reflector_metrics.go

@@ -0,0 +1,89 @@
+/*
+Copyright 2016 The Kubernetes 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.
+*/
+
+// This file provides abstractions for setting the provider (e.g., prometheus)
+// of metrics.
+
+package cache
+
+import (
+	"sync"
+)
+
+// GaugeMetric represents a single numerical value that can arbitrarily go up
+// and down.
+type GaugeMetric interface {
+	Set(float64)
+}
+
+// CounterMetric represents a single numerical value that only ever
+// goes up.
+type CounterMetric interface {
+	Inc()
+}
+
+// SummaryMetric captures individual observations.
+type SummaryMetric interface {
+	Observe(float64)
+}
+
+type noopMetric struct{}
+
+func (noopMetric) Inc()            {}
+func (noopMetric) Dec()            {}
+func (noopMetric) Observe(float64) {}
+func (noopMetric) Set(float64)     {}
+
+// MetricsProvider generates various metrics used by the reflector.
+type MetricsProvider interface {
+	NewListsMetric(name string) CounterMetric
+	NewListDurationMetric(name string) SummaryMetric
+	NewItemsInListMetric(name string) SummaryMetric
+
+	NewWatchesMetric(name string) CounterMetric
+	NewShortWatchesMetric(name string) CounterMetric
+	NewWatchDurationMetric(name string) SummaryMetric
+	NewItemsInWatchMetric(name string) SummaryMetric
+
+	NewLastResourceVersionMetric(name string) GaugeMetric
+}
+
+type noopMetricsProvider struct{}
+
+func (noopMetricsProvider) NewListsMetric(name string) CounterMetric         { return noopMetric{} }
+func (noopMetricsProvider) NewListDurationMetric(name string) SummaryMetric  { return noopMetric{} }
+func (noopMetricsProvider) NewItemsInListMetric(name string) SummaryMetric   { return noopMetric{} }
+func (noopMetricsProvider) NewWatchesMetric(name string) CounterMetric       { return noopMetric{} }
+func (noopMetricsProvider) NewShortWatchesMetric(name string) CounterMetric  { return noopMetric{} }
+func (noopMetricsProvider) NewWatchDurationMetric(name string) SummaryMetric { return noopMetric{} }
+func (noopMetricsProvider) NewItemsInWatchMetric(name string) SummaryMetric  { return noopMetric{} }
+func (noopMetricsProvider) NewLastResourceVersionMetric(name string) GaugeMetric {
+	return noopMetric{}
+}
+
+var metricsFactory = struct {
+	metricsProvider MetricsProvider
+	setProviders    sync.Once
+}{
+	metricsProvider: noopMetricsProvider{},
+}
+
+// SetReflectorMetricsProvider sets the metrics provider
+func SetReflectorMetricsProvider(metricsProvider MetricsProvider) {
+	metricsFactory.setProviders.Do(func() {
+		metricsFactory.metricsProvider = metricsProvider
+	})
+}

vendor/k8s.io/client-go/tools/cache/retry_with_deadline.go

@@ -0,0 +1,78 @@
+/*
+Copyright 2022 The Kubernetes 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 (
+	"k8s.io/utils/clock"
+	"time"
+)
+
+type RetryWithDeadline interface {
+	After(error)
+	ShouldRetry() bool
+}
+
+type retryWithDeadlineImpl struct {
+	firstErrorTime   time.Time
+	lastErrorTime    time.Time
+	maxRetryDuration time.Duration
+	minResetPeriod   time.Duration
+	isRetryable      func(error) bool
+	clock            clock.Clock
+}
+
+func NewRetryWithDeadline(maxRetryDuration, minResetPeriod time.Duration, isRetryable func(error) bool, clock clock.Clock) RetryWithDeadline {
+	return &retryWithDeadlineImpl{
+		firstErrorTime:   time.Time{},
+		lastErrorTime:    time.Time{},
+		maxRetryDuration: maxRetryDuration,
+		minResetPeriod:   minResetPeriod,
+		isRetryable:      isRetryable,
+		clock:            clock,
+	}
+}
+
+func (r *retryWithDeadlineImpl) reset() {
+	r.firstErrorTime = time.Time{}
+	r.lastErrorTime = time.Time{}
+}
+
+func (r *retryWithDeadlineImpl) After(err error) {
+	if r.isRetryable(err) {
+		if r.clock.Now().Sub(r.lastErrorTime) >= r.minResetPeriod {
+			r.reset()
+		}
+
+		if r.firstErrorTime.IsZero() {
+			r.firstErrorTime = r.clock.Now()
+		}
+		r.lastErrorTime = r.clock.Now()
+	}
+}
+
+func (r *retryWithDeadlineImpl) ShouldRetry() bool {
+	if r.maxRetryDuration <= time.Duration(0) {
+		return false
+	}
+
+	if r.clock.Now().Sub(r.firstErrorTime) <= r.maxRetryDuration {
+		return true
+	}
+
+	r.reset()
+	return false
+}

vendor/k8s.io/client-go/tools/cache/store.go

@@ -0,0 +1,399 @@
+/*
+Copyright 2014 The Kubernetes 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"
+	"strings"
+
+	"k8s.io/apimachinery/pkg/api/meta"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+)
+
+// Store is a generic object storage and processing interface.  A
+// Store holds a map from string keys to accumulators, and has
+// operations to add, update, and delete a given object to/from the
+// accumulator currently associated with a given key.  A Store also
+// knows how to extract the key from a given object, so many operations
+// are given only the object.
+//
+// In the simplest Store implementations each accumulator is simply
+// the last given object, or empty after Delete, and thus the Store's
+// behavior is simple storage.
+//
+// Reflector knows how to watch a server and update a Store.  This
+// package provides a variety of implementations of Store.
+type Store interface {
+
+	// Add adds the given object to the accumulator associated with the given object's key
+	Add(obj interface{}) error
+
+	// Update updates the given object in the accumulator associated with the given object's key
+	Update(obj interface{}) error
+
+	// Delete deletes the given object from the accumulator associated with the given object's key
+	Delete(obj interface{}) error
+
+	// List returns a list of all the currently non-empty accumulators
+	List() []interface{}
+
+	// ListKeys returns a list of all the keys currently associated with non-empty accumulators
+	ListKeys() []string
+
+	// Get returns the accumulator associated with the given object's key
+	Get(obj interface{}) (item interface{}, exists bool, err error)
+
+	// GetByKey returns the accumulator associated with the given key
+	GetByKey(key string) (item interface{}, exists bool, err error)
+
+	// Replace will delete the contents of the store, using instead the
+	// given list. Store takes ownership of the list, you should not reference
+	// it after calling this function.
+	Replace([]interface{}, string) error
+
+	// Resync is meaningless in the terms appearing here but has
+	// meaning in some implementations that have non-trivial
+	// additional behavior (e.g., DeltaFIFO).
+	Resync() error
+}
+
+// TransactionType defines the type of a transaction operation. It is used to indicate whether
+// an object is being added, updated, or deleted.
+type TransactionType string
+
+const (
+	TransactionTypeAdd    TransactionType = "Add"
+	TransactionTypeUpdate TransactionType = "Update"
+	TransactionTypeDelete TransactionType = "Delete"
+)
+
+// Transaction represents a single operation or event in a process. It holds a generic Object
+// associated with the transaction and a Type indicating the kind of transaction being performed.
+type Transaction struct {
+	Object interface{}
+	Type   TransactionType
+}
+
+type TransactionStore interface {
+	// Transaction allows multiple operations to occur within a single lock acquisition to
+	// ensure progress can be made when there is contention.
+	Transaction(txns ...Transaction) *TransactionError
+}
+
+var _ error = &TransactionError{}
+
+type TransactionError struct {
+	SuccessfulIndices []int
+	TotalTransactions int
+	Errors            []error
+}
+
+func (t *TransactionError) Error() string {
+	return fmt.Sprintf("failed to execute (%d/%d) transactions failed due to: %v",
+		t.TotalTransactions-len(t.SuccessfulIndices), t.TotalTransactions, t.Errors)
+}
+
+// KeyFunc knows how to make a key from an object. Implementations should be deterministic.
+type KeyFunc func(obj interface{}) (string, error)
+
+// KeyError will be returned any time a KeyFunc gives an error; it includes the object
+// at fault.
+type KeyError struct {
+	Obj interface{}
+	Err error
+}
+
+// Error gives a human-readable description of the error.
+func (k KeyError) Error() string {
+	return fmt.Sprintf("couldn't create key for object %+v: %v", k.Obj, k.Err)
+}
+
+// Unwrap implements errors.Unwrap
+func (k KeyError) Unwrap() error {
+	return k.Err
+}
+
+// ExplicitKey can be passed to MetaNamespaceKeyFunc if you have the key for
+// the object but not the object itself.
+type ExplicitKey string
+
+// MetaNamespaceKeyFunc is a convenient default KeyFunc which knows how to make
+// keys for API objects which implement meta.Interface.
+// The key uses the format <namespace>/<name> unless <namespace> is empty, then
+// it's just <name>.
+//
+// Clients that want a structured alternative can use ObjectToName or MetaObjectToName.
+// Note: this would not be a client that wants a key for a Store because those are
+// necessarily strings.
+//
+// TODO maybe some day?: change Store to be keyed differently
+func MetaNamespaceKeyFunc(obj interface{}) (string, error) {
+	if key, ok := obj.(ExplicitKey); ok {
+		return string(key), nil
+	}
+	objName, err := ObjectToName(obj)
+	if err != nil {
+		return "", err
+	}
+	return objName.String(), nil
+}
+
+// ObjectToName returns the structured name for the given object,
+// if indeed it can be viewed as a metav1.Object.
+func ObjectToName(obj interface{}) (ObjectName, error) {
+	meta, err := meta.Accessor(obj)
+	if err != nil {
+		return ObjectName{}, fmt.Errorf("object has no meta: %v", err)
+	}
+	return MetaObjectToName(meta), nil
+}
+
+// MetaObjectToName returns the structured name for the given object
+func MetaObjectToName(obj metav1.Object) ObjectName {
+	if len(obj.GetNamespace()) > 0 {
+		return ObjectName{Namespace: obj.GetNamespace(), Name: obj.GetName()}
+	}
+	return ObjectName{Namespace: "", Name: obj.GetName()}
+}
+
+// SplitMetaNamespaceKey returns the namespace and name that
+// MetaNamespaceKeyFunc encoded into key.
+//
+// TODO: replace key-as-string with a key-as-struct so that this
+// packing/unpacking won't be necessary.
+func SplitMetaNamespaceKey(key string) (namespace, name string, err error) {
+	parts := strings.Split(key, "/")
+	switch len(parts) {
+	case 1:
+		// name only, no namespace
+		return "", parts[0], nil
+	case 2:
+		// namespace and name
+		return parts[0], parts[1], nil
+	}
+
+	return "", "", fmt.Errorf("unexpected key format: %q", key)
+}
+
+// `*cache` implements Indexer in terms of a ThreadSafeStore and an
+// associated KeyFunc.
+type cache struct {
+	// cacheStorage bears the burden of thread safety for the cache
+	cacheStorage ThreadSafeStore
+	// keyFunc is used to make the key for objects stored in and retrieved from items, and
+	// should be deterministic.
+	keyFunc KeyFunc
+	// Called with every object put in the cache.
+	transformer TransformFunc
+}
+
+var _ Store = &cache{}
+
+func (c *cache) Transaction(txns ...Transaction) *TransactionError {
+	txnStore, ok := c.cacheStorage.(ThreadSafeStoreWithTransaction)
+	if !ok {
+		return &TransactionError{
+			TotalTransactions: len(txns),
+			Errors: []error{
+				errors.New("transaction not supported"),
+			},
+		}
+	}
+	keyedTxns := make([]ThreadSafeStoreTransaction, 0, len(txns))
+	successfulIndices := make([]int, 0, len(txns))
+	errs := make([]error, 0)
+	for i := range txns {
+		txn := txns[i]
+		key, err := c.keyFunc(txn.Object)
+		if err != nil {
+			errs = append(errs, KeyError{txn.Object, err})
+			continue
+		}
+		successfulIndices = append(successfulIndices, i)
+		keyedTxns = append(keyedTxns, ThreadSafeStoreTransaction{txn, key})
+	}
+	txnStore.Transaction(keyedTxns...)
+	if len(errs) > 0 {
+		return &TransactionError{
+			SuccessfulIndices: successfulIndices,
+			TotalTransactions: len(txns),
+			Errors:            errs,
+		}
+	}
+	return nil
+}
+
+// Add inserts an item into the cache.
+func (c *cache) Add(obj interface{}) error {
+	key, err := c.keyFunc(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+	if c.transformer != nil {
+		obj, err = c.transformer(obj)
+		if err != nil {
+			return fmt.Errorf("transforming: %w", err)
+		}
+	}
+	c.cacheStorage.Add(key, obj)
+	return nil
+}
+
+// Update sets an item in the cache to its updated state.
+func (c *cache) Update(obj interface{}) error {
+	key, err := c.keyFunc(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+	if c.transformer != nil {
+		obj, err = c.transformer(obj)
+		if err != nil {
+			return fmt.Errorf("transforming: %w", err)
+		}
+	}
+	c.cacheStorage.Update(key, obj)
+	return nil
+}
+
+// Delete removes an item from the cache.
+func (c *cache) Delete(obj interface{}) error {
+	key, err := c.keyFunc(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+	c.cacheStorage.Delete(key)
+	return nil
+}
+
+// List returns a list of all the items.
+// List is completely threadsafe as long as you treat all items as immutable.
+func (c *cache) List() []interface{} {
+	return c.cacheStorage.List()
+}
+
+// ListKeys returns a list of all the keys of the objects currently
+// in the cache.
+func (c *cache) ListKeys() []string {
+	return c.cacheStorage.ListKeys()
+}
+
+// GetIndexers returns the indexers of cache
+func (c *cache) GetIndexers() Indexers {
+	return c.cacheStorage.GetIndexers()
+}
+
+// Index returns a list of items that match on the index function
+// Index is thread-safe so long as you treat all items as immutable
+func (c *cache) Index(indexName string, obj interface{}) ([]interface{}, error) {
+	return c.cacheStorage.Index(indexName, obj)
+}
+
+// IndexKeys returns the storage keys of the stored objects whose set of
+// indexed values for the named index includes the given indexed value.
+// The returned keys are suitable to pass to GetByKey().
+func (c *cache) IndexKeys(indexName, indexedValue string) ([]string, error) {
+	return c.cacheStorage.IndexKeys(indexName, indexedValue)
+}
+
+// ListIndexFuncValues returns the list of generated values of an Index func
+func (c *cache) ListIndexFuncValues(indexName string) []string {
+	return c.cacheStorage.ListIndexFuncValues(indexName)
+}
+
+// ByIndex returns the stored objects whose set of indexed values
+// for the named index includes the given indexed value.
+func (c *cache) ByIndex(indexName, indexedValue string) ([]interface{}, error) {
+	return c.cacheStorage.ByIndex(indexName, indexedValue)
+}
+
+func (c *cache) AddIndexers(newIndexers Indexers) error {
+	return c.cacheStorage.AddIndexers(newIndexers)
+}
+
+// Get returns the requested item, or sets exists=false.
+// Get is completely threadsafe as long as you treat all items as immutable.
+func (c *cache) Get(obj interface{}) (item interface{}, exists bool, err error) {
+	key, err := c.keyFunc(obj)
+	if err != nil {
+		return nil, false, KeyError{obj, err}
+	}
+	return c.GetByKey(key)
+}
+
+// GetByKey returns the request item, or exists=false.
+// GetByKey is completely threadsafe as long as you treat all items as immutable.
+func (c *cache) GetByKey(key string) (item interface{}, exists bool, err error) {
+	item, exists = c.cacheStorage.Get(key)
+	return item, exists, nil
+}
+
+// Replace will delete the contents of 'c', using instead the given list.
+// 'c' takes ownership of the list, you should not reference the list again
+// after calling this function.
+func (c *cache) Replace(list []interface{}, resourceVersion string) error {
+	items := make(map[string]interface{}, len(list))
+	for _, item := range list {
+		key, err := c.keyFunc(item)
+		if err != nil {
+			return KeyError{item, err}
+		}
+
+		if c.transformer != nil {
+			item, err = c.transformer(item)
+			if err != nil {
+				return fmt.Errorf("transforming: %w", err)
+			}
+		}
+		items[key] = item
+	}
+	c.cacheStorage.Replace(items, resourceVersion)
+	return nil
+}
+
+// Resync is meaningless for one of these
+func (c *cache) Resync() error {
+	return nil
+}
+
+type StoreOption = func(*cache)
+
+func WithTransformer(transformer TransformFunc) StoreOption {
+	return func(c *cache) {
+		c.transformer = transformer
+	}
+}
+
+// NewStore returns a Store implemented simply with a map and a lock.
+func NewStore(keyFunc KeyFunc, opts ...StoreOption) Store {
+	c := &cache{
+		cacheStorage: NewThreadSafeStore(Indexers{}, Indices{}),
+		keyFunc:      keyFunc,
+	}
+	for _, opt := range opts {
+		opt(c)
+	}
+	return c
+}
+
+// NewIndexer returns an Indexer implemented simply with a map and a lock.
+func NewIndexer(keyFunc KeyFunc, indexers Indexers) Indexer {
+	return &cache{
+		cacheStorage: NewThreadSafeStore(indexers, Indices{}),
+		keyFunc:      keyFunc,
+	}
+}

vendor/k8s.io/client-go/tools/cache/synctrack/lazy.go

@@ -0,0 +1,83 @@
+/*
+Copyright 2023 The Kubernetes 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 synctrack
+
+import (
+	"sync"
+	"sync/atomic"
+)
+
+// Lazy defers the computation of `Evaluate` to when it is necessary. It is
+// possible that Evaluate will be called in parallel from multiple goroutines.
+type Lazy[T any] struct {
+	Evaluate func() (T, error)
+
+	cache atomic.Pointer[cacheEntry[T]]
+}
+
+type cacheEntry[T any] struct {
+	eval   func() (T, error)
+	lock   sync.RWMutex
+	result *T
+}
+
+func (e *cacheEntry[T]) get() (T, error) {
+	if cur := func() *T {
+		e.lock.RLock()
+		defer e.lock.RUnlock()
+		return e.result
+	}(); cur != nil {
+		return *cur, nil
+	}
+
+	e.lock.Lock()
+	defer e.lock.Unlock()
+	if e.result != nil {
+		return *e.result, nil
+	}
+	r, err := e.eval()
+	if err == nil {
+		e.result = &r
+	}
+	return r, err
+}
+
+func (z *Lazy[T]) newCacheEntry() *cacheEntry[T] {
+	return &cacheEntry[T]{eval: z.Evaluate}
+}
+
+// Notify should be called when something has changed necessitating a new call
+// to Evaluate.
+func (z *Lazy[T]) Notify() { z.cache.Swap(z.newCacheEntry()) }
+
+// Get should be called to get the current result of a call to Evaluate. If the
+// current cached value is stale (due to a call to Notify), then Evaluate will
+// be called synchronously. If subsequent calls to Get happen (without another
+// Notify), they will all wait for the same return value.
+//
+// Error returns are not cached and will cause multiple calls to evaluate!
+func (z *Lazy[T]) Get() (T, error) {
+	e := z.cache.Load()
+	if e == nil {
+		// Since we don't force a constructor, nil is a possible value.
+		// If multiple Gets race to set this, the swap makes sure only
+		// one wins.
+		z.cache.CompareAndSwap(nil, z.newCacheEntry())
+		e = z.cache.Load()
+	}
+	return e.get()
+}

vendor/k8s.io/client-go/tools/cache/synctrack/synctrack.go

@@ -0,0 +1,120 @@
+/*
+Copyright 2022 The Kubernetes 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 synctrack contains utilities for helping controllers track whether
+// they are "synced" or not, that is, whether they have processed all items
+// from the informer's initial list.
+package synctrack
+
+import (
+	"sync"
+	"sync/atomic"
+
+	"k8s.io/apimachinery/pkg/util/sets"
+)
+
+// AsyncTracker helps propagate HasSynced in the face of multiple worker threads.
+type AsyncTracker[T comparable] struct {
+	UpstreamHasSynced func() bool
+
+	lock    sync.Mutex
+	waiting sets.Set[T]
+}
+
+// Start should be called prior to processing each key which is part of the
+// initial list.
+func (t *AsyncTracker[T]) Start(key T) {
+	t.lock.Lock()
+	defer t.lock.Unlock()
+	if t.waiting == nil {
+		t.waiting = sets.New[T](key)
+	} else {
+		t.waiting.Insert(key)
+	}
+}
+
+// Finished should be called when finished processing a key which was part of
+// the initial list. Since keys are tracked individually, nothing bad happens
+// if you call Finished without a corresponding call to Start. This makes it
+// easier to use this in combination with e.g. queues which don't make it easy
+// to plumb through the isInInitialList boolean.
+func (t *AsyncTracker[T]) Finished(key T) {
+	t.lock.Lock()
+	defer t.lock.Unlock()
+	if t.waiting != nil {
+		t.waiting.Delete(key)
+	}
+}
+
+// HasSynced returns true if the source is synced and every key present in the
+// initial list has been processed. This relies on the source not considering
+// itself synced until *after* it has delivered the notification for the last
+// key, and that notification handler must have called Start.
+func (t *AsyncTracker[T]) HasSynced() bool {
+	// Call UpstreamHasSynced first: it might take a lock, which might take
+	// a significant amount of time, and we can't hold our lock while
+	// waiting on that or a user is likely to get a deadlock.
+	if !t.UpstreamHasSynced() {
+		return false
+	}
+	t.lock.Lock()
+	defer t.lock.Unlock()
+	return t.waiting.Len() == 0
+}
+
+// SingleFileTracker helps propagate HasSynced when events are processed in
+// order (i.e. via a queue).
+type SingleFileTracker struct {
+	// Important: count is used with atomic operations so it must be 64-bit
+	// aligned, otherwise atomic operations will panic. Having it at the top of
+	// the struct will guarantee that, even on 32-bit arches.
+	// See https://pkg.go.dev/sync/atomic#pkg-note-BUG for more information.
+	count int64
+
+	UpstreamHasSynced func() bool
+}
+
+// Start should be called prior to processing each key which is part of the
+// initial list.
+func (t *SingleFileTracker) Start() {
+	atomic.AddInt64(&t.count, 1)
+}
+
+// Finished should be called when finished processing a key which was part of
+// the initial list. You must never call Finished() before (or without) its
+// corresponding Start(), that is a logic error that could cause HasSynced to
+// return a wrong value. To help you notice this should it happen, Finished()
+// will panic if the internal counter goes negative.
+func (t *SingleFileTracker) Finished() {
+	result := atomic.AddInt64(&t.count, -1)
+	if result < 0 {
+		panic("synctrack: negative counter; this logic error means HasSynced may return incorrect value")
+	}
+}
+
+// HasSynced returns true if the source is synced and every key present in the
+// initial list has been processed. This relies on the source not considering
+// itself synced until *after* it has delivered the notification for the last
+// key, and that notification handler must have called Start.
+func (t *SingleFileTracker) HasSynced() bool {
+	// Call UpstreamHasSynced first: it might take a lock, which might take
+	// a significant amount of time, and we don't want to then act on a
+	// stale count value.
+	if !t.UpstreamHasSynced() {
+		return false
+	}
+	return atomic.LoadInt64(&t.count) <= 0
+}

vendor/k8s.io/client-go/tools/cache/the_real_fifo.go

@@ -0,0 +1,526 @@
+/*
+Copyright 2025 The Kubernetes 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 (
+	"fmt"
+	"sync"
+	"time"
+
+	utilruntime "k8s.io/apimachinery/pkg/util/runtime"
+	"k8s.io/apimachinery/pkg/util/sets"
+	utiltrace "k8s.io/utils/trace"
+)
+
+// RealFIFOOptions is the configuration parameters for RealFIFO.
+type RealFIFOOptions struct {
+	// KeyFunction is used to figure out what key an object should have. (It's
+	// exposed in the returned RealFIFO's keyOf() method, with additional
+	// handling around deleted objects and queue state).
+	// Optional, the default is MetaNamespaceKeyFunc.
+	KeyFunction KeyFunc
+
+	// KnownObjects is expected to return a list of keys that the consumer of
+	// this queue "knows about". It is used to decide which items are missing
+	// when Replace() is called; 'Deleted' deltas are produced for the missing items.
+	// KnownObjects is required.
+	KnownObjects KeyListerGetter
+
+	// If set, will be called for objects before enqueueing them. Please
+	// see the comment on TransformFunc for details.
+	Transformer TransformFunc
+}
+
+const (
+	defaultBatchSize = 1000
+)
+
+var _ QueueWithBatch = &RealFIFO{}
+
+// RealFIFO is a Queue in which every notification from the Reflector is passed
+// in order to the Queue via Pop.
+// This means that it
+// 1. delivers notifications for items that have been deleted
+// 2. delivers multiple notifications per item instead of simply the most recent value
+type RealFIFO struct {
+	lock sync.RWMutex
+	cond sync.Cond
+
+	items []Delta
+
+	// populated is true if the first batch of items inserted by Replace() has been populated
+	// or Delete/Add/Update was called first.
+	populated bool
+	// initialPopulationCount is the number of items inserted by the first call of Replace()
+	initialPopulationCount int
+
+	// keyFunc is used to make the key used for queued item insertion and retrieval, and
+	// should be deterministic.
+	keyFunc KeyFunc
+
+	// knownObjects list keys that are "known" --- affecting Delete(),
+	// Replace(), and Resync()
+	knownObjects KeyListerGetter
+
+	// Indication the queue is closed.
+	// Used to indicate a queue is closed so a control loop can exit when a queue is empty.
+	// Currently, not used to gate any of CRUD operations.
+	closed bool
+
+	// Called with every object if non-nil.
+	transformer TransformFunc
+
+	// batchSize determines the maximum number of objects we can combine into a batch.
+	batchSize int
+}
+
+var (
+	_ = Queue(&RealFIFO{})             // RealFIFO is a Queue
+	_ = TransformingStore(&RealFIFO{}) // RealFIFO implements TransformingStore to allow memory optimizations
+)
+
+// Close the queue.
+func (f *RealFIFO) Close() {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	f.closed = true
+	f.cond.Broadcast()
+}
+
+// KeyOf exposes f's keyFunc, but also detects the key of a Deltas object or
+// DeletedFinalStateUnknown objects.
+func (f *RealFIFO) keyOf(obj interface{}) (string, error) {
+	if d, ok := obj.(Deltas); ok {
+		if len(d) == 0 {
+			return "", KeyError{obj, ErrZeroLengthDeltasObject}
+		}
+		obj = d.Newest().Object
+	}
+	if d, ok := obj.(Delta); ok {
+		obj = d.Object
+	}
+	if d, ok := obj.(DeletedFinalStateUnknown); ok {
+		return d.Key, nil
+	}
+	return f.keyFunc(obj)
+}
+
+// HasSynced returns true if an Add/Update/Delete are called first,
+// or the first batch of items inserted by Replace() has been popped.
+func (f *RealFIFO) HasSynced() bool {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	return f.hasSynced_locked()
+}
+
+// ignoring lint to reduce delta to the original for review.  It's ok adjust later.
+//
+//lint:file-ignore ST1003: should not use underscores in Go names
+func (f *RealFIFO) hasSynced_locked() bool {
+	return f.populated && f.initialPopulationCount == 0
+}
+
+// addToItems_locked appends to the delta list.
+func (f *RealFIFO) addToItems_locked(deltaActionType DeltaType, skipTransform bool, obj interface{}) error {
+	// we must be able to read the keys in order to determine whether the knownObjcts and the items
+	// in this FIFO overlap
+	_, err := f.keyOf(obj)
+	if err != nil {
+		return KeyError{obj, err}
+	}
+
+	// Every object comes through this code path once, so this is a good
+	// place to call the transform func.
+	//
+	// If obj is a DeletedFinalStateUnknown tombstone or the action is a Sync,
+	// then the object have already gone through the transformer.
+	//
+	// If the objects already present in the cache are passed to Replace(),
+	// the transformer must be idempotent to avoid re-mutating them,
+	// or coordinate with all readers from the cache to avoid data races.
+	// Default informers do not pass existing objects to Replace.
+	if f.transformer != nil {
+		_, isTombstone := obj.(DeletedFinalStateUnknown)
+		if !isTombstone && !skipTransform {
+			var err error
+			obj, err = f.transformer(obj)
+			if err != nil {
+				return err
+			}
+		}
+	}
+
+	f.items = append(f.items, Delta{
+		Type:   deltaActionType,
+		Object: obj,
+	})
+	f.cond.Broadcast()
+
+	return nil
+}
+
+// Add inserts an item, and puts it in the queue. The item is only enqueued
+// if it doesn't already exist in the set.
+func (f *RealFIFO) Add(obj interface{}) error {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+
+	f.populated = true
+	retErr := f.addToItems_locked(Added, false, obj)
+
+	return retErr
+}
+
+// Update is the same as Add in this implementation.
+func (f *RealFIFO) Update(obj interface{}) error {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+
+	f.populated = true
+	retErr := f.addToItems_locked(Updated, false, obj)
+
+	return retErr
+}
+
+// Delete removes an item. It doesn't add it to the queue, because
+// this implementation assumes the consumer only cares about the objects,
+// not the order in which they were created/added.
+func (f *RealFIFO) Delete(obj interface{}) error {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+
+	f.populated = true
+	retErr := f.addToItems_locked(Deleted, false, obj)
+
+	return retErr
+}
+
+// IsClosed checks if the queue is closed
+func (f *RealFIFO) IsClosed() bool {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+	return f.closed
+}
+
+// Pop waits until an item is ready and processes it. If multiple items are
+// ready, they are returned in the order in which they were added/updated.
+// The item is removed from the queue (and the store) before it is processed.
+// process function is called under lock, so it is safe
+// update data structures in it that need to be in sync with the queue.
+func (f *RealFIFO) Pop(process PopProcessFunc) (interface{}, error) {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+
+	for len(f.items) == 0 {
+		// When the queue is empty, invocation of Pop() is blocked until new item is enqueued.
+		// When Close() is called, the f.closed is set and the condition is broadcasted.
+		// Which causes this loop to continue and return from the Pop().
+		if f.closed {
+			return nil, ErrFIFOClosed
+		}
+
+		f.cond.Wait()
+	}
+
+	isInInitialList := !f.hasSynced_locked()
+	item := f.items[0]
+	// The underlying array still exists and references this object, so the object will not be garbage collected unless we zero the reference.
+	f.items[0] = Delta{}
+	f.items = f.items[1:]
+	if f.initialPopulationCount > 0 {
+		f.initialPopulationCount--
+	}
+
+	// Only log traces if the queue depth is greater than 10 and it takes more than
+	// 100 milliseconds to process one item from the queue.
+	// Queue depth never goes high because processing an item is locking the queue,
+	// and new items can't be added until processing finish.
+	// https://github.com/kubernetes/kubernetes/issues/103789
+	if len(f.items) > 10 {
+		id, _ := f.keyOf(item)
+		trace := utiltrace.New("RealFIFO Pop Process",
+			utiltrace.Field{Key: "ID", Value: id},
+			utiltrace.Field{Key: "Depth", Value: len(f.items)},
+			utiltrace.Field{Key: "Reason", Value: "slow event handlers blocking the queue"})
+		defer trace.LogIfLong(100 * time.Millisecond)
+	}
+
+	// we wrap in Deltas here to be compatible with preview Pop functions and those interpreting the return value.
+	err := process(Deltas{item}, isInInitialList)
+	return Deltas{item}, err
+}
+
+func (f *RealFIFO) PopBatch(process ProcessBatchFunc) error {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+
+	for len(f.items) == 0 {
+		// When the queue is empty, invocation of Pop() is blocked until new item is enqueued.
+		// When Close() is called, the f.closed is set and the condition is broadcasted.
+		// Which causes this loop to continue and return from the Pop().
+		if f.closed {
+			return ErrFIFOClosed
+		}
+
+		f.cond.Wait()
+	}
+
+	isInInitialList := !f.hasSynced_locked()
+	unique := sets.NewString()
+	deltas := make([]Delta, 0, min(len(f.items), f.batchSize))
+	// only bundle unique items into a batch
+	for i := 0; i < f.batchSize && i < len(f.items); i++ {
+		if f.initialPopulationCount > 0 && i >= f.initialPopulationCount {
+			break
+		}
+		item := f.items[i]
+		id, err := f.keyOf(item)
+		if err != nil {
+			// close the batch here if error happens
+			// TODO: log the error when RealFIFOOptions supports passing klog instance like deprecated DeltaFIFO
+			// still pop the broken item out of queue to be compatible with the non-batch behavior it should be safe
+			// when 1st element is broken, however for Nth broken element, there's possible risk that broken item
+			// still can be processed and broke the uniqueness of the batch unexpectedly.
+			deltas = append(deltas, item)
+			// The underlying array still exists and references this object, so the object will not be garbage collected unless we zero the reference.
+			f.items[i] = Delta{}
+			break
+		}
+		if unique.Has(id) {
+			break
+		}
+		unique.Insert(id)
+		deltas = append(deltas, item)
+		// The underlying array still exists and references this object, so the object will not be garbage collected unless we zero the reference.
+		f.items[i] = Delta{}
+	}
+	if f.initialPopulationCount > 0 {
+		f.initialPopulationCount -= len(deltas)
+	}
+	f.items = f.items[len(deltas):]
+
+	// Only log traces if the queue depth is greater than 10 and it takes more than
+	// 100 milliseconds to process one item from the queue (with a max of 1 second for the whole batch)
+	// Queue depth never goes high because processing an item is locking the queue,
+	// and new items can't be added until processing finish.
+	// https://github.com/kubernetes/kubernetes/issues/103789
+	if len(f.items) > 10 {
+		id, _ := f.keyOf(deltas[0])
+		trace := utiltrace.New("RealFIFO PopBatch Process",
+			utiltrace.Field{Key: "ID", Value: id},
+			utiltrace.Field{Key: "Depth", Value: len(f.items)},
+			utiltrace.Field{Key: "Reason", Value: "slow event handlers blocking the queue"},
+			utiltrace.Field{Key: "BatchSize", Value: len(deltas)})
+		defer trace.LogIfLong(min(100*time.Millisecond*time.Duration(len(deltas)), time.Second))
+	}
+
+	err := process(deltas, isInInitialList)
+	return err
+}
+
+// Replace
+// 1. finds those items in f.items that are not in newItems and creates synthetic deletes for them
+// 2. finds items in knownObjects that are not in newItems and creates synthetic deletes for them
+// 3. adds the newItems to the queue
+func (f *RealFIFO) Replace(newItems []interface{}, resourceVersion string) error {
+	f.lock.Lock()
+	defer f.lock.Unlock()
+
+	// determine the keys of everything we're adding.  We cannot add the items until after the synthetic deletes have been
+	// created for items that don't existing in newItems
+	newKeys := sets.Set[string]{}
+	for _, obj := range newItems {
+		key, err := f.keyOf(obj)
+		if err != nil {
+			return KeyError{obj, err}
+		}
+		newKeys.Insert(key)
+	}
+
+	queuedItems := f.items
+	queuedKeys := []string{}
+	lastQueuedItemForKey := map[string]Delta{}
+	for _, queuedItem := range queuedItems {
+		queuedKey, err := f.keyOf(queuedItem.Object)
+		if err != nil {
+			return KeyError{queuedItem.Object, err}
+		}
+
+		if _, seen := lastQueuedItemForKey[queuedKey]; !seen {
+			queuedKeys = append(queuedKeys, queuedKey)
+		}
+		lastQueuedItemForKey[queuedKey] = queuedItem
+	}
+
+	// all the deletes already in the queue are important. There are two cases
+	// 1. queuedItems has delete for key/X and newItems has replace for key/X.  This means the queued UID was deleted and a new one was created.
+	// 2. queuedItems has a delete for key/X and newItems does NOT have key/X.  This means the queued item was deleted.
+	// Do deletion detection against objects in the queue.
+	for _, queuedKey := range queuedKeys {
+		if newKeys.Has(queuedKey) {
+			continue
+		}
+
+		// Delete pre-existing items not in the new list.
+		// This could happen if watch deletion event was missed while
+		// disconnected from apiserver.
+		lastQueuedItem := lastQueuedItemForKey[queuedKey]
+		// if we've already got the item marked as deleted, no need to add another delete
+		if lastQueuedItem.Type == Deleted {
+			continue
+		}
+
+		// if we got here, then the last entry we have for the queued item is *not* a deletion and we need to add a delete
+		deletedObj := lastQueuedItem.Object
+
+		retErr := f.addToItems_locked(Deleted, true, DeletedFinalStateUnknown{
+			Key: queuedKey,
+			Obj: deletedObj,
+		})
+		if retErr != nil {
+			return fmt.Errorf("couldn't enqueue object: %w", retErr)
+		}
+	}
+
+	// Detect deletions for objects not present in the queue, but present in KnownObjects
+	knownKeys := f.knownObjects.ListKeys()
+	for _, knownKey := range knownKeys {
+		if newKeys.Has(knownKey) { // still present
+			continue
+		}
+		if _, inQueuedItems := lastQueuedItemForKey[knownKey]; inQueuedItems { // already added delete for these
+			continue
+		}
+
+		deletedObj, exists, err := f.knownObjects.GetByKey(knownKey)
+		if err != nil {
+			deletedObj = nil
+			utilruntime.HandleError(fmt.Errorf("error during lookup, placing DeleteFinalStateUnknown marker without object: key=%q, err=%w", knownKey, err))
+		} else if !exists {
+			deletedObj = nil
+			utilruntime.HandleError(fmt.Errorf("key does not exist in known objects store, placing DeleteFinalStateUnknown marker without object: key=%q", knownKey))
+		}
+		retErr := f.addToItems_locked(Deleted, false, DeletedFinalStateUnknown{
+			Key: knownKey,
+			Obj: deletedObj,
+		})
+		if retErr != nil {
+			return fmt.Errorf("couldn't enqueue object: %w", retErr)
+		}
+	}
+
+	// now that we have the deletes we need for items, we can add the newItems to the items queue
+	for _, obj := range newItems {
+		retErr := f.addToItems_locked(Replaced, false, obj)
+		if retErr != nil {
+			return fmt.Errorf("couldn't enqueue object: %w", retErr)
+		}
+	}
+
+	if !f.populated {
+		f.populated = true
+		f.initialPopulationCount = len(f.items)
+	}
+
+	return nil
+}
+
+// Resync will ensure that every object in the Store has its key in the queue.
+// This should be a no-op, because that property is maintained by all operations.
+func (f *RealFIFO) Resync() error {
+	// TODO this cannot logically be done by the FIFO, it can only be done by the indexer
+	f.lock.Lock()
+	defer f.lock.Unlock()
+
+	if f.knownObjects == nil {
+		return nil
+	}
+
+	keysInQueue := sets.Set[string]{}
+	for _, item := range f.items {
+		key, err := f.keyOf(item.Object)
+		if err != nil {
+			return KeyError{item, err}
+		}
+		keysInQueue.Insert(key)
+	}
+
+	knownKeys := f.knownObjects.ListKeys()
+	for _, knownKey := range knownKeys {
+		// If we are doing Resync() and there is already an event queued for that object,
+		// we ignore the Resync for it. This is to avoid the race, in which the resync
+		// comes with the previous value of object (since queueing an event for the object
+		// doesn't trigger changing the underlying store <knownObjects>.
+		if keysInQueue.Has(knownKey) {
+			continue
+		}
+
+		knownObj, exists, err := f.knownObjects.GetByKey(knownKey)
+		if err != nil {
+			utilruntime.HandleError(fmt.Errorf("unable to queue object for sync: key=%q, err=%w", knownKey, err))
+			continue
+		} else if !exists {
+			utilruntime.HandleError(fmt.Errorf("key does not exist in known objects store, unable to queue object for sync: key=%q", knownKey))
+			continue
+		}
+
+		retErr := f.addToItems_locked(Sync, true, knownObj)
+		if retErr != nil {
+			return fmt.Errorf("couldn't queue object: %w", err)
+		}
+	}
+
+	return nil
+}
+
+// Transformer implements the TransformingStore interface.
+func (f *RealFIFO) Transformer() TransformFunc {
+	return f.transformer
+}
+
+// NewRealFIFO returns a Store which can be used to queue up items to
+// process.
+func NewRealFIFO(keyFunc KeyFunc, knownObjects KeyListerGetter, transformer TransformFunc) *RealFIFO {
+	return NewRealFIFOWithOptions(RealFIFOOptions{
+		KeyFunction:  keyFunc,
+		KnownObjects: knownObjects,
+		Transformer:  transformer,
+	})
+}
+
+// NewRealFIFOWithOptions returns a Queue which can be used to process changes to
+// items. See also the comment on RealFIFO.
+func NewRealFIFOWithOptions(opts RealFIFOOptions) *RealFIFO {
+	if opts.KeyFunction == nil {
+		opts.KeyFunction = MetaNamespaceKeyFunc
+	}
+
+	if opts.KnownObjects == nil {
+		panic("coding error: knownObjects must be provided")
+	}
+
+	f := &RealFIFO{
+		items:        make([]Delta, 0, 10),
+		keyFunc:      opts.KeyFunction,
+		knownObjects: opts.KnownObjects,
+		transformer:  opts.Transformer,
+		batchSize:    defaultBatchSize,
+	}
+
+	f.cond.L = &f.lock
+	return f
+}

vendor/k8s.io/client-go/tools/cache/thread_safe_store.go

@@ -0,0 +1,432 @@
+/*
+Copyright 2014 The Kubernetes 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 (
+	"fmt"
+	"sync"
+	"time"
+
+	"k8s.io/apimachinery/pkg/util/sets"
+	utiltrace "k8s.io/utils/trace"
+)
+
+// ThreadSafeStore is an interface that allows concurrent indexed
+// access to a storage backend.  It is like Indexer but does not
+// (necessarily) know how to extract the Store key from a given
+// object.
+//
+// TL;DR caveats: you must not modify anything returned by Get or List as it will break
+// the indexing feature in addition to not being thread safe.
+//
+// The guarantees of thread safety provided by List/Get are only valid if the caller
+// treats returned items as read-only. For example, a pointer inserted in the store
+// through `Add` will be returned as is by `Get`. Multiple clients might invoke `Get`
+// on the same key and modify the pointer in a non-thread-safe way. Also note that
+// modifying objects stored by the indexers (if any) will *not* automatically lead
+// to a re-index. So it's not a good idea to directly modify the objects returned by
+// Get/List, in general.
+type ThreadSafeStore interface {
+	Add(key string, obj interface{})
+	Update(key string, obj interface{})
+	Delete(key string)
+	Get(key string) (item interface{}, exists bool)
+	List() []interface{}
+	ListKeys() []string
+	Replace(map[string]interface{}, string)
+	Index(indexName string, obj interface{}) ([]interface{}, error)
+	IndexKeys(indexName, indexedValue string) ([]string, error)
+	ListIndexFuncValues(name string) []string
+	ByIndex(indexName, indexedValue string) ([]interface{}, error)
+	GetIndexers() Indexers
+
+	// AddIndexers adds more indexers to this store. This supports adding indexes after the store already has items.
+	AddIndexers(newIndexers Indexers) error
+	// Resync is a no-op and is deprecated
+	Resync() error
+}
+
+// ThreadSafeStoreWithTransaction is a store that can batch execute multiple transactions.
+type ThreadSafeStoreWithTransaction interface {
+	ThreadSafeStore
+	// Transaction allows performing multiple writes in one call.
+	Transaction(fns ...ThreadSafeStoreTransaction)
+}
+
+// ThreadSafeStoreTransaction embeds a Transaction and includes the specific Key identifying the affected object.
+type ThreadSafeStoreTransaction struct {
+	Transaction
+	Key string
+}
+
+// storeIndex implements the indexing functionality for Store interface
+type storeIndex struct {
+	// indexers maps a name to an IndexFunc
+	indexers Indexers
+	// indices maps a name to an Index
+	indices Indices
+}
+
+func (i *storeIndex) reset() {
+	i.indices = Indices{}
+}
+
+func (i *storeIndex) getKeysFromIndex(indexName string, obj interface{}) (sets.Set[string], error) {
+	indexFunc := i.indexers[indexName]
+	if indexFunc == nil {
+		return nil, fmt.Errorf("Index with name %s does not exist", indexName)
+	}
+
+	indexedValues, err := indexFunc(obj)
+	if err != nil {
+		return nil, err
+	}
+	index := i.indices[indexName]
+
+	var storeKeySet sets.Set[string]
+	if len(indexedValues) == 1 {
+		// In majority of cases, there is exactly one value matching.
+		// Optimize the most common path - deduping is not needed here.
+		storeKeySet = index[indexedValues[0]]
+	} else {
+		// Need to de-dupe the return list.
+		// Since multiple keys are allowed, this can happen.
+		storeKeySet = sets.Set[string]{}
+		for _, indexedValue := range indexedValues {
+			for key := range index[indexedValue] {
+				storeKeySet.Insert(key)
+			}
+		}
+	}
+
+	return storeKeySet, nil
+}
+
+func (i *storeIndex) getKeysByIndex(indexName, indexedValue string) (sets.Set[string], error) {
+	indexFunc := i.indexers[indexName]
+	if indexFunc == nil {
+		return nil, fmt.Errorf("Index with name %s does not exist", indexName)
+	}
+
+	index := i.indices[indexName]
+	return index[indexedValue], nil
+}
+
+func (i *storeIndex) getIndexValues(indexName string) []string {
+	index := i.indices[indexName]
+	names := make([]string, 0, len(index))
+	for key := range index {
+		names = append(names, key)
+	}
+	return names
+}
+
+func (i *storeIndex) addIndexers(newIndexers Indexers) error {
+	oldKeys := sets.KeySet(i.indexers)
+	newKeys := sets.KeySet(newIndexers)
+
+	if oldKeys.HasAny(sets.List(newKeys)...) {
+		return fmt.Errorf("indexer conflict: %v", oldKeys.Intersection(newKeys))
+	}
+
+	for k, v := range newIndexers {
+		i.indexers[k] = v
+	}
+	return nil
+}
+
+// updateSingleIndex modifies the objects location in the named index:
+// - for create you must provide only the newObj
+// - for update you must provide both the oldObj and the newObj
+// - for delete you must provide only the oldObj
+// updateSingleIndex must be called from a function that already has a lock on the cache
+func (i *storeIndex) updateSingleIndex(name string, oldObj interface{}, newObj interface{}, key string) {
+	var oldIndexValues, indexValues []string
+	indexFunc, ok := i.indexers[name]
+	if !ok {
+		// Should never happen. Caller is responsible for ensuring this exists, and should call with lock
+		// held to avoid any races.
+		panic(fmt.Errorf("indexer %q does not exist", name))
+	}
+	if oldObj != nil {
+		var err error
+		oldIndexValues, err = indexFunc(oldObj)
+		if err != nil {
+			panic(fmt.Errorf("unable to calculate an index entry for key %q on index %q: %v", key, name, err))
+		}
+	} else {
+		oldIndexValues = oldIndexValues[:0]
+	}
+
+	if newObj != nil {
+		var err error
+		indexValues, err = indexFunc(newObj)
+		if err != nil {
+			panic(fmt.Errorf("unable to calculate an index entry for key %q on index %q: %v", key, name, err))
+		}
+	} else {
+		indexValues = indexValues[:0]
+	}
+
+	idx := i.indices[name]
+	if idx == nil {
+		idx = index{}
+		i.indices[name] = idx
+	}
+
+	if len(indexValues) == 1 && len(oldIndexValues) == 1 && indexValues[0] == oldIndexValues[0] {
+		// We optimize for the most common case where indexFunc returns a single value which has not been changed
+		return
+	}
+
+	for _, value := range oldIndexValues {
+		i.deleteKeyFromIndex(key, value, idx)
+	}
+	for _, value := range indexValues {
+		i.addKeyToIndex(key, value, idx)
+	}
+}
+
+// updateIndices modifies the objects location in the managed indexes:
+// - for create you must provide only the newObj
+// - for update you must provide both the oldObj and the newObj
+// - for delete you must provide only the oldObj
+// updateIndices must be called from a function that already has a lock on the cache
+func (i *storeIndex) updateIndices(oldObj interface{}, newObj interface{}, key string) {
+	for name := range i.indexers {
+		i.updateSingleIndex(name, oldObj, newObj, key)
+	}
+}
+
+func (i *storeIndex) addKeyToIndex(key, indexValue string, index index) {
+	set := index[indexValue]
+	if set == nil {
+		set = sets.Set[string]{}
+		index[indexValue] = set
+	}
+	set.Insert(key)
+}
+
+func (i *storeIndex) deleteKeyFromIndex(key, indexValue string, index index) {
+	set := index[indexValue]
+	if set == nil {
+		return
+	}
+	set.Delete(key)
+	// If we don't delete the set when zero, indices with high cardinality
+	// short lived resources can cause memory to increase over time from
+	// unused empty sets. See `kubernetes/kubernetes/issues/84959`.
+	if len(set) == 0 {
+		delete(index, indexValue)
+	}
+}
+
+// threadSafeMap implements ThreadSafeStore
+type threadSafeMap struct {
+	lock  sync.RWMutex
+	items map[string]interface{}
+
+	// index implements the indexing functionality
+	index *storeIndex
+}
+
+func (c *threadSafeMap) Transaction(txns ...ThreadSafeStoreTransaction) {
+	c.lock.Lock()
+	defer c.lock.Unlock()
+	trace := utiltrace.New("ThreadSafeMap Transaction Process",
+		utiltrace.Field{Key: "Size", Value: len(txns)},
+		utiltrace.Field{Key: "Reason", Value: "Slow batch process due to too many items"})
+	defer trace.LogIfLong(min(500*time.Millisecond*time.Duration(len(txns)), 5*time.Second))
+
+	for _, txn := range txns {
+		switch txn.Type {
+		case TransactionTypeAdd:
+			c.addLocked(txn.Key, txn.Object)
+		case TransactionTypeUpdate:
+			c.updateLocked(txn.Key, txn.Object)
+		case TransactionTypeDelete:
+			c.deleteLocked(txn.Key)
+		}
+	}
+}
+
+func (c *threadSafeMap) Add(key string, obj interface{}) {
+	c.Update(key, obj)
+}
+
+func (c *threadSafeMap) addLocked(key string, obj interface{}) {
+	c.updateLocked(key, obj)
+}
+
+func (c *threadSafeMap) Update(key string, obj interface{}) {
+	c.lock.Lock()
+	defer c.lock.Unlock()
+	c.updateLocked(key, obj)
+}
+
+func (c *threadSafeMap) updateLocked(key string, obj interface{}) {
+	oldObject := c.items[key]
+	c.items[key] = obj
+	c.index.updateIndices(oldObject, obj, key)
+}
+
+func (c *threadSafeMap) Delete(key string) {
+	c.lock.Lock()
+	defer c.lock.Unlock()
+	c.deleteLocked(key)
+}
+
+func (c *threadSafeMap) deleteLocked(key string) {
+	if obj, exists := c.items[key]; exists {
+		c.index.updateIndices(obj, nil, key)
+		delete(c.items, key)
+	}
+}
+
+func (c *threadSafeMap) Get(key string) (item interface{}, exists bool) {
+	c.lock.RLock()
+	defer c.lock.RUnlock()
+	item, exists = c.items[key]
+	return item, exists
+}
+
+func (c *threadSafeMap) List() []interface{} {
+	c.lock.RLock()
+	defer c.lock.RUnlock()
+	list := make([]interface{}, 0, len(c.items))
+	for _, item := range c.items {
+		list = append(list, item)
+	}
+	return list
+}
+
+// ListKeys returns a list of all the keys of the objects currently
+// in the threadSafeMap.
+func (c *threadSafeMap) ListKeys() []string {
+	c.lock.RLock()
+	defer c.lock.RUnlock()
+	list := make([]string, 0, len(c.items))
+	for key := range c.items {
+		list = append(list, key)
+	}
+	return list
+}
+
+func (c *threadSafeMap) Replace(items map[string]interface{}, resourceVersion string) {
+	c.lock.Lock()
+	defer c.lock.Unlock()
+	c.items = items
+
+	// rebuild any index
+	c.index.reset()
+	for key, item := range c.items {
+		c.index.updateIndices(nil, item, key)
+	}
+}
+
+// Index returns a list of items that match the given object on the index function.
+// Index is thread-safe so long as you treat all items as immutable.
+func (c *threadSafeMap) Index(indexName string, obj interface{}) ([]interface{}, error) {
+	c.lock.RLock()
+	defer c.lock.RUnlock()
+
+	storeKeySet, err := c.index.getKeysFromIndex(indexName, obj)
+	if err != nil {
+		return nil, err
+	}
+
+	list := make([]interface{}, 0, storeKeySet.Len())
+	for storeKey := range storeKeySet {
+		list = append(list, c.items[storeKey])
+	}
+	return list, nil
+}
+
+// ByIndex returns a list of the items whose indexed values in the given index include the given indexed value
+func (c *threadSafeMap) ByIndex(indexName, indexedValue string) ([]interface{}, error) {
+	c.lock.RLock()
+	defer c.lock.RUnlock()
+
+	set, err := c.index.getKeysByIndex(indexName, indexedValue)
+	if err != nil {
+		return nil, err
+	}
+	list := make([]interface{}, 0, set.Len())
+	for key := range set {
+		list = append(list, c.items[key])
+	}
+
+	return list, nil
+}
+
+// IndexKeys returns a list of the Store keys of the objects whose indexed values in the given index include the given indexed value.
+// IndexKeys is thread-safe so long as you treat all items as immutable.
+func (c *threadSafeMap) IndexKeys(indexName, indexedValue string) ([]string, error) {
+	c.lock.RLock()
+	defer c.lock.RUnlock()
+
+	set, err := c.index.getKeysByIndex(indexName, indexedValue)
+	if err != nil {
+		return nil, err
+	}
+	return sets.List(set), nil
+}
+
+func (c *threadSafeMap) ListIndexFuncValues(indexName string) []string {
+	c.lock.RLock()
+	defer c.lock.RUnlock()
+
+	return c.index.getIndexValues(indexName)
+}
+
+func (c *threadSafeMap) GetIndexers() Indexers {
+	return c.index.indexers
+}
+
+func (c *threadSafeMap) AddIndexers(newIndexers Indexers) error {
+	c.lock.Lock()
+	defer c.lock.Unlock()
+
+	if err := c.index.addIndexers(newIndexers); err != nil {
+		return err
+	}
+
+	// If there are already items, index them
+	for key, item := range c.items {
+		for name := range newIndexers {
+			c.index.updateSingleIndex(name, nil, item, key)
+		}
+	}
+
+	return nil
+}
+
+func (c *threadSafeMap) Resync() error {
+	// Nothing to do
+	return nil
+}
+
+// NewThreadSafeStore creates a new instance of ThreadSafeStore.
+func NewThreadSafeStore(indexers Indexers, indices Indices) ThreadSafeStore {
+	return &threadSafeMap{
+		items: map[string]interface{}{},
+		index: &storeIndex{
+			indexers: indexers,
+			indices:  indices,
+		},
+	}
+}

vendor/k8s.io/client-go/tools/cache/undelta_store.go

@@ -0,0 +1,89 @@
+/*
+Copyright 2015 The Kubernetes 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
+
+// UndeltaStore listens to incremental updates and sends complete state on every change.
+// It implements the Store interface so that it can receive a stream of mirrored objects
+// from Reflector.  Whenever it receives any complete (Store.Replace) or incremental change
+// (Store.Add, Store.Update, Store.Delete), it sends the complete state by calling PushFunc.
+// It is thread-safe.  It guarantees that every change (Add, Update, Replace, Delete) results
+// in one call to PushFunc, but sometimes PushFunc may be called twice with the same values.
+// PushFunc should be thread safe.
+type UndeltaStore struct {
+	Store
+	PushFunc func([]interface{})
+}
+
+// Assert that it implements the Store interface.
+var _ Store = &UndeltaStore{}
+
+// Add inserts an object into the store and sends complete state by calling PushFunc.
+// Note about thread safety.  The Store implementation (cache.cache) uses a lock for all methods.
+// In the functions below, the lock gets released and reacquired betweend the {Add,Delete,etc}
+// and the List.  So, the following can happen, resulting in two identical calls to PushFunc.
+// time            thread 1                  thread 2
+// 0               UndeltaStore.Add(a)
+// 1                                         UndeltaStore.Add(b)
+// 2               Store.Add(a)
+// 3                                         Store.Add(b)
+// 4               Store.List() -> [a,b]
+// 5                                         Store.List() -> [a,b]
+func (u *UndeltaStore) Add(obj interface{}) error {
+	if err := u.Store.Add(obj); err != nil {
+		return err
+	}
+	u.PushFunc(u.Store.List())
+	return nil
+}
+
+// Update sets an item in the cache to its updated state and sends complete state by calling PushFunc.
+func (u *UndeltaStore) Update(obj interface{}) error {
+	if err := u.Store.Update(obj); err != nil {
+		return err
+	}
+	u.PushFunc(u.Store.List())
+	return nil
+}
+
+// Delete removes an item from the cache and sends complete state by calling PushFunc.
+func (u *UndeltaStore) Delete(obj interface{}) error {
+	if err := u.Store.Delete(obj); err != nil {
+		return err
+	}
+	u.PushFunc(u.Store.List())
+	return nil
+}
+
+// Replace will delete the contents of current store, using instead the given list.
+// 'u' takes ownership of the list, you should not reference the list again
+// after calling this function.
+// The new contents complete state will be sent by calling PushFunc after replacement.
+func (u *UndeltaStore) Replace(list []interface{}, resourceVersion string) error {
+	if err := u.Store.Replace(list, resourceVersion); err != nil {
+		return err
+	}
+	u.PushFunc(u.Store.List())
+	return nil
+}
+
+// NewUndeltaStore returns an UndeltaStore implemented with a Store.
+func NewUndeltaStore(pushFunc func([]interface{}), keyFunc KeyFunc) *UndeltaStore {
+	return &UndeltaStore{
+		Store:    NewStore(keyFunc),
+		PushFunc: pushFunc,
+	}
+}