[release] v1.0.0：发布前全面审查与修复

- CMake/Server 头版本号统一为 1.0.0，通过 configure_file 注入避免硬编码
- HttpServer 多线程安全文档补充（ioThreads > 1 时 handler 并发警告）
- WebSocket 新增 onDisconnect 回调，正常/异常断开均触发
- clang-format 18 → 22.1.2，Standard 设为 Latest 支持 C++26
- 替换 5 个弃用选项为 clang-format 22 新语法
- CI 添加 pip install clang-format==22.1.1 保证 Ubuntu 上版本一致

Author: Hical61

.clang-format

@@ -2,8 +2,9 @@
 
 # 语言: None, Cpp, Java, JavaScript, ObjC, Proto, TableGen, TextProto, CSharp
 # Language: Cpp
-# 标准: c++03, c++11, c++14, c++17, c++20, c++26, Latest, Auto
-Standard: Auto
+# 标准: c++03, c++11, c++14, c++17, c++20, Latest, Auto
+# 使用 Latest 以支持 C++26 语法（clang-format 22+）
+Standard: Latest
 # 基于什么风格：LLVM、Google、GNU、Chromium、Mozilla、WebKit、Microsoft
 # BasedOnStyle: LLVM
 # 使用tab字符: Never, ForIndentation, ForContinuationAndIndentation, Always
@@ -38,8 +39,8 @@ AlignEscapedNewlines: Left
 AlignOperands:  true
 # 对齐连续的尾随的注释
 AlignTrailingComments:  true
-# 允许所有构造函数初始化列表放在下一行
-AllowAllConstructorInitializersOnNextLine: false
+# 构造函数初始化列表打包方式: Never, BinPack, CurrentLine, NextLine, NextLineOnly
+PackConstructorInitializers: NextLine
 # 允许所有参数放在下一行
 AllowAllArgumentsOnNextLine: false
 # 允许函数声明的所有参数在放在下一行
@@ -56,15 +57,13 @@ AllowShortIfStatementsOnASingleLine: Never
 AllowShortLoopsOnASingleLine : false
 # 允许短的Lambdas在同一行
 AllowShortLambdasOnASingleLine: None
-# 总是在定义返回类型后换行(deprecated)
-AlwaysBreakAfterDefinitionReturnType: None
-# 总是在返回类型后换行: None, All, TopLevel(顶级函数，不包括在类中的函数),
-#   AllDefinitions(所有的定义，不包括声明), TopLevelDefinitions(所有的顶级函数的定义)
-AlwaysBreakAfterReturnType: None
+# 在返回类型后换行: None, Automatic, ExceptShortType, All, TopLevel,
+#   AllDefinitions, TopLevelDefinitions
+BreakAfterReturnType: None
 # 总是在多行string字面量前换行
 AlwaysBreakBeforeMultilineStrings:  false
-# 总是在template声明后换行
-AlwaysBreakTemplateDeclarations: Yes
+# 在template声明后换行: Leave, No, MultiLine, Yes
+BreakTemplateDeclarations: Yes
 # false表示函数实参要么都在同一行，要么都各自一行
 BinPackArguments: false
 # false表示所有形参要么都在同一行，要么都各自一行
@@ -129,8 +128,7 @@ ColumnLimit: 120
 PenaltyReturnTypeOnItsOwnLine: 999
 # 描述具有特殊意义的注释的正则表达式，它不应该被分割为多行或以其它方式改变
 CommentPragmas: '^ IWYU pragma:'
-# 构造函数的初始化列表要么都在同一行，要么都各自一行
-ConstructorInitializerAllOnOneLineOrOnePerLine: true
+# (已由 PackConstructorInitializers 替代)
 # 构造函数的初始化列表的缩进宽度
 # ConstructorInitializerIndentWidth: 2
 # 延续的行的缩进宽度

.github/workflows/ci.yml

@@ -38,6 +38,7 @@ jobs:
         run: |
           sudo apt-get update
           sudo apt-get install -y libboost-all-dev libssl-dev libgtest-dev cmake
+          pip install clang-format==22.1.1
 
       # ── Linux 构建与测试 ──
       - name: Configure (Linux)

CHANGELOG.md

@@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [1.0.0] - 2026-04-11
+## [1.0.0] - 2026-04-12
 
 首次公开发布。
 

CLAUDE.md

@@ -67,6 +67,10 @@ find src -name '*.cpp' | xargs clang-tidy -p build
 - `Middleware.h` — Onion-model middleware pipeline with `MiddlewareNext` chaining
 - `Coroutine.h` — `Awaitable<T>` alias for `boost::asio::awaitable<T>`, plus `sleep()` / `coSpawn()` helpers
 - `Reflection.h` / `MetaJson.h` / `MetaRoutes.h` — C++26 reflection layer (see below)
+- `StaticFiles.h` — Static file serving with ETag/304, MIME detection, path traversal protection
+- `Multipart.h/cpp` — RFC 7578 multipart/form-data parser (256 part DoS limit)
+- `Session.h/cpp` — In-memory session manager with lazy GC, 128-bit secure random IDs, `makeSessionMiddleware` factory
+- `Version.h.in` — CMake-configured version header (single source of truth from `project(VERSION)`)
 
 **`src/asio/`** — Boost.Asio concrete implementations:
 - `AsioEventLoop` — Wraps `boost::asio::io_context`, implements `EventLoop`

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.20)
-project(hical VERSION 0.2.0 LANGUAGES CXX)
+project(hical VERSION 1.0.0 LANGUAGES CXX)
 
 # C++26 反射可选支持
 option(HICAL_ENABLE_REFLECTION "Enable C++26 reflection (requires compatible compiler)" OFF)

examples/benchmark.cpp

@@ -16,11 +16,7 @@ class BenchmarkClient
 					int num_requests,
 					std::atomic<int>& completed,
 					std::atomic<int>& errors)
-		: socket_(io)
-		, resolver_(io)
-		, num_requests_(num_requests)
-		, completed_(completed)
-		, errors_(errors)
+		: socket_(io), resolver_(io), num_requests_(num_requests), completed_(completed), errors_(errors)
 	{
 		auto endpoints = resolver_.resolve(host, port);
 		boost::asio::async_connect(socket_,

src/CMakeLists.txt

@@ -1,5 +1,12 @@
 # Hical 核心库源码
 
+# 从 CMake 版本号生成 Version.h（唯一版本号来源）
+configure_file(
+    ${CMAKE_CURRENT_SOURCE_DIR}/core/Version.h.in
+    ${CMAKE_CURRENT_BINARY_DIR}/core/Version.h
+    @ONLY
+)
+
 # 核心库实现
 add_library(hical_core
     core/InetAddress.cpp
@@ -24,6 +31,7 @@ add_library(hical_core
 target_include_directories(hical_core
     PUBLIC
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}>
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>
     $<INSTALL_INTERFACE:include>
 )
 

src/asio/AsioTimer.cpp

@@ -5,11 +5,7 @@ namespace hical
 {
 
 	AsioTimer::AsioTimer(AsioEventLoop* loop, double delay, Callback cb)
-		: loop_(loop)
-		, timer_(loop->getIoContext())
-		, callback_(std::move(cb))
-		, interval_(delay)
-		, repeating_(false)
+		: loop_(loop), timer_(loop->getIoContext()), callback_(std::move(cb)), interval_(delay), repeating_(false)
 	{
 	}
 

src/core/HttpResponse.cpp

@@ -1,4 +1,5 @@
 #include "HttpResponse.h"
+#include <iomanip>
 #include <sstream>
 
 namespace hical
@@ -71,8 +72,30 @@ namespace hical
 			return;
 		}
 
+		// RFC 6265 cookie-value 合法字符百分号编码
+		// 合法: %x21 / %x23-2B / %x2D-3A / %x3C-5B / %x5D-7E
+		auto encodeCookieValue = [](const std::string& raw) -> std::string
+		{
+			std::ostringstream encoded;
+			encoded << std::hex << std::uppercase;
+			for (unsigned char c : raw)
+			{
+				bool safe = (c == 0x21) || (c >= 0x23 && c <= 0x2B) || (c >= 0x2D && c <= 0x3A)
+							|| (c >= 0x3C && c <= 0x5B) || (c >= 0x5D && c <= 0x7E);
+				if (safe)
+				{
+					encoded << static_cast<char>(c);
+				}
+				else
+				{
+					encoded << '%' << std::setw(2) << std::setfill('0') << static_cast<int>(c);
+				}
+			}
+			return encoded.str();
+		};
+
 		std::ostringstream oss;
-		oss << name << "=" << value;
+		oss << name << "=" << encodeCookieValue(value);
 
 		if (!options.path.empty())
 		{

src/core/HttpServer.cpp

@@ -1,5 +1,6 @@
 #include "HttpServer.h"
 #include "MemoryPool.h"
+#include "core/Version.h"
 #include "WebSocket.h"
 #include <boost/beast/websocket.hpp>
 #include <iostream>
@@ -314,7 +315,7 @@ namespace hical
 				// 设置通用头部
 				auto& nativeRes = res.native();
 				nativeRes.version(11);
-				nativeRes.set(http::field::server, "hical/0.2.0");
+				nativeRes.set(http::field::server, HICAL_VERSION_STRING);
 				nativeRes.keep_alive(req.native().keep_alive());
 				nativeRes.prepare_payload();
 
@@ -333,7 +334,7 @@ namespace hical
 			{
 				// 请求体过大：返回 413 Payload Too Large
 				http::response<http::string_body> res {http::status::payload_too_large, 11};
-				res.set(http::field::server, "hical/0.2.0");
+				res.set(http::field::server, HICAL_VERSION_STRING);
 				res.set(http::field::connection, "close");
 				res.body() = "Request body too large";
 				res.prepare_payload();
@@ -352,33 +353,35 @@ namespace hical
 												http::request<http::string_body> req,
 												const Router::WsRoute& wsRoute)
 	{
+		std::unique_ptr<WebSocketSession> session;
+
 		try
 		{
 			ws::stream<tcp::socket> wsStream(std::move(socket));
 
 			// 接受 WebSocket 升级
 			co_await wsStream.async_accept(req, boost::asio::use_awaitable);
 
-			WebSocketSession session(std::move(wsStream));
+			session = std::make_unique<WebSocketSession>(std::move(wsStream));
 
 			// 调用连接回调
 			if (wsRoute.onConnect)
 			{
-				co_await wsRoute.onConnect(session);
+				co_await wsRoute.onConnect(*session);
 			}
 
 			// 消息循环
-			while (session.isOpen())
+			while (session->isOpen())
 			{
-				auto msg = co_await session.receive();
+				auto msg = co_await session->receive();
 				if (!msg.has_value())
 				{
 					break;
 				}
 
 				if (wsRoute.onMessage)
 				{
-					co_await wsRoute.onMessage(*msg, session);
+					co_await wsRoute.onMessage(*msg, *session);
 				}
 			}
 		}
@@ -389,6 +392,19 @@ namespace hical
 				// 忽略正常关闭
 			}
 		}
+
+		// 连接断开回调（正常退出和异常退出都会触发）
+		if (session && wsRoute.onDisconnect)
+		{
+			try
+			{
+				co_await wsRoute.onDisconnect(*session);
+			}
+			catch (...)
+			{
+				// 忽略断开回调中的异常
+			}
+		}
 	}
 
 } // namespace hical