Add a WatchStreamExt trait for stream chaining

[clux]

From discussion with @teozkr after #698 in december.
This tries to solve the problem in a more generic way using Stream helpers.
A single example using it is included for now. Want to have some reviews before tidying this up properly. ..well, i had free time now, have tidied.

It was not trivial (but followed similar bits from tokio-stream following the StreamExt setup). it might not be the best way to do this, but every other path i tried failed.

EDIT: Note the methods in here were further renamed in #906 before the 0.72.0 release.

failed path

tried a smarter setup without having to reimplement `into_iter_applied` inlined into an `impl Stream` but i just couldn't get the types to line up. the `impl Stream` we get is opaque and cannot be put inside the struct `AppliesGen` ```rust #[pin_project] /// Stream returned by the [`Applies`](super::WatchStreamExt::watch_applies) method. #[must_use = "streams do nothing unless polled"] pub struct AppliesGen { #[pin] stream: St, phantom: PhantomData, } impl AppliesGen where K: Sized + Send + 'static, St: Stream, watcher::Error>> + 'static, { pub(super) fn new(st: St) -> Self { let stream = utils::try_flatten_applied(st); // opaque type :( AppliesGen { stream, phantom: PhantomData } } } impl Stream for AppliesGen where { type Item = Result;

fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<OptionSelf::Item> {
self.as_mut()
.project()
.stream
.poll_next(cx)
}
}

</p>
</details>

[codecov-commenter]

Codecov Report

Merging #899 (81ab1db) into master (f3eee32) will increase coverage by 0.25%.
The diff coverage is 91.66%.

@@            Coverage Diff             @@
##           master     #899      +/-   ##
==========================================
+ Coverage   70.35%   70.61%   +0.25%     
==========================================
  Files          62       64       +2     
  Lines        4291     4339      +48     
==========================================
+ Hits         3019     3064      +45     
- Misses       1272     1275       +3     

Impacted Files	Coverage Δ
kube-runtime/src/utils/mod.rs	17.64% <ø> (ø)
kube-runtime/src/utils/watch_ext.rs	0.00% <0.00%> (ø)
kube-runtime/src/utils/event_flatten.rs	97.77% <97.77%> (ø)
kube-runtime/src/wait.rs	70.00% <0.00%> (+2.00%)	⬆️

[nightkr]

This can be pin_mut! rather than boxed

[clux]

yeah, i am using it elsewhere. i just don't want to mix pin into the easy go-to example.

[nightkr]

All in all, minor implementation nits but much happier with the new API!

We should probably either delete the old flatteners, or turn them into (deprecated) aliases for the new trait methods.

[nightkr]

Happy to kill off try_flatten_* and merge this now then.

[clux]

I'm going to mark those as deprecated (with notice of removal in 0.75.0) and then update all the examples first.
Thanks for the great review!

[nightkr]

Deprecation is good enough to me.

[kazk]

Maybe it's just me, but WatchStreamExt::watch_applies and WatchStreamExt::watch_touches sounds kind of awkward.

applied_objects and touched_objects?

watcher(api, lp).applied_objects()
watcher(api, lp).touched_objects()

reflector(store, watcher(api, lp)).applied_objects()
trigger_with(watcher(api, lp).touched_objects(), |obj| {})

Or even just applied and touched?

[clux]

yeah, I personally like those better myself, even the short variants makes sense to me.
if not the short ones, then at the very least the _objects suffix is better than a watch prefix - which is almost implied by the trait.

[clux]

Raised a PR in #906 for this.