fix(router): handle escaped colons and inline verbs in v4 (#3132)

* fix(router): keep escaped colon and parameter routes reachable in v4

* fix(router): parse inline verbs consistently in v4

* fix(router): backtrack inline verb splits in v4

* perf(router): preserve v4 fast path without inline verbs

* fix(router): retry inline verb splits on the param node in v4

Backport of the v5 change. Replace the whole-search retry plan with a
backtrack point on the param node: when a candidate split fails, the
same param node is retried with the next literal-colon split and finally
the whole path segment before routing backtracks to its parent. Static >
param > any priority of ancestors, the leaf rule of later params, group
middleware and catch-all routes are no longer affected by a failed split.

An escaped colon after a parameter starts an inline verb only when the
rest of that path segment is static (`/:name\:cancel`, optionally
followed by `/...`). Split candidates are then scanned once per segment,
so a request with many colons is routed in linear time. Other escaped
colons after a parameter keep their older meaning as part of the
parameter name.

The duplicated fast-path Find and the router-level inline verb flag are
removed. The param scan uses strings.IndexByte, which keeps router
benchmarks within about 0.3% of v4 (geomean).

* fix(router): retry inline verb splits after a wildcard fails

A wildcard ends the route search, but a param value above it that ended
at an inline verb split is now retried with the next split and the whole
segment, so a verb route with a wildcard cannot shadow a generic route
for other methods.

The retry now runs only when routing backtracks from the inline verb
child into its param node, instead of on every dead end.

An escaped colon after a parameter keeps its older meaning (part of the
parameter name) unless the first one in the segment starts an inline
verb, so a later `\:` cannot turn such a legacy route into a verb route.
Reverse writes placeholders for such names without the backslash, as
before. Dead hasColonChild bookkeeping for split nodes is removed.

* fix(router): keep backtracking below an inline verb split

When a wildcard fails below a param value that ended at an inline verb
split, keep backtracking one node at a time instead of jumping to that
param node, so the other routes below the split are tried before the
next split. Without a pending split a failed wildcard still ends the
search as before, and the check does not change the routing state.

Adds tests for nested splits, routes below a split and a RouteNotFound
wildcard below a split.

* fix(router): keep escaped colons after complex param names in v4

An escaped colon after a param name that contains ':' or '*' keeps its
older meaning as part of the name. The escaped colon check is shared in
the route syntax scanner. Adds tests for RouteNotFound on the whole
segment and Reverse placeholders.

* fix(router): keep leaf params matching the rest of the path

Registering an inline verb route under a param gave the param node a
static child, so a sibling route ending in that param (`/files/:path`)
stopped matching values across slashes. When the inline verb child is
the node's only child, a param value without a split now takes the rest
of the path, as a leaf param does.

* test(router): cover leaf param fallbacks next to an inline verb

Drop the param and any child checks that cannot fail for a param node, and pin 405, RouteNotFound and wildcard fallbacks for a param value that spans slashes next to an inline verb route.

Author: vishr

route_path.go

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: © 2015 LabStack LLC and Echo contributors
+
+package echo
+
+import "strings"
+
+// routePathPart is one parsed piece of a route pattern. A backslash before a
+// colon makes the colon static. After a parameter name it starts an inline verb
+// (`/:name\:cancel`) when the rest of that path segment is static.
+type routePathPart struct {
+	kind  kind
+	value string
+}
+
+func parseRoutePath(path string) []routePathPart {
+	var parts []routePathPart
+	walkRoutePath(path, func(part routePathPart) { parts = append(parts, part) })
+	return parts
+}
+
+// walkRoutePath is the common syntax scanner. Reverse uses it directly to
+// avoid allocating a parts slice for each URL it builds.
+func walkRoutePath(path string, emit func(routePathPart)) {
+	for i := 0; i < len(path); {
+		if isEscapedColon(path, i) {
+			emit(routePathPart{kind: staticKind, value: ":"})
+			i += 2
+		} else if path[i] == ':' {
+			start := i + 1
+			i = start
+			plainName := true // an escaped colon only starts an inline verb after a name without ':' or '*'
+			for i < len(path) && path[i] != '/' {
+				if isEscapedColon(path, i) {
+					if plainName && isInlineVerb(path[i+2:]) {
+						break
+					}
+					// not an inline verb: the rest of the segment is the param name, as before inline verbs
+					for i < len(path) && path[i] != '/' {
+						i++
+					}
+					break
+				}
+				if path[i] == ':' || path[i] == '*' {
+					plainName = false
+				}
+				i++
+			}
+			emit(routePathPart{kind: paramKind, value: path[start:i]})
+		} else if path[i] == '*' {
+			start := i
+			for i < len(path) && path[i] != '/' {
+				i++
+			}
+			emit(routePathPart{kind: anyKind, value: path[start:i]})
+		} else {
+			start := i
+			for i < len(path) && path[i] != ':' && path[i] != '*' && !isEscapedColon(path, i) {
+				i++
+			}
+			emit(routePathPart{kind: staticKind, value: path[start:i]})
+		}
+	}
+}
+
+func isEscapedColon(path string, i int) bool {
+	return path[i] == '\\' && i+1 < len(path) && path[i+1] == ':'
+}
+
+// isInlineVerb reports whether the route text after an escaped colon stays
+// static up to the end of its path segment. Only then can the router find where
+// the parameter value ends by trying the colons in the requested segment. Other
+// escaped colons keep the older meaning and remain part of the parameter name.
+func isInlineVerb(rest string) bool {
+	for i := 0; i < len(rest) && rest[i] != '/'; i++ {
+		switch rest[i] {
+		case '*':
+			return false
+		case ':':
+			if i == 0 || rest[i-1] != '\\' {
+				return false
+			}
+		}
+	}
+	return true
+}
+
+func routeTreePath(parts []routePathPart) (string, []int) {
+	var path strings.Builder
+	var paramMarkers []int
+	for _, part := range parts {
+		switch part.kind {
+		case staticKind:
+			path.WriteString(part.value)
+		case paramKind:
+			paramMarkers = append(paramMarkers, path.Len())
+			path.WriteByte(':')
+		case anyKind:
+			path.WriteByte(anyLabel)
+			return path.String(), paramMarkers
+		}
+	}
+	return path.String(), paramMarkers
+}