Internals

内部边界

产品只承诺 include/wknet 下的公共 ABI。src/wknetlib 供库内分层和用户态协议测试使用，不构成可安装 ABI；产品驱动不要包含内部头。

公共 vs 内部

层	位置	调用方
公共 API	`include/wknet/http	websocket
测试钩子	include/wknet/test/Test.h（WKNET_USER_MODE_TEST）	仅用户态测试
内部实现	src/wknetlib/*	库自身

Wknet.h 只聚合公共头，不包含 session / transport / net / tls 实现头。

内部分层（贡献者）

命名空间 / 目录	职责
session	路由、代理、连接池、重定向、异步、HTTP/WS/H3 编排
transport	opaque TCP 字节流（明文 / TLS 包装）
net	WSK 生命周期、解析、TCP/UDP socket 服务
tls	握手、记录保护、会话恢复、证书验证
http1 / http2 / ws	协议状态机
quic / http3 / qpack	QUIC v1 / HTTP/3 / QPACK
rtl	堆、Workspace、工具

边界规则：

• 协议层不直接读写连接池字段；池策略只在 session
• transport::Transport 只承载 TCP 字节流；UDP 归 net::WskDatagramSocket；QUIC 状态机归 quic
• Alt-Svc 学习 / 竞速 / 回落只在 session
• 跨模块不得包含其他模块的 *Private.hpp（白盒测试除外）
• 不恢复平行 client 层或第二套网络生命周期

测试钩子

用户态测试通过 WKNET_USER_MODE_TEST 下的窄接口注入传输、IRQL 或调度。测试钩子不包含在 Wknet.h 的产品路径中。

内存与实现

• 库内禁止栈缓冲；堆对象 + Workspace 常驻高频缓冲
• 无异常、无 RTTI；函数 noexcept；SAL 注解
• 实现用独立 .cpp，共享声明用 .h / .hpp；禁止 .inc 实现分片

相关：架构 · 构建与测试 · 贡献指南

---

English

Internals

The product promises only the public ABI under include/wknet. src/wknetlib holds the in-library layering and user-mode protocol tests; it is not an installable ABI. Product drivers should not include internal headers.

Public vs internal

Layer	Location	Caller
Public API	`include/wknet/http	websocket
Test hooks	include/wknet/test/Test.h (WKNET_USER_MODE_TEST)	User-mode tests only
Implementation	src/wknetlib/*	The library itself

Wknet.h aggregates public headers only. It leaves out session / transport / net / tls implementation headers.

Internal layering (contributors)

Namespace / tree	Responsibility
session	Routing, proxy, pool, redirects, async, HTTP/WS/H3 orchestration
transport	Opaque TCP byte streams (cleartext / TLS wrap)
net	WSK lifetime, resolve, TCP/UDP socket services
tls	Handshake, record protection, resumption, certificate validation
http1 / http2 / ws	Protocol state machines
quic / http3 / qpack	QUIC v1 / HTTP/3 / QPACK
rtl	Heap, Workspace, utilities

Rules:

• Protocol layers do not write pool fields; pool policy lives only in session
• transport::Transport carries TCP only; UDP is net::WskDatagramSocket; QUIC state is quic
• Alt-Svc learning / racing / fallback live only in session
• Modules must not include another module’s *Private.hpp (except white-box tests)
• No parallel client layer or second network lifetime

Test hooks

User-mode tests inject transport, IRQL, or scheduling through the narrow WKNET_USER_MODE_TEST surface. Hooks are not on the normal Wknet.h product path.

Memory and implementation

• No stack buffers in the library; heap objects plus Workspace-resident hot buffers
• No exceptions, no RTTI; functions are noexcept; SAL annotations required
• Implementations are standalone .cpp files with .h / .hpp shared declarations; no .inc implementation fragments

See also: Architecture · Build & test · Contributing