What it is
A utility submodule that enforces per-actor action quotas inside a SpacetimeDB module, tracking how many times each user or service has performed a given action within a rolling time window and blocking requests that exceed the configured limit.
Where it fits
- Social or content apps: Preventing users from flooding a feed by capping how many posts, comments, or reactions they can submit per minute.
- API abuse prevention: Throttling automated clients or bots that hammer expensive reducer calls faster than legitimate users would.
- Tiered access control: Giving free-tier users a lower quota and paid-tier users a higher one by configuring separate scopes per tier.
- Game action throttling: Limiting how often a player can perform a high-impact action, such as sending a challenge or claiming a reward, within a cooldown window.
- Admin-controlled moderation: Letting administrators inspect current usage across all actors and manually clear buckets when investigating abuse.
How it works
Each action type gets its own named scope with a configured limit and time window. When a user triggers that action, the submodule checks a per-actor bucket for that scope. If the actor still has capacity, the request is allowed and the bucket is decremented. If the bucket is empty, the request is rejected and the caller receives a structured error along with information about when their quota resets. The check and the action happen in the same transaction, so there is no gap where a rejected action could slip through.
Buckets are created on first use and expire naturally once their time window passes. A background sweep runs on a fixed schedule to delete expired records, keeping the tracking tables from growing unboundedly. Administrators can tune how many rows each sweep removes, trigger a sweep immediately, or wipe all buckets at once if needed.
Remaining capacity can be exposed to clients through a read-only view, letting a UI show a user how many actions they have left before hitting their limit. Because views have no live clock, the submodule provides a way to pass the current server time into the status check so that an already-expired window is reported as fully reset rather than still exhausted.
