stt::security::ConnectionLimiter类 参考

统一的连接与请求安全裁决器（IP 级 + fd 级，多策略限流 + 黑名单）。 更多...

#include <sttnet.h>

Public 成员函数
	ConnectionLimiter (const int &maxConn=20, const int &idleTimeout=60)
	构造函数。 更多...
void	setConnectStrategy (const RateLimitType &type)
	设置“连接速率限流”所使用的策略。 更多...
void	setRequestStrategy (const RateLimitType &type)
	设置“IP 级请求限流”所使用的策略。 更多...
void	setPathStrategy (const RateLimitType &type)
	设置“path 级请求限流”所使用的策略。 更多...
void	setPathLimit (const std::string &path, const int &times, const int &secs)
	设置某个路径的额外限流规则（path 级）。 更多...
DefenseDecision	allowConnect (const std::string &ip, const int &fd, const int &times, const int &secs)
	对新建立的连接进行安全裁决（IP 级）。 更多...
DefenseDecision	allowRequest (const std::string &ip, const int &fd, const std::string_view &path, const int &times, const int &secs)
	对已建立连接的一次请求进行安全裁决。 更多...
void	clearIP (const std::string &ip, const int &fd)
	在连接断开时回收对应 fd 的状态。 更多...
bool	connectionDetect (const std::string &ip, const int &fd)
	检测并清理僵尸连接（fd 级）。 更多...

详细描述

统一的连接与请求安全裁决器（IP 级 + fd 级，多策略限流 + 黑名单）。

ConnectionLimiter 是一个“安全门（Security Gate）”， 所有连接建立与请求处理在进入业务逻辑前，都必须经过该类的裁决。

本类不直接执行业务行为（如 close / send / sleep）， 而是返回一个 DefenseDecision 结果，由外层统一执行。

---

设计概览

本类实现的是一个分层防御模型：

• IP 级防御：
  • 并发连接数限制（maxConnections）
  • 建连速率限制（connectRate）
  • IP 风险评分（badScore）
  • 临时黑名单（blacklist，带 TTL）
• fd 级防御：
  • 请求速率限制（requestRate）
  • path 级额外限流（pathRate）
  • 连接活动时间记录（lastActivity）

    ---

防御裁决语义

allowConnect / allowRequest 的返回值为 DefenseDecision：

• ALLOW (0)：
  • 允许继续处理
• DROP (1)：
  • 无视本次请求（不回应、不处理）
  • 主要用于 request 阶段的轻度防御
• CLOSE (2)：
  • 立即断开连接
  • 可伴随 IP 风险升级或临时封禁

注解

• connect 阶段由于 TCP 连接已建立，通常只使用 ALLOW / CLOSE
• DROP 主要用于 request 阶段（fd 已存在时）

  ---

策略与限流

本类支持多种限流策略（见 RateLimitType）：

• Cooldown
• FixedWindow
• SlidingWindow
• TokenBucket

不同维度使用不同策略：

• 建连速率：connectStrategy（默认 Cooldown）
• fd 级请求速率：requestStrategy（默认 SlidingWindow）
• path 级请求速率：pathStrategy（默认 SlidingWindow）

  ---

线程安全

警告

本类本身不包含锁：

• table / pathConfig / blacklist 的并发安全 需由上层保证（如事件循环线程、外部互斥锁等）。

  ---

生命周期说明

• allowConnect：
  • 判断 IP 是否允许进入应用层
  • 在 ALLOW 时登记 fd
• allowRequest：
  • 对已登记 fd 进行请求裁决
• clearIP：
  • 在连接关闭时调用，回收 fd 与并发计数
• connectionDetect：
  • 用于检测并清理长时间无活动的僵尸连接

构造及析构函数说明

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

inline

构造函数。

参数

maxConn	同一 IP 允许的最大并发连接数（activeConnections 上限）。
idleTimeout	连接僵尸检测超时时间（秒）。若 < 0 表示不做僵尸检测。

成员函数说明

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

对新建立的连接进行安全裁决（IP 级）。

参数

ip	对端 IP 地址。
fd	新 accept 得到的文件描述符。
times	在 secs 秒内允许的最大建连次数。
secs	建连速率统计窗口（秒）。

返回

DefenseDecision

• ALLOW：允许该连接进入应用层（fd 将被登记）
• CLOSE：拒绝并应立即断开连接

注解

• connect 阶段通常不使用 DROP
• 若命中黑名单或高风险状态，将直接返回 CLOSE

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

对已建立连接的一次请求进行安全裁决。

参数

ip	对端 IP 地址。
fd	当前请求对应的文件描述符。
path	请求路径（用于 path 级限流）。
times	fd 级请求速率上限。
secs	请求速率统计窗口（秒）。

返回

DefenseDecision

• ALLOW：正常处理请求
• DROP：无视本次请求（不回应）
• CLOSE：断开连接

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

在连接断开时回收对应 fd 的状态。

参数

ip	对端 IP 地址。
fd	已关闭的文件描述符。

注解

• 必须在 close(fd) 后调用
• 用于维护 activeConnections 与内部状态一致性

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

检测并清理僵尸连接（fd 级）。

参数

ip	对端 IP 地址。
fd	待检测的文件描述符。

返回

true 该连接被判定为僵尸并已清理

false 未超时或不存在

注解

• “活动”指 allowConnect / allowRequest 更新 lastActivity
• 建议由外部定时器触发调用，避免热路径扫描

void stt::security::ConnectionLimiter::setConnectStrategy

(

const RateLimitType &

type

)

设置“连接速率限流”所使用的策略。

参数

type	策略类型，见 RateLimitType 说明。

注解

不调用本函数时，默认策略为 RateLimitType::Cooldown 。

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

设置某个路径的额外限流规则（path 级）。

参数

path	需要额外限流的路径，例如 "/login"、"/register"。
times	在 secs 秒内允许的最大请求次数。
secs	统计窗口长度（秒）。

注解

setPathLimit 配置的是 额外规则：

• allowRequest 调用时传入的 (times, secs) 仍然会作为 IP 级规则先执行；
• 若 path 命中此配置，则再执行 path 级规则；
• 两者为 AND 关系：任何一层失败即拒绝。

void stt::security::ConnectionLimiter::setPathStrategy

(

const RateLimitType &

type

)

设置“path 级请求限流”所使用的策略。

参数

type	策略类型，见 RateLimitType 说明。

注解

不调用本函数时，默认策略为 RateLimitType::SlidingWindow 。

void stt::security::ConnectionLimiter::setRequestStrategy

(

const RateLimitType &

type

)

设置“IP 级请求限流”所使用的策略。

参数

type	策略类型，见 RateLimitType 说明。

注解

不调用本函数时，默认策略为 RateLimitType::SlidingWindow 。

---

该类的文档由以下文件生成:

• include/sttnet.h