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

apis/v1alpha1/shared_types.go

@@ -175,9 +175,9 @@ const (
 	ConditionRouteAdmitted RouteConditionType = "Admitted"
 )
 
-// RouteGatewayStatus describes the status of a route with respect to an
-// associated Gateway.
-type RouteGatewayStatus struct {
+// RouteStatusGatewayReference describes the status of a route with respect to
+// an associated Gateway.
+type RouteStatusGatewayReference struct {
 	// GatewayRef is a reference to a Gateway object that is associated with
 	// the route.
 	GatewayRef GatewayReference `json:"gatewayRef"`
@@ -210,7 +210,7 @@ type RouteStatus struct {
 	// by any Gateway.
 	//
 	// +kubebuilder:validation:MaxItems=100
-	Gateways []RouteGatewayStatus `json:"gateways"`
+	Gateways []RouteStatusGatewayReference `json:"gateways"`
 }
 
 // Hostname is used to specify a hostname that should be matched.

apis/v1alpha1/tcproute_types.go

@@ -60,11 +60,27 @@ 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, all requests
+	// from the associated gateway listener will match.
+	//
+	// A client request may match multiple route 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:
+	// * 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.
+	//
+	// If ties still exist within the Route that has been given precedence:
+	// * The first matching rule meeting the above criteria.
 	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=8

apis/v1alpha1/tlsroute_types.go

@@ -65,11 +65,28 @@ 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, all requests
+	// from the associated gateway listener will match.
+	//
+	// A client request may match multiple route rules. Matching precedence MUST
+	// be determined in order of the following criteria, continuing on ties:
+	//
+	// * The longest matching SNI.
+	// * 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:
+	// * 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.
+	//
+	// If ties still exist within the Route that has been given precedence:
+	// * The first matching rule meeting the above criteria.
 	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=8

apis/v1alpha1/udproute_types.go

@@ -60,11 +60,27 @@ 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, all requests
+	// from the associated gateway listener will match.
+	//
+	// A client request may match multiple route 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:
+	// * 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.
+	//
+	// If ties still exist within the Route that has been given precedence:
+	// * The first matching rule meeting the above criteria.
 	//
 	// +optional
 	// +kubebuilder:validation:MaxItems=8