Reactor-core: `firstWithValue` exposure of combination of error and empty sources only

[simonbasle]

Motivation

In the original issue #2173 part of the discussion was around how to expose the fact that all the sources either completed empty or with an error. The original plan was that if the operator was unable to produce an actual value, it should fail with NoSuchElementException e (which has been implemented) then allow to distinguish between error and empty sources via a Exceptions.unwrapMultiple(e.getCause()).

Unfortunately, it was instead implemented as a _suppressed_ exception rather than a cause, and this slipped past the review (#2363) 😢

This is clunkier from a usability perspective from the original plan:

Flux.firstWithValue(Flux.error(new IllegalStateException("boom")), Flux.empty())
    .onErrorResume(NoSuchElementException.class, nse -> {
        // boilerplate from there...
        Throwable[] suppressed = nse.getSuppressed();
        if (suppressed.length != 1) return Mono.error(nse);
        //...to there
        return Exceptions.unwrapMultiple(suppressed[0])
                         .stream()
                         .filter(NoSuchElementException.class::isInstance)
                         .findFirst()
                         .map(t -> Mono.just("has empty sources"))
                         .orElse(Mono.just("has only errors"));
    })

compared to:

Flux.firstWithValue(Flux.error(new IllegalStateException("boom")), Flux.empty())
    .onErrorResume(NoSuchElementException.class,
            nse -> Exceptions.unwrapMultiple(nse.getCause())
                             .stream()
                             .filter(NoSuchElementException.class::isInstance)
                             .findFirst()
                             .map(t -> Mono.just("has empty sources"))
                             .orElse(Mono.just("has only errors"))
    )

Desired solution

Since this behavior is technically not documented, can we get away with amending the behavior before officially documenting it?

Considered alternatives

1. Expose the composite through both getCause() and getSuppressed()[0] (but that implies some duplication when printing the stacktrace).
2. Keep it as is for the foreseeable future (throughout 3.4.x)

[simonbasle]

This was done primarily because NoSuchElementException has no constructor that takes a _cause_.
However, it is still possible to use iniCause(Throwable) right after construction, which would fix the issue.

[simonbasle]

cc @berry120 @camsteffen we think this is "undocumented behavior", hidden enough that we can get away with fixing it right now. pinging you as you are likely the first users of the feature, so don't rely on getting the detail per source for now 🙇

[berry120]

@simonbasle Good call, I think that's the right decision. Thanks very much for the heads up 👍