From fc0b069a6befb44f3b5d6bce0c622f9f0969b722 Mon Sep 17 00:00:00 2001 From: Patrick Ohly Date: Wed, 17 Jun 2026 16:13:15 +0200 Subject: [PATCH] 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 --- .../samplecontroller/v1alpha1/foo.go | 104 +++++++++++++++++- .../samplecontroller/v1alpha1/interface.go | 6 +- 2 files changed, 101 insertions(+), 9 deletions(-) diff --git a/pkg/generated/informers/externalversions/samplecontroller/v1alpha1/foo.go b/pkg/generated/informers/externalversions/samplecontroller/v1alpha1/foo.go index 67436566..d948ccb6 100644 --- a/pkg/generated/informers/externalversions/samplecontroller/v1alpha1/foo.go +++ b/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) +} diff --git a/pkg/generated/informers/externalversions/samplecontroller/v1alpha1/interface.go b/pkg/generated/informers/externalversions/samplecontroller/v1alpha1/interface.go index 403b0276..0fa0d026 100644 --- a/pkg/generated/informers/externalversions/samplecontroller/v1alpha1/interface.go +++ b/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} }