[Backend] Upgrade Redis Backend for Multi-Process / Distributed Environments

[Vishisht16]

🎯 Objective

Refactor the current Redis storage backend to properly support multi-process (e.g., multiple Uvicorn workers) and distributed environments using atomic operations or distributed locks.

💡 Why this matters

Currently, HumaneProxy supports Redis as a backend, but the rate-limiting and trajectory window logic relies on in-memory state or non-atomic Redis operations. If an enterprise deploys HumaneProxy behind a load balancer with 4 Gunicorn/Uvicorn workers, race conditions can occur in updating the session risk trajectory or rate limits. We need true distributed state handling.

✅ Acceptance Criteria

• Review the current RedisBackend implementation in storage/.
• Implement atomic operations for rate-limiting (e.g., using Redis INCR with EXPIRE natively, or a Lua script for sliding window rate limits).
• Ensure the exponential time-decay trajectory window correctly appends and retrieves risk scores atomically across multiple workers.
• Write a test case (or script) that simulates concurrent requests from multiple threads to ensure no race conditions occur.

📚 Resources

• Redis Rate Limiting Patterns
• redis-py Pipelines and Transactions

[Ad1th]

Hi! I’d like to work on this issue. I’m interested in improving the Redis backend for proper multi-worker/distributed support using atomic Redis operations and Lua scripts where appropriate. I can also add concurrency tests to validate race-condition safety across multiple workers/threads. Please assign this issue to me if it’s available.

@Vishisht16

[Vishisht16]

Hello @Ad1th, allow me a couple of days to receive detailed official instructions from GSSoC team for scoring and assignments. Rest assured, I'll assign it to you as soon as I receive the formal details since you were the first to comment.

[Ad1th]

okay, thank you

[Vishisht16]

@Ad1th please walk me through your approach in detail, along with a summary of what files you would change or create. I want to know whether you've properly understood the scope of work or not and how exactly you'll manage to do it.

[Ad1th]

Okay so, first I would implement atomic rate limiting wiht Lua, instead of GET + SETX (since redis executes scripts transactionally), I can also keep the regular INCR as a fallback. (only redis.py is enough to modify)

then comes the distributed trajectory workflow, here, I would store trajectory data in Redis sorted sets. I will auto trim to keep only 5 recent entries. (redis.py and trajectory.py ill edit) (here, workers will be able to read each other's history from redis)

After that, I would edit base.py, it would extend the base interface a bit (to improve it, I can store and get trajectory windows)

then I would create new files for tests ofc, one for redis concurrency and in the test scenarios, i cna test for rate limits, distributed sessions and burst attacks

then ofc, ill update the readme accordingly.

pls lmk if this is fine, or if u need any modifications/ further changes, or anything done in a certain way.

[Vishisht16]

@Ad1th the approach is somewhat in the right direction, but there was some oversight and things I want you to consider.
Giving you a few points you should really take note of while writing the code:

1. Use register_script() from redis-py so we use EVALSHA. Also, just making you aware that there's a bug where INCR is not called by check_rate_limit() after first request. The Lua script would also be fixing this particular issue, so we don't require an INCR fallback.

2. Make sure that log() in redis.py is also made atomic. pipeline() is batching commands but might not be atomic if used with another worker. You can use a Lua script or MULTI/EXEC transactions for this.

3. Important: We're using EscalationStore for SQLite, Postgres and Redis backends. It's strict and will crash the app for SQLite and Postgres users if only updated for Redis. Instead of this, check if HUMANE_PROXY_STORAGE_BACKEND=redis. If it's Redis, create a dedicated RedisTrajectoryStore to handle sorted sets, otherwise fallback to current in-memory dict/deque.

4. Explicit Permission: Use fakeredis to write actual concurrency tests by spinning up multiple threads while calling check_rate_limit() and trajectories simultaneously to make sure there are no race conditions. I'm giving you explicit permission to add fakeredis to [dev] dependencies in pyproject.toml. You're not allowed to touch anything else in that file.

Let me know if the scope of the whole task is clear now. If there are any questions, feel free to ask and I'll help you out.

[Ad1th]

Okay, will definitely keep all of this in mind while coding, I'll also triple check and test run everything to make sure its working fine, before raising the PR.

[Vishisht16]

Alright, go ahead.