Handling multiple RateLimit-Policy and RateLimit headers

[kevinswiber]

There's support for multiple policies in a single RateLimit-Policy header, but how should clients process multiple RateLimit-Policy headers? And what happens if a single response has multiple RateLimit headers?

[darrelmiller]

Clients can track remaining quota for each policy using the policy identifier as key. When the client receives a RateLimit header they policy identifier is used to track which is the associated policy.

GET /foo

200 OK
RateLimit-Policy: policy1;q=100;w=3600, policy2;q=1000;w=36400;
RateLimit: policy1;r=20;t=20, policy2;r=121;t=300;

[nfriedly]

Just to double-check, is

GET /foo

200 OK
RateLimit-Policy: policy1;q=100;w=3600, policy2;q=1000;w=36400;
RateLimit: policy1;r=20;t=20, policy2;r=121;t=300;

considered functionally equivalent to

GET /foo

200 OK
RateLimit-Policy: policy1;q=100;w=3600;
RateLimit: policy1;r=20;t=20;
RateLimit-Policy: policy2;q=1000;w=36400;
RateLimit: policy2;r=121;t=300;

Or is there a requirement that they're combined into a single RateLimit-Policy header and a single RateLimit header?

(I'd prefer treating the two as functionally equivalent, and I think some systems will automatically transform the later into the former.)

[Acconut]

Yes, they are equivalent. Since RateLimit and RateLimit-Policy are Lists from Structured Fields, their entries can be split across fields or combined. See https://www.rfc-editor.org/rfc/rfc8941#name-lists for details and an example.

[kevinswiber]

@darrelmiller @Acconut Oh, I completely missed this section!

This document uses the terms List, Item and Integer from Section 3 of [STRUCTURED-FIELDS] to specify syntax and parsing, along with the concept of "bare item".

I wonder if there's a way to make this clearer in the spec. Not only did I not see this, but I didn't register why "List" was capitalized in this paragraph:

The "RateLimit-Policy" response header field is a non-empty List of Quota Policy Items (Section 3.1).

Even if we repeat that it's a Structured Field here, I think the repetition would be worth it.

Thanks for clarifying!

[Acconut]

Thanks for the feedback. I'm not an editor on this draft, but I would support adding a sentence that mentions that RateLimit and RateLimit-Policy header fields can be split and merged due to them being SF Lists.