WIP checkpoint: Redis rate-limiting dependency

backend/alembic/env.py

@@ -8,7 +8,7 @@ from sqlalchemy.ext.asyncio import create_async_engine
 
 from app.config import settings
 from app.database import Base
-from app.models import user, session, world, asset, friendship, follow, block  # noqa: F401
+from app.models import user, session, world, asset  # noqa: F401
 
 # this is the Alembic Config object, which provides
 # access to the values within the .ini file in use.

backend/alembic/versions/0002_social_graph.py

@@ -1,136 +0,0 @@
-"""social graph: friendships, follows, blocks
-
-Revision ID: 0002_social_graph
-Revises: 0001_initial
-Create Date: 2026-08-18 00:00:00.000000
-"""
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-# revision identifiers, used by Alembic.
-revision: str = "0002_social_graph"
-down_revision: Union[str, None] = "0001_initial"
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    """Create friendships, follows, and blocks tables."""
-    op.create_table(
-        "friendships",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("requester_id", sa.Integer(), nullable=False),
-        sa.Column("addressee_id", sa.Integer(), nullable=False),
-        sa.Column("status", sa.String(length=20), server_default="pending", nullable=False),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), nullable=True),
-        sa.CheckConstraint(
-            "status IN ('pending', 'accepted')",
-            name="ck_friendships_status",
-        ),
-        sa.CheckConstraint(
-            "requester_id <> addressee_id",
-            name="ck_friendships_no_self",
-        ),
-        sa.ForeignKeyConstraint(
-            ["addressee_id"],
-            ["users.id"],
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["requester_id"],
-            ["users.id"],
-            ondelete="CASCADE",
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint(
-            "requester_id",
-            "addressee_id",
-            name="uq_friendships_requester_addressee",
-        ),
-    )
-    op.create_index(op.f("ix_friendships_id"), "friendships", ["id"], unique=False)
-    op.create_index(op.f("ix_friendships_addressee_id"), "friendships", ["addressee_id"], unique=False)
-    op.create_index(op.f("ix_friendships_requester_id"), "friendships", ["requester_id"], unique=False)
-
-    op.create_table(
-        "follows",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("follower_id", sa.Integer(), nullable=False),
-        sa.Column("followed_id", sa.Integer(), nullable=False),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-        sa.CheckConstraint(
-            "follower_id <> followed_id",
-            name="ck_follows_no_self",
-        ),
-        sa.ForeignKeyConstraint(
-            ["followed_id"],
-            ["users.id"],
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["follower_id"],
-            ["users.id"],
-            ondelete="CASCADE",
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint(
-            "follower_id",
-            "followed_id",
-            name="uq_follows_follower_followed",
-        ),
-    )
-    op.create_index(op.f("ix_follows_id"), "follows", ["id"], unique=False)
-    op.create_index(op.f("ix_follows_followed_id"), "follows", ["followed_id"], unique=False)
-    op.create_index(op.f("ix_follows_follower_id"), "follows", ["follower_id"], unique=False)
-
-    op.create_table(
-        "blocks",
-        sa.Column("id", sa.Integer(), nullable=False),
-        sa.Column("blocker_id", sa.Integer(), nullable=False),
-        sa.Column("blocked_id", sa.Integer(), nullable=False),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-        sa.CheckConstraint(
-            "blocker_id <> blocked_id",
-            name="ck_blocks_no_self",
-        ),
-        sa.ForeignKeyConstraint(
-            ["blocked_id"],
-            ["users.id"],
-            ondelete="CASCADE",
-        ),
-        sa.ForeignKeyConstraint(
-            ["blocker_id"],
-            ["users.id"],
-            ondelete="CASCADE",
-        ),
-        sa.PrimaryKeyConstraint("id"),
-        sa.UniqueConstraint(
-            "blocker_id",
-            "blocked_id",
-            name="uq_blocks_blocker_blocked",
-        ),
-    )
-    op.create_index(op.f("ix_blocks_id"), "blocks", ["id"], unique=False)
-    op.create_index(op.f("ix_blocks_blocked_id"), "blocks", ["blocked_id"], unique=False)
-    op.create_index(op.f("ix_blocks_blocker_id"), "blocks", ["blocker_id"], unique=False)
-
-
-def downgrade() -> None:
-    """Drop friendships, follows, and blocks tables."""
-    op.drop_index(op.f("ix_blocks_blocker_id"), table_name="blocks")
-    op.drop_index(op.f("ix_blocks_blocked_id"), table_name="blocks")
-    op.drop_index(op.f("ix_blocks_id"), table_name="blocks")
-    op.drop_table("blocks")
-
-    op.drop_index(op.f("ix_follows_follower_id"), table_name="follows")
-    op.drop_index(op.f("ix_follows_followed_id"), table_name="follows")
-    op.drop_index(op.f("ix_follows_id"), table_name="follows")
-    op.drop_table("follows")
-
-    op.drop_index(op.f("ix_friendships_requester_id"), table_name="friendships")
-    op.drop_index(op.f("ix_friendships_addressee_id"), table_name="friendships")
-    op.drop_index(op.f("ix_friendships_id"), table_name="friendships")
-    op.drop_table("friendships")

backend/app/config.py

@@ -16,6 +16,7 @@ class Settings(BaseSettings):
 
     # Redis
     REDIS_URL: str = "redis://localhost:6379/0"
+    REDIS_TIMEOUT_SECONDS: float = 2.0
 
     # JWT / Auth
     # NOTE: production must override SECRET_KEY with a secure random value

backend/app/models/__init__.py

@@ -2,17 +2,5 @@ from app.models.user import User
 from app.models.session import Session
 from app.models.world import World
 from app.models.asset import Asset
-from app.models.friendship import Friendship, FriendshipStatus
-from app.models.follow import Follow
-from app.models.block import Block
 
-__all__ = [
-    "User",
-    "Session",
-    "World",
-    "Asset",
-    "Friendship",
-    "FriendshipStatus",
-    "Follow",
-    "Block",
-]
+__all__ = ["User", "Session", "World", "Asset"]

backend/app/models/block.py

@@ -1,48 +0,0 @@
-"""Block model: a hard deny that also hides content and prevents DMs."""
-
-from sqlalchemy import CheckConstraint, Column, DateTime, ForeignKey, Integer, UniqueConstraint
-from sqlalchemy.orm import relationship
-from sqlalchemy.sql import func
-
-from app.database import Base
-
-
-class Block(Base):
-    __tablename__ = "blocks"
-    __table_args__ = (
-        UniqueConstraint(
-            "blocker_id",
-            "blocked_id",
-            name="uq_blocks_pair",
-        ),
-        CheckConstraint(
-            "blocker_id <> blocked_id",
-            name="ck_blocks_no_self",
-        ),
-    )
-
-    id = Column(Integer, primary_key=True, index=True)
-    blocker_id = Column(
-        Integer,
-        ForeignKey("users.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-    blocked_id = Column(
-        Integer,
-        ForeignKey("users.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
-
-    blocker = relationship(
-        "User",
-        foreign_keys=[blocker_id],
-        back_populates="blocks_issued",
-    )
-    blocked = relationship(
-        "User",
-        foreign_keys=[blocked_id],
-        back_populates="blocks_received",
-    )

backend/app/models/follow.py

@@ -1,48 +0,0 @@
-"""Follow model: a one-way relationship requiring no approval."""
-
-from sqlalchemy import CheckConstraint, Column, DateTime, ForeignKey, Integer, UniqueConstraint
-from sqlalchemy.orm import relationship
-from sqlalchemy.sql import func
-
-from app.database import Base
-
-
-class Follow(Base):
-    __tablename__ = "follows"
-    __table_args__ = (
-        UniqueConstraint(
-            "follower_id",
-            "followed_id",
-            name="uq_follows_pair",
-        ),
-        CheckConstraint(
-            "follower_id <> followed_id",
-            name="ck_follows_no_self",
-        ),
-    )
-
-    id = Column(Integer, primary_key=True, index=True)
-    follower_id = Column(
-        Integer,
-        ForeignKey("users.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-    followed_id = Column(
-        Integer,
-        ForeignKey("users.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
-
-    follower = relationship(
-        "User",
-        foreign_keys=[follower_id],
-        back_populates="following",
-    )
-    followed = relationship(
-        "User",
-        foreign_keys=[followed_id],
-        back_populates="followers",
-    )

backend/app/models/friendship.py

@@ -1,74 +0,0 @@
-"""Friendship model: a one-directional request that becomes mutual on accept."""
-
-from sqlalchemy import (
-    CheckConstraint,
-    Column,
-    DateTime,
-    ForeignKey,
-    Integer,
-    String,
-    UniqueConstraint,
-)
-from sqlalchemy.orm import relationship
-from sqlalchemy.sql import func
-
-from app.database import Base
-
-
-class FriendshipStatus:
-    """String values for the friendship.status column."""
-
-    PENDING = "pending"
-    ACCEPTED = "accepted"
-
-
-class Friendship(Base):
-    __tablename__ = "friendships"
-    __table_args__ = (
-        UniqueConstraint(
-            "requester_id",
-            "addressee_id",
-            name="uq_friendships_pair",
-        ),
-        CheckConstraint(
-            "requester_id <> addressee_id",
-            name="ck_friendships_no_self",
-        ),
-        CheckConstraint(
-            "status IN ('pending', 'accepted')",
-            name="ck_friendships_status",
-        ),
-    )
-
-    id = Column(Integer, primary_key=True, index=True)
-    requester_id = Column(
-        Integer,
-        ForeignKey("users.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-    addressee_id = Column(
-        Integer,
-        ForeignKey("users.id", ondelete="CASCADE"),
-        nullable=False,
-        index=True,
-    )
-    status = Column(
-        String(20),
-        nullable=False,
-        default=FriendshipStatus.PENDING,
-        server_default=FriendshipStatus.PENDING,
-    )
-    created_at = Column(DateTime(timezone=True), server_default=func.now())
-    updated_at = Column(DateTime(timezone=True), onupdate=func.now())
-
-    requester = relationship(
-        "User",
-        foreign_keys=[requester_id],
-        back_populates="sent_friend_requests",
-    )
-    addressee = relationship(
-        "User",
-        foreign_keys=[addressee_id],
-        back_populates="received_friend_requests",
-    )

backend/app/models/user.py

@@ -19,41 +19,3 @@ class User(Base):
     sessions = relationship("Session", back_populates="user", cascade="all, delete-orphan")
     worlds = relationship("World", back_populates="owner")
     assets = relationship("Asset", back_populates="owner")
-
-    # Social graph
-    sent_friend_requests = relationship(
-        "Friendship",
-        foreign_keys="Friendship.requester_id",
-        back_populates="requester",
-        cascade="all, delete-orphan",
-    )
-    received_friend_requests = relationship(
-        "Friendship",
-        foreign_keys="Friendship.addressee_id",
-        back_populates="addressee",
-        cascade="all, delete-orphan",
-    )
-    following = relationship(
-        "Follow",
-        foreign_keys="Follow.follower_id",
-        back_populates="follower",
-        cascade="all, delete-orphan",
-    )
-    followers = relationship(
-        "Follow",
-        foreign_keys="Follow.followed_id",
-        back_populates="followed",
-        cascade="all, delete-orphan",
-    )
-    blocks_issued = relationship(
-        "Block",
-        foreign_keys="Block.blocker_id",
-        back_populates="blocker",
-        cascade="all, delete-orphan",
-    )
-    blocks_received = relationship(
-        "Block",
-        foreign_keys="Block.blocked_id",
-        back_populates="blocked",
-        cascade="all, delete-orphan",
-    )

backend/app/rate_limit.py

@@ -0,0 +1,293 @@
+"""Redis-backed token-bucket rate limiting.
+
+This module provides a reusable FastAPI dependency that rate-limits requests
+per endpoint scope (optionally per-user) using an atomic Lua script on Redis.
+
+If Redis is unavailable the limiter can either allow the request through
+(fail-open) or reject it with a ``503`` (fail-closed), depending on the
+policy configured for that limit. Chat send uses fail-closed by default
+because flooding/abuse is worse than a temporary outage.
+
+Example
+-------
+    from app.rate_limit import rate_limit, named_limit
+
+    chat_send_limit = rate_limit(
+        named_limit("chat_send", capacity=5, refill_rate=0.2, fail_open=False),
+        user_id_dependency=Depends(get_current_user_id),
+    )
+
+    @router.post("/messages")
+    async def send_message(
+        payload: MessageCreate,
+        current_user: CurrentUser,
+        db: DbDep,
+        _: None = Depends(chat_send_limit),
+    ):
+        ...
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable
+
+from fastapi import Depends, HTTPException, Request, status
+from redis.asyncio import Redis
+from redis.exceptions import RedisError
+
+from app.config import settings
+
+# Atomic token-bucket implementation.
+#
+# KEYS[1] is the bucket key. ARGV[1] is the bucket capacity, ARGV[2] is the
+# refill rate in tokens per second, ARGV[3] is the current Unix time in
+# seconds (float), and ARGV[4] is the request cost (tokens to take).
+#
+# The bucket state is stored as a hash with "tokens" and "ts". The script
+# refills the bucket up to capacity, then takes the requested tokens. It
+# returns an array:
+#   [0] allowed (1 or 0)
+#   [1] tokens remaining after the take
+#   [2] retry-after seconds (0 when allowed)
+_TOKEN_BUCKET_LUA = """
+local key = KEYS[1]
+local capacity = tonumber(ARGV[1])
+local refill_rate = tonumber(ARGV[2])
+local now = tonumber(ARGV[3])
+local cost = tonumber(ARGV[4])
+
+local state = redis.call("HMGET", key, "tokens", "ts")
+local tokens = capacity
+local ts = now
+
+if state[1] ~= false then
+    tokens = tonumber(state[1])
+    ts = tonumber(state[2]) or now
+end
+
+local elapsed = math.max(0, now - ts)
+tokens = math.min(capacity, tokens + (elapsed * refill_rate))
+
+local allowed = 0
+local retry_after = 0
+
+if tokens >= cost then
+    tokens = tokens - cost
+    allowed = 1
+else
+    -- Time until enough tokens for a single request have accrued.
+    retry_after = math.ceil((cost - tokens) / refill_rate)
+end
+
+-- Keep the bucket state small and expire-able. Retaining the timestamp as a
+-- float lets partial tokens accumulate smoothly between requests.
+redis.call("HSET", key, "tokens", tostring(tokens), "ts", tostring(now))
+redis.call("PEXPIRE", key, 600000)
+
+return {allowed, tostring(tokens), retry_after}
+"""
+
+
+class RateLimitExceeded(HTTPException):
+    """Raised when a rate-limit bucket has no tokens left."""
+
+    def __init__(self, retry_after: int) -> None:
+        super().__init__(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail="Rate limit exceeded",
+            headers={"Retry-After": str(retry_after)},
+        )
+
+
+@dataclass(frozen=True)
+class RateLimit:
+    """Definition of a named token-bucket rate limit.
+
+    ``capacity`` is the burst size and ``refill_rate`` is the steady-state
+    token accumulation rate (tokens/second). For example,
+    ``RateLimit(name="chat_send", capacity=10, refill_rate=1.0)`` allows a
+    burst of 10 requests and then one request per second on average.
+    """
+
+    name: str
+    capacity: int
+    refill_rate: float
+    # When Redis is unreachable: ``True`` allows the request (fail-open),
+    # ``False`` rejects it with 503 (fail-closed).
+    fail_open: bool = True
+
+    def __post_init__(self) -> None:
+        if not self.name:
+            raise ValueError("name must be non-empty")
+        if self.capacity <= 0:
+            raise ValueError("capacity must be positive")
+        if self.refill_rate <= 0:
+            raise ValueError("refill_rate must be positive")
+
+
+def default_user_scope(request: Request, user_id: int | None) -> str:
+    """Scope a bucket per authenticated user, or per client IP if anonymous."""
+    if user_id is not None:
+        return f"user:{user_id}"
+    client = request.client
+    return f"ip:{client.host if client else 'unknown'}"
+
+
+@dataclass(frozen=True)
+class RateLimitConfig:
+    """A named rate limit plus how it is applied to a request."""
+
+    limit: RateLimit
+    # Builds the Redis key fragment for the request. The resolved user id is
+    # passed as the second argument (or ``None`` for anonymous limits).
+    scope: Callable[[Request, int | None], str] = default_user_scope
+
+
+@dataclass(frozen=True)
+class RateLimitResult:
+    """Outcome of a rate-limit check (used by tests)."""
+
+    allowed: bool
+    remaining: int
+    retry_after: int
+
+
+_redis_client: Redis | None = None
+
+
+def get_redis() -> Redis:
+    """Return a shared async Redis client for rate limiting.
+
+    The client is created lazily (``Redis.from_url`` does not connect until a
+    command is issued), so this dependency never blocks or fails just because
+    Redis is down.
+    """
+    global _redis_client
+    if _redis_client is None:
+        _redis_client = Redis.from_url(
+            settings.REDIS_URL,
+            encoding="utf-8",
+            decode_responses=True,
+            socket_connect_timeout=settings.REDIS_TIMEOUT_SECONDS,
+            socket_timeout=settings.REDIS_TIMEOUT_SECONDS,
+        )
+    return _redis_client
+
+
+class RateLimiter:
+    """Enforce a token bucket in Redis.
+
+    Buckets are keyed as ``rate:{limit.name}:{scope_key}`` so multiple
+    endpoints can share a named limit while remaining independently bucketed.
+    """
+
+    def __init__(self, config: RateLimitConfig, redis: Redis | None = None) -> None:
+        self._config = config
+        self._redis = redis
+
+    def _redis_client(self) -> Redis:
+        return self._redis or get_redis()
+
+    def _bucket_key(self, request: Request, user_id: int | None) -> str:
+        limit = self._config.limit
+        scope_key = self._config.scope(request, user_id)
+        return f"rate:{limit.name}:{scope_key}"
+
+    async def check(self, request: Request, user_id: int | None = None) -> RateLimitResult:
+        """Atomically refill/take a token and return the outcome.
+
+        Redis failures are mapped to ``allowed=True`` (fail-open) or
+        ``allowed=False`` (fail-closed, represented with ``retry_after=-1``)
+        according to the limit's policy, without raising.
+        """
+        limit = self._config.limit
+        key = self._bucket_key(request, user_id)
+
+        try:
+            result = await self._redis_client().eval(
+                _TOKEN_BUCKET_LUA,
+                1,
+                key,
+                str(limit.capacity),
+                str(limit.refill_rate),
+                str(time.time()),
+                "1",  # each request consumes one token
+            )
+        except RedisError:
+            if limit.fail_open:
+                return RateLimitResult(allowed=True, remaining=0, retry_after=0)
+            # Fail-closed: no reliable retry estimate is available.
+            return RateLimitResult(allowed=False, remaining=0, retry_after=-1)
+
+        # Redis may return ints or strings depending on decode_responses.
+        allowed = bool(int(result[0]))
+        remaining = int(result[1])
+        retry_after = int(result[2])
+        return RateLimitResult(allowed=allowed, remaining=remaining, retry_after=retry_after)
+
+    async def __call__(self, request: Request, user_id: int | None = None) -> None:
+        """Enforce the rate limit, raising 429 or 503 as appropriate."""
+        result = await self.check(request, user_id)
+        if result.allowed:
+            return
+
+        if result.retry_after < 0:
+            # Redis was unavailable and this limit is fail-closed.
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail="Rate limiting service unavailable",
+            )
+        raise RateLimitExceeded(retry_after=result.retry_after)
+
+
+def named_limit(
+    name: str,
+    *,
+    capacity: int,
+    refill_rate: float,
+    fail_open: bool = True,
+) -> RateLimitConfig:
+    """Create a named rate-limit config with the default per-user/IP scope.
+
+    ``capacity`` is the burst size and ``refill_rate`` is tokens/second.
+    """
+    return RateLimitConfig(
+        limit=RateLimit(
+            name=name,
+            capacity=capacity,
+            refill_rate=refill_rate,
+            fail_open=fail_open,
+        )
+    )
+
+
+def rate_limit(
+    config: RateLimitConfig,
+    *,
+    user_id_dependency: Any = None,
+) -> Callable[[Request, Any], Awaitable[None]]:
+    """Build a FastAPI dependency enforcing ``config``.
+
+    ``user_id_dependency`` optionally injects the authenticated user id, e.g.
+    ``Depends(get_current_user_id)``. If omitted the limiter buckets by client
+    IP (the ``default_user_scope`` fallback), which is suitable for anonymous
+    endpoints but should be paired with an auth resolver for per-user limits.
+
+    The returned callable is intended for ``Depends(...)``.
+    """
+
+    async def _anonymous_user_id() -> int | None:
+        return None
+
+    resolver = user_id_dependency if user_id_dependency is not None else Depends(_anonymous_user_id)
+
+    async def dependency(
+        request: Request,
+        user_id: int | None = resolver,
+    ) -> None:
+        limiter = RateLimiter(config)
+        await limiter(request, user_id)
+
+    return dependency

backend/tests/test_rate_limit.py

@@ -0,0 +1,193 @@
+"""Tests for the Redis-backed token-bucket rate limiter.
+
+These tests use fakeredis (Lua enabled via lupa) so no live Redis server is
+required.
+"""
+
+import asyncio
+import sys
+
+import pytest
+from fastapi import Depends, FastAPI, Request
+from fastapi.testclient import TestClient
+
+sys.path.insert(0, "/workspace")
+
+import fakeredis.aioredis
+from redis.asyncio import Redis
+from redis.exceptions import ConnectionError
+
+from app.rate_limit import (
+    RateLimit,
+    RateLimitConfig,
+    RateLimiter,
+    default_user_scope,
+    named_limit,
+    rate_limit,
+)
+
+
+@pytest.fixture()
+def fake_redis():
+    return fakeredis.aioredis.FakeRedis(decode_responses=True)
+
+
+def make_request(client_ip: str = "127.0.0.1") -> Request:
+    scope = {
+        "type": "http",
+        "method": "GET",
+        "path": "/",
+        "headers": [],
+        "client": (client_ip, 12345),
+    }
+    return Request(scope)
+
+
+@pytest.mark.asyncio
+async def test_token_bucket_allows_burst_then_exhausts(fake_redis):
+    limiter = RateLimiter(
+        RateLimitConfig(
+            limit=RateLimit(name="burst", capacity=3, refill_rate=0.1),
+        ),
+        redis=fake_redis,
+    )
+    request = make_request()
+
+    results = []
+    for _ in range(4):
+        result = await limiter.check(request, user_id=42)
+        results.append(result)
+
+    assert [r.allowed for r in results] == [True, True, True, False]
+    assert results[0].remaining == 2
+    assert results[1].remaining == 1
+    assert results[2].remaining == 0
+    assert results[3].retry_after > 0
+
+
+@pytest.mark.asyncio
+async def test_retry_after_reflects_refill_rate(fake_redis):
+    limiter = RateLimiter(
+        RateLimitConfig(
+            limit=RateLimit(name="slow", capacity=1, refill_rate=0.5),
+        ),
+        redis=fake_redis,
+    )
+    request = make_request()
+
+    assert (await limiter.check(request, user_id=7)).allowed is True
+    denied = await limiter.check(request, user_id=7)
+    assert denied.allowed is False
+    # 1 token / 0.5 tokens per second = 2 seconds.
+    assert denied.retry_after == 2
+
+
+@pytest.mark.asyncio
+async def test_separate_scopes_get_separate_buckets(fake_redis):
+    limiter = RateLimiter(
+        RateLimitConfig(
+            limit=RateLimit(name="scoped", capacity=1, refill_rate=0.1),
+        ),
+        redis=fake_redis,
+    )
+    request = make_request()
+
+    assert (await limiter.check(request, user_id=1)).allowed is True
+    assert (await limiter.check(request, user_id=2)).allowed is True
+    assert (await limiter.check(request, user_id=1)).allowed is False
+
+
+@pytest.mark.asyncio
+async def test_fail_open_returns_allowed_when_redis_unavailable():
+    class BrokenRedis(Redis):
+        async def eval(self, *args, **kwargs):
+            raise ConnectionError("down")
+
+    limiter = RateLimiter(
+        RateLimitConfig(
+            limit=RateLimit(name="open", capacity=1, refill_rate=0.1, fail_open=True),
+        ),
+        redis=BrokenRedis(),
+    )
+    result = await limiter.check(make_request(), user_id=1)
+    assert result.allowed is True
+
+
+@pytest.mark.asyncio
+async def test_fail_closed_returns_denied_with_negative_retry_after():
+    class BrokenRedis(Redis):
+        async def eval(self, *args, **kwargs):
+            raise ConnectionError("down")
+
+    limiter = RateLimiter(
+        RateLimitConfig(
+            limit=RateLimit(name="closed", capacity=1, refill_rate=0.1, fail_open=False),
+        ),
+        redis=BrokenRedis(),
+    )
+    result = await limiter.check(make_request(), user_id=1)
+    assert result.allowed is False
+    assert result.retry_after == -1
+
+
+@pytest.mark.asyncio
+async def test_fail_closed_call_raises_503(fake_redis):
+    class BrokenRedis(Redis):
+        async def eval(self, *args, **kwargs):
+            raise ConnectionError("down")
+
+    limiter = RateLimiter(
+        RateLimitConfig(
+            limit=RateLimit(name="closed", capacity=1, refill_rate=0.1, fail_open=False),
+        ),
+        redis=BrokenRedis(),
+    )
+    with pytest.raises(Exception) as exc_info:
+        await limiter(make_request(), user_id=1)
+    assert exc_info.value.status_code == 503
+
+
+def test_named_limit_builds_expected_config():
+    config = named_limit(
+        "chat_send",
+        capacity=5,
+        refill_rate=0.2,
+        fail_open=False,
+    )
+    assert config.limit.name == "chat_send"
+    assert config.limit.capacity == 5
+    assert config.limit.refill_rate == 0.2
+    assert config.limit.fail_open is False
+    assert config.scope is default_user_scope
+
+
+def test_invalid_limit_definition_rejected():
+    with pytest.raises(ValueError):
+        named_limit("bad", capacity=0, refill_rate=1.0)
+    with pytest.raises(ValueError):
+        named_limit("bad", capacity=1, refill_rate=0)
+
+
+def test_dependency_integration_returns_429_with_retry_after():
+    async def fake_user_id() -> int:
+        return 99
+
+    chat_limit = rate_limit(
+        named_limit("chat_send_test", capacity=2, refill_rate=0.1, fail_open=False),
+        user_id_dependency=Depends(fake_user_id),
+    )
+
+    app = FastAPI()
+
+    @app.get("/probe")
+    async def probe(_: None = Depends(chat_limit)):
+        return {"ok": True}
+
+    client = TestClient(app)
+    assert client.get("/probe").status_code == 200
+    assert client.get("/probe").status_code == 200
+
+    denied = client.get("/probe")
+    assert denied.status_code == 429
+    assert denied.headers["retry-after"]
+    assert denied.json() == {"detail": "Rate limit exceeded"}