A Rate Limiter With No Redis: flock and One JSON File
Django's default cache is per-process, so a rate-limit counter in it is silently wrong the moment you run more than one worker. Here is a correct limiter built on one JSON file and flock.
A bot found the contact form on a small Django site we run and started hammering it. One box, four gunicorn workers, SQLite, no Redis - and we did not want to add a daemon and a monitoring check to solve a problem that is fundamentally "count things for sixty seconds".
The first attempt, and why it was wrong
The obvious thing is Django's cache framework:
from django.core.cache import cache
def too_many(ip, limit=5, window=3600):
key = 'contact:%s' % ip
count = cache.get(key, 0)
if count >= limit:
return True
cache.set(key, count + 1, window)
return False
It passes every test you write for it under runserver, then goes to production and quietly stops limiting anything.
The reason is that Django's default cache backend is LocMemCache, and that is a plain Python dict inside the process. Not shared memory, not a file. With four gunicorn workers you have four independent counters and requests sprayed across all of them, so the effective limit becomes N times the intended one - where N is a worker count you will change one day without remembering it was load-bearing.
And it is silently wrong: a limiter off by 4x does not throw and does not log. Confirm it in one line - set a key in four separate python -c processes and read it back in each; every process sees only its own write.
The usual answers are Redis or Memcached, and if you already run one, use it - django-ratelimit on a shared cache backend is a fine solution. But "already run one" is doing a lot of work there. Adding Redis for this means a new daemon, a new systemd unit, a new failure mode when it is unreachable, and one more thing that wakes you up: a large tax on a contact form.
The alternative: one file, one lock
All four workers already share the filesystem. fcntl.flock gives you mutual exclusion over a file descriptor, arbitrated by the kernel across processes on the same machine. Hold an exclusive lock across a read-modify-write of one small JSON file and the counter is correct.
"""File-backed sliding-window rate limiter. One JSON file, one flock."""
import errno
import fcntl
import json
import os
import time
STATE_PATH = os.environ.get('RATELIMIT_STATE', '/var/lib/myapp/ratelimit.json')
def _ensure(path):
directory = os.path.dirname(path)
if directory and not os.path.isdir(directory):
os.makedirs(directory, exist_ok=True)
if not os.path.exists(path):
# O_CREAT|O_EXCL so two workers racing to create it cannot
# truncate each other's file.
try:
fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
except OSError as exc:
if exc.errno != errno.EEXIST:
raise
else:
os.write(fd, b'{}')
os.close(fd)
def hit(key, limit, window, path=None, now=None):
"""Record a hit for `key`. Return (allowed, retry_after_seconds)."""
path = path or STATE_PATH
now = time.time() if now is None else now
_ensure(path)
with open(path, 'r+') as f:
fcntl.flock(f.fileno(), fcntl.LOCK_EX)
try:
raw = f.read()
try:
state = json.loads(raw) if raw.strip() else {}
if not isinstance(state, dict):
state = {}
except ValueError:
# Truncated or hand-edited file: start over and allow.
state = {}
cutoff = now - window
pruned = {}
for k, stamps in state.items():
recent = [t for t in stamps
if isinstance(t, (int, float)) and t > cutoff]
if recent:
pruned[k] = recent
state = pruned
stamps = state.get(key, [])
if len(stamps) >= limit:
retry_after = max(int(stamps[0] + window - now) + 1, 1)
allowed = False
else:
stamps.append(now)
state[key] = stamps
allowed, retry_after = True, 0
f.seek(0)
json.dump(state, f)
f.truncate() # without this, a shrinking payload leaves tail garbage
f.flush()
os.fsync(f.fileno())
return allowed, retry_after
finally:
fcntl.flock(f.fileno(), fcntl.LOCK_UN)
One open, in r+ mode
The file is opened once and the lock is held across the read and the write. Opening to read, closing, then reopening to write is the classic mistake: between the two opens another worker slips in and your write clobbers its increment. 'r+' is read-plus-write without truncating, so the file must exist first - hence _ensure, which uses O_CREAT|O_EXCL so two workers starting at once cannot blank each other's state.
seek, dump, and the truncate everyone forgets
After reading, the file position is at the end. f.seek(0) rewinds so the new JSON overwrites the old. But overwriting a longer document with a shorter one leaves the tail of the old one in place, and the result is a file that looks like {"a": [1]}[2], "b": [3]} - invalid JSON, produced by code that ran without error.
The vicious part is the timing. While traffic grows the payload only gets longer, so the bug is invisible. It appears the first time the state shrinks - a quiet hour, keys pruned - days after the deploy, with no related change in the log. f.truncate() after the dump is the whole fix.
A sliding window, not a bucket
The state is a list of hit timestamps per key, and each call drops the ones older than the window. That gives a true sliding window: five per hour means five in any rolling hour, not five per clock hour with a free reset that a bot will find immediately.
The cost is storage proportional to the limit - five floats at five per hour. Do not use this shape for a limit of ten thousand.
Pruning
Every call rebuilds the dict keeping only keys with recent hits. Without that, every IP that ever touched the endpoint stays in the file forever and you have built a slow memory leak on disk. Pruning on write bounds the file by recent traffic, and costs nothing because you are already parsing the whole document.
Corrupt input degrades to allow
If the JSON will not parse, the code resets to an empty dict and allows the request. That is a deliberate fail-open choice: returning 500 to every visitor because a file got truncated during a disk-full event would be a worse outage than the one this prevents. Where failing open is unacceptable - a password reset endpoint, a paid API - invert it and return (False, window) in that branch. Either way, pick on purpose and write it in a comment.
Verifying it, including the part that matters
A lock you have not tested under concurrency is a lock you are hoping about. The test below covers the window behaviour, then the real one: eight processes, forty attempts each, limit twenty, asserting that exactly twenty are allowed. It runs the same logic with the flock lines removed too, so the race is not hypothetical.
import fcntl, json, multiprocessing, os, sys, tempfile, time
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import ratelimit
TMP = tempfile.mkdtemp(prefix='rl-')
# The same function with the flock lines removed, to show the race is real.
def unlocked_hit(key, limit, window, path=None, now=None):
now = time.time() if now is None else now
ratelimit._ensure(path)
with open(path, 'r+') as f:
raw = f.read()
try:
state = json.loads(raw) if raw.strip() else {}
except ValueError:
state = {}
stamps = [t for t in state.get(key, []) if t > now - window]
if len(stamps) >= limit:
return False, 1
time.sleep(0.0005) # widen the window the lock would have closed
stamps.append(now)
state[key] = stamps
f.seek(0); json.dump(state, f); f.truncate()
return True, 0
def worker(args):
path, use_lock = args
fn = ratelimit.hit if use_lock else unlocked_hit
return sum(1 for _ in range(40) if fn('burst', 20, 60.0, path=path)[0])
# (a) allows N, blocks N+1
p = os.path.join(TMP, 'a.json')
results = [ratelimit.hit('ip:203.0.113.7', 3, 1.0, path=p)[0] for _ in range(5)]
print('a) limit=3, five calls ->', results)
assert results == [True, True, True, False, False]
# (b) allows again once the window has passed
time.sleep(1.1)
allowed, retry = ratelimit.hit('ip:203.0.113.7', 3, 1.0, path=p)
print('b) after the 1s window ->', allowed)
assert allowed is True
# (c) concurrency: the assertion that proves the lock
for use_lock in (True, False):
path = os.path.join(TMP, 'c-%s.json' % use_lock)
with multiprocessing.Pool(8) as pool:
counts = pool.map(worker, [(path, use_lock)] * 8)
print('c) %s: 8 procs x 40 attempts, limit 20 -> allowed %d %s'
% ('with flock ' if use_lock else 'without flock', sum(counts), counts))
if use_lock:
assert sum(counts) == 20, 'expected exactly 20, got %d' % sum(counts)
# (d) a corrupt file degrades to allow rather than 500
p = os.path.join(TMP, 'd.json')
open(p, 'w').write('{"burst": [1, 2, 3')
print('d) corrupt file ->', ratelimit.hit('burst', 2, 60.0, path=p))
print('ALL ASSERTIONS PASSED')
The real output:
a) limit=3, five calls -> [True, True, True, False, False]
b) after the 1s window -> True
c) with flock : 8 procs x 40 attempts, limit 20 -> allowed 20 [3, 17, 0, 0, 0, 0, 0, 0]
c) without flock: 8 procs x 40 attempts, limit 20 -> allowed 210 [40, 18, 22, 13, 40, 34, 22, 21]
d) corrupt file -> (True, 0)
ALL ASSERTIONS PASSED
Twenty with the lock. Two hundred and ten without - more than ten times the intended limit, from the same code minus the lock lines. The exact figure varies run to run, which is itself the point: a race does not fail the same way twice.
Wiring it into Django
A decorator is enough. Return 429 with a Retry-After header: a well-behaved client honours it, and a badly-behaved one cannot claim it was not told.
from functools import wraps
from django.http import HttpResponse
from .ratelimit import hit
def client_ip(request):
# Only trust XFF if a proxy you control sets it.
forwarded = request.META.get('HTTP_X_FORWARDED_FOR', '')
if forwarded:
return forwarded.split(',')[0].strip()
return request.META.get('REMOTE_ADDR', '0.0.0.0')
def rate_limit(limit, window, scope='default'):
def decorator(view):
@wraps(view)
def wrapper(request, *args, **kwargs):
if request.method in ('GET', 'HEAD', 'OPTIONS'):
return view(request, *args, **kwargs)
key = '%s:%s' % (scope, client_ip(request))
allowed, retry_after = hit(key, limit, window)
if not allowed:
response = HttpResponse(
'Too many requests.', status=429,
content_type='text/plain; charset=utf-8')
response['Retry-After'] = str(retry_after)
return response
return view(request, *args, **kwargs)
return wrapper
return decorator
@rate_limit(limit=5, window=3600, scope='contact')
def contact_submit(request):
return HttpResponse('Thanks, I reply within two business days.')
The X-Forwarded-For comment is not decoration: read that header without a proxy in front that overwrites it, and anyone can fake one for a fresh bucket per request.
Where the file goes
Outside the web root. Not "inside it with an .htaccess deny rule" - outside it. A deny rule is one config mistake or one migration to a different web server away from being gone, and the failure is silent: the file becomes downloadable, and it holds a list of your visitors' IP addresses with timestamps. /var/lib/myapp/ratelimit.json, owned by the app user, mode 0600. No rule to get wrong, because the path was never served.
Put it on real local disk, too. On NFS, flock semantics vary by version and mount option, and a limiter that is usually atomic is not one.
When not to do this
The honest boundary is the machine. flock coordinates processes on one kernel; it knows nothing about a second app server. Scale to two boxes behind a load balancer and each has its own file and its own count - back to the multiplication problem, except at 2x per box instead of 4x per worker, which looks like it is nearly working. At that point Redis stops being overkill and starts being right. Write the interface so hit() is the only thing that changes.
Three more disqualifiers. flock is POSIX and advisory: nothing on Windows, and it only excludes processes that also ask for it - a maintenance script editing the file directly will corrupt your state regardless. Every call is an open, a parse, a serialise and an fsync, which is fine at contact-form rates and miserable at thousands per second. And if you need distributed quotas or per-plan API limits with billing attached, buy something built for it.
Within its boundary, though, it is hard to beat: no new service, no new failure mode, nothing new to monitor, and a correctness property you can assert in a two-second test.
This is the kind of decision that makes up a lot of Django and Python work: not choosing frameworks, but deciding whether a problem deserves infrastructure. We also handle the smaller front-end builds that come with it. Start a project, describe the problem, and we reply within two business days.
We ship and run our own products. We build yours the same way.
Start a project