Cooldown Bucket

[PenguinBoi12]

The existing cooldown system tracks usage per sender (ctx.sender is the dict key in cooldown_calls). There is no way to apply a cooldown per room or globally across all users, which are common requirements for rate-limiting or noisy commands.

The idea is to add a BucketType that controls what the cooldown key is derived from. Per-user is the current behaviour and remains the default; per-room keys on ctx.room.room_id.

Proposed API

from matrix.checks import cooldown, BucketType

@cooldown(rate=1, period=10, bucket=BucketType.room)
@bot.command()
async def announce(ctx):
    await ctx.reply("Announcement!")

@cooldown(rate=5, period=60, bucket=BucketType.global_)
@bot.command()
async def search(ctx, query: str):
    ...

The change is localised to Command.set_cooldown in command.py, the user_id = ctx.sender line becomes a key derivation step based on the bucket type. BucketType can be a simple enum.Enum. The cooldown decorator in checks.py needs the extra parameter forwarded through; with default being global.. No structural changes to Command or Registry are needed beyond that.