Unified connection & request security gate (IP-level + fd-level, multi-strategy limiting + blacklist). More...

#include <sttnet_English.h>

Public Member Functions
	ConnectionLimiter (const int &maxConn=20, const int &idleTimeout=60)
	Constructor. More...

void	setConnectStrategy (const RateLimitType &type)
	Set the strategy used for connection-rate limiting. More...

void	setRequestStrategy (const RateLimitType &type)
	Set the strategy used for fd-level request limiting. More...

void	setPathStrategy (const RateLimitType &type)
	Set the strategy used for path-level extra limiting. More...

void	setPathLimit (const std::string &path, const int &times, const int &secs)
	Configure extra rate limits for a specific path (path-level rule). More...

DefenseDecision	allowConnect (const std::string &ip, const int &fd, const int &times, const int &secs)
	Security decision for a newly accepted connection (IP-level gate). More...

DefenseDecision	allowRequest (const std::string &ip, const int &fd, const std::string_view &path, const int &times, const int &secs)
	Security decision for a single request on an existing connection. More...

void	clearIP (const std::string &ip, const int &fd)
	Reclaim state for an fd when the connection is closed. More...

bool	connectionDetect (const std::string &ip, const int &fd)
	Detect and cleanup an idle/zombie connection. More...

void	banIP (const std::string &ip, int banSeconds, const std::string &reasonCN, const std::string &reasonEN)
	Immediately add the specified IP to the blacklist (direct ban). More...

void	unbanIP (const std::string &ip)
	Manually remove an IP address from the blacklist. More...

bool	isBanned (const std::string &ip) const
	Check whether the specified IP address is currently banned. More...

Detailed Description

Unified connection & request security gate (IP-level + fd-level, multi-strategy limiting + blacklist).

ConnectionLimiter is a "Security Gate". All connections and requests must pass through it before business logic runs.

This class does NOT directly perform side effects (close/send/sleep). Instead, it returns a DefenseDecision for the caller to enforce.

Design Overview

Layered defense model:

IP-level defense:
- Concurrent connection limit (maxConnections)
- Connection rate limit (connectRate)
- IP risk scoring (badScore)
- Temporary blacklist with TTL (blacklist)
fd-level defense:
- Per-connection request rate (requestRate)
- Per-path extra limits (pathRate)
- Activity tracking (lastActivity) for zombie detection

Decision Semantics

allowConnect / allowRequest return DefenseDecision:

ALLOW (0): proceed
DROP (1): ignore silently (request stage only)
CLOSE (2): close immediately (may escalate / ban)

Note

Connect stage usually uses only ALLOW / CLOSE.
DROP is mainly used in request stage.

Strategies

Supported algorithms (see RateLimitType):

Cooldown
FixedWindow
SlidingWindow
TokenBucket

Defaults:

connectStrategy: Cooldown
requestStrategy: SlidingWindow
pathStrategy: SlidingWindow

Thread Safety

Warning: This class is NOT thread-safe by itself. Concurrent access to internal tables (table/pathConfig/blacklist) must be protected externally (e.g. single event-loop thread, or a mutex).

Lifecycle

allowConnect:
- Decide whether a new connection is allowed
- On ALLOW, register the fd under the IP
allowRequest:
- Decide whether a request on an existing fd is allowed
clearIP:
- Called when a connection is closed, to reclaim state and counters
connectionDetect:
- Detect and cleanup idle/zombie connections (should be called by a timer)

Constructor & Destructor Documentation

stt::security::ConnectionLimiter::ConnectionLimiter	(	const int &	maxConn = `20`,
		const int &	idleTimeout = `60`
	)

inline

Constructor.

Parameters

maxConn	Max concurrent connections allowed per IP (activeConnections cap).
idleTimeout	Idle timeout (seconds) used for zombie detection. If < 0, disable.

Member Function Documentation

DefenseDecision stt::security::ConnectionLimiter::allowConnect	(	const std::string &	ip,
		const int &	fd,
		const int &	times,
		const int &	secs
	)

Security decision for a newly accepted connection (IP-level gate).

Parameters

ip	Remote IP address.
fd	Newly accepted file descriptor.
times	Maximum allowed connection attempts within `secs`.
secs	Connection-rate window size (seconds).

Returns

DefenseDecision

ALLOW: connection is allowed and fd will be registered
CLOSE: reject and caller should close the connection immediately

Note

Connect stage typically does not use DROP.
If the IP is blacklisted or in a high-risk state, returns CLOSE directly.

DefenseDecision stt::security::ConnectionLimiter::allowRequest	(	const std::string &	ip,
		const int &	fd,
		const std::string_view &	path,
		const int &	times,
		const int &	secs
	)

Security decision for a single request on an existing connection.

Parameters

ip	Remote IP address.
fd	File descriptor associated with the request.
path	Request path (used for path-level extra limiting).
times	Request-rate limit (max requests within `secs`).
secs	Request-rate window size (seconds).

Returns

DefenseDecision

ALLOW: process normally
DROP: ignore silently (no response)
CLOSE: close connection

void stt::security::ConnectionLimiter::banIP	(	const std::string &	ip,
		int	banSeconds,
		const std::string &	reasonCN,
		const std::string &	reasonEN
	)

Immediately add the specified IP to the blacklist (direct ban).

This function is used when a client exhibits clearly malicious behavior. It bypasses score-based and progressive penalties and directly bans the IP by inserting it into the blacklist.

Ban semantics:

If the IP is not currently blacklisted: it will be added;
If the IP is already blacklisted: the ban expiration time will be refreshed (overwritten);
If banSeconds < 0: the ban is permanent (implemented using std::chrono::steady_clock::time_point::max).

Parameters

ip	The IP address to be banned.
banSeconds	Ban duration in seconds: > 0 : ban for `banSeconds` seconds (temporary ban) = 0 : no operation < 0 : permanent ban
reasonCN	Ban reason in Chinese (for logging).
reasonEN	Ban reason in English (for logging).

Note

This function does not immediately close existing connections; the caller should close the corresponding fd after receiving a DefenseDecision::CLOSE decision.
Uses std::chrono::steady_clock and is not affected by system time changes.
This function represents a terminal security action and should be used with caution.

If the IP is already banned and the existing expiration time is later than the new one, the longer ban will be preserved (the ban will not be shortened).

void stt::security::ConnectionLimiter::clearIP	(	const std::string &	ip,
		const int &	fd
	)

Reclaim state for an fd when the connection is closed.

Parameters

ip	Remote IP address.
fd	Closed file descriptor.

Note

Must be called after close(fd).
Keeps activeConnections and internal state consistent.

bool stt::security::ConnectionLimiter::connectionDetect	(	const std::string &	ip,
		const int &	fd
	)

Detect and cleanup an idle/zombie connection.

Parameters

ip	Remote IP address.
fd	File descriptor to check.

Returns: true The connection is considered zombie and has been cleaned up.; false Not timed out or not found.

Note

"Activity" means allowConnect()/allowRequest() updates lastActivity.
Prefer calling via a timer instead of scanning hot paths.

bool stt::security::ConnectionLimiter::isBanned ( const std::string & ip ) const

Check whether the specified IP address is currently banned.

Parameters

ip	The IP address to check.

Returns: true The IP is currently banned.; false The IP is not banned or the ban has expired.

void stt::security::ConnectionLimiter::setConnectStrategy ( const RateLimitType & type )

Set the strategy used for connection-rate limiting.

Parameters

type	Strategy type, see RateLimitType.

Note: Default is RateLimitType::Cooldown.

void stt::security::ConnectionLimiter::setPathLimit	(	const std::string &	path,
		const int &	times,
		const int &	secs
	)

Configure extra rate limits for a specific path (path-level rule).

Parameters

path	Target path, e.g. "/login", "/register".
times	Maximum allowed requests within `secs`.
secs	Window size (seconds).

Note

setPathLimit() defines an additional rule:

The (times, secs) passed into allowRequest() is still applied first as the connection/IP-level rule.
If path matches a configured rule, the path-level rule is evaluated next.
Relationship is AND: any layer failing results in rejection.

void stt::security::ConnectionLimiter::setPathStrategy ( const RateLimitType & type )

Set the strategy used for path-level extra limiting.

Parameters

type	Strategy type, see RateLimitType.

Note: Default is RateLimitType::SlidingWindow.

void stt::security::ConnectionLimiter::setRequestStrategy ( const RateLimitType & type )

Set the strategy used for fd-level request limiting.

Parameters

type	Strategy type, see RateLimitType.

Note: Default is RateLimitType::SlidingWindow.

void stt::security::ConnectionLimiter::unbanIP ( const std::string & ip )

Manually remove an IP address from the blacklist.

Parameters

ip	The IP address to be unbanned.

The documentation for this class was generated from the following file:

include/sttnet_English.h

Public Member Functions

Detailed Description

Design Overview

Decision Semantics

Strategies

Thread Safety

Lifecycle

Constructor & Destructor Documentation

Member Function Documentation