matches is unneeded if RateLimit is applied to an HTTPRoute. For example:

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: example
spec:
  ...
  rules:
    - matches:
        headers:
          - name: x-user-tier
            value: one
      filters:
        - type: ExtensionRef
          extensionRef:
            group: gateway.envoyproxy.io
            kind: RateLimiting
            name: ratelimit-specific-requests
      backendRefs:
        - name: httpbin
          port: 80

Matching criteria can be derived from the HTTPRoute that references the RateLimiting filter and RateLimiting can define the rate limit policy, e.g. domain and descriptors (for type Global).

the matches criteria within HTTPRoute helps map a specific traffic flow to a destination backend.
Even though the RateLimit is linked to a specific HTTPRoute, the matches criteria here further maps the traffic to specific users (source ip, header etc)

It feels to me like this is the biggest decision here - adding an extra layer of matching inside the ratelimit filter rather than having it filter whatever is configured in the HTTPRoute is an interesting approach - it's not really what I expected when thinking about this, tbh.

@arkodg, do you think you could put some explanation in this doc (maybe in the decisions made section) as to why you've chosen this way rather than the one Daneyon suggested? I'm not saying we should change it, just that we should record the reasons we've decided this way.

agreed, ive added a section on it under Design Decisions

I'm ok with matches, I did a similar design in my personal project with another name (rules).

It took me some time to understand the Distinct type. I have a feeling others will feel the same. What if we only supported Exact and RegularExpression? If Value is unspecified for Exact, then all values of name are selected.

same as #706 (comment)

Should we provide additional context to Name as Gateway API does, e.g. multiple rules with the same header name?

xref: https://github.com/kubernetes-sigs/gateway-api/blob/v0.6.0/apis/v1alpha2/grpcroute_types.go#L385-L389

@kflynn ^ comment is another candidate to resolve in a follow-on PR.

This comment can be removed if we drop the Distinct type. See https://github.com/envoyproxy/gateway/pull/706/files#r1054657720 for additional details.

Two of the three header matching types proposed in this PR are the same as upstream Gateway API. Do you know why Gateway API doesn't support the Distinct type? If not, it could be valuable to share our use case and get feedback.

its naming as well as use case has already been upvoted by reviewers, so I feel strongly to keep it, and proactively present it to the users, and get feedback for this v1alpha1 version.

Do you know why Gateway API doesn't support the Distinct type?

"Distinct" isn't really a matching mechanism per se, but rather denotes that each unique value for a header the RLS sees will get its own rate limiting bucket, which doesn't really fit into the idea of matching request attributes to funnel to a backend

It should be noted in the godocs that the global field is only applicable for type Global. I understand that Global is the only type currently supported but this will prevent confusion when other types, e.g. Local, are supported in the future. @arkodg please note this in the follow-on issue or @kflynn please resolve this in your PR.

@kflynn it would be appreciated if you can improve the godocs for this field.

@kflynn ^ comment is another candidate to resolve in a follow-on PR.

@arkodg constants should be defined for the ^ enums. For example:

const (
	// SecondRateLimitUnit defines the "Second" rate limit unit.
	SecondRateLimitUnit RateLimitUnit = "Second"

	...
)

cc: @kflynn