Path resolution in Quarkus

Once upon a time, Quarkus defined additional endpoints for things like health checks and metrics. They were served from the quarkus.http.root-path alongside any endpoints the application defined. This isn’t always obvious, as quarkus.http.root-path is / by default, making it effectively invisible.

As these proliferated, we started worrying about polluting the application endpoint namespace, and thinking about how we could group these non-application endpoints together to avoid colliding with application endpoints and make it easier to deal with security and access policies. Some users further asked if we could serve these non-application endpoints from another port entirely (we haven’t gotten there yet).

The first step was to group all of these extension-defined endpoints together. This was the genesis of the non-application endpoint path. The default location of this new path was /q, and it was nested under the HTTP root path, just as the other endpoints had been. The effect was to move /health to /q/health, as an example.

We knew that moving some of these endpoints, like metrics and health, would be problematic for already deployed applications and human muscle memory. To ease the transition, we added redirects for some of these endpoints, so that if you visited /metrics you would be redirected to /q/metrics.

Non-application endpoint support shipped in 1.11.0.Final.

And then things started to go sideways. Some cloud hosting providers only accept 200 as a definition of health, for example, so the redirect (a 301) didn’t have the intended effect. There was also some confusion about how to turn the non-application endpoint off to return to previous behavior, and further questions about how to move specific endpoints out of this non-application endpoint collection.

As an aside, how we got into this situation is not helped by differences in how libraries behave. Vert.x always wants segments beginning with leading slashes when creating routes, for example, while JAX-RS effectively ignores leading slashes in @Path annotations. Anyone used to Vert.x always adds leading slashes, and anyone using JAX-RS just does whatever and it magically works.

In Quarkus, an implementation detail was exposed by accident: non-application endpoints defined by extensions are based on Vert.x routes. Default path configuration values started with slashes to enable quick route creation and allow simple append behavior. There wasn’t anything in the early days of Quarkus to suggest this was a bad idea, and developers with experience in JAX-RS didn’t have any warnings one way or the other, because JAX-RS handles it.

Now, however, we were in the situation where paths weren’t being resolved as people expected, and the configuration changes required to resolve that situation either weren’t intuitive or lead to other problems. We ended up putting all of the possible configuration permutations into a spreadsheet so we could see side by side what happened when you combined different configuration values. The results were not awesome. However, the exercise allowed us to step back and look at the big picture to evaluate what needed to change to allow application and non-application endpoints to behave as you need them to.

While the set of configuration attributes used to configure paths in Quarkus remains unchanged, how configured values are interpreted is different:

These updates have been made available and the dust should all have settled with 1.11.5.Final and 1.12.1.Final.

Note that convenience redirects for non-application endpoints are still present, but they can be disabled by setting quarkus.http.redirect-to-non-application-root-path to false. That hasn’t changed at all.

Let’s go through some examples of how paths resolve using our new rules. We’ll start with the following assumptions:

The configuration attributes we care most about are:

We’ll also highlight some configurable non-application endpoints of interest:

Let’s look at what happens when we start pulling levers. In the examples below, pay attention to punctuation in config, as that will be the key to why things behave the way they do.

For the most part, we hope this will be transparent. We discovered some very inconsistent path handling along the way, which lead us to believe that many (or even most) of these values are never customized.

You are most likely to see a behavior change if you have customized the HTTP root path. In that case, we hope the new rules and examples above will help you understand how to tweak your configuration to get everything to behave the way you want it to.

Extension writers will see the biggest change. The Writing extensions guide has been updated to describe changes to the build items used to create non-application endpoints. The general rule, however, is to avoid constructing your own endpoint paths, and rely on NonApplicationRootPathBuildItem and HttpRootPathBuildItem to construct them for you.

While we know it is impossible to make everyone happy, we hope we have at least managed to acheive a pattern for configuration that leads to more predictable and consistent results. And we apologize (again), for any behavior changes you may have observed as we sorted this out.