Fix: #23. Cap conveyed throughput. See #19.

[ioggstream]

This PR

• MUST NOT expose unwanted throughput
• SHOULD cap conveyed throughput
• FAQ on w informative

[ucarion]

To be clear, w is informative, but the rest of Limit is not?

[ioggstream]

Before all, thanks @ucarion for your contribution: it really helps in improving the specs.

To be clear, w is informative, but the rest of Limit is not?

The Limit parameter identifies the total quota available; everything after the first comma is informative. I think that we should file a specific issue to identify the perimeter of the normative part.

On a certain point of view, all the three RateLimit fields are informative: the client is not forced to respect them. The point is mostly related to implementation and interoperability. For example an interoperable client could do something like that when a server doesn't send Remaining.

if "Remaining" not in headers:
  remaining = headers["Limit"] 
else:
  remaining = headers["Remaining"]

rps = remaining / headers["Reset"]

... validate rps, filter values too high, ... 

OTOH while a client implementation is free to parse and use w, a server should not rely on a generic client (eg on the web) processing those information. This is because at the moment the vast majority of clients won't do it and we don't want to force client implementing the current 3-integer models to change their implementation.

[ucarion]

That little piece of code is super helpful! Maybe we should speak in pseudo-code more often, I had no idea we would consider that sort of behavior valid.

I don't want to bog down this PR any further, I think things are cleared up!

[ioggstream]

close and reopen for gh

[ioggstream]

reopen

[ioggstream]

reopen

[ioggstream]

Thanks @darrelmiller! @unleashed feel free to merge if you agree.

[ioggstream]

@darrelmiller all suggestions are merged now ;)