[feat] HttpRequest 支持获取对端地址

之前 handler 里拿不到客户端 IP，限流、审计、白名单这些场景都没法做。给 HttpRequest 加了 peerAddr()，连接层 accept 后取一次 remote_endpoint 注入，handler、中间件、WS/SSE 握手链路都能读到。InetAddress 顺带补了 isValid()。

另外修了个遗留问题：RateLimiter 默认 key 读 hical.remote_addr 属性但一直没人往里写，默认限流所有请求共用一个桶。改成优先用 peerAddr()，删掉那个半成品的 kRemoteAddrKey 常量。

Author: Hical61

CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- **HttpRequest 获取对端地址**：`HttpRequest::peerAddr()` 返回客户端对端 `InetAddress`（`toIp()`/`toIpPort()`/`port()` 自取），`InetAddress` 新增 `isValid()` 判断地址有效性。连接层 `handleSession` 在连接建立时取一次 `remote_endpoint()` 注入到本连接所有请求，handler、中间件、WS/SSE 握手链路都能拿到真实对端地址（[#16](https://github.com/Hical61/Hical/issues/16)）
+
+### Fixed
+- **RateLimiter 默认限流 key 失效**：默认 key 提取之前读 `"hical.remote_addr"` 请求属性，但连接层从未注入该属性，导致所有请求共享一个桶（限流形同虚设）。改为优先取 `peerAddr()`、无效时回退 `X-Forwarded-For`、再兜底 `"global"`
+
+### Changed
+- **移除 `kRemoteAddrKey` 常量**：`"hical.remote_addr"` 属性键随上一条修复退场。此前它只被 RateLimiter 默认 key 提取读取，从未有连接层写入，属于半成品接线；现在对端地址走 `peerAddr()` 一等接口，不再用魔法字符串属性传递
+
 ## [2.6.8] - 2026-08-09
 
 ### Added

docs/api_reference.md

@@ -318,6 +318,7 @@ HTTP 请求封装，对原生 HTTP 解析结果的 hical 风格封装。
 | `jsonBody()`     | 无               | `const boost::json::value&` | 将消息体解析为 JSON（多次调用返回缓存引用） |
 | `readJson<T>()`  | 无               | `T`                         | 将消息体反序列化为 T（需 `HICAL_JSON`）     |
 | `contentType()`  | 无               | `std::string_view`          | 获取 Content-Type 头                        |
+| `peerAddr()`     | 无               | `const InetAddress&`        | 获取客户端对端地址（未注入时为无效地址）    |
 | `param(name)`    | name: 参数名     | `const std::string&`        | 获取路径参数                                |
 | `hasParam(name)` | name: 参数名     | `bool`                      | 是否有指定路径参数                          |
 | `native()`       | 无               | `NativeRequest&`            | 获取底层原生请求引用                        |
@@ -367,13 +368,14 @@ HTTP 请求封装，对原生 HTTP 解析结果的 hical 风格封装。
 
 #### 构建请求的方法
 
-| 方法                     | 参数                                               | 返回值 | 说明                               |
-| ------------------------ | -------------------------------------------------- | ------ | ---------------------------------- |
-| `setMethod(method)`      | method: HTTP 方法                                  | `void` | 设置 HTTP 方法                     |
-| `setTarget(target)`      | target: 目标 URI                                   | `void` | 设置请求路径                       |
-| `setHeader(name, value)` | name: 字段名<br>value: 字段值 (`std::string_view`) | `void` | 设置头部字段（拒绝含 CR/LF 的值）  |
-| `setBody(body)`          | body: 消息体                                       | `void` | 设置消息体（不动 Content-Type 头） |
-| `setParam(name, value)`  | name: 参数名<br>value: 参数值                      | `void` | 设置路径参数（由 Router 内部调用） |
+| 方法                     | 参数                                               | 返回值 | 说明                                          |
+| ------------------------ | -------------------------------------------------- | ------ | --------------------------------------------- |
+| `setMethod(method)`      | method: HTTP 方法                                  | `void` | 设置 HTTP 方法                                |
+| `setTarget(target)`      | target: 目标 URI                                   | `void` | 设置请求路径                                  |
+| `setHeader(name, value)` | name: 字段名<br>value: 字段值 (`std::string_view`) | `void` | 设置头部字段（拒绝含 CR/LF 的值）             |
+| `setBody(body)`          | body: 消息体                                       | `void` | 设置消息体（不动 Content-Type 头）            |
+| `setParam(name, value)`  | name: 参数名<br>value: 参数值                      | `void` | 设置路径参数（由 Router 内部调用）            |
+| `setPeerAddr(addr)`      | addr: `const InetAddress&`                         | `void` | 设置对端地址（由连接层注入，测试/构建请求用） |
 
 #### 示例
 

docs/examples_guide.md

@@ -35,7 +35,7 @@
 | ---------- | ------------------------------------------------ |
 | C++ 编译器 | GCC 14+ / Clang 20+ / MSVC 2022+（需支持 C++20） |
 | CMake      | 3.20+                                            |
-| Boost      | 1.82+（Asio、JSON）；DB 中间件 >= 1.85              |
+| Boost      | 1.82+（Asio、JSON）；DB 中间件 >= 1.85           |
 | OpenSSL    | 3.0+                                             |
 
 **MSYS2 MINGW64 快速安装：**

docs/performance_report.md

@@ -142,12 +142,12 @@ strace + perf 火焰图实测 10K 并发下发现的浪费点，逐一消除：
 
 strace 实测 10K 并发下，每次 keep-alive 请求的 `async_wait(wait_read)` 都触发一次多余的 `epoll_ctl(MOD)`——EPOLLIN 早在注册连接时就加了，反复 MOD 纯属浪费。改法：循环顶用 256B 栈缓冲 `async_read_some` 替代 `async_wait`，走 Asio 投机路径，有数据直接返回、没数据挂起等 epoll 通知，全程不碰 epoll_ctl。
 
-| 指标 | 优化前 | 优化后 | 变化 |
-|------|:------:|:------:|:----:|
-| epoll_ctl 调用数 | 32,563 | 9,173 | ↓71.8% |
-| epoll_ctl 时间占比 | 26.51% | 5.57% | ↓20.94 p.p. |
-| 空闲连接额外内存 | 0 | +256B（协程帧栈） | 可忽略 |
-| 总系统调用数 | 99,579 | 79,504 | ↓20.2% |
+| 指标               | 优化前 |      优化后       |    变化     |
+| ------------------ | :----: | :---------------: | :---------: |
+| epoll_ctl 调用数   | 32,563 |       9,173       |   ↓71.8%    |
+| epoll_ctl 时间占比 | 26.51% |       5.57%       | ↓20.94 p.p. |
+| 空闲连接额外内存   |   0    | +256B（协程帧栈） |   可忽略    |
+| 总系统调用数       | 99,579 |      79,504       |   ↓20.2%    |
 
 ---
 

ports/hical61-hical/portfile.cmake

@@ -4,7 +4,7 @@ vcpkg_from_github(
     OUT_SOURCE_PATH SOURCE_PATH
     REPO Hical61/Hical
     REF "v${VERSION}"
-    SHA512 feeebad5debd254b564b13822f5ef69b76d03f817f046b6ebf201c438b65cb7a19bc3e81bd8248b3edebc2d43e5d6f90d60d4de60c7a50dc4aefd2ca2bbb8057
+    SHA512 244f87004d6a4c9ca2e04d555ee0c20faf3db8623b90c4c73f4c5de1dffff0a24d2a5d0d8bd633e89363d63204845583af30c1139e50d09c7c24657d66ca3a06
     HEAD_REF main
 )
 

src/core/HttpRequest.cpp

@@ -146,6 +146,16 @@ namespace hical
 		}
 	}
 
+	const InetAddress& HttpRequest::peerAddr() const
+	{
+		return peerAddr_;
+	}
+
+	void HttpRequest::setPeerAddr(const InetAddress& addr)
+	{
+		peerAddr_ = addr;
+	}
+
 	// ============ 路径参数 ============
 
 	const std::string& HttpRequest::param(std::string_view name) const

src/core/HttpRequest.h

@@ -7,6 +7,7 @@
 
 #include "HeaderMap.h"
 #include "HttpTypes.h"
+#include "InetAddress.h"
 #include <any>
 #include <array>
 #include <boost/json.hpp>
@@ -211,6 +212,18 @@ namespace hical
 		void setHeader(const std::string& name, const std::string& value);
 		void setBody(const std::string& body);
 
+		/**
+		 * @brief 获取对端网络地址
+		 * @return 对端地址引用（未设置时为默认构造的无效地址）
+		 */
+		[[nodiscard]] const InetAddress& peerAddr() const;
+
+		/**
+		 * @brief 设置对端网络地址
+		 * @param addr 对端地址
+		 */
+		void setPeerAddr(const InetAddress& addr);
+
 		// ============ 路径参数 ============
 
 		/**
@@ -296,6 +309,7 @@ namespace hical
 		void parseFormParams() const;
 
 		NativeRequest req_;
+		InetAddress peerAddr_;
 		// setter 专用拥有存储（测试/构建请求场景，不在热路径）
 		std::string ownedTarget_;
 		HeaderMap ownedHeaders_;

src/core/HttpSessionImpl.cpp

@@ -7,6 +7,7 @@
 
 #include "HttpServer.h"
 #include "FixedBuffer.h"
+#include "InetAddress.h"
 #include "MemoryPool.h"
 #include "ReadBufferPool.h"
 #include "SseSession.h"
@@ -554,6 +555,11 @@ namespace hical
 		// 期间设置的 O_NONBLOCK 是实现细节，不能依赖它保持生效。
 		socket.non_blocking(true);
 
+		// 对端地址是连接级信息，取一次供本连接所有请求复用。
+		// socket 刚 accept 必然已连接，getpeername() 不会失败，与 TcpServer::acceptLoop 同款写法。
+		auto remoteEp = socket.remote_endpoint();
+		InetAddress peerAddr(remoteEp.address().to_string(), remoteEp.port());
+
 		// entry 在协程栈上，Guard 析构时自动注销
 		// 声明在 SocketGuard 后面 → 先析构（先 unregister 再关 socket）
 		IdleScanner::Entry idleEntry;
@@ -1016,6 +1022,7 @@ namespace hical
 
 				// ====== 阶段 D：构建 HttpRequest 并分发 ======
 				HttpRequest req = HttpRequest::fromParsed(std::move(nativeReq));
+				req.setPeerAddr(peerAddr);
 
 				// 检查 WebSocket 升级请求
 				if (req.native().isUpgrade())

src/core/InetAddress.cpp

@@ -81,6 +81,13 @@ namespace hical
 		return isIpV6_;
 	}
 
+	bool InetAddress::isValid() const
+	{
+		// 默认构造只 memset 了 addr6_ 且 isIpV6_=false，此时 addr_.sin_family 为 0
+		// 按 isIpV6_ 标志读取对应 union 成员的 sin_family，避免读错成员
+		return isIpV6_ ? (addr6_.sin6_family == AF_INET6) : (addr_.sin_family == AF_INET);
+	}
+
 	const struct sockaddr* InetAddress::getSockAddr() const
 	{
 		return isIpV6_ ? reinterpret_cast<const struct sockaddr*>(&addr6_)

src/core/InetAddress.h

@@ -70,6 +70,13 @@ namespace hical
 		 */
 		bool isIpV6() const;
 
+		/**
+		 * @brief 地址是否有效
+		 * 默认构造或解析失败时地址族为 0，返回 false。
+		 * @return true 如果已解析为有效的 IPv4 或 IPv6 地址
+		 */
+		[[nodiscard]] bool isValid() const;
+
 		/**
 		 * @brief 获取底层 sockaddr 结构
 		 * @return sockaddr 指针