Skip to content

Storage API

Storage Backends

Memory Backends

Bases: RateLimiterBackend

In-memory rate limiter using sliding window with TTL cleanup.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/memory.py
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
class MemoryRateLimiter(RateLimiterBackend):
    """In-memory rate limiter using sliding window with TTL cleanup."""

    def __init__(self, *, engine: Literal["python", "rust"] = "python") -> None:
        """Initialize one process-local engine; no implicit fallback is performed."""
        validate_engine(engine)
        self.engine = engine
        self._native: RateCore | None = (
            load_native().RateLimiterCore() if engine == "rust" else None
        )
        self._counters: dict[str, deque[float]] = defaultdict(deque)
        self._lock = asyncio.Lock()

    async def allow(self, key: str, max_events: int, per_seconds: int) -> bool:
        """Check if request is allowed and increment counter."""
        validate_interval(max_events, "max_events")
        validate_interval(per_seconds, "per_seconds")
        if self._native is not None:
            return self._native.allow_text(
                key, max_events, per_seconds, time.monotonic()
            )
        async with self._lock:
            now = time.monotonic()
            # Clean up old entries
            counter = self._cleanup_old_entries(key, now, per_seconds)
            # Keep the deque local instead of repeating dictionary lookups.
            if len(counter) < max_events:
                counter.append(now)
                return True
            return False

    async def get_remaining(self, key: str, max_events: int, per_seconds: int) -> int:
        """Get remaining requests in current window."""
        validate_interval(max_events, "max_events")
        validate_interval(per_seconds, "per_seconds")
        if self._native is not None:
            return self._native.remaining(
                _native_key(key), max_events, per_seconds, time.monotonic()
            )
        async with self._lock:
            now = time.monotonic()
            # Clean up old entries
            counter = self._cleanup_old_entries(key, now, per_seconds)
            current_count = len(counter)
            return max(0, max_events - current_count)

    def _cleanup_old_entries(
        self, key: str, now: float, per_seconds: int
    ) -> deque[float]:
        """Remove entries older than the window."""
        window_start = now - per_seconds
        counter = self._counters[key]
        # Remove old entries from the left
        while counter and counter[0] < window_start:
            counter.popleft()
        return counter

    # Convenience methods for tests
    async def increment_rate_limit(self, key: str, window: int) -> int:
        """Increment rate limit counter and return current count."""
        if self._native is not None:
            return self._native.increment(_native_key(key), window, time.monotonic())
        async with self._lock:
            now = time.monotonic()
            # Clean up old entries
            counter = self._cleanup_old_entries(key, now, window)
            counter.append(now)
            return len(counter)

    async def get_rate_limit(self, key: str) -> int:
        """Get current rate limit count for key."""
        if self._native is not None:
            return self._native.count(_native_key(key), time.monotonic())
        async with self._lock:
            now = time.monotonic()
            # Clean up old entries (use a reasonable default window)
            counter = self._cleanup_old_entries(key, now, 60)
            return len(counter)

    async def reset_rate_limit(self, key: str) -> None:
        """Reset rate limit for key."""
        if self._native is not None:
            self._native.reset(_native_key(key))
            return
        async with self._lock:
            if key in self._counters:
                self._counters[key].clear()

__init__(*, engine='python')

Initialize one process-local engine; no implicit fallback is performed.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/memory.py
22
23
24
25
26
27
28
29
30
def __init__(self, *, engine: Literal["python", "rust"] = "python") -> None:
    """Initialize one process-local engine; no implicit fallback is performed."""
    validate_engine(engine)
    self.engine = engine
    self._native: RateCore | None = (
        load_native().RateLimiterCore() if engine == "rust" else None
    )
    self._counters: dict[str, deque[float]] = defaultdict(deque)
    self._lock = asyncio.Lock()

allow(key, max_events, per_seconds) async

Check if request is allowed and increment counter.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/memory.py
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
async def allow(self, key: str, max_events: int, per_seconds: int) -> bool:
    """Check if request is allowed and increment counter."""
    validate_interval(max_events, "max_events")
    validate_interval(per_seconds, "per_seconds")
    if self._native is not None:
        return self._native.allow_text(
            key, max_events, per_seconds, time.monotonic()
        )
    async with self._lock:
        now = time.monotonic()
        # Clean up old entries
        counter = self._cleanup_old_entries(key, now, per_seconds)
        # Keep the deque local instead of repeating dictionary lookups.
        if len(counter) < max_events:
            counter.append(now)
            return True
        return False

get_rate_limit(key) async

Get current rate limit count for key.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/memory.py
88
89
90
91
92
93
94
95
96
async def get_rate_limit(self, key: str) -> int:
    """Get current rate limit count for key."""
    if self._native is not None:
        return self._native.count(_native_key(key), time.monotonic())
    async with self._lock:
        now = time.monotonic()
        # Clean up old entries (use a reasonable default window)
        counter = self._cleanup_old_entries(key, now, 60)
        return len(counter)

get_remaining(key, max_events, per_seconds) async

Get remaining requests in current window.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/memory.py
50
51
52
53
54
55
56
57
58
59
60
61
62
63
async def get_remaining(self, key: str, max_events: int, per_seconds: int) -> int:
    """Get remaining requests in current window."""
    validate_interval(max_events, "max_events")
    validate_interval(per_seconds, "per_seconds")
    if self._native is not None:
        return self._native.remaining(
            _native_key(key), max_events, per_seconds, time.monotonic()
        )
    async with self._lock:
        now = time.monotonic()
        # Clean up old entries
        counter = self._cleanup_old_entries(key, now, per_seconds)
        current_count = len(counter)
        return max(0, max_events - current_count)

increment_rate_limit(key, window) async

Increment rate limit counter and return current count.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/memory.py
77
78
79
80
81
82
83
84
85
86
async def increment_rate_limit(self, key: str, window: int) -> int:
    """Increment rate limit counter and return current count."""
    if self._native is not None:
        return self._native.increment(_native_key(key), window, time.monotonic())
    async with self._lock:
        now = time.monotonic()
        # Clean up old entries
        counter = self._cleanup_old_entries(key, now, window)
        counter.append(now)
        return len(counter)

reset_rate_limit(key) async

Reset rate limit for key.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/memory.py
 98
 99
100
101
102
103
104
105
async def reset_rate_limit(self, key: str) -> None:
    """Reset rate limit for key."""
    if self._native is not None:
        self._native.reset(_native_key(key))
        return
    async with self._lock:
        if key in self._counters:
            self._counters[key].clear()

Bases: DebounceBackend

In-memory debounce backend using monotonic time.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/memory.py
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
class MemoryDebounce(DebounceBackend):
    """In-memory debounce backend using monotonic time."""

    def __init__(self, *, engine: Literal["python", "rust"] = "python") -> None:
        """Initialize one process-local engine; no implicit fallback is performed."""
        validate_engine(engine)
        self.engine = engine
        self._native: DebounceCore | None = (
            load_native().DebounceCore() if engine == "rust" else None
        )
        self._store: dict[str, float] = {}
        self._lock = asyncio.Lock()

    async def seen(self, key: str, window_seconds: int, fingerprint: str) -> bool:
        """Check if fingerprint was seen within window and record it."""
        validate_interval(window_seconds, "window_seconds")
        if self._native is not None:
            return self._native.seen_text(
                f"{key}:{fingerprint}", window_seconds, time.monotonic()
            )
        k = f"{key}:{fingerprint}"
        async with self._lock:
            now = time.monotonic()
            ts = self._store.get(k, 0)
            if ts and ts + window_seconds > now:
                return True
            self._store[k] = now
            return False

    # Convenience methods for tests
    async def set_debounce(self, key: str, delay: float) -> None:
        """Set debounce for a key."""
        if self._native is not None:
            self._native.set(_native_key(key), delay, time.monotonic())
            return
        async with self._lock:
            now = time.monotonic()
            if delay <= 0:
                # For zero or negative delay, don't set debounce
                if key in self._store:
                    del self._store[key]
            else:
                self._store[key] = now + delay

    async def is_debounced(self, key: str) -> bool:
        """Check if key is currently debounced."""
        if self._native is not None:
            return self._native.active(_native_key(key), time.monotonic())
        async with self._lock:
            now = time.monotonic()
            ts = self._store.get(key, 0)
            if ts and ts >= now:  # Use >= for boundary case
                return True
            # Clean up expired entries
            if key in self._store:
                del self._store[key]
            return False

    @property
    def _debounces(self) -> dict[str, float]:
        """Access to internal storage for testing."""
        if self._native is not None:
            return {
                bytes(key).decode("utf-8", "surrogatepass"): value
                for key, value in self._native.snapshot()
            }
        return self._store

__init__(*, engine='python')

Initialize one process-local engine; no implicit fallback is performed.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/memory.py
111
112
113
114
115
116
117
118
119
def __init__(self, *, engine: Literal["python", "rust"] = "python") -> None:
    """Initialize one process-local engine; no implicit fallback is performed."""
    validate_engine(engine)
    self.engine = engine
    self._native: DebounceCore | None = (
        load_native().DebounceCore() if engine == "rust" else None
    )
    self._store: dict[str, float] = {}
    self._lock = asyncio.Lock()

is_debounced(key) async

Check if key is currently debounced.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/memory.py
152
153
154
155
156
157
158
159
160
161
162
163
164
async def is_debounced(self, key: str) -> bool:
    """Check if key is currently debounced."""
    if self._native is not None:
        return self._native.active(_native_key(key), time.monotonic())
    async with self._lock:
        now = time.monotonic()
        ts = self._store.get(key, 0)
        if ts and ts >= now:  # Use >= for boundary case
            return True
        # Clean up expired entries
        if key in self._store:
            del self._store[key]
        return False

seen(key, window_seconds, fingerprint) async

Check if fingerprint was seen within window and record it.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/memory.py
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
async def seen(self, key: str, window_seconds: int, fingerprint: str) -> bool:
    """Check if fingerprint was seen within window and record it."""
    validate_interval(window_seconds, "window_seconds")
    if self._native is not None:
        return self._native.seen_text(
            f"{key}:{fingerprint}", window_seconds, time.monotonic()
        )
    k = f"{key}:{fingerprint}"
    async with self._lock:
        now = time.monotonic()
        ts = self._store.get(k, 0)
        if ts and ts + window_seconds > now:
            return True
        self._store[k] = now
        return False

set_debounce(key, delay) async

Set debounce for a key.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/memory.py
138
139
140
141
142
143
144
145
146
147
148
149
150
async def set_debounce(self, key: str, delay: float) -> None:
    """Set debounce for a key."""
    if self._native is not None:
        self._native.set(_native_key(key), delay, time.monotonic())
        return
    async with self._lock:
        now = time.monotonic()
        if delay <= 0:
            # For zero or negative delay, don't set debounce
            if key in self._store:
                del self._store[key]
        else:
            self._store[key] = now + delay

Redis Backends

Bases: RateLimiterBackend

Redis rate limiter using INCR + EXPIRE pattern.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/redis.py
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
class RedisRateLimiter(RateLimiterBackend):
    """Redis rate limiter using INCR + EXPIRE pattern."""

    def __init__(self, redis: Redis, prefix: str) -> None:
        """Initialize the rate limiter."""
        self._redis = redis
        self._prefix = prefix

    async def allow(self, key: str, max_events: int, per_seconds: int) -> bool:
        """Check if request is allowed and increment counter."""
        validate_interval(max_events, "max_events")
        validate_interval(per_seconds, "per_seconds")
        try:
            redis_key = f"{self._prefix}:rate:{key}"
            # Increment and expiry must commit together, including after a worker dies.
            count = await cast(
                Awaitable[int],
                self._redis.eval(
                    "local n = redis.call('INCR', KEYS[1]); "
                    "if redis.call('TTL', KEYS[1]) == -1 then "
                    "redis.call('EXPIRE', KEYS[1], ARGV[1]); end; return n",
                    1,
                    redis_key,
                    str(per_seconds),
                ),
            )
            return int(count) <= max_events
        except RedisError as e:
            raise BackendOperationError(f"Failed to check rate limit: {e}") from e

    async def get_remaining(self, key: str, max_events: int, per_seconds: int) -> int:
        """Get remaining requests in current window."""
        validate_interval(max_events, "max_events")
        validate_interval(per_seconds, "per_seconds")
        try:
            redis_key = f"{self._prefix}:rate:{key}"
            val = await self._redis.get(redis_key)
            return max(0, max_events - int(val or 0))
        except RedisError as e:
            raise BackendOperationError(f"Failed to get remaining: {e}") from e

__init__(redis, prefix)

Initialize the rate limiter.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/redis.py
19
20
21
22
def __init__(self, redis: Redis, prefix: str) -> None:
    """Initialize the rate limiter."""
    self._redis = redis
    self._prefix = prefix

allow(key, max_events, per_seconds) async

Check if request is allowed and increment counter.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/redis.py
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
async def allow(self, key: str, max_events: int, per_seconds: int) -> bool:
    """Check if request is allowed and increment counter."""
    validate_interval(max_events, "max_events")
    validate_interval(per_seconds, "per_seconds")
    try:
        redis_key = f"{self._prefix}:rate:{key}"
        # Increment and expiry must commit together, including after a worker dies.
        count = await cast(
            Awaitable[int],
            self._redis.eval(
                "local n = redis.call('INCR', KEYS[1]); "
                "if redis.call('TTL', KEYS[1]) == -1 then "
                "redis.call('EXPIRE', KEYS[1], ARGV[1]); end; return n",
                1,
                redis_key,
                str(per_seconds),
            ),
        )
        return int(count) <= max_events
    except RedisError as e:
        raise BackendOperationError(f"Failed to check rate limit: {e}") from e

get_remaining(key, max_events, per_seconds) async

Get remaining requests in current window.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/redis.py
46
47
48
49
50
51
52
53
54
55
async def get_remaining(self, key: str, max_events: int, per_seconds: int) -> int:
    """Get remaining requests in current window."""
    validate_interval(max_events, "max_events")
    validate_interval(per_seconds, "per_seconds")
    try:
        redis_key = f"{self._prefix}:rate:{key}"
        val = await self._redis.get(redis_key)
        return max(0, max_events - int(val or 0))
    except RedisError as e:
        raise BackendOperationError(f"Failed to get remaining: {e}") from e

Bases: DebounceBackend

Redis debounce backend using SET NX EX pattern.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/redis.py
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
class RedisDebounce(DebounceBackend):
    """Redis debounce backend using SET NX EX pattern."""

    def __init__(self, redis: Redis, prefix: str) -> None:
        """Initialize the debounce backend."""
        self._redis = redis
        self._prefix = prefix

    async def seen(self, key: str, window_seconds: int, fingerprint: str) -> bool:
        """Check if fingerprint was seen within window and record it."""
        validate_interval(window_seconds, "window_seconds")
        try:
            k = f"{self._prefix}:debounce:{key}:{fingerprint}"
            added = await self._redis.set(
                k, int(time.time()), ex=window_seconds, nx=True
            )
            # nx=True => returns True if set, None if exists
            return added is None
        except RedisError as e:
            raise BackendOperationError(f"Failed to check debounce: {e}") from e

__init__(redis, prefix)

Initialize the debounce backend.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/redis.py
61
62
63
64
def __init__(self, redis: Redis, prefix: str) -> None:
    """Initialize the debounce backend."""
    self._redis = redis
    self._prefix = prefix

seen(key, window_seconds, fingerprint) async

Check if fingerprint was seen within window and record it.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/redis.py
66
67
68
69
70
71
72
73
74
75
76
77
async def seen(self, key: str, window_seconds: int, fingerprint: str) -> bool:
    """Check if fingerprint was seen within window and record it."""
    validate_interval(window_seconds, "window_seconds")
    try:
        k = f"{self._prefix}:debounce:{key}:{fingerprint}"
        added = await self._redis.set(
            k, int(time.time()), ex=window_seconds, nx=True
        )
        # nx=True => returns True if set, None if exists
        return added is None
    except RedisError as e:
        raise BackendOperationError(f"Failed to check debounce: {e}") from e

Storage Protocols

Bases: Protocol

Protocol for rate limiting storage backend.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/base.py
10
11
12
13
14
15
16
17
18
19
20
@runtime_checkable
class RateLimiterBackend(Protocol):
    """Protocol for rate limiting storage backend."""

    async def allow(self, key: str, max_events: int, per_seconds: int) -> bool:
        """Check if request is allowed and increment counter."""
        ...

    async def get_remaining(self, key: str, max_events: int, per_seconds: int) -> int:
        """Get remaining requests in current window."""
        ...

allow(key, max_events, per_seconds) async

Check if request is allowed and increment counter.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/base.py
14
15
16
async def allow(self, key: str, max_events: int, per_seconds: int) -> bool:
    """Check if request is allowed and increment counter."""
    ...

get_remaining(key, max_events, per_seconds) async

Get remaining requests in current window.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/base.py
18
19
20
async def get_remaining(self, key: str, max_events: int, per_seconds: int) -> int:
    """Get remaining requests in current window."""
    ...

Bases: Protocol

Protocol for debouncing storage backend.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/base.py
23
24
25
26
27
28
29
@runtime_checkable
class DebounceBackend(Protocol):
    """Protocol for debouncing storage backend."""

    async def seen(self, key: str, window_seconds: int, fingerprint: str) -> bool:
        """Check if fingerprint was seen within window and record it."""
        ...

seen(key, window_seconds, fingerprint) async

Check if fingerprint was seen within window and record it.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/base.py
27
28
29
async def seen(self, key: str, window_seconds: int, fingerprint: str) -> bool:
    """Check if fingerprint was seen within window and record it."""
    ...

Factory

Build infrastructure backends (rate_limiter + debounce) based on configuration.

Source code in packages/aiogram-sentinel/src/aiogram_sentinel/storage/factory.py
10
11
12
13
14
15
16
17
def build_infra(config: SentinelConfig) -> InfraBundle:
    """Build infrastructure backends (rate_limiter + debounce) based on configuration."""
    if config.backend == "memory":
        return _build_memory_infra(config)
    elif config.backend == "redis":
        return _build_redis_infra(config)
    else:
        raise ConfigurationError(f"Unsupported backend: {config.backend}")