feat: add defaultFilters option to skip JOSDK internal update filters (#3438)

Signed-off-by: xstefank <xstefank122@gmail.com>

Author: xstefank

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/BaseConfigurationService.java

@@ -321,6 +321,8 @@ private <P extends HasMetadata> ResolvedControllerConfiguration<P> controllerCon
     var triggerReconcilerOnAllEvents =
         annotation != null && annotation.triggerReconcilerOnAllEvents();
 
+    var defaultFilters = annotation == null || annotation.defaultFilters();
+
     InformerConfiguration<P> informerConfig =
         InformerConfiguration.builder(resourceClass)
             .initFromAnnotation(annotation != null ? annotation.informer() : null, context)
@@ -341,7 +343,8 @@ private <P extends HasMetadata> ResolvedControllerConfiguration<P> controllerCon
         dependentFieldManager,
         this,
         informerConfig,
-        triggerReconcilerOnAllEvents);
+        triggerReconcilerOnAllEvents,
+        defaultFilters);
   }
 
   /**

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ControllerConfiguration.java

@@ -121,4 +121,8 @@ default boolean triggerReconcilerOnAllEvent() {
   default boolean triggerReconcilerOnAllEvents() {
     return false;
   }
+
+  default boolean isDefaultFilters() {
+    return true;
+  }
 }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ControllerConfigurationOverrider.java

@@ -46,6 +46,7 @@ public class ControllerConfigurationOverrider<R extends HasMetadata> {
   private Map<DependentResourceSpec, Object> configurations;
   private final InformerConfiguration<R>.Builder config;
   private boolean triggerReconcilerOnAllEvents;
+  private boolean defaultFilters;
 
   private ControllerConfigurationOverrider(ControllerConfiguration<R> original) {
     this.finalizer = original.getFinalizerName();
@@ -59,6 +60,7 @@ private ControllerConfigurationOverrider(ControllerConfiguration<R> original) {
     this.name = original.getName();
     this.fieldManager = original.fieldManager();
     this.triggerReconcilerOnAllEvents = original.triggerReconcilerOnAllEvents();
+    this.defaultFilters = original.isDefaultFilters();
   }
 
   public ControllerConfigurationOverrider<R> withFinalizer(String finalizer) {
@@ -186,6 +188,11 @@ public ControllerConfigurationOverrider<R> withTriggerReconcilerOnAllEvents(
     return this;
   }
 
+  public ControllerConfigurationOverrider<R> withDefaultFilters(boolean defaultFilters) {
+    this.defaultFilters = defaultFilters;
+    return this;
+  }
+
   /**
    * Sets a max page size limit when starting the informer. This will result in pagination while
    * populating the cache. This means that longer lists will take multiple requests to fetch. See
@@ -231,6 +238,7 @@ public ControllerConfiguration<R> build() {
         original.getConfigurationService(),
         config.buildForController(),
         triggerReconcilerOnAllEvents,
+        defaultFilters,
         original.getWorkflowSpec().orElse(null));
   }
 

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/config/ResolvedControllerConfiguration.java

@@ -45,6 +45,7 @@ public class ResolvedControllerConfiguration<P extends HasMetadata>
   private final ConfigurationService configurationService;
   private final String fieldManager;
   private final boolean triggerReconcilerOnAllEvents;
+  private final boolean defaultFilters;
   private WorkflowSpec workflowSpec;
 
   public ResolvedControllerConfiguration(ControllerConfiguration<P> other) {
@@ -61,6 +62,7 @@ public ResolvedControllerConfiguration(ControllerConfiguration<P> other) {
         other.getConfigurationService(),
         other.getInformerConfig(),
         other.triggerReconcilerOnAllEvents(),
+        other.isDefaultFilters(),
         other.getWorkflowSpec().orElse(null));
   }
 
@@ -77,6 +79,7 @@ public ResolvedControllerConfiguration(
       ConfigurationService configurationService,
       InformerConfiguration<P> informerConfig,
       boolean triggerReconcilerOnAllEvents,
+      boolean defaultFilters,
       WorkflowSpec workflowSpec) {
     this(
         name,
@@ -90,7 +93,8 @@ public ResolvedControllerConfiguration(
         fieldManager,
         configurationService,
         informerConfig,
-        triggerReconcilerOnAllEvents);
+        triggerReconcilerOnAllEvents,
+        defaultFilters);
     setWorkflowSpec(workflowSpec);
   }
 
@@ -106,7 +110,8 @@ protected ResolvedControllerConfiguration(
       String fieldManager,
       ConfigurationService configurationService,
       InformerConfiguration<P> informerConfig,
-      boolean triggerReconcilerOnAllEvents) {
+      boolean triggerReconcilerOnAllEvents,
+      boolean defaultFilters) {
     this.informerConfig = informerConfig;
     this.configurationService = configurationService;
     this.name = ControllerConfiguration.ensureValidName(name, associatedReconcilerClassName);
@@ -120,6 +125,7 @@ protected ResolvedControllerConfiguration(
         ControllerConfiguration.ensureValidFinalizerName(finalizer, getResourceTypeName());
     this.fieldManager = fieldManager;
     this.triggerReconcilerOnAllEvents = triggerReconcilerOnAllEvents;
+    this.defaultFilters = defaultFilters;
   }
 
   protected ResolvedControllerConfiguration(
@@ -139,7 +145,8 @@ protected ResolvedControllerConfiguration(
         null,
         configurationService,
         InformerConfiguration.builder(resourceClass).buildForController(),
-        false);
+        false,
+        true);
   }
 
   @Override
@@ -234,4 +241,9 @@ public String fieldManager() {
   public boolean triggerReconcilerOnAllEvents() {
     return triggerReconcilerOnAllEvents;
   }
+
+  @Override
+  public boolean isDefaultFilters() {
+    return defaultFilters;
+  }
 }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ControllerConfiguration.java

@@ -105,4 +105,15 @@ MaxReconciliationInterval maxReconciliationInterval() default
    * documentation for further details.
    */
   boolean triggerReconcilerOnAllEvents() default false;
+
+  /**
+   * When set to {@code false}, JOSDK will not apply its default internal update filters
+   * (generation- aware, finalizer-needed, marked-for-deletion) to the controller's event source.
+   * The user's {@link Informer#onUpdateFilter()} becomes the sole filter and has full control. To
+   * keep any of the default behavior, compose it explicitly using the static methods on {@link
+   * io.javaoperatorsdk.operator.processing.event.source.controller.InternalEventFilters}.
+   *
+   * @return whether JOSDK's internal update filters are applied
+   */
+  boolean defaultFilters() default true;
 }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/controller/ControllerEventSource.java

@@ -52,18 +52,24 @@ public ControllerEventSource(Controller<T> controller) {
     this.controller = controller;
 
     final var config = controller.getConfiguration();
-    OnUpdateFilter internalOnUpdateFilter =
-        onUpdateFinalizerNeededAndApplied(controller.useFinalizer(), config.getFinalizerName())
-            .or(onUpdateGenerationAware(config.isGenerationAware()))
-            .or(onUpdateMarkedForDeletion());
 
     // by default the on add should be processed in all cases regarding internal filters
     final var informerConfig = config.getInformerConfig();
     Optional.ofNullable(informerConfig.getOnAddFilter()).ifPresent(this::setOnAddFilter);
-    Optional.ofNullable(informerConfig.getOnUpdateFilter())
-        .ifPresentOrElse(
-            filter -> setOnUpdateFilter(filter.and(internalOnUpdateFilter)),
-            () -> setOnUpdateFilter(internalOnUpdateFilter));
+
+    if (config.isDefaultFilters()) {
+      OnUpdateFilter internalOnUpdateFilter =
+          defaultFilters(
+              controller.useFinalizer(), config.getFinalizerName(), config.isGenerationAware());
+      Optional.ofNullable(informerConfig.getOnUpdateFilter())
+          .ifPresentOrElse(
+              filter -> setOnUpdateFilter(filter.and(internalOnUpdateFilter)),
+              () -> setOnUpdateFilter(internalOnUpdateFilter));
+    } else {
+      var userFilter = informerConfig.getOnUpdateFilter();
+      setOnUpdateFilter(userFilter != null ? userFilter : (newResource, oldResource) -> true);
+    }
+
     Optional.ofNullable(informerConfig.getGenericFilter()).ifPresent(this::setGenericFilter);
     setControllerConfiguration(config);
   }

operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/controller/InternalEventFilters.java

@@ -22,15 +22,15 @@ public class InternalEventFilters {
 
   private InternalEventFilters() {}
 
-  static <T extends HasMetadata> OnUpdateFilter<T> onUpdateMarkedForDeletion() {
+  public static <T extends HasMetadata> OnUpdateFilter<T> onUpdateMarkedForDeletion() {
     // the old resource is checked since in corner cases users might still want to update the status
     // for a resource that is marked for deletion
 
     return (newResource, oldResource) ->
         !oldResource.isMarkedForDeletion() && newResource.isMarkedForDeletion();
   }
 
-  static <T extends HasMetadata> OnUpdateFilter<T> onUpdateGenerationAware(
+  public static <T extends HasMetadata> OnUpdateFilter<T> onUpdateGenerationAware(
       boolean generationAware) {
 
     return (newResource, oldResource) -> {
@@ -46,7 +46,7 @@ static <T extends HasMetadata> OnUpdateFilter<T> onUpdateGenerationAware(
     };
   }
 
-  static <T extends HasMetadata> OnUpdateFilter<T> onUpdateFinalizerNeededAndApplied(
+  public static <T extends HasMetadata> OnUpdateFilter<T> onUpdateFinalizerNeededAndApplied(
       boolean useFinalizer, String finalizerName) {
     return (newResource, oldResource) -> {
       if (useFinalizer) {
@@ -61,4 +61,11 @@ static <T extends HasMetadata> OnUpdateFilter<T> onUpdateFinalizerNeededAndAppli
       }
     };
   }
+
+  public static <T extends HasMetadata> OnUpdateFilter<T> defaultFilters(
+      boolean useFinalizer, String finalizerName, boolean generationAware) {
+    return InternalEventFilters.<T>onUpdateFinalizerNeededAndApplied(useFinalizer, finalizerName)
+        .or(onUpdateGenerationAware(generationAware))
+        .or(onUpdateMarkedForDeletion());
+  }
 }

operator-framework-core/src/test/java/io/javaoperatorsdk/operator/processing/event/source/controller/ControllerEventSourceTest.java

@@ -140,13 +140,44 @@ void callsBroadcastsOnResourceEvents() {
             eq(ResourceAction.UPDATED), eq(customResource1), eq(customResource1));
   }
 
+  @Test
+  void withoutDefaultFiltersUserFilterIsAppliedDirectly() {
+    TestCustomResource cr = TestUtils.testCustomResource();
+    cr.getMetadata().setFinalizers(List.of(FINALIZER));
+    cr.getMetadata().setGeneration(1L);
+
+    // Without default filters, only the user filter runs — no internal generation/finalizer checks.
+    // User filter accepts unconditionally, so the event passes even with same generation.
+    OnUpdateFilter<TestCustomResource> userFilter = (newRes, oldRes) -> true;
+    source = new ControllerEventSource<>(new TestController(null, userFilter, null, false));
+    setUpSource(source, true, controllerConfig);
+
+    source.handleEvent(ResourceAction.UPDATED, cr, cr, null);
+
+    verify(eventHandler, times(1)).handleEvent(any());
+  }
+
+  @Test
+  void withoutDefaultFiltersUserFilterCanRejectEvents() {
+    TestCustomResource cr = TestUtils.testCustomResource();
+
+    OnUpdateFilter<TestCustomResource> userFilter = (newRes, oldRes) -> false;
+    source = new ControllerEventSource<>(new TestController(null, userFilter, null, false));
+    setUpSource(source, true, controllerConfig);
+
+    source.handleEvent(ResourceAction.UPDATED, cr, cr, null);
+
+    verify(eventHandler, never()).handleEvent(any());
+  }
+
   @Test
   void filtersOutEventsOnAddAndUpdate() {
     TestCustomResource cr = TestUtils.testCustomResource();
 
     OnAddFilter<TestCustomResource> onAddFilter = (res) -> false;
     OnUpdateFilter<TestCustomResource> onUpdatePredicate = (res, res2) -> false;
-    source = new ControllerEventSource<>(new TestController(onAddFilter, onUpdatePredicate, null));
+    source =
+        new ControllerEventSource<>(new TestController(onAddFilter, onUpdatePredicate, null, true));
     setUpSource(source, true, controllerConfig);
 
     source.handleEvent(ResourceAction.ADDED, cr, null, null);
@@ -159,7 +190,7 @@ void filtersOutEventsOnAddAndUpdate() {
   void genericFilterFiltersOutAddUpdateAndDeleteEvents() {
     TestCustomResource cr = TestUtils.testCustomResource();
 
-    source = new ControllerEventSource<>(new TestController(null, null, res -> false));
+    source = new ControllerEventSource<>(new TestController(null, null, res -> false, true));
     setUpSource(source, true, controllerConfig);
 
     source.handleEvent(ResourceAction.ADDED, cr, null, null);
@@ -174,7 +205,7 @@ void ownUpdateEchoIsFilteredOutByEventFilter() throws InterruptedException {
     // End-to-end smoke for the event-filter wiring on the controller path: an event for our
     // own write must not propagate. Detail-level filter scenarios are covered in
     // EventingDetailTest / EventFilterSupportTest.
-    source = spy(new ControllerEventSource<>(new TestController(null, null, null)));
+    source = spy(new ControllerEventSource<>(new TestController(null, null, null, true)));
     setUpSource(source, true, controllerConfig);
     doReturn(Optional.empty()).when(source).get(any());
 
@@ -189,7 +220,7 @@ void ownUpdateEchoIsFilteredOutByEventFilter() throws InterruptedException {
   @Test
   void foreignUpdateDuringFilteringPropagatesAsUpdate() {
     // An external event during the filter window must surface (not be filtered as own).
-    source = spy(new ControllerEventSource<>(new TestController(null, null, null)));
+    source = spy(new ControllerEventSource<>(new TestController(null, null, null, true)));
     setUpSource(source, true, controllerConfig);
 
     var latch = sendForEventFilteringUpdate(2);
@@ -203,7 +234,7 @@ void foreignUpdateDuringFilteringPropagatesAsUpdate() {
   void deleteEventDuringFilteringPropagatesAsDelete() {
     // A DELETE arriving during the filter window must surface — the resource has gone,
     // so the filter must not silence it just because our own write is still tracking RVs.
-    source = spy(new ControllerEventSource<>(new TestController(null, null, null)));
+    source = spy(new ControllerEventSource<>(new TestController(null, null, null, true)));
     setUpSource(source, true, controllerConfig);
 
     var latch = sendForEventFilteringUpdate(2);
@@ -223,7 +254,7 @@ void deleteEventDuringFilteringPropagatesAsDelete() {
   void multipleForeignEventsDuringFilteringMergeIntoSingleEvent() {
     // Several external events during one filter window collapse into a single
     // synthesized event spanning prev → latest seen.
-    source = spy(new ControllerEventSource<>(new TestController(null, null, null)));
+    source = spy(new ControllerEventSource<>(new TestController(null, null, null, true)));
     setUpSource(source, true, controllerConfig);
 
     var latch = sendForEventFilteringUpdate(2);
@@ -266,17 +297,18 @@ private static class TestController extends Controller<TestCustomResource> {
     public TestController(
         OnAddFilter<TestCustomResource> onAddFilter,
         OnUpdateFilter<TestCustomResource> onUpdateFilter,
-        GenericFilter<TestCustomResource> genericFilter) {
+        GenericFilter<TestCustomResource> genericFilter,
+        boolean defaultFilters) {
       super(
           reconciler,
-          new TestConfiguration(true, onAddFilter, onUpdateFilter, genericFilter),
+          new TestConfiguration(true, onAddFilter, onUpdateFilter, genericFilter, defaultFilters),
           MockKubernetesClient.client(TestCustomResource.class));
     }
 
     public TestController(boolean generationAware) {
       super(
           reconciler,
-          new TestConfiguration(generationAware, null, null, null),
+          new TestConfiguration(generationAware, null, null, null, true),
           MockKubernetesClient.client(TestCustomResource.class));
     }
 
@@ -298,7 +330,8 @@ public TestConfiguration(
         boolean generationAware,
         OnAddFilter<TestCustomResource> onAddFilter,
         OnUpdateFilter<TestCustomResource> onUpdateFilter,
-        GenericFilter<TestCustomResource> genericFilter) {
+        GenericFilter<TestCustomResource> genericFilter,
+        boolean defaultFilters) {
       super(
           "test",
           generationAware,
@@ -316,7 +349,8 @@ public TestConfiguration(
               .withGenericFilter(genericFilter)
               .withComparableResourceVersions(true)
               .buildForController(),
-          false);
+          false,
+          defaultFilters);
     }
   }
 }