client-go: type-safe informers and indexers

All code using the result of the generated client-go Informer() (a
cache.SharedIndexInformer) constantly has to do type casts from "any" to the
actual type of the objects managed by the informer.

This is:
- annoying at best
- often done inconsistently (should failed type assertions be logged and if so,
  how?)
- a source of bugs (not handling FinalStateUnknown, not handling missing
  object, type in event handler not matching the type in the informer)

In contrast, the Lister() result *is* typed. It converts without a type check
in e.g. ResourceIndexer[T].List:

	err = cache.ListAllByNamespace(l.indexer, l.namespace, selector, func(m interface{}) {
		ret = append(ret, m.(T))
	})

This change here does the same wrapping for SharedIndexInformer, Indexer,
index functions and event handler support code. OnDelete is passed
a DeletedObject struct to cover the different scenarios that can occur
when reporting deletion (stale or even nil object!). Extracting key or
name from DeletedObject is guaranteed to never fail because the type-safe
API is restricted to types where the necessary meta data is guaranteed
to be available. This removes another class of tedious error checking.

While not strictly needed, aliases are generated for the generic types because
they are often shorter, easier to type (in particular with auto-complete) and
may help with avoiding an import of k8s.io/client-go/tools/cache.

This is a Go API break because all generated interfaces
change.

Kubernetes-commit: b83b3b39db5eee75af14cdb8d30cfc6899792ec2

pkg/generated/informers/externalversions/samplecontroller/v1alpha1/foo.go

@@ -34,12 +34,40 @@ import (
 )
 
 // FooInformer provides access to a shared informer and lister for
-// Foos.
+// Foos. Prefer using the type-safe variant (see [TypedFooInformer]).
 type FooInformer interface {
 	Informer() cache.SharedIndexInformer
 	Lister() samplecontrollerv1alpha1.FooLister
 }
 
+// TypedFooInformer provides access to a shared informer and lister for
+// Foos, including the type-safe TypedInformer variant.
+// It is a superset of FooInformer.
+type TypedFooInformer interface {
+	Informer() cache.SharedIndexInformer
+	TypedInformer() FooIndexInformer
+	Lister() samplecontrollerv1alpha1.FooLister
+}
+
+// FooIndexInformer is a wrapper around the underlying [cache.SharedIndexInformer]
+// with type-safe variants of several methods.
+type FooIndexInformer cache.TypedSharedIndexInformer[*apissamplecontrollerv1alpha1.Foo]
+
+// FooHandlerFuncs is a specialization of [cache.TypedResourceEventHandlerFuncs] for Foo.
+type FooHandlerFuncs = cache.TypedResourceEventHandlerFuncs[*apissamplecontrollerv1alpha1.Foo]
+
+// FooDetailedHandlerFuncs is a specialization of [cache.TypedResourceEventHandlerDetailedFuncs] for Foo.
+type FooDetailedHandlerFuncs = cache.TypedResourceEventHandlerDetailedFuncs[*apissamplecontrollerv1alpha1.Foo]
+
+// FooFilteringHandler is a specialization of [cache.TypedFilteringResourceEventHandler] for Foo.
+type FooFilteringHandler = cache.TypedFilteringResourceEventHandler[*apissamplecontrollerv1alpha1.Foo]
+
+// FooIndexers is a specialization of [cache.TypedIndexers] for Foo.
+type FooIndexers = cache.TypedIndexers[*apissamplecontrollerv1alpha1.Foo]
+
+// DeletedFoo is a specialization of [cache.DeletedObject] for Foo.
+type DeletedFoo = cache.DeletedObject[*apissamplecontrollerv1alpha1.Foo]
+
 type fooInformer struct {
 	factory          internalinterfaces.SharedInformerFactory
 	tweakListOptions internalinterfaces.TweakListOptionsFunc
@@ -49,25 +77,49 @@ type fooInformer struct {
 // NewFooInformer constructs a new informer for Foo type.
 // Always prefer using an informer factory to get a shared informer instead of getting an independent
 // one. This reduces memory footprint and number of connections to the server.
+// If you really need an independent one, prefer using the type-safe variant (see [NewTypedFooInformer]).
 func NewFooInformer(client versioned.Interface, namespace string, resyncPeriod time.Duration, indexers cache.Indexers) cache.SharedIndexInformer {
 	return NewFooInformerWithOptions(client, namespace, internalinterfaces.InformerOptions{ResyncPeriod: resyncPeriod, Indexers: indexers})
 }
 
+// NewTypedFooInformer constructs a new informer for Foo type.
+// Always prefer using an informer factory to get a shared informer instead of getting an independent
+// one. This reduces memory footprint and number of connections to the server.
+func NewTypedFooInformer(client versioned.Interface, namespace string, resyncPeriod time.Duration, indexers FooIndexers) FooIndexInformer {
+	return NewTypedFooInformerWithOptions(client, namespace, internalinterfaces.InformerOptions{ResyncPeriod: resyncPeriod, Indexers: cache.TypedIndexersToIndexers(indexers)})
+}
+
 // NewFilteredFooInformer constructs a new informer for Foo type.
 // Always prefer using an informer factory to get a shared informer instead of getting an independent
 // one. This reduces memory footprint and number of connections to the server.
+// If you really need an independent one, prefer using the type-safe variant (see [NewTypedFilteredFooInformer]).
 func NewFilteredFooInformer(client versioned.Interface, namespace string, resyncPeriod time.Duration, indexers cache.Indexers, tweakListOptions internalinterfaces.TweakListOptionsFunc) cache.SharedIndexInformer {
-	return NewFooInformerWithOptions(client, namespace, internalinterfaces.InformerOptions{ResyncPeriod: resyncPeriod, Indexers: indexers, TweakListOptions: tweakListOptions})
+	return NewTypedFooInformerWithOptions(client, namespace, internalinterfaces.InformerOptions{ResyncPeriod: resyncPeriod, Indexers: indexers, TweakListOptions: tweakListOptions})
+}
+
+// NewTypedFilteredFooInformer constructs a new informer for Foo type.
+// Always prefer using an informer factory to get a shared informer instead of getting an independent
+// one. This reduces memory footprint and number of connections to the server.
+func NewTypedFilteredFooInformer(client versioned.Interface, namespace string, resyncPeriod time.Duration, indexers FooIndexers, tweakListOptions internalinterfaces.TweakListOptionsFunc) FooIndexInformer {
+	return NewTypedFooInformerWithOptions(client, namespace, internalinterfaces.InformerOptions{ResyncPeriod: resyncPeriod, Indexers: cache.TypedIndexersToIndexers(indexers), TweakListOptions: tweakListOptions})
 }
 
 // NewFooInformerWithOptions constructs a new informer for Foo type with additional options.
 // Always prefer using an informer factory to get a shared informer instead of getting an independent
 // one. This reduces memory footprint and number of connections to the server.
+// If you really need an independent one, prefer using the type-safe variant (see [NewTypedFooInformerWithOptions]).
 func NewFooInformerWithOptions(client versioned.Interface, namespace string, options internalinterfaces.InformerOptions) cache.SharedIndexInformer {
+	return NewTypedFooInformerWithOptions(client, namespace, options)
+}
+
+// NewTypedFooInformerWithOptions constructs a new informer for Foo type with additional options.
+// Always prefer using an informer factory to get a shared informer instead of getting an independent
+// one. This reduces memory footprint and number of connections to the server.
+func NewTypedFooInformerWithOptions(client versioned.Interface, namespace string, options internalinterfaces.InformerOptions) FooIndexInformer {
 	gvr := schema.GroupVersionResource{Group: "samplecontroller.k8s.io", Version: "v1alpha1", Resource: "foos"}
 	identifier := options.InformerName.WithResource(gvr)
 	tweakListOptions := options.TweakListOptions
-	return cache.NewSharedIndexInformerWithOptions(
+	return cache.NewTypedSharedIndexInformer[*apissamplecontrollerv1alpha1.Foo](cache.NewSharedIndexInformerWithOptions(
 		cache.ToListWatcherWithWatchListSemantics(&cache.ListWatch{
 			ListFunc: func(opts v1.ListOptions) (runtime.Object, error) {
 				if tweakListOptions != nil {
@@ -100,17 +152,57 @@ func NewFooInformerWithOptions(client versioned.Interface, namespace string, opt
 			Indexers:     options.Indexers,
 			Identifier:   identifier,
 		},
-	)
+	))
 }
 
 func (f *fooInformer) defaultInformer(client versioned.Interface, resyncPeriod time.Duration) cache.SharedIndexInformer {
-	return NewFooInformerWithOptions(client, f.namespace, internalinterfaces.InformerOptions{ResyncPeriod: resyncPeriod, Indexers: cache.Indexers{cache.NamespaceIndex: cache.MetaNamespaceIndexFunc}, InformerName: f.factory.InformerName(), TweakListOptions: f.tweakListOptions})
+	return NewTypedFooInformerWithOptions(client, f.namespace, internalinterfaces.InformerOptions{ResyncPeriod: resyncPeriod, Indexers: cache.Indexers{cache.NamespaceIndex: cache.MetaNamespaceIndexFunc}, InformerName: f.factory.InformerName(), TweakListOptions: f.tweakListOptions})
 }
 
 func (f *fooInformer) Informer() cache.SharedIndexInformer {
-	return f.factory.InformerFor(&apissamplecontrollerv1alpha1.Foo{}, f.defaultInformer)
+	return f.TypedInformer()
+}
+
+func (f *fooInformer) TypedInformer() FooIndexInformer {
+	return cache.NewTypedSharedIndexInformer[*apissamplecontrollerv1alpha1.Foo](f.factory.InformerFor(&apissamplecontrollerv1alpha1.Foo{}, f.defaultInformer))
 }
 
 func (f *fooInformer) Lister() samplecontrollerv1alpha1.FooLister {
 	return samplecontrollerv1alpha1.NewFooLister(f.Informer().GetIndexer())
 }
+
+// ToTypedFooInformer converts an untyped informer into a TypedFooInformer.
+//
+// WARNING: this conversion is only safe if the informer handles objects of type
+// *Foo. If that is not the case, calling type-safe methods of the returned
+// TypedFooInformer leads to runtime panics. A safer alternative is to pass
+// around a TypedFooInformer instances that was obtained from a
+// SharedInformerFactory.
+func ToTypedFooInformer(informer FooInformer) TypedFooInformer {
+	if informer, ok := informer.(TypedFooInformer); ok {
+		return informer
+	}
+	return &fooTypedInformerAdapter{informer}
+}
+
+type fooTypedInformerAdapter struct {
+	FooInformer
+}
+
+func (a *fooTypedInformerAdapter) TypedInformer() FooIndexInformer {
+	return cache.NewTypedSharedIndexInformer[*apissamplecontrollerv1alpha1.Foo](a.Informer())
+}
+
+// ToFooIndexInformer converts an untyped informer into a FooIndexInformer.
+//
+// WARNING: this conversion is only safe if the informer handles objects of type
+// *Foo. If that is not the case, calling type-safe methods of the returned
+// FooIndexInformer leads to runtime panics. A safer alternative is to pass
+// around a FooIndexInformer instances that was obtained from a
+// SharedInformerFactory.
+func ToFooIndexInformer(informer cache.SharedIndexInformer) FooIndexInformer {
+	if informer, ok := informer.(FooIndexInformer); ok {
+		return informer
+	}
+	return cache.NewTypedSharedIndexInformer[*apissamplecontrollerv1alpha1.Foo](informer)
+}

pkg/generated/informers/externalversions/samplecontroller/v1alpha1/interface.go

@@ -25,7 +25,7 @@ import (
 // Interface provides access to all the informers in this group version.
 type Interface interface {
 	// Foos returns a FooInformer.
-	Foos() FooInformer
+	Foos() TypedFooInformer
 }
 
 type version struct {
@@ -39,7 +39,7 @@ func New(f internalinterfaces.SharedInformerFactory, namespace string, tweakList
 	return &version{factory: f, namespace: namespace, tweakListOptions: tweakListOptions}
 }
 
-// Foos returns a FooInformer.
-func (v *version) Foos() FooInformer {
+// Foos returns a TypedFooInformer.
+func (v *version) Foos() TypedFooInformer {
 	return &fooInformer{factory: v.factory, namespace: v.namespace, tweakListOptions: v.tweakListOptions}
 }