[Conformance] ListenerSet conflict status reasons are inconsistent across API comments, GEP-1713 examples, and current tests

[JackStromberg]

There appears to be a mismatch between the documented Gateway API Listener/ListenerSet status model and the current gateway-api v1.5.1 ListenerSet conformance tests.

For ListenerSet listener conflicts, the docs and GEP examples indicate that the losing listener should report:

• Conflicted=True with reason HostnameConflict or ProtocolConflict
• Accepted=False with reason PortUnavailable
• Programmed=False with reason PortUnavailable

However, the current v1.5.1 ListenerSet conformance tests expect:

• Conflicted=True with reason HostnameConflict or ProtocolConflict
• Accepted=False with reason HostnameConflict or ProtocolConflict
• Programmed=False with reason HostnameConflict or ProtocolConflict

This creates an ambiguity for implementations; following the published docs/examples can fail current conformance.

Findings

1. Gateway API reason definitions suggest HostnameConflict / ProtocolConflict are Conflicted reasons

• ListenerReasonHostnameConflict is documented as:
  • used with the Conflicted condition when the listener conflicts with hostnames in other listeners
• ListenerReasonProtocolConflict is documented as:
  • used with the Conflicted condition when listeners share a port but have conflicting protocols

2. Gateway API reason definitions suggest PortUnavailable is the preferred Accepted=False loser reason

• ListenerConditionAccepted lists preferred False reasons including:

  • PortUnavailable
  • UnsupportedProtocol
  • NoValidCACertificate
  • UnsupportedValue

• ListenerReasonPortUnavailable is documented as:

  • used with the Accepted condition when the listener requests a port that cannot be used on the Gateway
  • examples include:
    • the port is already in use
    • the port is not supported by the implementation

This matches the idea that the loser in a merged-listener conflict is not accepted because the effective port slot is unavailable.

3. GEP-1713 conflict examples use PortUnavailable for Accepted=False and Programmed=False

In GEP-1713 Conformance Details, the ListenerSet conflict examples show the conflicted listener using:

• Accepted=False, reason PortUnavailable
• Programmed=False, reason PortUnavailable
• Conflicted=True, reason HostnameConflict or ProtocolConflict

This appears in both:

• ListenerSet protocol conflict examples
• ListenerSet hostname conflict examples

4. Current v1.5.1 ListenerSet conformance tests expect the conflict-specific reason on all three listener conditions

Current upstream tests appear to assert:

For hostname conflict:

• Accepted=False, reason HostnameConflict
• Programmed=False, reason HostnameConflict
• Conflicted=True, reason HostnameConflict

For protocol conflict:

• Accepted=False, reason ProtocolConflict
• Programmed=False, reason ProtocolConflict
• Conflicted=True, reason ProtocolConflict

Relevant tests:

• conformance/tests/listenerset-hostname-conflict.go
• conformance/tests/listenerset-protocol-conflict.go

Why this is a problem

This creates two competing sources of truth:

1. API reason constant comments and GEP-1713 examples
2. Current upstream ListenerSet conformance tests

An implementation that follows the published docs/examples can fail conformance.
An implementation that follows current conformance may end up with a reason taxonomy that is harder to justify from the API definitions.

Recommendation

I think the cleaner and better-documented behavior is:

• Conflicted=True -> HostnameConflict / ProtocolConflict
• Accepted=False -> PortUnavailable
• Programmed=False -> PortUnavailable for these ListenerSet conflict cases, following GEP-1713’s examples

Expected outcome

A single authoritative status mapping for ListenerSet conflict cases so implementations do not have to choose between:

• following the docs/GEP examples, or
• passing the current upstream conformance tests

[mikemorris]

I think this might be mostly the same concern as #4692? @JackStromberg could we consolidate discussion over there?

(If it is indeed the same scope, fine to leave this issue open and we can update the PR to mark as "fixes" this.)

[JackStromberg]

Yes, it looks like they are related. IMO, the proposed fix is a bit broad; I do like that the GEP is very prescriptive in what should be the expected experience vs generically allowing anything.