Kuadrant / Kuadrant/architecture
Improve the description of the route selectors in RFC 0001
- Dominant language
- No language data
- Stars
- 3
- Forks
- 16
- Avg merge
- 7d 11h
- Merged PRs (30d)
- 2
Description
The semantics of RLPv2's `routeSelectors`, presented with [RFC 0001](https://github.com/Kuadrant/architecture/blob/main/rfcs/0001-rlp-v2.md), 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)
Contributor guide
Research direction
Read RFC 0001 at rfcs/0001-rlp-v2.md, focusing on the routeSelectors examples and their relationship to HTTPRouteMatches and when conditions. Clarify the matching rules, subset behavior, atomic fields, policy attachment, status reporting, and the design trade-off described in the issue. Done means a newcomer can understand what route selectors select and why they exist.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100