Better document the connection between `HttpServerRequest#path()` and `RoutingContext#normalizedPath()`

[gsmet]

Describe the feature

In Quarkus, we often see people confused and using HttpServerRequest#path() instead of RoutingContext#normalizedPath().

This can lead to potential security issues if we are not careful when people are using paths like /../secured/resource/ and there is some matching on /secured/resource.
On our security layer, we have been careful about that but there are some less critical extensions where we were using the original request path where we should actually have used the normalized path.

I'm not exactly sure how we can help with that. One option would be to extend the HttpServerRequest#path() javadoc to clearly state it's a non-normalized path and RoutingContext#normalizedPath() should be used to get the normalized path... but it crosses the modules boundary so I'm not sure you will like it.

In any case, even seasoned developers on our side made the mistake and we also had users complaining so I think it's worth trying to improve the situation.

Contribution

No response

[Ladicek]

Funny thing is that the implementation of RoutingContext.normalizedPath() is super simple and basically only calls to an utility method that is not in Vert.x Web, but in Vert.x Core. I personally think it would be possible to just put normalizedPath() to HttpServerRequest.

[mathias82]

Subscribing to follow the discussion. I ran into this while working on Quarkus and the clarification around normalizedPath() would have avoided confusion.

@gsmet I have open a PR for vert.x web #2832 and vert.x core eclipse-vertx/vert.x#5824

[vietj]

Funny thing is that the implementation of RoutingContext.normalizedPath() is super simple and basically only calls to an utility method that is not in Vert.x Web, but in Vert.x Core. I personally think it would be possible to just put normalizedPath() to HttpServerRequest.

I think we'd rather have a path(boolean normalized) with a default being false

[mathias82]

Funny thing is that the implementation of RoutingContext.normalizedPath() is super simple and basically only calls to an utility method that is not in Vert.x Web, but in Vert.x Core. I personally think it would be possible to just put normalizedPath() to HttpServerRequest.

I think we'd rather have a path(boolean normalized) with a default being false

I like the idea of adding path(boolean normalized).

For example:

request.path(); // same as request.path(false)
request.path(false); // raw path as received from the client
request.path(true); // normalized path (without "//", "/../", "/./", etc.)

This would make the API explicit, avoid confusion between raw and normalized paths,
and allow users to opt into normalization when doing routing or security checks
without breaking existing applications.