fix #178 by introducing a BuilderAllowSpec intermediate step in the builder

[simonbasle]

This commit introduces a STATIC_INITIALIZER constant in BlockHound, so
it becomes easier to discover that the features relying on the
String methodName parameter can work with <clinit> for static
initializer.

Additionally, this is documented in the customization examples and
used in the StaticInitTest.

Fixes #178.

[simonbasle]

(oops, the branch is misnamed and should refer to #178 rather than 176)

[simonbasle]

cc @rstoyanchev @bsideup

[rstoyanchev]

I like the idea but could you please also add a paragraph in the Javadoc of allow and disallow that explicitly mentions this scenario?:

<p>To allow blocking in the static initializer block of a class, use the constant `{@link #STATIC_INITIALIZER} as the method name`.

[simonbasle]

I like the idea but could you please also add a paragraph in the Javadoc of allow and disallow that explicitly mentions this scenario?

Done 👍

[bsideup]

since this constant would never change (part of the JVM's spec), I do not feel that it makes sense to introduce it. We could keep the docs section (for both <clinit> and <init>), but the constant will only create an unnecessary noise in the public signature of this class.

[simonbasle]

I don't know. Mentioning the reserved method name in the doc indeed feels like a minimum viable solution, but feels slightly less user-friendly than providing a safe constant which can quickly be auto-completed. Would it limit the noise drawback if the constant was defined in Builder instead of BlockHound? @rstoyanchev as a user, what do you think?

[rstoyanchev]

I also prefer an explicit API with documentation as a minimum. That said, thinking more about the constant it also gets slightly verbose with the class name included, and it's not automatically discoverable.

What about adding a sub-builder step:

builder
    .allowBlockingCallsInside("com.example.ClassA", "methodA")
    .allowBlockingCallsInside("com.example.ClassB").staticInitializers()
    .disallowBlockingCallsInside("com.example.ClassC").constructors();

The sub-builder something like:

interface BlockingCallSpec {

    BlockHound.Builder staticInitializers();

    BlockHound.Builder constructors();

}

Or perhaps an enum after all?

builder
    .allowBlockingCallsInside("com.example.ClassA", "methodA")
    .allowBlockingCallsInside("com.example.ClassB", BlockHound.TargetType.STATIC_INITIALIZER)
    .disallowBlockingCallsInside("com.example.ClassC", BlockHound.TargetType.CONSTRUCTORS);

[simonbasle]

exploring the builder idea in this PR and the enum in #184

[simonbasle]

@rstoyanchev @bsideup dc9186b introduces a BuilderAllowSpec. Since we only support static init for now, maybe it is a bit overkill. It would be even worse if we wanted to prevent going back to the Builder (via and()) without having configured at least one method first (as this would mean introducing 2 interfaces for the builder, so that .allowBlockingCallsInside("foo").and() isn't possible)

[rstoyanchev]

I don't see anything for "Disallow". Doesn't that need the same? The same builder could support both.

[simonbasle]

it could, but I wasn't able to test the disallow feature. Either I misunderstand it or there is something wrong with the feature (which isn't tested)... so for now I prefer to focus on the allow-static-initializer case which is demonstrably supported.

[bsideup]

@simonbasle re "disallow": see https://github.com/reactor/BlockHound/blob/master/docs/customization.md#dis-allowing-blocking-calls-inside-methods

[simonbasle]

I saw that and didn't find it crystal clear.
The following tests fail:

public class BlockingDisallowTest {

    static {
        BlockHound.install(b -> b
                .disallowBlockingCallsInside("reactor.core.publisher.Flux", "just")
                .disallowBlockingCallsInside(NonBlockingClass.class.getName(), "example")
        );
    }

    @Test
    public void shouldDisallowFluxJust() {
        assertThatExceptionOfType(RuntimeException.class)
                .isThrownBy(() ->
                        Mono.just("one")
                            .publishOn(Schedulers.parallel())
                            .flatMapMany(i -> Flux.just("one", "two"))
                            .blockLast()
                )
                .withCauseInstanceOf(BlockingOperationError.class);

    }

    @Test
    public void shouldDisallowNonBlocking() {
        NonBlockingClass nbc = new NonBlockingClass();

        assertThatExceptionOfType(RuntimeException.class)
                .isThrownBy(() ->
                        Mono.fromCallable(nbc::example)
                            .subscribeOn(Schedulers.parallel())
                            .block()
                )
                .withCauseInstanceOf(BlockingOperationError.class);
    }

    static class NonBlockingClass {

        String example() {
            return "example";
        }
    }
}

What am I missing?

[bsideup]

You seem to be missing how BlockHound works, see https://github.com/reactor/BlockHound/blob/master/docs/how_it_works.md and especially "Blocking call decision".

tl;dr: disallowBlockingCallsInside disallows blocking calls inside provided method (as per the API method's name). It does not, however, mark the method as blocking, so your Flux.just or NonBlockingClass.example makes no sense.

[bsideup]

I do not support the idea of adding DSL just for the sake of marking static constructors.
Also, disallowing should be supported.

Last but not least, it seems that static constructor is the only type of methods added by it, which only confirms that a dedicated DSL is an overkill