Merge pull request #2436 from youngnick/distinct-listeners

Add distinct concept to Listener definition

apis/v1beta1/gateway_types.go

@@ -69,49 +69,38 @@ type GatewaySpec struct {
 	// logical endpoints that are bound on this Gateway's addresses.
 	// At least one Listener MUST be specified.
 	//
-	// Each listener in a Gateway must have a unique combination of Hostname,
-	// Port, and Protocol.
+	// Each Listener in a set of Listeners (for example, in a single Gateway)
+	// MUST be _distinct_, in that a traffic flow MUST be able to be assigned to
+	// exactly one listener. (This section uses "set of Listeners" rather than
+	// "Listeners in a single Gateway" because implementations MAY merge configuration
+	// from multiple Gateways onto a single data plane, and these rules _also_
+	// apply in that case).
 	//
-	// Within the HTTP Conformance Profile, the below combinations of port and
-	// protocol are considered Core and MUST be supported:
+	// Practically, this means that each listener in a set MUST have a unique
+	// combination of Port, Protocol, and, if supported by the protocol, Hostname.
 	//
-	// 1. Port: 80, Protocol: HTTP
-	// 2. Port: 443, Protocol: HTTPS
+	// Some combinations of port, protocol, and TLS settings are considered
+	// Core support and MUST be supported by implementations based on their
+	// targeted conformance profile:
 	//
-	// Within the TLS Conformance Profile, the below combinations of port and
-	// protocol are considered Core and MUST be supported:
+	// HTTP Profile
 	//
-	// 1. Port: 443, Protocol: TLS
+	// 1. HTTPRoute, Port: 80, Protocol: HTTP
+	// 2. HTTPRoute, Port: 443, Protocol: HTTPS, TLS Mode: Terminate, TLS keypair provided
 	//
-	// Port and protocol combinations not listed above are considered Extended.
+	// TLS Profile
 	//
-	// A Gateway's Listeners are considered "compatible" if:
+	// 1. TLSRoute, Port: 443, Protocol: TLS, TLS Mode: Passthrough
 	//
-	// 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.
+	// "Distinct" Listeners have the following property:
 	//
-	// 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.
+	// 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 match requests to only one of the Listeners using other
+	// Listener fields.
 	//
-	// 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:
+	// For example, the following Listener scenarios are distinct:
 	//
 	// 1. Multiple Listeners with the same Port that all use the "HTTP"
 	//    Protocol that all have unique Hostname values.
@@ -120,18 +109,68 @@ type GatewaySpec struct {
 	// 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.
+	// Some fields in the Listener struct have possible values that affect
+	// whether the Listener is distinct. Hostname is particularly relevant
+	// for HTTP or HTTPS protocols.
+	//
+	// When using the Hostname value to select between same-Port, same-Protocol
+	// Listeners, the Hostname value must be different on each Listener for the
+	// Listener to be distinct.
+	//
+	// When the Listeners are distinct based on Hostname, inbound request
+	// hostnames MUST match from the most specific to least specific Hostname
+	// values to choose the correct Listener and its associated set of Routes.
 	//
-	// 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 `""`.
 	//
+	// Additionally, if there are multiple wildcard entries, more specific
+	// wildcard entries must be processed before less specific wildcard entries.
+	// For example, `"*.foo.example.com"` takes precedence over `"*.example.com"`.
+	// The precise definition here is that the higher the number of dots in the
+	// hostname to the right of the wildcard character, the higher the precedence.
+	//
+	// The wildcard character will match any number of characters _and dots_ to
+	// the left, however, so `"*.example.com"` will match both
+	// `"foo.bar.example.com"` _and_ `"bar.example.com"`.
+	//
+	// If a set of Listeners contains Listeners that are not distinct, then those
+	// Listeners are Conflicted, and the implementation MUST set the "Conflicted"
+	// condition in the Listener Status to "True".
+	//
+	// Implementations MAY choose to accept a Gateway with some Conflicted
+	// Listeners only if they only accept the partial Listener set that contains
+	// no Conflicted Listeners. To put this another way, implementations may
+	// accept a partial Listener set only if they throw out *all* the conflicting
+	// Listeners. No picking one of the conflicting listeners as the winner.
+	// This also means that the Gateway must have at least one non-conflicting
+	// Listener in this case, otherwise it violates the requirement that at
+	// least one Listener must be present.
+	//
+	// The implementation MUST set a "ListenersNotValid" condition on the
+	// Gateway Status when the Gateway contains Conflicted Listeners whether or
+	// not they accept the Gateway. That Condition SHOULD clearly
+	// indicate in the Message which Listeners are conflicted, and which are
+	// Accepted. Additionally, the Listener status for those listeners SHOULD
+	// indicate which Listeners are conflicted and not Accepted.
+	//
+	// A Gateway's Listeners are considered "compatible" if:
+	//
+	// 1. They are distinct.
+	// 2. The implementation can serve them in compliance with the Addresses
+	//    requirement that all Listeners are available on all assigned
+	//    addresses.
+	//
+	// 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.
+	//
+	// For example, 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, even though they are distinct.
+	//
 	// Note that requests SHOULD match at most one Listener. For example, if
 	// Listeners are defined for "foo.example.com" and "*.example.com", a
 	// request to "foo.example.com" SHOULD only be routed using routes attached
@@ -166,9 +205,6 @@ type GatewaySpec struct {
 	// other networking infrastructure, or some other address that traffic will
 	// be sent to.
 	//
-	// The .listener.hostname field is used to route traffic that has already
-	// arrived at the Gateway to the correct in-cluster destination.
-	//
 	// If no Addresses are specified, the implementation MAY schedule the
 	// Gateway in an implementation-specific manner, assigning an appropriate
 	// set of Addresses.