Route path is decoded twice when it reaches the router already decoded

[totally-not-ai]

Description of the bug

Route resolution decodes the path it is given, but the path does not always
reach it encoded. PathUtil.getSegmentsListWithDecoding() — used by
RouteSegment#getNavigationRouteTarget since #22791 — assumes a
percent-encoded path, while two of the three entry points hand it an already
decoded one:

• BootstrapHandler builds the Location from
  HttpServletRequest#getPathInfo(), which the servlet container has already
  decoded → decoded.
• Flow.ts sends window.location.pathname without decoding it, both as the
  location parameter of the init request and as the route of
  UI#browserNavigate → encoded (deliberately, see fix: preserve URL-encoded characters in wildcard route parameters #22791).
• UI#navigate(String) and BeforeEvent#forwardTo(String) take whatever the
  application passes, which in practice is human readable → decoded.

The two decoded sources are therefore decoded a second time. #25671 is one
consequence of this (a literal non-ASCII character was destroyed by the second
decode) and is fixed in #25672, but that fix only makes the second decode
harmless for characters that are not percent escapes. The contract problem
itself is still there, with two remaining symptoms.

1. A literal percent sign in the path is eaten.

A browser request for /wild/a%2541 means the literal text a%41. The
container decodes the path info to /wild/a%41, the router decodes it a second
time, and the view receives aA. The same happens for
UI.navigate("wild/a%41").

2. Location#getPath() depends on how the user arrived.

For the same URL, an application observing BeforeEvent#getLocation() sees the
decoded path after an eager server-side page load and the percent-encoded path
after a client-side navigation.

Expected behavior

The path that reaches route resolution has one well-defined form, and a path
segment is decoded exactly once, so that a route or a parameter value keeps the
characters the user actually navigated to. Location#getPath() returns the same
value for the same URL regardless of the navigation trigger.

Minimal reproducible example

With a wildcard route:

@Route("wild")
public class WildView extends Div implements HasUrlParameter<String> {
    @Override
    public void setParameter(BeforeEvent event,
            @WildcardParameter String parameter) {
        add(new Span("[" + parameter + "]"));
    }
}

Open http://localhost:8080/wild/a%2541 directly (so that the server side
resolves it). Expected [a%41], actual [aA].

For the second symptom, add System.out.println(event.getLocation().getPath())
to a BeforeEnterObserver of a route with a space in it, and compare opening
the URL directly with navigating to it from another view through a
RouterLink.

Proposed solution

A canonical form has to be picked for the path that reaches the router, and both
options have consequences:

1. Canonical encoded — build the bootstrap Location from the raw request
   URI instead of getPathInfo(), and require pre-encoded input from
   UI#navigate and BeforeEvent#forwardTo, as RouteConfiguration#getUrl
   already documents. The eager page load then agrees with client-side
   navigation, which is encoded today. But UI.navigate("grüße") stays broken,
   and Location#getPath() starts returning percent-encoded text on the initial
   load, which applications can observe.
2. Canonical decoded — decode exactly once, at the boundary where the
   encoded form is known, and never again in the router. That is the form
   applications want downstream, but it needs Location to carry the path as
   segments rather than as one string, because rejoining decoded segments loses
   the distinction between a literal slash and %2F that fix: preserve URL-encoded characters in wildcard route parameters #22791 was about.

Either way Location semantics change, which is why it is not part of #25672.

Versions

• Vaadin / Flow version: main, and any 24.9.12+ / 25.1+ where
  PathUtil#getSegmentsListWithDecoding exists

[totally-not-ai]

Confirmed: this is a real bug, and both symptoms reproduce on main. I pinned them as two deliberately failing tests in RouterTest on the branch fix/decode-route-path-exactly-once (no PR yet, because the fix needs a decision — see below):

• wildcard_parameter_with_literal_percent_sign — wild/a%41 (what the container hands over for a request to /wild/a%2541) → the view gets aA, expected a%41.
• parameter_with_encoded_and_decoded_path_sameValue — the same URL gives john%20doe when it arrives encoded (client-side navigation) and john doe when it arrives decoded (eager server-side load).

Root cause

The path is a plain String all the way into the route matcher, and nobody records whether it is still percent-encoded:

• BootstrapHandler:216 and JavaScriptBootstrapHandler:116-121 build the Location from getPathInfo(), which the container has already decoded.
• Flow.ts:302 (getFlowRoutePath) deliberately does not decode, and Flow.ts:455 sends location= encoded — so client-side navigation is encoded.
• DefaultRouteResolver:47-49 passes location.getPath() — one joined string — into RouteRegistry#getNavigationRouteTarget, and RouteSegment:285-289 splits it into a raw list and a decoded list.
• The decode itself happens in two places, both assuming encoded input: PathUtil#getSegmentsListWithDecoding (static route matching) and ParameterDeserializer:116 (wildcard values). Both came with fix: preserve URL-encoded characters in wildcard route parameters #22791.

One more data point that is worth folding into the fix: the decoding is not uniform inside the router either. RouteSegment deliberately stores the raw segment as the parameter value (RouteSegment:619 and :630) and RouteParameters#getValue returns it unchanged. So a @WildcardParameter value is decoded (in ParameterDeserializer), while a plain HasUrlParameter<String> value and every RouteParameters value are not — that is what the second test above shows. "Decoded exactly once" currently holds for two of the four consumers; whichever canonical form is picked, these should be unified in the same change.

The two options, with what they actually cost

1. Canonical encoded — match on the encoded path, decode once when a value is handed to the application.

• Build the bootstrap Location from the raw request URI instead of getPathInfo(). Both entry points are then encoded, and both symptoms go away. VaadinRequest only exposes the decoded getPathInfo(), so this means either casting to VaadinServletRequest and using getRequestURI() minus context and servlet path, or adding a raw accessor to VaadinRequest — a small public API addition.
• UI#navigate(String) and BeforeEvent#forwardTo(String) would take pre-encoded paths. To keep navigate("grüße") and navigate("a b") working, normalize at that boundary: escape what must be escaped, leave existing valid %XX escapes alone. The residual ambiguity (an application passing a literal %41) is then a documented contract — and it is already the contract for client-side navigation.
• Decode at delivery for all parameter types, not only wildcards.
• Cost: Location#getPath() returns percent-encoded text on the eager page load too, which applications can observe (HighlightConditions, AbstractRouteNotFoundError:69, InternalServerError, logging). Note this makes the minority case match the majority — every client-side navigation is already encoded today. A decoded accessor on Location would be a friendly companion.
• Watch out: RouteConfiguration#getUrl does not encode parameter values today (HasUrlParameterFormat#getUrl just joins toString()), while RouterLink:443 encodes the finished URL. If getUrl starts encoding, RouterLink double-encodes.

2. Canonical decoded — decode per segment at the client boundary, never in the router.

• Decode each segment of the init location parameter and of the ui-navigate / ui-leave-navigation route; leave the bootstrap path as is; drop both decodes from the router.
• Needs route resolution to consume Location#getSegments() instead of re-splitting getPath(). Location already stores segments, but DefaultRouteResolver flattens them into a string, and that is exactly where the %2F-versus-/ distinction from fix: preserve URL-encoded characters in wildcard route parameters #22791 is lost. So RouteRegistry#getNavigationRouteTarget(String) needs a segment-list counterpart — new public API.
• Location#getPath() stays readable, which is what applications want, but it becomes a lossy rendering of the location whenever a segment contains a literal slash.
• Watch out for the write-back path: History:408-415 sends Location#getPathWithQueryParameters() to the browser verbatim, and UI#replaceStateIfDiffersAndNoReplacePending (UI:2240-2253) compares location.getPath() against the encoded route the client sent. With a decoded Location, every navigation to an encoded URL would look "changed" and trigger a spurious replaceState that writes the decoded text into the address bar. Both sites need explicit re-encoding.

Recommendation

Option 1. It has the smaller blast radius — no new public API on the resolution path, no client change, and the router keeps being able to tell %2F from / without threading segments through everything — and it is what servlet- and JAX-RS-style routing does: match on the encoded path, decode when the value reaches the application. The price is Location#getPath() being encoded on the first load as well, which is a documentable change and already the behaviour for every client-side navigation.

Either option changes observable Location semantics, so it should land on main only and not be backported; #25672 stays the safe part that can go to the maintenance branches.

Happy to implement whichever option is chosen, on top of the reproduction branch — just say which one.