Implement header based routing

[Tratcher]

Fixes #405

Design points:

• The ability to specify one or more header and value(s) that must be present on a request in order to route.
• Exposed from both code and config.
  • Should we allow you to specify a route using only a header? Today routes must have a path or host.
  • In config I've included both a Value and Values properties for convivence in the common single value scenario. Values takes priority if set. We may also want to do this with Host and Hosts, Header and Headers.
• Headers are lower priority matches than paths, methods, and hosts. One unanticipated side effect of this I saw was if one route specifies methods and another specifies headers, the methods route will always win as more specific. The headers check only comes into play if the higher priority checks are equal.
• Comparisons are case-insensitive by default to match the rest of routing, but you can opt-into case-sensitive checks.
  • Headers do not have consistent semantics like other parts of the request. Casing shouldn't matter in the average scenario, but there are some data types such as base64 encoded values where casing significantly changes the interpretation.
  • The case sensitivity option is implemented separately from match modes. When I included some of the match modes we may add in the future, and tried merging them with the case in/sensitive option it got very verbose and redundant. E.g. ExactHeaderCaseSensitive, ExactHeaderCaseInsensitive, ExactValueCaseSensitive, ExactValueCaseInsensitive, etc.. Even regexes have an optional, separate case sensitivity flag.
• Only a limited set of header matching rules have been implemented, scoped to the customer requirements. See the docs for details.
  • Multi-header and multi-value headers are not supported.
  • Complex matching such as regex patterns are not supported.
  • The matching rules are specified separately from the values because there's no well-defined pattern syntax for header formats short of a full regex. The customer requirements so far only call for basic value matching.
• Routing has some advanced performance features like INodeBuilderPolicy that we are not implementing in this first pass. They add significant complexity and it's not clear yet if they're needed for our scenarios.

Other oddities:

• Bumped the 3.1 dependencies to 3.1.8 to pick up a fix in routing.

[alnikola]

Looks good overall besides some comments on test coverage below.

Resolved

[JamesNK]

Routing has some advanced performance features like INodeBuilderPolicy that we are not implementing in this first pass. They add significant complexity and it's not clear yet if they're needed for our scenarios.

The main benefit is performance. It moves logic from being executed per-request to at startup when the DFA is built.

[alnikola]

LGTM

[javiercn]

Looks great!

[samsp-msft]

• Headers are lower priority matches than paths, methods, and hosts. One unanticipated side effect of this I saw was if one route specifies methods and another specifies headers, the methods route will always win as more specific. The headers check only comes into play if the higher priority checks are equal.

Is there a way to add a manual priority/weight to routes to bypass the default ordering. For example if I want all requests with a debug header to go to a specific destination, could I flag that rule in some way to push it to the top of the stack?

[javiercn]

Is there a way to add a manual priority/weight to routes to bypass the default ordering. For example if I want all requests with a debug header to go to a specific destination, could I flag that rule in some way to push it to the top of the stack?

If you are able to specify the route order explicitly that takes precedence over anything else. Routing supports that, I'm not sure if YARP exposes it, but it would be something good to expose.

[Tratcher]

Yes, YARP exposes the Order option on routes.

[halter73]

Should we demonstrate this in one of the examples?

[Tratcher]

I don't know. It's more of an escape hatch for people, I'm not sure how much it will get used.

[halter73]

If we decide to do this, I like ContainsExactValue and ContainsValuePrefix names, but I'm not sure how common of a requirement matching individual values from multi-value headers will be.

[Tratcher]

We're not doing these right now, we'll wait for feedback first. I left them here as examples of possible future values.

I don't know about Contains, it has mixed connotations from string.Contains and ICollection.Contains, we'd want the latter.

[halter73]

Why use a internal static Equals instead of overriding object.Equals?

[Tratcher]

To simplify the calling code when either value might be null.

[halter73]

How did we come up with this precedence order? I feel like host should be first or last overall even if it's technically just another header.

[Tratcher]

The first three are already built into AspNetCore routing with that precedence. Our only choice is where to rank headers. Per some other comments I'll add a note here that this can be overridden per route by setting the Order property.

[Tratcher]

/azp run

[azure-pipelines]

No pipelines are associated with this pull request.