What it is
A SpacetimeDB module that enforces per-actor action quotas inside your server-side logic, 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: Prevent users from flooding a feed by capping how many posts, comments, or reactions they can submit per minute.
- API abuse prevention: Protect expensive server-side operations, such as search queries or AI completions, from being hammered by a single caller.
- Tiered access control: Apply different quotas to free versus paid users by configuring separate policies per tier, each with its own scope and limit.
- Game action throttling: Limit how frequently a player can perform high-impact actions like crafting, trading, or sending messages to other players.
- Admin-controlled moderation: Let administrators inspect active usage buckets, manually clear them, or adjust sweep behavior without redeploying the module.
How it works
Each action type gets its own named policy that specifies a maximum number of uses and the length of the time window. When a user triggers that action, the module checks a small record (a "bucket") associated with that user and action. If the bucket has remaining capacity, the action proceeds and the count is decremented. If not, the request is rejected immediately with a structured error that the client can handle gracefully.
Buckets are created on first use and automatically expire after their time window closes. A background sweep runs on a regular schedule to delete expired records, keeping the tracking tables from growing unboundedly. Administrators can tune how aggressively the sweep runs or trigger it manually if needed.
Capacity status is readable without consuming any quota, so your application can show users how many actions they have left and when their limit resets. The module also maintains its own administrator list, separate from your application's user roles, so rate-limit management can be delegated independently.
