Provide and document a way to handle single-page application redirects

[gschjetne]

Affects: 5.3.8

---

The problem was previously discussed in #21328, but as @danbim pointed out, it's not a reliable solution as it overrides other routes in the application.

I tried to annotate the static resource bean with @Order(Ordered.LOWEST_PRECEDENCE), but that seems to only make it the lowest of the annotated beans, not lowest of all beans like it would need to be for this to work. I checked the documentation for ways to specify a custom error page instead of the white label one, and the only thing I could find was a static 404.html file, but as far as I can tell there is no way to change the status to 200.

This has been asked for countless of times on StackOverflow and similar places, and the answers range from completely wrong to completely ridiculous, like using regexes or explicit routes to catch everything that the front end might conceivably want to handle.

I'm suggesting that Spring as a back-end for SPAs is a common enough use case to warrant a reliable solution.

[gschjetne]

For reference, here's the best I could come up with, which if not wrong is still ridiculous, throwing loose coupling from dependency injection out the window, since you always have to remember which path prefixes to keep out:

import org.springframework.context.annotation.Bean
import org.springframework.core.io.ClassPathResource
import org.springframework.stereotype.Component
import org.springframework.web.reactive.function.server.RouterFunctions
import org.springframework.web.reactive.function.server.RouterFunctions.resources
import reactor.core.publisher.Mono

@Component
class Client {
    @Bean
    fun client() = resources { request ->
        val path = request.uri().path
        if (path.startsWith("/graphql") || path.startsWith("/auth")) {
            Mono.empty()
        } else {
            resourceLookup.apply(request)
        }
    }

    private val resourceLookup = RouterFunctions
        .resourceLookupFunction("/**", ClassPathResource("public/"))
        .andThen {
            it.switchIfEmpty(Mono.just(ClassPathResource("public/index.html")))
        }
}

[goatfryed]

I have a similar issue as described here, so I wanted to document my solution for everyone searching for the same issue.

Note that resourceLookupFunctions didn't solve the issue for me, because I wanted to be able to serve resources from outside the classpath in development mode via spring.web.resources.static-locations = path/to/frontend/dist

I ended up implementing a WebExceptionHandler. It works well for me so far.

@Component
@Order(-2)
public class HtmlRequestNotFoundHandler implements WebExceptionHandler {

    private final DispatcherHandler dispatcherHandler;

    private final RequestPredicate PREDICATE = RequestPredicates.accept(MediaType.TEXT_HTML);

    public HtmlRequestNotFoundHandler(DispatcherHandler dispatcherHandler) {
        this.dispatcherHandler = dispatcherHandler;
    }

    @Override
    public Mono<Void> handle(ServerWebExchange exchange, Throwable throwable) {
        if (
            isNotFoundAndShouldBeForwarded(exchange, throwable)
        ) {
            var forwardRequest = exchange.mutate().request(it -> it.path("/index.html"));
            return dispatcherHandler.handle(forwardRequest.build());
        }
        return Mono.error(throwable);
    }

    private boolean isNotFoundAndShouldBeForwarded(ServerWebExchange exchange, Throwable throwable) {
        if (throwable instanceof ResponseStatusException
            && ((ResponseStatusException) throwable).getStatusCode() == HttpStatus.NOT_FOUND
        ) {

            var serverRequest = ServerRequest.create(exchange, Collections.emptyList());
            return PREDICATE.test(serverRequest);
        }

        return false;
    }

}

[bclozel]

There are various solutions described out there and I agree they are all far from perfect. Most of them involve some kind of heuristics that try to describe front-end application routes in general (like @RequestMapping(value = "/**/{path:[^.]*}")) or by elimination (everything but /api/**). This can be achieved with filters, controller endpoints or functional routes - usually ordering is an issue as those route definitions match lots of URLs.

I think the main problem here is that the web framework has no way of knowing which routes are declared by the front-end application. Ideally, the back-end app should get a list of routes and patterns and forward those to the index page automatically. Without that, all other solutions will remain imperfect: false positives or maintenance issues.

As far as I know, other web frameworks from other languages have the same issue. Some front-end libraries send the Sec-Fetch-Mode: navigate header when navigating routes in the app but I don't think this would be covered by initial browser requests.

In summary, I don't think there's anything actionable right now for Spring.

[sdeleuze]

Given the traffic on SO for this kind of issues, I am wondering if we could at least try to provide a bit more guidance in our reference doc. I am also wondering if we could make some features already supported more discoverable.

See for example this SO answer from @dsyer, where this kind of configuration is proposed and voted massively:

public void addViewControllers(ViewControllerRegistry registry) {
    registry.addViewController("/").setViewName("forward:/index.html");
}

I think that's pretty useful for the need raised here, but:

• Very difficult to find this capability in our reference doc since you have to figure out combining View Controllers documentation + forwarding support
• forward: string prefix is not discoverable. Notice we provide a more discoverable addRedirectViewController() shortcut for redirects but not for forwards.
• Pretty sure most users are not even aware that patterns are supported for addViewController() string parameter.
• @EnableWebMvc likely disables Spring Boot index.html making users even more confused. Declaring a WebMvcConfigurer bean with @Bean allows to avoid this issue and can be documented on Framework side without Boot specifics.

Maybe we could:

• Add dedicated documentation for this use case in Spring MVC and Spring WebFlux (to be decided where)
• Spring MVC: forward redirects with some guidance to avoid the traps mentioned above, and document functional router as an alternative
• Discuss if we should add a more discoverable forward view method that does not require using forward: prefix
• Spring WebFlux: document functional router best practices for that use case if that's the preferred way to configure it
• Link and potentially complement that on Spring Boot side via Support client side routing out of the box spring-boot#27554

We can maybe discuss that during our next team meeting.

[dsyer]

All of those suggestions would be welcome (to me and to many I expect), but none of them actually nails the central requirement of being able to configure a fallback handler for requests that do not match other mappings (expect in a limited way possibly hinted at with the "patterns are supported" comment). I know why that is an unpopular idea, but it serves a purpose, and maybe we need to solve that problem as well? One suggestion I have that would reduce the unpopularity is to provide a fallback for only requests that can be identified in some way as browser-based and expecting HTML (content negotiation, agent identification, or something).

[sdeleuze]

I can see the initial appeal of the fallback approach, but in practice you will still have to define patterns, so not sure we would introduce such dedicated mechanism + forwarding transparently is pretty specific and hard to translate in term of programming model.

As pointed out by @bclozel, the right solution for that would probably be the frontend framework sharing client-side routes with the backend, but that's hard to provide as a builtin feature, would create a lot of coupling. And the headers set by the frontend framework will indeed not cover the initial request, which is IMO a blocker.

After a team related discussion, we are going to introduce a dedicated documentation section that will provide related guidance for both Spring MVC and WebFlux, leveraging the fact that function router gives a great deal of flexibility to deal with that kind of concern. We will also list alternatives like view controllers (Spring MVC only) and filters.

Let see how we much we can help fullstack developers with proper guidance on what we have today, and see how it goes.

[sdeleuze]

While working on the documentation, I found we probably miss a feature in the functional router API to be able to support the most common use case, so I may turn this documentation issue to an enhancement one (with related documentation).

Functional router seems the sweet spot to support such feature on both Spring MVC and Spring WebFlux in a consistent way. But I think we miss a related API since in RouterFunctions.Builder#resources(java.lang.String, org.springframework.core.io.Resource) the provided resource represent a directory where files to serve can be found, not the file to serve. You can see a great example of twisted usage for that use case here.

As a consequence, my proposal is to introduce a new RouterFunctions.Builder#resource(java.lang.String, org.springframework.core.io.Resource) (singular variant without a trailing s) that would redirect the pattern parameter to the specified file resource. This feature looks useful for the use case of that issue, but also for others, and would be much easier to leverage than a custom implementation using RouterFunctions#resourceLookupFunction.

In practice, users could specify:

@Bean
RouterFunction<ServerResponse> router() {
	var index = new ClassPathResource("static/index.html");
	return RouterFunctions.route()
			.resource("*.html", index)
			.resource("admin/*.html", index)
			.build();
}

Looks cleaner, simpler and more consistent than filter or view controller variants. Custom predicates can of course be created for more advanced use cases.

Any thoughts @poutsma @bclozel @jnizet @dsyer ?