enerthya.dev-antiflood

Rate limiter avançado para o bot Enerthya.

Keyed por commandName + userId + guildId, com burst window deslizante, penalidade progressiva (aditiva ou exponencial) e whitelist de cargos.

Depende de enerthya.dev-common para formatação de tempo — não reimplementa o que já existe.

Instalação

npm install enerthya.dev-antiflood

Uso básico

const { AntifloodManager, isBlocked, formatRetryAfter } = require("enerthya.dev-antiflood");

const antiflood = new AntifloodManager({
  globalRule: {
    windowMs:    5000,     // janela deslizante de 5s
    maxHits:     3,        // máximo de 3 usos nessa janela
    penaltyMode: "ADDITIVE",
    penaltyStep: 10000,    // +10s de penalidade por hit excedente
    maxPenalty:  60000,    // teto de 60s de penalidade
  },
  whitelistRoleIds: ["ID_CARGO_ADMIN"],
});

// Dentro do handler de comando:
const result = antiflood.check({
  userId:        interaction.user.id,
  guildId:       interaction.guildId,
  commandName:   "ban",
  memberRoleIds: interaction.member.roles.cache.map(r => r.id),
});

if (isBlocked(result)) {
  return interaction.reply({
    content: `Você está usando este comando rápido demais. Aguarde ${formatRetryAfter(result.retryAfterMs)}.`,
    ephemeral: true,
  });
}

API

new AntifloodManager(options?)

| Opção | Tipo | Padrão | Descrição | |---|---|---|---| | globalRule | object | veja DEFAULT_RULE | Regra aplicada quando não há regra por comando | | whitelistRoleIds | string[] | [] | Cargos que sempre passam sem checagem | | enabled | boolean | true | Master switch |

.setRule(commandName, ruleConfig) → this

Registra uma regra específica para um comando. Tem prioridade sobre a global.

.addWhitelist(...roleIds) → this

Adiciona cargos à whitelist em runtime.

.removeWhitelist(roleId) → this

Remove um cargo da whitelist.

.check({ userId, guildId?, commandName?, memberRoleIds? })

Retorna:

{
  result:       "ALLOWED" | "THROTTLED" | "PENALIZED" | "WHITELISTED",
  retryAfterMs: number,   // ms até poder tentar de novo (0 se liberado)
  hitsInWindow: number,   // hits acumulados na janela atual
  penaltyUntil: number,   // timestamp fim da penalidade (0 se não há)
  rule:         object,   // regra que foi aplicada
}

.reset({ userId, guildId?, commandName? })

Desbloqueia manualmente um usuário para um comando+guild.

.resetAll()

Limpa todo o estado (ex: restart do bot).

.disable() / .enable()

Liga/desliga o rate limiter globalmente.

createRule(config?)

Valida e retorna um objeto de regra frozen. Útil para criar regras de forma isolada.

const { createRule, PENALTY_MODE } = require("enerthya.dev-antiflood");

const strictRule = createRule({
  windowMs:    3000,
  maxHits:     1,
  penaltyMode: PENALTY_MODE.EXPONENTIAL,
  penaltyStep: 5000,
  maxPenalty:  120000,
});

FLOOD_RESULT (constantes)

| Valor | Descrição | |---|---| | ALLOWED | Passou normalmente | | THROTTLED | Bloqueado até janela deslizar (sem penalidade progressiva) | | PENALIZED | Bloqueado com penalidade progressiva ativa | | WHITELISTED | Bypassed por cargo na whitelist |

PENALTY_MODE (constantes)

| Valor | Comportamento | |---|---| | NONE | Bloqueia até a janela deslizar — sem penalidade extra | | ADDITIVE | Cada hit excedente adiciona penaltyStep ms à trava | | EXPONENTIAL | Cada hit excedente dobra a duração da trava (2^n * penaltyStep) |

formatRetryAfter(ms) → string

Converte ms em texto PT-BR legível. Delega para enerthya.dev-common.

formatRetryAfter(1500)  // "1 segundo"
formatRetryAfter(65000) // "1 minuto, 5 segundos"

isBlocked(checkResult) → boolean

true se result é THROTTLED ou PENALIZED.

Dependências

| Pacote | Uso | |---|---| | enerthya.dev-common | formatTime para formatar retryAfterMs em PT-BR |