Update docs on ShallowEtagHeaderFilter with regards to ASYNC dispatches

[cdalexndr]

Affects: 5.2.0.RELEASE

Original issue: spring-projects/spring-boot#18931

Registering ShallowEtagHeaderFilter with default configuration breaks async web requests, causing timeouts:

    @Bean
    public Filter etagFilter() {
        return new ShallowEtagHeaderFilter();
    }

The correct configuration is:

@Bean
public FilterRegistrationBean<ShallowEtagHeaderFilter> etagFilter() {
    FilterRegistrationBean<ShallowEtagHeaderFilter> registration = new FilterRegistrationBean<>(new ShallowEtagHeaderFilter());
    registration.setDispatcherTypes(EnumSet.of(DispatcherType.REQUEST, DispatcherType.ASYNC));
    return registration;
}

Please update the documentation to include this configuration for async requests, or provide a way to automatically configure for async requests.

[rstoyanchev]

Actually, FilterRegistrationBean is a Spring Boot mechanism, so the Spring Framework reference isn't a good place for the above snippet.

In the Spring Framework we support a WebApplicationInitializer for DispatcherServlet setup. That lets you provide an array of Servlet Filter instances all of which are then automatically registered for ASYNC dispatches.

The thinking behind this is that a) DispatcherServlet has asyncSupported enabled by default so filters would fail on async requests if they didn't have this flag enabled too, and b) once asyncSupported is enabled it becomes a runtime decision and all filters must be able to decide for themselves and that's what the shouldNotFilterAsyncDispatch flag in OncePerRequestFilter is all about.

I hate bouncing this around but I'm afraid there is nothing further to do here. At best I see Spring Boot providing some guidance on using FilterRegistrationBean with regards to async, perhaps some general advice that ASYNC dispatches are safe to enable for any OncePerRequestFilter which will do the right thing at runtime and either participate or back off. Another option is to automatically add ASYNC to any OncePerRequestFilter at least.

/cc @wilkinsona

[wilkinsona]

We can take another look on the Boot side, but I do think it is worth noting somewhere in Framework that ShallowEtagHeaderFilter must be registered for async dispatches and that it will break if it is not. I don't think it's safe to make assumptions about how a user will register the filter. In addition to Boot's FilterRegistrationBean, a user could register it via web.xml or via a sub-class annotated with @WebFilter. In both cases the Servlet spec's default of only REQUEST will be used and there's nothing in the documentation for ShallowEtagHeaderFilter to help someone avoid that mistake.