HTTP协议及操作更多...

HTTP 的协作图:

专题
	WebSocket
	WebSocket升级协议实现

类
class	neforce::http::async_filter
	异步过滤器基类（回调模式）更多...
class	neforce::http::chunked_body_reader
	HTTP Chunked Transfer Encoding 读取器更多...
class	neforce::http::csrf_filter
	CSRF防护过滤器更多...
class	neforce::http::health_check_filter
	健康检查端点过滤器更多...
class	neforce::http::http2_connection
	HTTP/2 连接管理器更多...
struct	neforce::http::http2_frame_header
	HTTP/2 帧头（RFC 7540 §4.1），9 字节 packed 布局更多...
struct	neforce::http::http2_settings_entry
	SETTINGS 帧中的单个参数条目更多...
struct	neforce::http::http2_priority
	流优先级信息（RFC 7540 §5.3）更多...
struct	neforce::http::http2_data_frame
	DATA 帧（RFC 7540 §6.1）更多...
struct	neforce::http::http2_headers_frame
	HEADERS 帧（RFC 7540 §6.2）更多...
struct	neforce::http::http2_rst_stream_frame
	RST_STREAM 帧（RFC 7540 §6.4）更多...
struct	neforce::http::http2_settings_frame
	SETTINGS 帧（RFC 7540 §6.5）更多...
struct	neforce::http::http2_ping_frame
	PING 帧（RFC 7540 §6.7）更多...
struct	neforce::http::http2_goaway_frame
	GOAWAY 帧（RFC 7540 §6.8）更多...
struct	neforce::http::http2_window_update_frame
	WINDOW_UPDATE 帧（RFC 7540 §6.9）更多...
struct	neforce::http::http2_push_promise_frame
	PUSH_PROMISE 帧（RFC 7540 §6.6）更多...
struct	neforce::http::http2_continuation_frame
	CONTINUATION 帧（RFC 7540 §6.10）更多...
struct	neforce::http::hpack_header_field
	HPACK 头部字段（名值对）更多...
class	neforce::http::hpack_encoder
	HPACK 头部编码器（RFC 7541）更多...
class	neforce::http::hpack_decoder
	HPACK 头部解码器（RFC 7541）更多...
class	neforce::http::http2_framer
	HTTP/2 帧编解码器更多...
class	neforce::http::http2_stream
	HTTP/2 流状态机更多...
class	neforce::http::http2_flow_control
	HTTP/2 流量控制器更多...
class	neforce::http::http2_settings
	HTTP/2 连接设置管理器更多...
struct	neforce::http::cached_response
	缓存的HTTP响应更多...
class	neforce::http::response_cache
	HTTP响应缓存更多...
class	neforce::http::cache_filter
	HTTP缓存过滤器更多...
class	neforce::http::http_client
	HTTP客户端类更多...
struct	neforce::http::http_client_response
	HTTP客户端响应结构更多...
struct	neforce::http::http_client_request
	HTTP客户端请求结构更多...
class	neforce::http::compress_filter
	HTTP响应压缩过滤器更多...
class	neforce::http::http_filter
	HTTP过滤器基类更多...
class	neforce::http::http_filter_chain
	HTTP过滤器链更多...
class	neforce::http::cors_filter
	CORS跨域过滤器更多...
class	neforce::http::logging_filter
	日志记录过滤器更多...
class	neforce::http::static_file_filter
	静态文件服务过滤器更多...
class	neforce::http::authentication_filter
	认证过滤器更多...
struct	neforce::http::byte_range
	字节范围结构体更多...
class	neforce::http::http_router
	HTTP路由器类更多...
class	neforce::http::security_headers_filter
	HTTP安全头过滤器更多...
class	neforce::http::http_server
	HTTP/HTTPS服务器类更多...
struct	neforce::http::http_server_request
	HTTP服务器请求结构更多...
struct	neforce::http::http_server_response
	HTTP服务器响应结构更多...
struct	neforce::http::http_cookie
	HTTP Cookie结构更多...
struct	neforce::http::http_session
	HTTP会话结构更多...
struct	neforce::http::lb_backend
	负载均衡后端节点更多...
class	neforce::http::load_balancer
	HTTP负载均衡管理器更多...
struct	neforce::http::multipart_field
	multipart/form-data 单个字段更多...
class	neforce::http::multipart_parser
	multipart/form-data 解析器更多...
class	neforce::http::route_trie
	段式Trie路由器更多...
struct	neforce::http::token_bucket
	令牌桶数据结构更多...
class	neforce::http::token_bucket_limiter
	令牌桶限流管理器更多...
class	neforce::http::token_bucket_filter
	令牌桶HTTP限流过滤器更多...
struct	neforce::http::proxy_backend
	反向代理后端服务器配置更多...
class	neforce::http::reverse_proxy_filter
	HTTP反向代理过滤器更多...
class	neforce::http::session_store
	会话存储抽象接口更多...
class	neforce::http::memory_session_store
	基于内存的会话存储实现更多...
class	neforce::http::redis_session_store
	Redis后端会话存储更多...
class	neforce::http::websocket_deflate_config
	permessage-deflate 扩展配置更多...
class	neforce::http::websocket_deflate
	per-message deflate 压缩/解压器更多...

类型定义
using	neforce::http::http_request = http_server_request
	HTTP请求类型别名
using	neforce::http::http_response = http_server_response
	HTTP响应类型别名

枚举
enum class	neforce::http::http2_frame_type : uint8_t { http2_frame_type::DATA = 0x0 , http2_frame_type::HEADERS = 0x1 , http2_frame_type::PRIORITY = 0x2 , http2_frame_type::RST_STREAM = 0x3 , http2_frame_type::SETTINGS = 0x4 , http2_frame_type::PUSH_PROMISE = 0x5 , http2_frame_type::PING = 0x6 , http2_frame_type::GOAWAY = 0x7 , http2_frame_type::WINDOW_UPDATE = 0x8 , http2_frame_type::CONTINUATION = 0x9 }
	HTTP/2 帧类型（RFC 7540 §6）更多...
enum class	neforce::http::http2_error : uint32_t { http2_error::NO_ERROR = 0x0 , http2_error::PROTOCOL_ERROR = 0x1 , http2_error::INTERNAL_ERROR = 0x2 , http2_error::FLOW_CONTROL_ERROR = 0x3 , http2_error::SETTINGS_TIMEOUT = 0x4 , http2_error::STREAM_CLOSED = 0x5 , http2_error::FRAME_SIZE_ERROR = 0x6 , http2_error::REFUSED_STREAM = 0x7 , http2_error::CANCEL = 0x8 , http2_error::COMPRESSION_ERROR = 0x9 , http2_error::CONNECT_ERROR = 0xA , http2_error::ENHANCE_YOUR_CALM = 0xB , http2_error::INADEQUATE_SECURITY = 0xC , http2_error::HTTP_1_1_REQUIRED = 0xD }
	HTTP/2 错误码（RFC 7540 §7）更多...
enum class	neforce::http::http2_settings_id : uint16_t { http2_settings_id::HEADER_TABLE_SIZE = 0x1 , http2_settings_id::ENABLE_PUSH = 0x2 , http2_settings_id::MAX_CONCURRENT_STREAMS = 0x3 , http2_settings_id::INITIAL_WINDOW_SIZE = 0x4 , http2_settings_id::MAX_FRAME_SIZE = 0x5 , http2_settings_id::MAX_HEADER_LIST_SIZE = 0x6 }
	HTTP/2 SETTINGS 参数标识符（RFC 7540 §6.5.2）更多...
enum class	neforce::http::http2_stream_state
	HTTP/2 流状态（RFC 7540 §5.1）
enum class	neforce::http::lb_strategy : uint8_t { lb_strategy::ROUND_ROBIN , lb_strategy::LEAST_CONNECTIONS , lb_strategy::WEIGHTED , lb_strategy::RANDOM }
	负载均衡策略更多...

函数
vector< byte_range >	neforce::http::parse_ranges (string_view range_header, uint64_t file_size, size_t max_ranges=100)
	解析HTTP Range头部值
string	neforce::http::build_content_range (const byte_range &range, uint64_t total_size)
	构建Content-Range头部值
string	neforce::http::build_multipart_ranges (const vector< byte_range > &ranges, string_view content_type, string_view boundary, function< string(const byte_range &)> get_range_body, uint64_t total_size=0)
	构建multipart/byteranges响应体

变量
constexpr uint32_t	neforce::http::HTTP2_MAX_FRAME_SIZE = 16384
	HTTP/2 最大帧负载大小（RFC 7540 §4.1）
constexpr uint32_t	neforce::http::HTTP2_DEFAULT_HEADER_TABLE_SIZE = 4096
	HPACK 默认动态表大小
constexpr uint32_t	neforce::http::HTTP2_DEFAULT_MAX_CONCURRENT_STREAMS = 100
	默认最大并发流数
constexpr uint32_t	neforce::http::HTTP2_DEFAULT_INITIAL_WINDOW_SIZE = 65535
	默认初始流控窗口
constexpr uint32_t	neforce::http::HTTP2_DEFAULT_MAX_HEADER_LIST_SIZE = 0xFFFFFFFF
	默认最大头部列表大小
constexpr size_t	neforce::http::HPACK_STATIC_TABLE_SIZE = 61
	HPACK 静态表条目数
constexpr string_view	neforce::http::HTTP2_CLIENT_PREFACE = "PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
	HTTP/2 客户端连接前言（RFC 7540 §3.5）

详细描述

HTTP协议及操作

本模块提供了完整的 HTTP/1.1 协议支持，涵盖客户端与服务端消息结构、Cookie与会话管理、路由分发、中间件过滤器链以及 WebSocket 升级协议。

遵循的国际标准

本实现严格遵循以下 IETF RFC 与相关标准规范：

HTTP/1.1 核心协议：

**IETF RFC 9110**：HTTP Semantics（HTTP 语义） https://www.rfc-editor.org/rfc/rfc9110.html
**IETF RFC 9112**：HTTP/1.1（消息语法与路由） https://www.rfc-editor.org/rfc/rfc9112.html

HTTP/2 核心协议：

**IETF RFC 7540**：HTTP/2（帧层、流、连接管理） https://www.rfc-editor.org/rfc/rfc7540.html
**IETF RFC 7541**：HPACK（HTTP/2 头部压缩算法） https://www.rfc-editor.org/rfc/rfc7541.html

HTTP 扩展能力：

**IETF RFC 9110 §8**：内容编码协商（Accept-Encoding / Content-Encoding）
**IETF RFC 9110 §14**：字节范围请求（Range / Content-Range / 206 Partial Content）
**IETF RFC 9110 §9.3.6**：CONNECT 方法（TCP 隧道代理）

HTTP 状态码与头字段注册：

**IANA HTTP Status Code Registry**：HTTP 状态码注册表 https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
**IANA Message Headers Registry**：HTTP 头字段注册表 https://www.iana.org/assignments/message-headers/message-headers.xhtml

HTTP 认证与安全：

**IETF RFC 9110 §11**：HTTP 认证框架
**IETF RFC 6797**：HTTP Strict Transport Security (HSTS) https://www.rfc-editor.org/rfc/rfc6797.html
**CSRF 防护**：Double-Submit Cookie 模式（防御跨站请求伪造攻击）
**Session Fixation 防护**：会话标识符再生（regenerate_id）

TLS / SNI 安全传输：

**IETF RFC 6066 §3**：Server Name Indication（TLS 扩展） https://www.rfc-editor.org/rfc/rfc6066.html
**IETF RFC 8446 §4.4.2**：TLS 1.3 中的 SNI 支持 https://www.rfc-editor.org/rfc/rfc8446.html

Cookie 与会话管理：

**IETF RFC 6265**：HTTP State Management Mechanism（Cookie 规范） https://www.rfc-editor.org/rfc/rfc6265.html
**IETF RFC 6265 §5.3**：SameSite Cookies（更新于 RFC 6265bis）

CORS 跨域资源共享：

**W3C Fetch Living Standard**：CORS 协议定义 https://fetch.spec.whatwg.org/#http-cors-protocol

WebSocket 协议：

**IETF RFC 6455**：The WebSocket Protocol https://www.rfc-editor.org/rfc/rfc6455.html
**IETF RFC 7692**：WebSocket Per-Message Deflate 扩展（permessage-deflate） https://www.rfc-editor.org/rfc/rfc7692.html

MIME 类型规范：

**IANA Media Types Registry**：MIME 类型注册表 https://www.iana.org/assignments/media-types/media-types.xhtml
**IETF RFC 6838**：Media Type Specifications and Registration Procedures https://www.rfc-editor.org/rfc/rfc6838.html

HTTP 状态码分类

根据 RFC 9110 §15，HTTP 状态码按百位数字分类：

类别	状态码范围	含义	典型状态码
1xx	100 – 199	信息响应	100 Continue, 101 Switching Protocols
2xx	200 – 299	成功	200 OK, 201 Created, 204 No Content
3xx	300 – 399	重定向	301 Moved Permanently, 302 Found, 304 Not Modified
4xx	400 – 499	客户端错误	400 Bad Request, 403 Forbidden, 404 Not Found
5xx	500 – 599	服务器错误	500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable

HTTP 请求方法

根据 RFC 9110 §9，本模块支持以下标准 HTTP 方法：

方法	RFC 引用	语义	幂等性	安全性
GET	§9.3.1	检索资源表示	是	是
POST	§9.3.3	提交数据进行处理	否	否
PUT	§9.3.4	替换或创建资源	是	否
DELETE	§9.3.5	删除资源	是	否
HEAD	§9.3.2	获取 GET 响应的头部	是	是
OPTIONS	§9.3.7	获取服务器支持的方法	是	是
TRACE	§9.3.8	回显请求（调试用）	是	是
CONNECT	§9.3.6	建立隧道（用于代理）	否	否
PATCH	RFC 5789	部分更新资源	否	否

Cookie 属性说明

根据 RFC 6265 §4.1，Cookie 支持以下属性：

属性	说明
Domain	指定 Cookie 可用的域名
Path	指定 Cookie 可用的路径前缀
Expires	指定过期时间（绝对时间）
Max-Age	指定有效期（相对秒数），优先级高于 Expires
Secure	仅通过 HTTPS 传输
HttpOnly	禁止 JavaScript 访问，缓解 XSS 攻击
SameSite	跨站请求策略：Strict（禁止跨站）、Lax（允许顶级导航）、None

CORS 响应头

根据 Fetch 标准，CORS 使用以下响应头：

响应头	说明
Access-Control-Allow-Origin	允许访问的源
Access-Control-Allow-Methods	允许的 HTTP 方法
Access-Control-Allow-Headers	允许的请求头
Access-Control-Allow-Credentials	是否允许携带凭证（Cookie）
Access-Control-Max-Age	预检请求结果缓存时间

WebSocket 协议细节

根据 RFC 6455，WebSocket 协议规范：

**握手升级**：

客户端发送 Upgrade: websocket 和 Connection: Upgrade
服务器返回 101 Switching Protocols
使用 Sec-WebSocket-Key 和 Sec-WebSocket-Accept 验证握手

**帧结构**（RFC 6455 §5.2）：

字段	位数	说明
FIN	1	是否为消息的最后一帧
RSV1-3	3	保留位，用于扩展
Opcode	4	帧类型：Continuation(0)、Text(1)、Binary(2)、Close(8)、Ping(9)、Pong(10)
MASK	1	客户端到服务器的帧必须设置掩码
Payload len	7/7+16/7+64	负载长度
Masking key	0/32	掩码密钥（仅客户端帧）

**关闭状态码**（RFC 6455 §7.4）：

状态码	名称	说明
1000	Normal Closure	正常关闭
1001	Going Away	端点离开（如浏览器关闭）
1002	Protocol Error	协议错误
1003	Unsupported Data	接收到不支持的数据类型
1008	Policy Violation	违反策略
1009	Message Too Big	消息过大
1011	Internal Error	服务器内部错误

实现细节

特性	规范参数
HTTP 版本	HTTP/1.1（RFC 9112）与 HTTP/2（RFC 7540）
HTTP/2 帧层	9 种帧类型：DATA / HEADERS / SETTINGS / PING / GOAWAY / RST_STREAM / WINDOW_UPDATE / PRIORITY / PUSH_PROMISE
HPACK 头部压缩	静态表 61 项 + 动态表 + Huffman 编码（RFC 7541）
头部字段大小写	不区分大小写，存储为原始大小写
分块传输编码	流式增量 chunked 解析，支持 Trailing Headers
内容协商	Accept-Encoding 解析，gzip/deflate 响应压缩
字节范围请求	单范围 206 与多范围 multipart/byteranges 206
CONNECT 隧道	双工 TCP 隧道中继，用于 HTTPS 代理
路由匹配	基于 Segment Radix Tree 的 O(k) 前缀匹配；静态路径、路径参数（:id）、通配符（*）、正则表达式回退
中间件执行顺序	预过滤 → 核心过滤 → 路由处理 → 后过滤
会话存储	可插拔 session_store（内存 / Redis 后端）
Cookie 解析	支持 Set-Cookie 和 Cookie 头
会话标识符	支持 JESSIONID, SESSIONID, PHPSESSID 等常见名称
CSRF 防护	Double-Submit Cookie 模式，仅验证状态变更方法
SNI 多证书	基于 TLS SNI 扩展的 hostname → SSL_CTX 映射，支持通配符
IO Context	Linux epoll 边缘触发，min-heap 定时器，单线程异步 I/O
WebSocket 运行模式	线程模式（3线程/会话）和事件驱动模式（零线程）双模
WebSocket 心跳	周期性发送 Ping 帧，等待 Pong 响应
WebSocket 压缩	permessage-deflate（RFC 7692），支持窗口比特位协商与上下文接管
WebSocket 升级	通用 Upgrade 分发器，支持自定义协议处理器

注解: 本模块的 HTTP 解析器严格遵循 RFC 9112 语法规则，支持分块传输编码（chunked）和 Content-Length 两种方式确定消息体长度。WebSocket 实现完整支持 RFC 6455 定义的控制帧（Ping/Pong/Close）和分片消息，并支持 RFC 7692 定义的 permessage-deflate 压缩扩展。HTTP/2 协议层提供纯 C++14 同步帧编解码，传输层由 io_context 驱动。

警告: 生产环境中应始终通过 HTTPS 使用 Secure 属性的 Cookie，并在敏感路由上启用 CSRF 防护。WebSocket 连接应考虑使用 WSS（WebSocket Secure）。

参见: https://www.rfc-editor.org/rfc/rfc9110.html; https://www.rfc-editor.org/rfc/rfc9112.html; https://www.rfc-editor.org/rfc/rfc7540.html; https://www.rfc-editor.org/rfc/rfc7541.html; https://www.rfc-editor.org/rfc/rfc6265.html; https://www.rfc-editor.org/rfc/rfc6455.html; https://www.rfc-editor.org/rfc/rfc7692.html; https://www.rfc-editor.org/rfc/rfc6066.html; https://fetch.spec.whatwg.org/

枚举类型说明

◆ http2_error

enum class neforce::http::http2_error : uint32_t

strong

HTTP/2 错误码（RFC 7540 §7）

枚举值
NO_ERROR	无错误
PROTOCOL_ERROR	协议错误
INTERNAL_ERROR	内部错误
FLOW_CONTROL_ERROR	流控违规
SETTINGS_TIMEOUT	SETTINGS 确认超时
STREAM_CLOSED	流已关闭
FRAME_SIZE_ERROR	帧大小错误
REFUSED_STREAM	流被拒绝
CANCEL	流取消
COMPRESSION_ERROR	压缩错误
CONNECT_ERROR	CONNECT 错误
ENHANCE_YOUR_CALM	速率过高
INADEQUATE_SECURITY	安全不足
HTTP_1_1_REQUIRED	需要 HTTP/1.1

在文件 http2_protocol.hpp 第 63 行定义.

◆ http2_frame_type

enum class neforce::http::http2_frame_type : uint8_t

strong

HTTP/2 帧类型（RFC 7540 §6）

枚举值
DATA	请求/响应体数据
HEADERS	头部块
PRIORITY	流优先级
RST_STREAM	流终止
SETTINGS	连接配置参数
PUSH_PROMISE	服务端推送承诺
PING	连接活性检测
GOAWAY	优雅关闭连接
WINDOW_UPDATE	流控窗口更新
CONTINUATION	头部块续帧

在文件 http2_protocol.hpp 第 43 行定义.

◆ http2_settings_id

enum class neforce::http::http2_settings_id : uint16_t

strong

HTTP/2 SETTINGS 参数标识符（RFC 7540 §6.5.2）

枚举值
HEADER_TABLE_SIZE	HPACK 动态表最大大小
ENABLE_PUSH	是否启用服务端推送
MAX_CONCURRENT_STREAMS	最大并发流数
INITIAL_WINDOW_SIZE	流级初始窗口大小
MAX_FRAME_SIZE	最大帧负载大小
MAX_HEADER_LIST_SIZE	最大头部列表大小

在文件 http2_protocol.hpp 第 83 行定义.

◆ lb_strategy

enum class neforce::http::lb_strategy : uint8_t

strong

负载均衡策略

枚举值
ROUND_ROBIN	轮询
LEAST_CONNECTIONS	最少连接
WEIGHTED	加权轮询
RANDOM	随机

在文件 load_balancer.hpp 第 28 行定义.

函数说明

◆ build_content_range()

string neforce::http::build_content_range	(	const byte_range &	range,
		uint64_t	total_size )

构建Content-Range头部值

参数

range	字节范围
total_size	总大小

返回: Content-Range值，如 "bytes 0-1023/4096"

引用了 build_content_range().

被这些函数引用 build_content_range().

◆ build_multipart_ranges()

string neforce::http::build_multipart_ranges	(	const vector< byte_range > &	ranges,
		string_view	content_type,
		string_view	boundary,
		function< string(const byte_range &)>	get_range_body,
		uint64_t	total_size = 0 )

构建multipart/byteranges响应体

参数

ranges	多个字节范围
content_type	文件的MIME类型
boundary	MIME分隔边界字符串
get_range_body	获取指定范围内容的回调函数
total_size

返回: multipart响应体字符串

引用了 build_multipart_ranges().

被这些函数引用 build_multipart_ranges().

◆ parse_ranges()

vector< byte_range > neforce::http::parse_ranges	(	string_view	range_header,
		uint64_t	file_size,
		size_t	max_ranges = 100 )

解析HTTP Range头部值

参数

range_header	Range头部值（不含"bytes="前缀）
file_size	文件总大小
max_ranges	最大允许的范围数量，超出时拒绝整个请求

返回: 解析出的字节范围列表，无效返回空vector

引用了 parse_ranges().

被这些函数引用 parse_ranges().

专题

类

类型定义

枚举

函数

变量

详细描述

遵循的国际标准

HTTP 状态码分类

HTTP 请求方法

Cookie 属性说明

CORS 响应头

WebSocket 协议细节

实现细节

枚举类型说明

◆ http2_error

◆ http2_frame_type

◆ http2_settings_id

◆ lb_strategy

函数说明

◆ build_content_range()

◆ build_multipart_ranges()

◆ parse_ranges()