Expand and clarify Listeners definition

apis/v1beta1/gateway_types.go

@@ -85,38 +85,62 @@ type GatewaySpec struct {
 	//
 	// Port and protocol combinations not listed above are considered Extended.
 	//
-	// An implementation MAY group Listeners by Port and then collapse each
-	// group of Listeners into a single Listener if the implementation
-	// determines that the Listeners in the group are "compatible". An
-	// implementation MAY also group together and collapse compatible
-	// Listeners belonging to different Gateways.
-	//
-	// For example, an implementation might consider Listeners to be
-	// compatible with each other if all of the following conditions are
-	// met:
-	//
-	// 1. Either each Listener within the group specifies the "HTTP"
-	//    Protocol or each Listener within the group specifies either
-	//    the "HTTPS" or "TLS" Protocol.
-	//
-	// 2. Each Listener within the group specifies a Hostname that is unique
-	//    within the group.
-	//
-	// 3. As a special case, one Listener within a group may omit Hostname,
-	//    in which case this Listener matches when no other Listener
-	//    matches.
-	//
-	// If the implementation does collapse compatible Listeners, the
-	// hostname provided in the incoming client request MUST be
-	// matched to a Listener to find the correct set of Routes.
-	// The incoming hostname MUST be matched using the Hostname
-	// field for each Listener in order of most to least specific.
-	// That is, exact matches must be processed before wildcard
-	// matches.
-	//
-	// If this field specifies multiple Listeners that have the same
-	// Port value but are not compatible, the implementation must raise
-	// a "Conflicted" condition in the Listener status.
+	// A Gateway's Listeners are considered "compatible" if:
+	//
+	// 1. The implementation can serve them in compliance with the Addresses
+	//    requirement that all Listeners are available on all assigned
+	//    addresses.
+	// 2. The implementation can match inbound requests to a single distinct
+	//    Listener. When multiple Listeners share values for fields (for
+	//    example, two Listeners with the same Port value), the implementation
+	//    can can match requests to only one of the Listeners using other
+	//    Listener fields.
+	//
+	// Compatible combinations in Extended support are expected to vary across
+	// implementations. A combination that is compatible for one implementation
+	// may not be compatible for another.
+	//
+	// If this field specifies multiple Listeners that are not compatible, the
+	// implementation MUST set the "Conflicted" condition in the Listener
+	// Status to "True".
+	//
+	// Implementations MAY choose to still accept a Gateway with conflicted
+	// Listeners if they accept a partial Listener set that contains no
+	// incompatible Listeners. They MUST set a "ListenersNotValid" condition
+	// the Gateway Status when the Gateway contains incompatible Listeners
+	// whether or not they accept the Gateway.
+	//
+	// For example, the following Listener scenarios may be compatible
+	// depending on implementation capabilities:
+	//
+	// 1. Multiple Listeners with the same Port that all use the "HTTP"
+	//    Protocol that all have unique Hostname values.
+	// 2. Multiple Listeners with the same Port that use either the "HTTPS" or
+	//    "TLS" Protocol that all have unique Hostname values.
+	// 3. A mixture of "TCP" and "UDP" Protocol Listeners, where no Listener
+	//    with the same Protocol has the same Port value.
+	//
+	// An implementation that cannot serve both TCP and UDP listeners on the same
+	// address, or cannot mix HTTPS and generic TLS listens on the same port
+	// would not consider those cases compatible.
+	//
+	// Implementations using the Hostname value to select between same-Port
+	// Listeners MUST match inbound request hostnames from the most specific
+	// to least specific Hostname values to find the correct set of Routes.
+	// Exact matches must be processed before wildcard matches, and wildcard
+	// matches must be processed before fallback (empty Hostname value)
+	// matches. For example, `"foo.example.com"` takes precedence over
+	// `"*.example.com"`, and `"*.example.com"` takes precedence over `""`.
+	//
+	// Implementations SHOULD NOT match requests to less specific Listeners if
+	// they exhaust attached routes on a more specific Listener. For example, a
+	// request for `subdomain.example.com/path` SHOULD NOT match an HTTPRoute
+	// attached to a Listener with Hostname `*.example.com` if there is a
+	// Listener with with Hostname `subdomain.example.com`, even if no routes
+	// on the second Listener match.
+	//
+	// Implementations MAY merge separate Gateways onto a single set of
+	// Addresses if all Listeners across all Gateways are compatible.
 	//
 	// Support: Core
 	//