guards.md

Guards and Rate Limits

Guards are reusable middleware blocks that enforce access rules before a handler runs. Use them to keep routing logic clean and consistent.

Built-in guards

• Preferred for authorization decisions:
  • RequireClientRightsAny - allow handlers when the current client account has any of the required TeamTalk UserRights.
  • RequireClientRightsAll - allow handlers when the current client account has all required TeamTalk UserRights.
• CommandOnly - allow only command messages.
• RequirePrivateMessage - allow private messages only.
• RequireChannelMessage - allow channel messages only.
• RequireCommand - allow a specific command name.
• RequireCommandPrefix - allow a specific prefix (/, !, etc.).
• RequireUserIds - allow a specific list of sender ids.
• Secondary / cache-based:
  • RequireUserType - allow a set of user_type values.

RequireUserType relies on Client::get_user, so it needs the sender to be available in the local cache.

RequireClientRightsAny and RequireClientRightsAll use the current logged-in account via Client::my_user_rights(). That matches the TeamTalk server/account model more closely than checking sender cache state.

In practice:

• Use rights-based guards for moderation, admin, broadcast, file, or channel management commands.
• Use RequireUserType only when you explicitly want sender classification from the cached User snapshot.

Example

use teamtalk::{
    CommandOnly, Permissions, RequireClientRightsAll, RequireClientRightsAny, RequireCommand,
    RequireCommandPrefix, RequirePrivateMessage, RequireUserIds, Router, UserId, UserRights,
};

let router = Router::new()
    .use_middleware(CommandOnly)
    .use_middleware(RequireCommandPrefix::new('/'))
    .use_middleware(RequirePrivateMessage)
    .use_middleware(RequireCommand::new("admin"))
    .use_middleware(RequireUserIds::new(vec![UserId(1), UserId(7)]))
    .use_middleware(RequireClientRightsAny::new(
        UserRights::KICK_USERS | UserRights::BAN_USERS,
    ))
    .use_middleware(RequireClientRightsAll::new(Permissions::moderator().rights()));

Use Permissions::moderator(), file_manager(), channel_admin(), media_sender(), desktop_controller(), or server_admin() / admin() when you want a predefined rights bundle instead of assembling bitmasks manually.

Rate limiting

Rate limiting is separate from guards, but it uses the same middleware pipeline.

use std::time::Duration;
use teamtalk::{RateLimitBySource, Router};

let router = Router::new().use_middleware(RateLimitBySource::new(Duration::from_secs(2)));