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...

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::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.

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.

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