feat: resource operation support multiple update modes (#3491)

### Summary

  This reworks `ResourceOperations` into the primary, idiomatic API for create/update/patch operations that keep the informer cache read-after-write consistent **and** control how the resulting own event is handled. Every operation comes in a
  default flavor and an `Options`-taking flavor, so users can tune caching vs. own-event filtering per call.

  Own-event filtering is only correct when the framework can distinguish an own write from a concurrent third-party write. This PR makes that requirement explicit through a small strategy model (`Options` → `Mode`) and a pluggable `Matcher`
  framework with sensible per-operation defaults.

  ### `Options` / `Mode`

  - **`matchAndFilter(matcher)` / `matchAndFilterWithDefaultMatcher(updateType)`** — compare desired vs. actual (cached) state; skip the write entirely if they already match, otherwise write and filter the own event. This is the **default** for the
  update/patch methods and the most efficient option (filters *and* avoids a needless API call).
  - **`filterWithOptimisticLocking()`** — filter the own event; the write **must** use optimistic locking (a resourceVersion set), otherwise an `IllegalArgumentException` is thrown. Guarantees a concurrent change is rejected server-side rather than
  silently filtered out.
  - **`cacheOnly()`** — only cache the response (read-after-write consistency), no own-event filtering.
  - **`forceFilterEvents()`** — always filter (mostly internal; safe only when correctness is otherwise guaranteed).

  ### Matcher framework

  - New `Matcher` interface plus default matchers for every `UpdateType` (`UPDATE`, `SSA`, `JSON_PATCH`, `JSON_MERGE_PATCH`, and their `*_STATUS` variants), backed by `MatcherUtils`.
  - `GenericKubernetesResourceMatcher.matchStatus(...)` added to match only the `/status` subtree (tolerating server-added fields by default).

  ### Framework integration

  - **Finalizer handling** (`ReconciliationDispatcher`): the finalizer is now added with `cacheOnly` (its own event is no longer filtered), replacing the previous filter + `INSTANT_RESCHEDULE` so the finalizer-add event itself drives the follow-up
  reconcile.
  - **Primary `UpdateControl` writes** now use `cacheOnly`, trading one extra self-triggered reconcile for correctness (a concurrent spec change during a status patch can no longer be absorbed by the own-event filter).
  - **`KubernetesDependentResource`** create/SSA now use `forceFilterEvents()`.
  - `AbstractExternalDependentResource` persists explicit state through `resourceOperations().create(...)`.

  ### Tests & docs
  
  - New ITs covering the concurrency and read-after-write edge cases: `ResourceOperationsIT`, `SecondaryResourceOperationsIT`, `SpecChangeDuringStatusPatchIT`, `OwnSsaStatusUpdateIT`, plus expanded `ResourceOperationsTest`, `PatchMatchersTest`,
  `StatusMatchersTest`.
  - Adjusted existing tests to the new event cadence (e.g. `SubResourceUpdateIT`, `WorkflowMultipleActivationIT` now snapshot reconcile counts only after they stabilize).
  - Docs updated: `reconciler.md`, `v5-5-migration.md`, `v5-5-release.md`, and the read-after-write blog post.

  ### Notes / follow-ups

  - The `Options` API is marked `@Experimental` (API may change).
  - Default matchers are heuristics — reconcilers relying on them should be tested against their concrete resources, or supply a custom `Matcher`.

Signed-off-by: Attila Mészáros <a_meszaros@apple.com>

Author: csviri

.github/workflows/integration-tests.yml

@@ -27,7 +27,7 @@ jobs:
     name: Integration tests (${{ inputs.java-version }}, ${{ inputs.kube-version }}, ${{ inputs.http-client }})
     runs-on: ubuntu-latest
     continue-on-error: ${{ inputs.experimental }}
-    timeout-minutes: 40
+    timeout-minutes: 120
     steps:
       - uses: actions/checkout@v7
         with:

docs/content/en/blog/news/read-after-write-consistency.md

@@ -30,8 +30,8 @@ public UpdateControl<WebPage> reconcile(WebPage webPage, Context<WebPage> contex
 }
 ```
 
-In addition to that, the framework will automatically filter events for your own updates,
-so they don't trigger the reconciliation again.
+In addition to that, the framework will provide facilities to filter out
+events for own updates so they don't trigger the reconciliation again.
 
 {{% alert color=success %}}
 **This should significantly simplify controller development, and will make reconciliation
@@ -180,12 +180,6 @@ From this point the idea of the algorithm is very simple:
    the one in the TRC. If yes, evict the resource from the TRC.
 3. When the controller reads a resource from cache, it checks the TRC first, then falls back to the Informer's cache.
 
-The actual filtering of events for our own writes is more nuanced than a simple
-"evict on RV ≥ TRC version" rule — it is driven by a per-resource state machine
-that tracks in-flight writes and the events received around them. See
-[Filtering events for our own updates](#filtering-events-for-our-own-updates) below.
-    
-
 ```mermaid
 sequenceDiagram
     box rgba(50,108,229,0.1)
@@ -226,10 +220,31 @@ sequenceDiagram
 When we update a resource, the informer will eventually propagate an event that would trigger a reconciliation.
 In most cases, however, this is not desirable. Since we already have the up-to-date resource at that point,
 we want to be notified only when the change originates outside our reconciler.
-Therefore, in addition to caching the resource, we filter out events caused by our own updates.
+Therefore, in addition to caching the resource, provide utilities to so you can optimize the update/patch
+operations to filter out those events.
+
+See [ResourceOperations](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ResourceOperations.java#L49) 
+for details.
+
+```java
+public UpdateControl<WebPage> reconcile(WebPage webPage, Context<WebPage> context) {
+    
+    ConfigMap managedConfigMap = prepareConfigMap(webPage);
+    
+   // resource operation in this case will resource only if
+   // it does not match the actual, and will filter our the related event
+   context.resourceOperations().serverSideApply(managedConfigMap);
+
+   // UpdateControl.patchStatus would only cache the resource to
+   // filter out events too you have to use resourceOperations.
+   context.resourceOperations().serverSideApplyPrimaryStatus(alterStatusObject(webPage));
+   
+   return UpdateControl.noUpdate();
+}
+```
 
-Note that the implementation of this is relatively complex: while performing the update, we record all the
-events received in the meantime and decide whether to propagate them further once the update request completes.
+Note that the implementation of this is relatively complex and has some caveats:
+while performing the update, we record all the events received in the meantime and decide whether to propagate them further once the update request completes.
 
 This way, we significantly reduce the number of reconciliations, making the whole process much more efficient.  
 

docs/content/en/docs/documentation/reconciler.md

@@ -192,6 +192,42 @@ supports stronger guarantees, both for primary and secondary resources. If this
      they would otherwise look like own echoes, since the relist may have
      hidden events.
 
+#### Requesting event filtering and its correctness requirements
+
+Own-event filtering is only safe if the framework can tell an own write apart from a concurrent
+third-party write. This requires **either**:
+
+- a *matcher* to be provided (so a filtered event can be confirmed to reflect the desired state we
+  just wrote), **or**
+- the update to be done using *optimistic locking* (a resource version set on the written resource),
+  so a conflicting concurrent change is rejected by the API server rather than silently swallowed.
+
+`ResourceOperations` methods accept an `Options` argument to select the behavior; each maps to a
+`Mode`:
+
+- `Options.matchAndFilter(matcher)` / `Options.matchAndFilterWithDefaultMatcher(updateType)` — compare
+  the desired state to the actual (cached) state; if they already match, skip the write entirely,
+  otherwise write and filter the own event. This is the **default** for the server-side apply and
+  patch (JSON Patch / JSON Merge Patch) methods, and generally the most efficient option: it filters
+  the own event *and* avoids a request to the API server when nothing changed. Default matchers are
+  provided for every operation type, but they are heuristics — a workflow relying on them should be
+  tested against the concrete resources it manages, or a custom matcher supplied.
+- `Options.filterWithOptimisticLocking()` — filter the own event; the write must use optimistic
+  locking (a resource version set on the written resource), otherwise an `IllegalArgumentException`
+  is thrown. Requiring optimistic locking guarantees a concurrent third-party change is rejected by
+  the API server rather than being silently filtered out. The overloads taking a matcher /
+  `updateType` additionally skip the write when the desired state already matches. This match +
+  optimistic locking combination is the **default** for the PUT `update` / `updatePrimary` /
+  `updatePrimaryStatus` methods (a full PUT should not clobber a concurrent change).
+- `Options.cacheOnly()` — only cache the response (read-cache-after-write consistency), no own-event
+  filtering.
+- `Options.forceFilterEvents()` — always filter, regardless of optimistic locking. Only safe when
+  correctness is otherwise guaranteed (mostly for internal usage); a concurrent external update in
+  the filter window may otherwise be missed until the next resync.
+
+See the [`ResourceOperations`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ResourceOperations.java)
+and `ResourceOperations.Options` documentation for details.
+
 
 In order to benefit from these stronger guarantees, use [`ResourceOperations`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ResourceOperations.java)
 from the context of the reconciliation:   
@@ -208,20 +244,26 @@ public UpdateControl<WebPage> reconcile(WebPage webPage, Context<WebPage> contex
     var upToDateResource = context.getSecondaryResource(ConfigMap.class);
 
     makeStatusChanges(webPage);
-    
-    // built in update methods by default use this feature
+    // patches the status and caches the response (does not filter the own event by default, see below)
     return UpdateControl.patchStatus(webPage);
 }
 ```
 
-`UpdateControl` and `ErrorStatusUpdateControl` by default use this functionality, but you can also update your primary resource at any time during the reconciliation using `ResourceOperations`:
+{{% alert title="UpdateControl and event filtering" %}}
+Since v5.5, returning an `UpdateControl` (or `ErrorStatusUpdateControl`) updates the resource and
+keeps the cache read-after-write consistent, but by default it **no longer filters the own event** —
+the resulting update may an additional reconciliation (which should be idempotent). To also filter the own
+event, perform the update through `ResourceOperations` instead and return `UpdateControl.noUpdate()`.
+{{% /alert %}}
+
+You can update your primary resource at any time during the reconciliation using `ResourceOperations`:
 
 ```java 
 
 public UpdateControl<WebPage> reconcile(WebPage webPage, Context<WebPage> context) {
 
     makeStatusChanges(webPage);
-    // this is equivalent to UpdateControl.patchStatus(webpage)
+    // updates the status, filters the own event and skips the write if nothing changed
     context.resourceOperations().serverSideApplyPrimaryStatus(webPage);
     return UpdateControl.noUpdate();
 }

docs/content/en/docs/migration/v5-5-migration.md

@@ -0,0 +1,69 @@
+---
+title: Migrating from v5.4 to v5.5
+description: Migrating from v5.4 to v5.5
+---
+
+## No breaking API changes
+
+v5.5 does **not** contain breaking API changes: existing code compiles and continues to work without
+modification. There is, however, one **behavioral** change around own-event filtering that you should
+be aware of (see below).
+
+## `UpdateControl` no longer filters own events by default
+
+In previous versions, updating the primary resource (or its status) by returning an `UpdateControl`
+from the reconciler would filter out the event caused by that own update, so the write did not
+trigger an additional reconciliation. Unfortunately, in some edge cases this could lead an 
+incorrect behavior, thus filtering out events which should be propagated.
+
+More precisely in case where for example the spec part of the primary resource was updated, while
+controller patched the status, but that patch status was a no-op operation. Note that
+these no-op operations are causing issue, which should not be done in first place.
+From 5.5 we provide methods in `ResourceOperations` which allow only operations which are 
+correct.
+
+From v5.5, `UpdateControl` **no longer filters these own events by default**. Returning an
+`UpdateControl` still updates the resource and keeps the cache read-after-write consistent, but the
+resulting update event is now delivered like any other event, which may cause an additional
+reconciliation.
+
+This is safe (reconciliations are expected to be idempotent), but if you relied on the previous
+filtering — for example to avoid an extra reconciliation after a status update — use
+[`ResourceOperations`](https://github.com/operator-framework/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ResourceOperations.java)
+directly, which does filter own events.
+
+### Using `ResourceOperations` instead
+
+`ResourceOperations` is available from the reconciliation `Context` via
+`context.resourceOperations()`. Instead of returning an `UpdateControl`, perform the update through
+it and return `UpdateControl.noUpdate()`:
+
+```java
+// before (v5.4): the own status update event was filtered
+@Override
+public UpdateControl<MyResource> reconcile(MyResource resource, Context<MyResource> context) {
+  resource.setStatus(new MyStatus().setReady(true));
+  return UpdateControl.patchStatus(resource);
+}
+```
+
+```java
+// after (v5.5): filter the own event explicitly via ResourceOperations
+@Override
+public UpdateControl<MyResource> reconcile(MyResource resource, Context<MyResource> context) {
+  resource.setStatus(new MyStatus().setReady(true));
+  context.resourceOperations().serverSideApplyPrimaryStatus(resource);
+  return UpdateControl.noUpdate();
+}
+```
+
+`ResourceOperations` covers every update/patch strategy (server-side apply, update, JSON Patch, JSON
+Merge Patch) for both the whole resource and the status subresource, as well as their primary
+variants. By default these operations match the desired state against the actual (cached) state
+before writing and filter the own event, so they only issue a request to the Kubernetes API server
+when something actually changed.
+
+> **Note**: Safe own-event filtering requires either a matcher (used by default) or the update to be
+> done with optimistic locking. See the `ResourceOperations` and `ResourceOperations.Options`
+> documentation for the available modes, the correctness requirements, and the caveats of the
+> default matchers.