Optional Rust memory engine (1.3.0 candidate)¶
The base aiogram-sentinel distribution remains a pure Python Hatchling wheel.
Python is the default and needs neither Rust nor the companion. Redis backends
always use Redis atomic operations as their distributed authority; selecting an
engine never adds a local Redis counter cache.
Publication is withheld: the serial qualification failed the required CPU
improvement gate. The companion remains available from source; there is no
native release or [native] extra. The Python base can ship independently. See
measured results and host limitations.
The source companion aiogram-sentinel-native==1.3.0 is built separately with
Maturin and ABI3 for Python 3.10+. It has no dependency on the base distribution.
There is no native extra until publication and performance qualification succeed.
For local evaluation after installing the exact matching companion wheel:
from aiogram_sentinel import SentinelConfig
from aiogram_sentinel.storage.memory import MemoryRateLimiter, MemoryDebounce
config = SentinelConfig(engine="rust") # memory infrastructure only
limiter = MemoryRateLimiter(engine="rust")
debounce = MemoryDebounce(engine="rust")
Explicit Rust selection checks the companion's distribution identity, exact
version and ABI1 capabilities before creating an engine. Missing wheels raise
NativeEngineUnavailable; mismatches raise NativeEngineIncompatible. Both are
configuration errors. Capability fields require exact tuple/string/integer
types (a boolean is not ABI1), and both complete kernel interfaces are checked
using fresh empty instances before either backend is exposed. This check never
calls a state-mutating operation. A kernel error propagates; no request is replayed against
Python after a native mutation. Do not catch the error and retry with a fresh
engine: that would discard the limiting history.
Both engines use one process's monotonic clock and hold no durable state. Native calls hold the GIL and a Rust mutex, with no asynchronous I/O or Python callback. They are atomic without an await; this does not claim parallel CPU throughput. Python retains its task lock. Separate instances never share counters. Choose Redis for multiple processes or replicas.
The engines preserve the existing memory behavior: rate-window cutoff is strict
(< now-window); duplicate debounce expiration is exclusive, while the direct
is_debounced helper includes its deadline. Rejected debounce calls do not extend
the window. Requests with a smaller window destructively discard older entries,
just as before. Other keys are never swept in a way that loses history visible
to a future larger window. This intentionally retains quiet keys; applications
requiring bounded persistent storage should use Redis. Backend keys and
fingerprints follow the public typed contract (str), including unpaired
surrogates, preserved through a UTF-8 surrogatepass byte boundary.
Verification and performance gate¶
tests/unit/test_native.py compares seeded sequences of all public operations,
window changes, keys and exact times against the Python reference. Rust unit
tests also exercise boundaries and quiet-key retention. Native CI builds seven
platform wheels; the separate publisher verifies exact assets and hashes rather
than rebuilding them. Base publishing accepts only base assets.
Run benchmarks/run.py --engine python|rust --output PATH [--quick] using an
installed package. The same script supports published 1.2.0, which has no engine
keyword. benchmarks/pyperf_memory.py records calibrated pyperf samples; set
SENTINEL_ENGINE=rust for native. cargo bench --manifest-path native/Cargo.toml
records Criterion kernels. Neither script injects the source tree into imports.
Development results are not release qualification. The completed serial comparison measured Rust/Python CPU ratios of 0.88350 for accepted rate-limit operations over many keys and 0.92370 for accepted debounce operations over many keys. Neither meets the required 20% reduction. The middleware update p95 ratio was 0.71225, but Python repeat spread exceeded 10%; no tail-latency gain can be claimed.
These are host-specific macOS x86_64 / CPython 3.12.13 observations, not universal performance claims. Constructor ABI hardening does not change the measured hot paths or native artifact and does not qualify speed. Native publication is withheld; functional platform checks do not override the failed gate.