Document the edge case with repeated query params

[pleshakov]

What would you like to be added:

Extend the documentation of the Name field of the HTTPQueryParamMatch to describe the edge case of having repeated query params with the same name in the query string of a request. For example, ?a=1&a=2.

Why this is needed:

This is needed to

• Ensure compatibility across Gateway implementations.
• To prevent users from relying on implementation-specific behavior which could cause issues when switching implementations.

For the query string ?a=1&a=2, currently, it is not specified whether the following matches match or not: (1)

queryParams:
- name: a
  value: "1"

(2)

queryParams:
- name: a
  value: "2"

Note that there is no standard that describes how a data plane must handle that case. Envoy, nginx use the first value of a param. See also https://github.com/kubernetes-sigs/gateway-api/discussions/1269

As discussed in the community meeting on July 18, 2022, in the documentation it makes sense to target the two sides of the Gateway API:

• The implementers: if the data plane allows, they should match against the first value of a param.
• The users: users should not route traffic based on repeated query params to guard themselves against potential differences in the Gateway API implementations.

See also the documentation of the repeated headers case https://github.com/kubernetes-sigs/gateway-api/blob/main/apis/v1beta1/httproute_types.go#L370-L371