Handlers for resuming only unmodified/idling/sleeping resources

[nolar]

Background

As discussed in #223 comments (#223 (comment) and below), there is one type of handlers is missing: when an operator restarts, it should process all the objects that existed before, but were neither updated, nor deleted.

Originally, this was a technical solution for @kopf.on.resume() handlers in #96. But then it was intentionally changed to #105 & 0.16 to make the resuming handlers for task/thread spawning, i.e. executed no matter what was the object's state on the operator startup (created/updated/deleted). And later fixed in #230 & 0.23rc1 to be actually executed as intended.

Goal

However, the use-case of "unmodified only" handlers is missing now, and cannot be simulated with any combination of the existing handlers.

Find a good name for it. @kopf.on.notice()? @kopf.on.recall()? @kopf.on.existence()? Anything else?

Add such a handler for "unmodified only" cases on the operator startup.

It must be triggered only if CREATE/UPDATE/DELETE cause reasons are not applicable. For all these causes, their relevant handlers will be executed, plus on-resume mixed-in handlers.

Related

A use-case described for these handlers (#223 (comment)) is basically a reconciliation, and may be related to #150 and #19.

In this case, however, the resource should be processed on the operator restarts — but should remain separated from the creation/update/deletion handlers for clarity, unlike @kopf.on.resume(), which is mixed in with all of them.

Implementation hints

This should be easy. First, see kopf.reactor.causation.Reason.RESUME — probably, must be renamed to something else to not be confused with the resuming handlers. Second, add a decorator in kopf.on with reason=WHATEVERITISNAMED, initial=True. This should be enough. Try in action. Add few tests (look for on.resume and Reason.RESUME tests). Add the docs.

[pshchelo]

first, thanks for your help with our use-case 👍

as for naming, I'd suggest on.exists, but whatever floats your boat :-)