Need docs on "How does this work"

[jensenbox]

Granted I know how it works but a new person just coming to this project needs to know how the internals do what it needs and the prerequisites - like having a cache set up.

[jsocol]

I think there’s a little overlap here with #120.

I’m definitely down to add more docs, especially in the getting started section if we’ve glossed over prereqs!

From a purely information architecture standpoint though, I would want to think about where to put/what to document in the “how this works internally” realm. I don’t think it’s critical for a new person using the library to know all the details and don’t want to overload new folks, but want to support advanced users/contributors/debuggers.

[hartwork]

I think one implementation detail that would be important to document to users is that Django Ratelimit uses modulo operation so that 1/m would allow two requests only few second apart if the clock is near the full minute, while a user could assume that 1/m would enforce >=60 seconds between two unblocked requests. What do you think? Is that documented somewhere?

In code:

django-ratelimit/ratelimit/core.py

Line 97 in 72edbe8

w = ts - (ts % period) + (zlib.crc32(value) % period)

[alexirpan]

I just hit the same behavior that @hartwork mentioned, I thought a limit of 3/m would limit there to be at most 3 requests in any 1 minute block of time, but the behavior in code is to slice time into 1 minute chunks and allow at most 3 request per chunk (which allows up to 6 requests in a few seconds if they're sent between switch between 2 minutes.) I didn't find any part of the documentation which mentioned this.