Route matching priority is confusing / not intuitive

[chris-branch]

I'm using Kong 2.5.0, but I do not believe this issue is version-specific. Consider two routes configured as follows:

{
    "name": "route-1",
    "paths": [ "/foo" ]
}

{
    "name": "route-2",
    "paths": [ "/foo/bar" ]
}

This works exactly as expected; requests to /foo match route-1, and requests for /foo/bar match route-2. Now modify route-1 leaving route-2 unchanged:

{
    "name": "route-1",
    "paths": [ "/foo" ],
    "methods": [ "GET"]
}

{
    "name": "route-2",
    "paths": [ "/foo/bar" ]
}

Based on the config above, I would expect the following:

1. GET /foo - resolves to route-1
2. <any_method> /foo - returns 404 for any_method other than GET
3. <any_method> /foo/bar - resolves to route-2

Instead, what actually happens is:

1. GET /foo - resolves to route-1 (good)
2. <any_method> /foo - returns 404 for any_method other than GET (good)
3. GET /foo/bar - resolves to route-1 (BAD)
4. <any_method> /foo/bar - resolves to route-2 for any_method other than GET (good)

The documentation is not clear on this topic:

https://docs.konghq.com/gateway-oss/2.5.x/proxy/

First, there is this:

"When proxying with path prefixes, the longest paths get evaluated first. This allow you to define two Routes with two paths: /service and /service/resource, and ensure that the former does not “shadow” the latter."

That's true sometimes, but apparently can be trumped by this:

"The rule is: when evaluating a request, Kong will first try to match the Routes with the most rules."

There are a couple issues here. First, the sentence as written is not clear. It doesn't match the route with the most number of rules defined; it (apparently) matches the route with the most number of rules that match the request. Second, this is not intuitive at all. I would not expect a modification to route-1 that makes the request method more strict for route-1 to break routing for route-2, but that's exactly what can happen if you aren't aware of the "rule count" priority.

The same issue can occur with host header rules. If route-1 (/foo) requires host headers, but route-2 (/foo/bar) does not, requests for /foo/bar will match route-1.

I would encourage you to revisit/rethink the "rule count" prioritization and instead always match longest path (as described in the first quote from the documentation above), then use additional rules for request method / host header / etc to eliminate route candidates from selection. If that's not possible, then I would encourage you to update the documentation to make "rule count" section more visible and mention that "rule count" may override other rules in each of the sections that describes the individual rules. For example:

"When proxying with path prefixes, the longest paths get evaluated first. This allow you to define two Routes with two paths: /service and /service/resource, and ensure that the former does not “shadow” the latter. NOTE: See the Matching priorities section below for situations where longest path may not get evaluated first."

[bungle]

GET /foo/bar - resolves to route-1 (BAD)

It resolves to route-1 as with route-1 more criterias match:

1. matches method
2. matches path prefix

whereas with route-2 it only matches path prefix.

It would be hugely breaking change if we change this. We would probably instead rather add exact match, OR add this as an option. Nginx supports things like =, ^~.

[chris-branch]

Yes, I'm (now) aware that the "number of criteria matched" is a higher-priority than path prefix, and this is by design. What I'm saying is this is counterintuitive and I would never have expected this behavior, and I'd be willing to bet that a majority of Kong users would say the same.

The problem is it creates non-obvious dependencies between routes, so that future changes to one route can cause unexpected impacts if other routes exist that happen to overlap the same path prefix. Here's a different example to help illustrate. Suppose you have a route that includes a host rule:

{
    "name": "my-route",
    "paths": [ "/foo/bar" ],
    "hosts": [ "example.com" ]
}

At some point in the future, you decide to modify this route and remove the host rule so that any host will be permitted (i.e., so /foo/bar is less restrictive). So, you change as follows:

{
    "name": "my-route",
    "paths": [ "/foo/bar" ]
}

That works as expected, unless you happen to have another route defined somewhere else that looks like this:

{
    "name": "another-route",
    "paths": [ "/foo" ],
    "hosts": [ "example.com" ]
}

After the modification to my-route above, requests to /foo/bar that have a host header of example.com now match another-route instead of my-route due to "number of criteria matched", so a request to /foo/bar acts as if the request was sent to /foo (i.e., forwards to the wrong upstream, etc.)

IMO, longest path prefix should always trump everything else to avoid these kinds of surprises. But I also understand your hands are tied with making a breaking-change of this magnitude at this point. I think adding some warnings/caveats in the documentation (especially the paragraph that discusses longest paths) could help others avoid the potential pitfalls.