stt::security Namespace Reference

API related to information security. More...

Classes
struct	RateState
	Runtime state for one limiter key (reused by multiple strategies). More...
struct	ConnectionState
	Security and limiter state for a single connection (fd). More...
struct	IPInformation
	Security state and connection set for a single IP. More...
class	ConnectionLimiter
	Unified connection & request security gate (IP-level + fd-level, multi-strategy limiting + blacklist). More...

Enumerations
enum	RateLimitType { RateLimitType::Cooldown, RateLimitType::FixedWindow, RateLimitType::SlidingWindow, RateLimitType::TokenBucket }
	Rate limiting algorithm / strategy type. More...
enum	DefenseDecision : int { ALLOW = 0, DROP = 1, CLOSE = 2 }
	Security decision returned by ConnectionLimiter. More...

Detailed Description

API related to information security.

Enumeration Type Documentation

enum stt::security::DefenseDecision : int

Security decision returned by ConnectionLimiter.

Every connection/request must pass the limiter before entering business logic.

• ALLOW (0):
  • Continue processing
• DROP (1):
  • Silently ignore the request (no response)
  • Intended for lightweight defense at request stage
• CLOSE (2):
  • Close the connection immediately
  • May be accompanied by risk escalation or temporary ban

Note

• Connect stage typically uses only ALLOW / CLOSE.
• DROP is primarily for request stage (fd already exists).

Enumerator
ALLOW
DROP
CLOSE

enum stt::security::RateLimitType

strong

Rate limiting algorithm / strategy type.

Each strategy has different semantics. Choose based on business traffic patterns and your abuse/threat model.

1) Cooldown (Punishment-based / cooldown limiting)

• Rule: Once times events occur within secs, all subsequent requests are rejected. The limiter only recovers after the system stays quiet for a full secs.
• Characteristics: Extremely strong against continuous abuse and brute-force attempts; unfriendly to legitimate short bursts.
• Suitable for:
  • Connection flood / brute-force protection (connect stage)
  • Login failure punishment (can be extended to fail-based rules)
  • Rapid scripted retries
• Not suitable for:
  • Endpoints where short bursts are normal and "natural recovery" is expected (e.g. page load producing multiple HTTP requests)

2) FixedWindow (Fixed window counter)

• Rule: Use a fixed window of length secs. Allow at most times events within the window. Counter resets when the window ends.
• Characteristics: Simple and low overhead; vulnerable to boundary spikes (burst around window edges).
• Suitable for:
  • Low-risk scenarios requiring simplicity
  • Clear quota semantics: "at most M times per N seconds"
• Not suitable for:
  • Strong adversarial scenarios (can be exploited via boundary behavior)

3) SlidingWindow (Sliding window / timestamp queue)

• Rule: At any time now, count events in (now - secs, now]; reject if count >= times.
• Characteristics: Fair and smooth; no boundary spike. Requires a timestamp deque (higher cost).
• Suitable for:
  • Public HTTP APIs, user operations where fairness is desired
  • Critical endpoints (e.g. /login, /register) at path-level
• Not suitable for:
  • Extremely high-QPS keys with large per-key history where memory/cost is tight (consider approximate buckets)

4) TokenBucket (Token bucket)

• Rule (common semantics): Tokens refill at a fixed rate. Each request consumes 1 token. If no token => reject. In this API, (times, secs) roughly maps to average rate ~= times/secs. Bucket capacity is typically on the same order as times (implementation-defined).
• Characteristics: Allows bursts (when tokens accumulated) while limiting long-term average. Very commonly used in production.
• Suitable for:
  • Traffic shaping (allow short bursts but control long-term average)
  • IM messages / HTTP requests where you want "not too hard, not too soft"
• Not suitable for:
  • Hard punishment requirement ("once exceeded, must stop for a while"): use Cooldown instead.

Enumerator
Cooldown
FixedWindow
SlidingWindow
TokenBucket