Improve the description of the route selectors in RFC 0001

[guicassolato]

The semantics of RLPv2's routeSelectors, presented with RFC 0001, is mainly described through examples. They lack a proper definition that helps users understand that they are not just another set of conditions, that complement the when conditions, by using a different syntax (i.e. the syntax of Gateway API's HTTPRouteMatches).

One who learns about RLPv2's route selectors for the first time, despite the name, might not immediately realize that the route selectors are selectors of routes (or parts of a route), that transitively induce a set of conditions. They are not to be read as the actual conditions themselves.

Specifically, how route selectors and HTTPRouteMatches are pairwise compared to select or not select HTTPRouteRules might not be clear at first glance. To decide whether the route selector selects a HTTPRouteRule or not, for each pair of route selector HTTPRouteMatch and HTTPRouteRule's HTTPRouteMatch:

1. The route selector selects the HTTPRouteRule if the HTTPRouteRule contains at least one HTTPRouteMatch that specifies fields that are literally identical to all the fields specified by at least one HTTPRouteMatch of the route selector.
2. A HTTPRouteMatch within a HTTPRouteRule may include other fields that are not specified in a route selector match and yet the route selector match selects the HTTPRouteRule if all fields of the route selector match are identically included in the HTTPRouteRule's HTTPRouteMatch; the opposite is NOT true.
3. Each field path of a HTTPRouteMatch, as well as each field method of a HTTPRouteMatch, as well as each element of the fields headers and queryParams of a HTTPRouteMatch, is atomic – this is true for the HTTPRouteMatches within a HTTPRouteRule, as well as for HTTPRouteMatches of a route selector.

Overall, it’s important that people understand:

1. the problem of sets and subsets of route matches that motivated having the route selectors as they are, especially what this problem represents in terms of challenges for reporting status to the user;
2. that policies in general are not self-contained objects; in fact, it’s inherent of policy attachment that the result of the policy depends, at least, on the spec of the object whose behavior is being extended, plus what’s in the policy itself. Because those objects are somewhat independent from each other, we need to work more with the status.

As a final note, the route selectors could have been implemented differently or even incorporated into the same language as the language of when conditions. In the end, we believe it’s a tradeoff between:

• A. A little bit more to learn beforehand, but easier to understand what's happening afterwards (from more comprehensible status), vs.
• B. Easier to write the policies in the first place, but hard to debug when they don't behave as expected (due to poor status reporting)