runtime: Add reconcile result finalizer

[darkowlzz]

Add runtime packages reconcile and object. reconcile package provides helpers for finalizing the result of reconciliation and create patch helper options based on the finalized results. object package provides helpers for reading and writing attributes of GitOps Toolkit objects (runtime.Object) without converting them to their actual types. This is used by reconcile while analyzing the results of reconciliation.

Background

In source-controller, internal/reconcile package provides helpers for summarizing the result of reconciliation and patching the mutated object at the end. It helps ensure that the status of the object is kstatus compliant and also takes into consideration other status attributes like status.lastHandledReconcileAt. It also handles logging and event recording the results after analyzing them.
All these did make the reconcilers to have consistent behavior and hide the complexity of result computation. But in order to use all these, the controllers need to adopt reconcile result abstraction, specific typed errors and custom status conditions such that the condition summary worked properly. These requirements may be too much to ask for simple controller with not too many sub-reconciliation steps.

HelmRepositoryOCI reconciler in source-controller is an example of a simple controller with simple status conditions (Ready, Reconciling and Stalled). In order to use the result summary and patching helpers described above, it'd have to add a lot of extra things which aren't necessary. In a way, it made the simple reconciler more complicated. To avoid using the existing helpers, HelmRepositoryOCI reconciler implemented all the final result computation and condition setting in-line, taking into consideration all the small details that the helpers handled. This showed an approach to make the tooling simpler such that a simple controller need not adopt all the complex requirements of the internal/reconcile package.

Package runtime/reconcile is a rewrite of the result computation and status condition setting based on the in-line result computation implementation in HelmRepositoryOCI reconciler with some more capabilities. It is also capable of working with complex conditions of different polarities and handle more different situations. Unlike the previous implementation, it does not handles patching of the object. The patching has to be done in the reconciler itself but it provides helpers to create patch helper options based on the computed results.
An example of the usage of this in HelmRepositoryOCI reconcile can be found in an experimental implementation . The results of swapping the in-line code with these new helpers remain the same. The results of the initial tests done months ago for status conditions are still the same, refer https://gist.github.com/darkowlzz/c5c86afb148ad06dc7c4cc8c6afcdaef .

This new helper should be good to use in other simpler controllers.

ResultFinalizer computes the final result of reconciliation. It is configured with what a successful reconciliation means to a particular reconciler, a success message to be used for successful reconciliation in the case of missing Ready condition on the object, and an optional list of conditions, which are used when a reconciler has complex conditions with varying polarities. The ResultFinalizer.Finalize() method takes the result of reconciliation (ctrl.Result, reconciliation error and the object being reconciled) and analyzes the input to determine a runtime result of reconciliation that's compliant with kstatus. It tries to automatically correct the results based on some known rules, respecting any logically correct values already set in the conditions. An example of the correction is if the status condition contains Reconciling=True, but ctrl.Result and error indicate a successful reconciliation, it'll remove the Reconciling condition from the status. Similarly, it won't allow Reconciling and Stalled condition to be on the status at the same time. Based on the input parameters, it'll determine the result and correctly mutate the status and the reconciliation result.

Ref: fluxcd/flux2#1601
This has been used in image-reflector-controller refactor, refer fluxcd/image-reflector-controller#311.

[darkowlzz]

Rebased and marking this as ready. The work in fluxcd/image-reflector-controller#311 using this helped evaluate this and add some of the missing parts.

[stefanprodan]

LGTM

Thanks @darkowlzz 🏅

[pjbgf]

LGTM

nicely done @darkowlzz!