support URI Template based route match

[lizan]

Description:
This was a part of discussion for #7728 but a separate issue, to add full or subset of URI Template (RFC6570) based route matching. The URI Template is already used in OpenAPI spec and gRPC JSON transcoding binding.

It will reduce the use case for regex as I see many use of regex is to support this.

[justin-mp]

RFC 6570 is great for creating URIs, but seems mum on actual matching patterns. What would be the plan for turning URI Templates into matchers?

I ask because we're in need of a more flexible route-matching, but are trying to avoid exposing the complexity (both in user-friendliness and in runtime speed) of regexes. We're thinking of building something based on "glob" operators:

The "glob" operators here follow common UNIX command-line conventions in order to be as familiar and flexible as possible.
For non-URL pattern matching, such as in header/cookie values and/or in CORS policies, the * operator matches any number of (zero or more) characters.

• The "*" operator, which matches zero or more characters, up to the next path separator ("/")
  • Example: "/api/v1/*" would match "/api/v1/get" but not "/api/v1/resourceName/post"
  • Similarly, “/videos/*.ts” would match “/videos/foo.ts” but not “/videos/id/1234/foo.ts”
• The "**" operator, which matches zero or more characters, ignoring any path separators.
  • Example: "/videos/**.ts" would match "/videos/hd/18313/output/hevc/segment-000001.ts", "/videos/sd/90574/output/dash/segment-000555.ts" and "/videos/test/foo.ts"
• The "?" operator, which matches exactly one character.
  • This can only be specified once (use * or ** if you need to match multiple characters)
  • Example: "/api/v?/**" would match "/api/v1/hello/get" but not "/api/v1beta1/hello/get"

The gRPC transcoder extends the RFC 6570 syntax so that expansion expressions can take matcher expressions. The matcher expressions are of the form {name=TEMPLATE} where TEMPLATE can expand to a combination of literals and glob operators (including * and **!). See http.proto for more details.

gRPC's TEMPLATE doesn't allow single-character ?, but presumably that wouldn't be hard to add especially since ? is already a reserved character for gRPC's TEMPLATE syntax.

We're not wedded to our particular syntax, but do need globbing, so something like gRPC could work for us.

What's the best way to move forward?

[htuch]

http.proto with ? added SGTM as the API here.

@mattklein123 @lizan @markdroth @envoyproxy/api-shepherds WDYT?

Also tagging @louiscryan @costinm for Istio.

[mattklein123]

I talked to @htuch about this offline and in general I'm in favor. I don't feel very strongly about the language so I would go with whatever the simplest thing is that satisfies the known use cases. In terms of Envoy implementation/API details, I think the easiest thing to do is going to be to implement a new regex engine here:

envoy/api/envoy/type/matcher/v3/regex.proto

Lines 49 to 53 in b23ee3b

	oneof engine_type {
	option (validate.required) = true;
	// Google's RE2 regex engine.
	GoogleRE2 google_re2 = 1 [(validate.rules).message = {required: true}];

Each engine implicitly has a supported language that is self enforced. I think we could just implement a new engine which has a very limited language and offer that as an option. I admittedly haven't thought through all the details, but I think this will be very simple from an API perspective to get working.

[louiscryan]

One other consideration of Justins example above is that the matcher emits an attribute/metadata by tagging match segments. This is useful for rewrites on forward and has uses in other policy contexts. Same would be true for regex groups.

@htuch

[htuch]

Yep, I think this is a pretty powerful approach. @louiscryan can we confirm that from the Istio-side that http.proto would be a good choice?

[josheinhorn]

@qiwzhang @nareddyt @TAOXUY can you guys take a look at this? I know you previously had an efficient trie-based implementation of this URI template pattern matching in a custom Envoy filter. This would at least be good prior art, if not the basis of this new implementation.

[nareddyt]

It would be ideal to have first-class support for URI templates in Envoy. For the time being, our product ESPv2 converts URI templates into regex route matchers when configuring the router.

I ask because we're in need of a more flexible route-matching, but are trying to avoid exposing the complexity (both in user-friendliness and in runtime speed) of regexes.

#13320 added performance benchmarks for Envoy's router with regex routes that emulate common OpenAPI path templates. We decided the performance impact was acceptable and implemented our own URI template to regex converter in golang. This approach has been working fine so far.

I know you previously had an efficient trie-based implementation of this URI template pattern matching in a custom Envoy filter. This would at least be good prior art, if not the basis of this new implementation.

Before we switched to converting URI templates to regex route matchers during config time, we has a custom filter and C++ library that supported URI templates in the data plane. It is similar to the library currently used by the gRPC transcoder filter. The trie-based implementation allows O(log(n)) path matching.

However, we moved away from this approach because the Envoy platform team had security concerns about introducing a handwritten parser into Envoy's dataplane.

I think the easiest thing to do is going to be to implement a new regex engine here. Each engine implicitly has a supported language that is self enforced. I think we could just implement a new engine which has a very limited language and offer that as an option.

It sounds like the current approach is to add first-class support for URI templates in the route configuration, but internally envoy will still use regex matchers to parse the URI template. Can we move to using the trie-based parser library and remove the intermediate regex? Otherwise I do not see much value added - users can convert the URI templates to regex at config time like we do currently, it's just moving that logic into Envoy.

[qiwzhang]

Per my understanding of mattklein123 idea of new engine_type inside RegexMatcher, it is NOT using regex. This new type can be implemented by grpc path_matcher which supports full URL template syntax. This change is very isolated, will not impact other code. I think its a good idea, it will achieve the same goal of not using regex to implement url_template.

For example

 oneof engine_type {
    option (validate.required) = true;

    // Google's RE2 regex engine.
    GoogleRE2 google_re2 = 1 [(validate.rules).message = {required: true}];

    // Google url tempalte, /foo/{x=**} or /bar/*/foo
    string google_url_template = 2;
  }

  // The regex match string. The string must be supported by the configured engine.
  string regex = 2 [(validate.rules).string = {min_len: 1}];   <=== can be empty for google_rul_template
}

[htuch]

Implementation wise I'm good with either internal safe_regex translation or the gRPC-JSON transcoder library if we can persuade ourselves it is robust here. @qiwzhang points is correct, Matt is suggesting we use the pluggable "regex" API message, not that this is actually a regex.

@qiwzhang what is you take on fuzzing and code quality/review for the path matcher?

Either way we go, we have code that requires tests, fuzzing and review. In particular, the tests/fuzzing are basically common if we treat this like a blackbox.

[qiwzhang]

Yes, the name RegexMatch is confusing after adding google_url_template. Maybe can rename it.

path_matcher code quality should be ok. It already has fuzz tests for its http_template code, we can add fuzz tests for path_matcher code too.

[qiwzhang]

I think Url Template will be used only for RouteMatch. Instead adding a new engine_type for RegexMatch, we can add url_template to RouteMatch as one of path_specifier.

How about:

    oneof path_specifier {
        option (validate.required) = true;

        ...

       ConnectMatcher connect_matcher = 12;

       // Support google url tempalte, /foo/{x=**} or /bar/*/foo
       string url_template = 13;
    }