From b01d87f365e0e5ba5baa95c06fe19547cf7c2f9a Mon Sep 17 00:00:00 2001 From: MatthaiosStavrou Date: Fri, 28 Nov 2025 22:42:13 +0200 Subject: [PATCH] docs(core): clarify raw request path vs normalized path usage Signed-off-by: MatthaiosStavrou --- vertx-core/src/main/asciidoc/http.adoc | 8 ++++++++ .../main/java/io/vertx/core/http/HttpRequestHead.java | 11 ++++++++++- 2 files changed, 18 insertions(+), 1 deletion(-) diff --git a/vertx-core/src/main/asciidoc/http.adoc b/vertx-core/src/main/asciidoc/http.adoc index 383e6e85c2b..bf0cbb82d23 100644 --- a/vertx-core/src/main/asciidoc/http.adoc +++ b/vertx-core/src/main/asciidoc/http.adoc @@ -187,6 +187,14 @@ For example, if the request URI was `a/b/c/page.html?param1=abc¶m2=xyz Then the path would be `/a/b/c/page.html` +Note that `HttpServerRequest#path()` returns the raw path as it was sent by the client. +This value may contain repeated separators such as `//` or path traversal markers like `..`. + +If you are using Vert.x Web and need to perform security-sensitive checks or route +comparisons based on a normalized version of the path, prefer using +`RoutingContext#normalizedPath()` instead. Vert.x Web applies additional +transformations to ensure the path is canonicalized before matching routes. + ==== Request query Use {@link io.vertx.core.http.HttpServerRequest#query} to return the query part of the URI diff --git a/vertx-core/src/main/java/io/vertx/core/http/HttpRequestHead.java b/vertx-core/src/main/java/io/vertx/core/http/HttpRequestHead.java index 839251d881a..bb2ce99e8fa 100644 --- a/vertx-core/src/main/java/io/vertx/core/http/HttpRequestHead.java +++ b/vertx-core/src/main/java/io/vertx/core/http/HttpRequestHead.java @@ -28,7 +28,16 @@ public interface HttpRequestHead { String uri(); /** - * @return The path part of the uri. For example {@code /somepath/somemorepath/someresource.foo} + * Returns the path component of the HTTP request URI. + *

+ * This is the raw, non-normalized path as received from the client. + * It may contain duplicated separators or traversal segments such as {@code ".."}. + *

+ * For security-sensitive logic (for example access control, routing or + * filesystem checks), applications should prefer using a normalized path + * provided by the framework instead of relying on this raw value. + * + * @return the raw path component of the request URI */ @Nullable String path();