Merge pull request #626 from robscott/route-conflicts

Clarifying how conflicting matches should be resolved in non-HTTP Routes

apis/v1alpha1/httproute_types.go

@@ -142,9 +142,8 @@ type RouteTLSConfig struct {
 // conditions, optionally executing additional processing steps, and forwarding
 // the request to an API object.
 type HTTPRouteRule struct {
-	// Matches define conditions used for matching the rule against
-	// incoming HTTP requests.
-	// Each match is independent, i.e. this rule will be matched
+	// Matches define conditions used for matching the rule against incoming
+	// HTTP requests. Each match is independent, i.e. this rule will be matched
 	// if **any** one of the matches is satisfied.
 	//
 	// For example, take the following matches configuration:
@@ -174,22 +173,27 @@ type HTTPRouteRule struct {
 	// HTTP request.
 	//
 	//
-	// A client request may match multiple HTTP route rules. Matching precedence
-	// MUST be determined in order of the following criteria, continuing on ties:
+	// Each client request MUST map to a maximum of one route rule. If a request
+	// matches multiple rules, matching precedence MUST be determined in order
+	// of the following criteria, continuing on ties:
 	//
 	// * The longest matching hostname.
 	// * The longest matching path.
 	// * The largest number of header matches.
 	//
-	// If ties still exist across multiple Routes:
+	// If ties still exist across multiple Routes, matching precedence MUST be
+	// determined in order of the following criteria, continuing on ties:
+	//
 	// * The oldest Route based on creation timestamp. For example, a Route with
 	//   a creation timestamp of "2020-09-08 01:02:03" is given precedence over
 	//   a Route with a creation timestamp of "2020-09-08 01:02:04".
-	// * The Route appearing first in alphabetical order (namespace/name) for
-	//   example, foo/bar is given precedence over foo/baz.
+	// * The Route appearing first in alphabetical order by
+	//   "<namespace>/<name>". For example, foo/bar is given precedence over
+	//   foo/baz.
 	//
-	// If ties still exist within the Route that has been given precedence:
-	// * The first matching rule meeting the above criteria.
+	// If ties still exist within the Route that has been given precedence,
+	// matching precedence MUST be granted to the first matching rule meeting
+	// the above criteria.
 	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=8

apis/v1alpha1/tcproute_types.go

@@ -60,11 +60,32 @@ type TCPRouteStatus struct {
 
 // TCPRouteRule is the configuration for a given rule.
 type TCPRouteRule struct {
-	// Matches define conditions used for matching the rule against
-	// incoming TCP connections. Each match is independent, i.e. this
-	// rule will be matched if **any** one of the matches is satisfied.
-	// If unspecified, all requests from the associated gateway TCP
-	// listener will match.
+	// Matches define conditions used for matching the rule against incoming TCP
+	// connections. Each match is independent, i.e. this rule will be matched if
+	// **any** one of the matches is satisfied. If unspecified (i.e. empty),
+	// this Rule will match all requests for the associated Listener.
+	//
+	// Each client request MUST map to a maximum of one route rule. If a request
+	// matches multiple rules, matching precedence MUST be determined in order
+	// of the following criteria, continuing on ties:
+	//
+	// * The most specific match specified by ExtensionRef. Each implementation
+	//   that supports ExtensionRef may have different ways of determining the
+	//   specificity of the referenced extension.
+	//
+	// If ties still exist across multiple Routes, matching precedence MUST be
+	// determined in order of the following criteria, continuing on ties:
+	//
+	// * The oldest Route based on creation timestamp. For example, a Route with
+	//   a creation timestamp of "2020-09-08 01:02:03" is given precedence over
+	//   a Route with a creation timestamp of "2020-09-08 01:02:04".
+	// * The Route appearing first in alphabetical order by
+	//   "<namespace>/<name>". For example, foo/bar is given precedence over
+	//   foo/baz.
+	//
+	// If ties still exist within the Route that has been given precedence,
+	// matching precedence MUST be granted to the first matching rule meeting
+	// the above criteria.
 	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=8

apis/v1alpha1/tlsroute_types.go

@@ -65,11 +65,35 @@ type TLSRouteStatus struct {
 
 // TLSRouteRule is the configuration for a given rule.
 type TLSRouteRule struct {
-	// Matches define conditions used for matching the rule against an
-	// incoming TLS handshake. Each match is independent, i.e. this
-	// rule will be matched if **any** one of the matches is satisfied.
-	// If unspecified, all requests from the associated gateway TLS
-	// listener will match.
+	// Matches define conditions used for matching the rule against incoming TLS
+	// connections. Each match is independent, i.e. this rule will be matched if
+	// **any** one of the matches is satisfied. If unspecified (i.e. empty),
+	// this Rule will match all requests for the associated Listener.
+	//
+	// Each client request MUST map to a maximum of one route rule. If a request
+	// matches multiple rules, matching precedence MUST be determined in order
+	// of the following criteria, continuing on ties:
+	//
+	// * The longest matching SNI.
+	// * The longest matching precise SNI (without a wildcard). This means that
+	//   "b.example.com" should be given precedence over "*.example.com".
+	// * The most specific match specified by ExtensionRef. Each implementation
+	//   that supports ExtensionRef may have different ways of determining the
+	//   specificity of the referenced extension.
+	//
+	// If ties still exist across multiple Routes, matching precedence MUST be
+	// determined in order of the following criteria, continuing on ties:
+	//
+	// * The oldest Route based on creation timestamp. For example, a Route with
+	//   a creation timestamp of "2020-09-08 01:02:03" is given precedence over
+	//   a Route with a creation timestamp of "2020-09-08 01:02:04".
+	// * The Route appearing first in alphabetical order by
+	//   "<namespace>/<name>". For example, foo/bar is given precedence over
+	//   foo/baz.
+	//
+	// If ties still exist within the Route that has been given precedence,
+	// matching precedence MUST be granted to the first matching rule meeting
+	// the above criteria.
 	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=8

apis/v1alpha1/udproute_types.go

@@ -60,11 +60,32 @@ type UDPRouteStatus struct {
 
 // UDPRouteRule is the configuration for a given rule.
 type UDPRouteRule struct {
-	// Matches define conditions used for matching the rule against
-	// incoming UDP connections. Each match is independent, i.e. this
-	// rule will be matched if **any** one of the matches is satisfied.
-	// If unspecified, all requests from the associated gateway UDP
-	// listener will match.
+	// Matches define conditions used for matching the rule against incoming UDP
+	// connections. Each match is independent, i.e. this rule will be matched if
+	// **any** one of the matches is satisfied. If unspecified (i.e. empty),
+	// this Rule will match all requests for the associated Listener.
+	//
+	// Each client request MUST map to a maximum of one route rule. If a request
+	// matches multiple rules, matching precedence MUST be determined in order
+	// of the following criteria, continuing on ties:
+	//
+	// * The most specific match specified by ExtensionRef. Each implementation
+	//   that supports ExtensionRef may have different ways of determining the
+	//   specificity of the referenced extension.
+	//
+	// If ties still exist across multiple Routes, matching precedence MUST be
+	// determined in order of the following criteria, continuing on ties:
+	//
+	// * The oldest Route based on creation timestamp. For example, a Route with
+	//   a creation timestamp of "2020-09-08 01:02:03" is given precedence over
+	//   a Route with a creation timestamp of "2020-09-08 01:02:04".
+	// * The Route appearing first in alphabetical order by
+	//   "<namespace>/<name>". For example, foo/bar is given precedence over
+	//   foo/baz.
+	//
+	// If ties still exist within the Route that has been given precedence,
+	// matching precedence MUST be granted to the first matching rule meeting
+	// the above criteria.
 	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=8