Adding Route Delegation Details for each HTTPRoute Capability

site-src/geps/gep-1058.md

@@ -0,0 +1,89 @@
+# GEP-1058: Route Inclusion and Delegation
+
+- Issue: [#1058](https://github.com/kubernetes-sigs/gateway-api/issues/1058)
+- Status: Provisional
+
+## TLDR
+
+Add support for a 2-tier hierarchy of route configuration to allow partial
+delegation of route settings and, provide more flexibility in how route
+configurations are organized and managed.
+
+## HTTPRoute Delegation Capabilities
+
+### Matching
+| Capability | Importance for Delegation | Complexity | Implementation Details |
+|---|---|---|---|
+| Hostnames | ? | Moderate | A three way intersection between Gateway, Parent Route, and Child Route hostnames |
+| Prefix Path on Parent, Prefix or Exact on Child | High | Low | Prefix path match of parent is prepended to child path match, child can support exact or prefix path matching |
+| Exact Path on Parent | Low | Moderate | Would require only "/" matches on child route |
+| Exact Path on Child | High | Low | Prefix path match of parent is prepended to child path match, child can support exact or prefix path matching |
+| Regex Path on Parent or Child | Low | Impossible | Maybe some complex merging is possible here, but I can't think of a good solution |
+| Exact Header on Parent and Child | Moderate | Low | Merge header matches, when duplicate keys appear, treat identically to duplicate match keys in same route |
+| Regex Header on Parent and Child | Low | Low | Merge header matches, when duplicate keys appear, treat identically to duplicate match keys in same route |
+| Exact Query Param on Parent and Child | Moderate | Low | Merge query param matches, when duplicate keys appear, treat identically to duplicate match keys in same route |
+| Regex Query Param on Parent and Child | Low | Low | Merge query param matches, when duplicate keys appear, treat identically to duplicate match keys in same route |
+| Method on Parent and Child | Low | Low | If methods don't overlap, no requests match, potentially surface in status |
+
+### Filters
+
+| Capability | Importance for Delegation | Complexity | Implementation Details |
+|---|---|---|---|
+| RequestHeaderModifier on Parent and Child | Moderate | High | The order of operations becomes the most important factor here. If we can confirm that all implementations can support an arbitary order of operations for Add, Set, and Remove operations, we could simply specify that configuration on child routes would be applied after parent routes. |
+| RequestMirror on Parent and Child | Low | High | Many implementations can only support mirroring a request to one destination. We could support Parent _or_ child, or state that one overrode the other |
+| RequestRedirect on Parent | Low | Impossible | Redirects simply don't make sense on parents that are delegating. |
+| RequestRedirect on Child | Moderate | Low | Redirects should be possible if they are only configured on child Route rules. |
+| URLRewrite on Parent and Child | Low | Impossible | It would be very difficult, maybe impossible, to merge this configuration. |
+| URLRewrite on Parent or Child | Low | Moderate | Rewrite configuration should be possible on either the parent or child, but not both at the same time. |
+
+
+## Open Questions
+
+### How do we handle multiple matches?
+
+Parent Route:
+
+```yaml
+matches:
+- path:
+  - prefix: /foo
+- path:
+  - prefix: /bar
+delegateToNamespace: foo
+```
+
+Child Route:
+
+```yaml
+matches:
+- path:
+  - prefix: /baz
+```
+
+* Does the child route match `/foo/bar` and `/bar/baz`?
+* Would it be preferable to require the child route to specify the full path?
+* How does this interact with potential matching conflicts for headers or query params?
+
+Parent Route:
+
+```yaml
+matches:
+- method: GET
+  path:
+  - prefix: /foo
+- method: POST
+  path:
+  - prefix: /bar
+delegateToNamespace: foo
+```
+
+Child Route:
+
+```yaml
+matches:
+- method: GET
+  path:
+  - prefix: /baz
+```
+
+* Does this only match `GET /foo/baz`?