The Penalty System tracks rate limit violations and can temporarily ban malicious actors.

PenaltyManager and the PENALTY_* presets are first-class exports from the package root in both SDKs (no more halt-rate/core/penalty deep imports).

Configuration

import { PenaltyManager, PENALTY_MODERATE } from 'halt-rate';

const penaltyManager = new PenaltyManager(store, {
  ...PENALTY_MODERATE,
  violationWeight: 1.0,    // Points per violation
  decayRate: 0.1,          // Points decay per minute
  threshold: 10.0,         // Points to trigger ban
  banDuration: 300         // Ban for 5 minutes
});

Integration

// 1. Check if user is banned
const penalty = await penaltyManager.getPenalty(userId);
if (penaltyManager.isActive(penalty)) {
  return res.status(403).json({ error: 'Account suspended' });
}

// 2. Report violations
if (!rateLimitResult.allowed) {
  await penaltyManager.recordViolation(userId);
}

Telemetry

Pass the same telemetry hook you use on the limiter to emit penalty_applied and violation events alongside the normal counters. Full details on Observability.

TypeScripttypescript

import { PenaltyManager, StatsCollector } from 'halt-rate';

const stats = new StatsCollector();
const penaltyManager = new PenaltyManager(store, config, { telemetry: stats });

// stats.snapshot().penaltiesApplied, stats.snapshot().violations

Pythonpython

from halt import PenaltyManager, StatsCollector

stats = StatsCollector()
manager = PenaltyManager(store=store, config=config, telemetry=stats)

# stats.snapshot()["penalties_applied"]