anytls 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 56a137e1d309ae5f93c6d0766cac36bd25d0f6b7246a41dc91de7b07c1ae3c9d
+  data.tar.gz: 2051953545edec2a5fda7709f942b79f6eb1adc6c882aae2d6e645db9e464af7
+SHA512:
+  metadata.gz: 9d2e182c0ea5fd15b42b6c4032e9462ade916cc4863a7295acd4d495ec004a9ff23998bf2808bc6bdcb2a2e5b6d75ab2199859eb7b8b407032a7ec1b286d680b
+  data.tar.gz: 28a8faeb2f4948725d016321bed77ab8a19752f3f40a0279c14603361864b028c854063c0e68af8690d2e7cf9363cc30ae942c90cbdbbe9075098ba06252fc76

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0 (2026-10-01)
+
+- Initial Ruby implementation of AnyTLS, a gem API and client/server command-line programs.
+- TLS certificate verification is enabled by default; explicit CA files use an isolated trust store.
+- Explicit resource limits and local TLS/cross-language validation entry points.
+- Socket shutdown wakes blocked readers before closing, including on Linux.
+- HTTP Upgrade requests with a body are rejected instead of silently dropping the body.
+- Invalid timeout values are rejected before dialing, and invalid padding does not leave wake sockets open.
+- The independent Ruby implementation is available under the MIT license.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AnyTLS Ruby contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,143 @@
+# AnyTLS Ruby
+
+Ruby 3.4+ 的 AnyTLS gem 与命令行客户端、服务端。参考版本固定为
+[`anytls-go` 的 `fd6167a`](https://github.com/anytls/anytls-go/tree/fd6167acd6d73b9fa3e607659951847fbc9e6c50)。
+核心代码不依赖 Rails。
+
+当前版本为 `0.1.0`，Ruby 实现使用 [MIT 许可证](LICENSE)。项目及参考代码的许可边界见
+[SOURCES](docs/SOURCES.md)。
+
+## 使用
+
+安装 gem 后可直接运行两个命令：
+
+```sh
+gem install anytls
+anytls-client --help
+anytls-server --help
+```
+
+从源码运行：
+
+```sh
+bundle install
+bundle exec ruby -Ilib bin/anytls-server --help
+bundle exec ruby -Ilib bin/anytls-client --help
+```
+
+服务端默认监听 `0.0.0.0:8443`，正常部署显式提供证书和私钥：
+
+```sh
+bundle exec ruby -Ilib bin/anytls-server \
+  --password-file /path/to/password \
+  --cert /path/to/fullchain.pem --key /path/to/private-key.pem
+```
+
+客户端默认在 `127.0.0.1:1080` 提供混合 SOCKS4/4a、SOCKS5、HTTP 代理：
+
+```sh
+bundle exec ruby -Ilib bin/anytls-client \
+  --server proxy.example.com:8443 --password-file /path/to/password
+```
+
+客户端默认验证 TLS 证书与主机名。`--sni` 设置验证名称和 SNI，`--ca-file`
+提供自有 CA。开发环境可让服务端使用 `--self-signed`，客户端需要显式选择
+`--insecure` 或信任该证书；关闭验证不会成为默认行为。
+
+`--server` 也接受 `anytls://PASSWORD@HOST:PORT/?sni=NAME&insecure=1#LABEL`。
+密码中的保留字符应百分号编码；显式命令行参数优先于 URI，URI 密码优先于
+`ANYTLS_PASSWORD` 环境变量。`--password` 与 `--password-file` 互斥。密码文件只移除
+末尾一次 LF/CRLF，保留密码自身的空格。诊断信息不回显密码、完整连接 URI 或 payload。
+
+兼容参考程序的 `-l`、`-s`、`-p`、`-m`、`-sni`、`-dr` 和 `-padding-scheme`。
+`-dr`/`--disable-reuse` 是诊断选项，每个连接使用新 session。
+INT/TERM 经唤醒 socket 交给正常线程处理，停止监听后清理现有连接。
+
+## Ruby API
+
+```ruby
+require "anytls"
+
+AnyTLS::Client.open(host: "proxy.example.com", port: 8443, password: ENV.fetch("ANYTLS_PASSWORD")) do |client|
+  client.connect("example.com", 80, timeout: 5) do |stream|
+    stream.write("GET / HTTP/1.0\r\nHost: example.com\r\n\r\n", timeout: 5)
+    puts stream.readpartial(4096, timeout: 5)
+  end
+end
+```
+
+`Stream#readpartial` 返回二进制 String，正常结束抛 `EOFError`；`read(length)` 遵循指定
+长度的 Ruby IO 读取习惯；`write` 成功返回写入字节数。写入成功只表示完成本地 TLS
+发送，不证明目标应用已处理。错误或超时后的数据不自动重放。Stream 没有独立 fd，
+不提供 `to_io` 或真正的 TCP half-close。
+
+AnyTLS 没有独立的认证成功回执；首次连接或 v1 peer 可能先返回尚未确认目标连接的
+Stream。`connection_status` 区分 `:unconfirmed`、`:confirmed`、`:failed`。远端拒绝、认证
+失败和连接关闭也可能在后续读写体现，不能仅凭创建 Stream 就声称远端目标已连接。
+
+UDP-over-TCP v2 支持固定目标与逐包目标：
+
+```ruby
+target = AnyTLS::Address.new(host: "127.0.0.1", port: 5353)
+client.open_datagrams(destination: target, timeout: 5) do |datagrams|
+  datagrams.send_packet("request".b, timeout: 5)
+  payload, source = datagrams.receive_packet(timeout: 5)
+end
+```
+
+省略固定 `destination:` 时，每次 `send_packet` 必须提供 `destination:`。UoT 的 16 位长度
+字段可承载最多 65,535 字节，空 datagram 有效。实际 UDP socket 还受地址族与系统发送
+上限约束，可能以 `EMSGSIZE` 拒绝较大的包；线协议上限不是网络发送保证。
+SOCKS5 UDP ASSOCIATE 通过同一 UoT 能力实现。
+
+```ruby
+tls = AnyTLS::TLSConfig.new(server: true, cert: "fullchain.pem", key: "private-key.pem")
+server = AnyTLS::Server.new(password: ENV.fetch("ANYTLS_PASSWORD"), tls: tls)
+server.run # 阻塞；由其他正常线程调用 server.stop(grace: 5)
+```
+
+构造 Client 不拨号；首次连接时才启动会话池。`min_idle_sessions` 是回收时保留已有空闲
+session 的数量，不会主动创建连接填满池。默认最多 128 个 session，空闲超时与检查间隔
+各 30 秒。客户端租用空闲 session；并发请求需要时建立新的 session。服务端默认最多
+256 个活动 stream。`Client#stats`、`Server#stats` 返回冻结的计数快照。
+
+## 功能与边界
+
+支持 AnyTLS 帧、设置协商、目标连接报告、会话复用、heartbeat、padding 更新和 UDP-over-TCP v2；
+混合代理支持 SOCKS4/4a CONNECT、SOCKS5 CONNECT/UDP ASSOCIATE、HTTP CONNECT、普通 HTTP
+转发、keep-alive、chunked body 和 HTTP Upgrade。SOCKS BIND、SOCKS 用户名密码认证、
+SOCKS UDP 分片和 UoT v1 不在当前接口范围。
+
+HTTP 转发使用 `protocol-http1` 解析消息边界，拒绝冲突 Content-Length/Transfer-Encoding
+及重复 Host。带请求体的 HTTP Upgrade 返回 400，避免丢弃消息体；无体 Upgrade 继续支持。
+HTTPS 目标使用 CONNECT。代理客户端监听仅默认绑定回环地址；扩大监听
+范围时由部署环境限制访问者。
+
+每条 TLS 连接只有一个 owner Thread。协议接收按 stream/session 字节预算限流；慢消费者
+超过预算会被关闭，避免无限增长或阻塞其他 stream。TLS/TCP 本身的队首阻塞仍然存在。
+设计和状态边界见 [ARCHITECTURE](docs/ARCHITECTURE.md)。
+
+## 验证
+
+```sh
+bundle exec rake test        # 单元、真实本地 TLS、CLI；跨语言测试独立执行
+bundle exec rake lint
+bundle exec rake package     # 临时 GEM_HOME 中离线安装依赖和构建包，再检查 require/CLI
+bundle exec rake stress      # 有界本地 TLS 并发场景，打印测量结果并检查线程回收
+```
+
+跨语言验收需自行取得固定 commit 的参考源码并构建；构建物不进入 Ruby gem：
+
+```sh
+git clone https://github.com/anytls/anytls-go.git /tmp/anytls-go
+git -C /tmp/anytls-go checkout fd6167acd6d73b9fa3e607659951847fbc9e6c50
+cd /tmp/anytls-go
+go build -o /tmp/anytls-go-client ./cmd/client
+go build -o /tmp/anytls-go-server ./cmd/server
+cd /path/to/anytls-ruby
+ANYTLS_GO_CLIENT=/tmp/anytls-go-client ANYTLS_GO_SERVER=/tmp/anytls-go-server \
+  ANYTLS_REQUIRE_INTEROP=1 bundle exec rake interop
+```
+
+CI 配置覆盖 Ruby 3.4/4.0 × Linux/macOS，以及固定 Go 参考双向互通。
+配置存在不等于远端 CI 已执行；验证证据与运行命令见 [VALIDATION](docs/VALIDATION.md)。

data/bin/anytls-client

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "anytls"
+require "anytls/cli/runner"
+
+exit AnyTLS::CLI::Runner.run(:client)

data/bin/anytls-server

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "anytls"
+require "anytls/cli/runner"
+
+exit AnyTLS::CLI::Runner.run(:server)

data/docs/ARCHITECTURE.md

@@ -0,0 +1,105 @@
+# 模块、所有权与协议边界
+
+## 分层
+
+| 层 | 类型 | 责任 |
+| --- | --- | --- |
+| 公共入口 | `Client`、`Server` | 连接生命周期、块形式资源管理、目标拨号与入站接入 |
+| 复用 | `SessionPool` | 按创建序号选择最新空闲 session，限制连接数，回收空闲 session |
+| 协议运行 | `Session` | 唯一 owner Thread、帧 dispatch、stream 状态、设置与 padding 协商 |
+| 虚拟 IO | `Stream`、`ByteBuffer` | 同步读写 API、串行化写调用、有界接收队列、EOF 与错误传播 |
+| TLS | `TLSConfig`、`Transport::TLSConnection` | TLS 参数、证书校验、握手、认证字节、非阻塞读写与重试 |
+| 协议值与编码 | `Address`、`Protocol::*` | 网络序字节编码、长度与类型校验、增量解帧、目标地址、设置 |
+| Padding | `Padding::Scheme`、`Padding::Writer` | 不可变原始方案及 MD5 标识、有限规则、发送片段与 WASTE |
+| UDP | `UoT::Connection`、`UoT::Server` | UoT v2 握手与包边界、UDP socket 资源 |
+| 入站应用 | `Inbound::Mixed/Socks4/Socks5/HTTPProxy` | SOCKS/HTTP 握手、目标解析、协议回复、UDP association |
+| IO 支撑 | `Deadline`、`IOHelpers`、`BufferedIO`、`Dialer`、`Relay` | 单调时间预算、有限缓冲、真实 TCP IO 和双向搬运 |
+| 交付 | `CLI::Options/Runner/ClientListener/Shutdown` | 参数、秘密来源、监听限制、信号转发与退出码 |
+
+核心仅占 `AnyTLS` 命名空间；显式 `require_relative` 加载，不 monkey-patch Ruby 类。
+构造配置对象和加载 gem 不监听端口或拨号。协议对象保持普通 Ruby 类和少量不可变值，
+不模拟 Go interface、goroutine/channel，也不引入 ActiveSupport。
+
+## 线协议与状态
+
+认证前导为密码 SHA-256 的 32 字节摘要、2 字节 padding 长度及 padding。摘要是原始字节，
+不是 hex 字符串。认证前导必须在 TLS 内传输。
+
+每个协议帧由 `command:uint8 + stream_id:uint32be + payload_length:uint16be + payload` 组成。
+增量 Decoder 能处理任意 header/body 分割；不把一次 TLS read 当成一帧。payload 最大
+65,535 字节，公开 Stream 大 write 在编码前分片。Decoder 先按声明长度完成帧边界解析；
+Session 与 Go 参考保持一致：未知命令的空 payload 可忽略，非空 payload 则拒绝并结束 session。
+
+Session 先完成 TLS 与认证，再推进 SETTINGS/SYN/PSH 等协议状态。服务端收到 SYN 时分配
+Stream，并将目标地址的读取与拨号交给有限 worker。v2 的 SYNACK 表达目标连接结果，
+不是独立的身份认证回执；v1 或尚未获知 peer 版本时保留 `unconfirmed` 状态。
+FIN 结束整个虚拟 stream，不提供 read/write 两侧独立关闭语义。
+
+Client pool 同一时刻将一个 session 租给一条业务 stream，完成后将其归还并复用。
+服务端 Session 解码器支持多条 stream 的帧，入站数量另受 session 和 server 限制。
+旧空闲连接检测、心跳和 peer stream-ID 限制都在 session 生命周期中处理，不由应用代理层重试。
+
+## 线程与 TLS 所有权
+
+Session owner 唯一持有 TLS IO 使用权；应用线程通过同步提交请求与 completion 等待写入结果。
+owner 运行具体的 AnyTLS 事件循环：处理请求、选择待发片段、推进 TLS write/read、dispatch
+完整帧、根据方向和最近 deadline 等待 TLS fd 或 wakeup socket。它不是通用调度器。
+
+同一 `SSLSocket` 不由 reader/writer 两线程直接共用。待重试的 `SSL_write` 保持完全相同
+的数据和长度；只有成功返回正整数后才推进偏移。write 返回 WANT_WRITE 时，下一次 TLS
+IO 只能重试该 write；不能插入 read。write 返回 WANT_READ 时可以读，但下一笔应用 write
+仍需等待当前 write 完成。[OpenSSL 维护者说明](https://github.com/openssl/openssl/discussions/30934)
+和 [SSL_write 文档](https://docs.openssl.org/3.0/man3/SSL_write/) 是此约束依据。
+
+握手、认证与关闭也归 owner。取消通过 wakeup socket，而不是向线程注入异常。
+发生发送超时后关闭整个 session，不跳过半帧或透明重放请求。
+证书 Context 配置完成后冻结，不能在其他连接使用时修改。
+
+Session 状态锁只保护短操作；锁内不等待网络、不回调调用者代码。Stream 写调用串行化，
+一个写调用内的帧保持顺序。双向 Relay 使用有限的线程，并在一端结束时关闭另一端以唤醒等待。
+
+## 时间预算与资源限制
+
+`Deadline` 使用 `CLOCK_MONOTONIC`。同一读写操作中的等待消耗同一预算，不在部分进度后
+重新计时；排队和锁等待也会消耗预算。连接、握手、目标拨号和关闭具有单独边界。
+
+| 限制 | 当前默认 |
+| --- | --- |
+| 客户端/服务端 TLS session 数 | 128 |
+| 服务端活动业务 stream 数 | 256 |
+| 单 session stream 数 | 32 |
+| 单 stream 接收缓冲 | 256 KiB |
+| 单 session 接收缓冲 | 4 MiB |
+| 单 session 提交发送预算 | 1 MiB，计入编码和 padding 预留 |
+| Stream 数据写片段 | 16 KiB |
+| UoT 包长度字段 | 65,535 字节；实际 UDP socket 另受地址族/系统大小限制 |
+| CLI 混合入站连接 | 256 |
+
+接收 owner 不能阻塞等待单个 Stream 消费。超过接收预算时终止对应 stream，并通知 peer；
+控制帧预算也不能无限增长。发送预算不足时让提交者等待。限制按 bytes 计费，不能只用
+队列条目数代表内存大小。上限约束 Ruby 可见缓冲，不宣称它是进程 RSS 的精确上界。
+
+同一 TCP 连接天然存在队首阻塞；有限缓冲只能限制 Ruby 自身的资源占用和慢消费者影响。
+当前没有扩展协议增加 per-stream credit，不承诺无限慢消费者仍可无损持续接收。
+
+## 秘密、错误与清理
+
+Client 默认验证证书和目标名称；`insecure: true` 必须显式选择。服务端必须有证书与私钥，
+或显式选择开发用途的临时自签名证书。配置加载错误不回显密码、URI 或私钥内容。
+
+参数错误使用 `ArgumentError`/`ConfigurationError`，协议和传输错误使用 `AnyTLS::Error`
+下的具体类型。正常 EOF 与故障分开；成功写入不是目标应用确认。`inspect` 和 CLI 日志不输出秘密。
+
+`close` 可重复调用。`ensure` 负责 socket、session、stream 与线程回收，保留原始业务错误。
+INT/TERM trap 只向 pipe 写字节；实际清理在正常线程执行。没有 gem publish、在线下载设备配置
+或全局代理设置等隐藏副作用。
+
+服务端 `stop(grace:)` 先停止监听，允许已经建立的 stream 在宽限期继续传输；到期再关闭
+剩余 session/目标 socket 并等待 worker 退出。并发 `stop` 服从第一次停止请求确定的边界，
+listener 退出时的清理不能提前缩短宽限期。关闭单个资源失败也必须继续释放剩余资源与计数。
+
+## 可扩展边界
+
+未来如果实际并发测量证明 native threads 不合适，可以整体迁移到单一 Async owner task；
+线协议 codec、Padding、Stream 契约与 TLS 重试不变量继续保留。当前不维护两套运行时、
+不自建插件注册系统、不将 HTTP/2 flow control 状态复制到 AnyTLS。

data/docs/SOURCES.md

@@ -0,0 +1,15 @@
+# Sources and licensing
+
+The protocol reference is [anytls/anytls-go](https://github.com/anytls/anytls-go),
+reviewed at commit `fd6167a`. This project is an independent Ruby implementation.
+The upstream repository did not provide a license grant in the reviewed checkout.
+This notice does not assign an upstream license or grant permission to redistribute
+upstream source or binaries. Cross-language tests obtain the reference separately.
+
+The independent Ruby implementation is released under the MIT license in
+[`LICENSE`](../LICENSE). This license applies to the Ruby project only and does not
+grant rights to the upstream Go source or binaries. Building and testing the gem
+does not publish it.
+
+The implementation uses the Ruby OpenSSL bindings and `protocol-http1`; their own
+license terms remain applicable. No upstream Go source is included in the gem.

data/docs/VALIDATION.md

@@ -0,0 +1,100 @@
+# 验证入口与证据范围
+
+本地 gate：
+
+| 命令 | 证明范围 |
+| --- | --- |
+| `bundle exec rake test` | codec/状态机与失败测试、真实回环 TLS、混合代理、CLI 进程生命周期 |
+| `bundle exec rake integration` | Ruby 客户端/服务端经真实 TCP+OpenSSL 的端到端路径 |
+| `bundle exec rake interop` | Go→Go 基线、Ruby→Go 和 Go→Ruby 的 TCP/UDP 路径 |
+| `bundle exec rake lint` | 项目 Ruby 规则与静态错误检测 |
+| `bundle exec rake package` | 实际 gem 文件列表、临时 GEM_HOME 中依赖安装、包加载与两个 executable |
+| `bundle exec rake stress` | 有界本地并发数据完整性、阶段耗时和线程回收 |
+
+普通 `test` 不包含跨语言测试。显式运行 interop 时若缺少参考二进制直接失败，
+不把 skip 算作互通成功。参考源码固定 commit 为
+`fd6167acd6d73b9fa3e607659951847fbc9e6c50`。
+
+`package` 使用已安装依赖的 gem cache，不访问网络，也不回退到全局 GEM_PATH；缺缓存会
+明确失败。OpenSSL native extension 在临时安装目录编译，因此需要 Ruby/OpenSSL 开发工具。
+产物与临时安装在验证后移除，不执行上传或发布。
+
+## 发布验证
+
+CI 的 Ubuntu / Ruby 4.0 任务在验证通过后上传 `anytls-gem` artifact，包含 gem 和 `SHA256SUMS`。
+发布前须确认同一提交的完整 Ruby 矩阵和 Go 互通任务均通过，下载该 artifact 并核对校验和。
+运行 `bundle exec ruby script/verify_package.rb /path/to/anytls-0.1.0.gem` 可验证已有包与当前源码
+的文件内容、元数据和依赖一致，并隔离安装该包；提供路径时不会重新构建 gem。
+GitHub Release 和 RubyGems 必须使用这一份验证过的包，发布后下载两处产物并核对 SHA256。
+
+## 本机执行记录
+
+2026-10-01，macOS arm64，Ruby 4.0.7 / 3.4.11，openssl gem 4.0.2，OpenSSL 3.6.4：
+
+运行时指纹：[Ruby 4.0](validation/runtime-ruby40.json)、[Ruby 3.4](validation/runtime-ruby34.json)。
+Ruby 3.4 的正确本地命令同时固定 PATH 和 Bundler 入口，依赖位于独立的 `ruby/3.4.0` 目录：
+
+```sh
+PATH=/opt/homebrew/opt/ruby@3.4/bin:$PATH BUNDLE_PATH=tmp/validation-ruby34 \
+  /opt/homebrew/opt/ruby@3.4/bin/bundle exec rake test
+```
+
+以下记录仅使用实际运行时指纹核对后的执行。
+
+- 真实 TLS/mixed integration：包含证书验证、TLS 1.2/1.3、完整证书链、TCP 与 UDP，以及混合代理端到端。
+- Ruby 4.0.7 最终完整本地 suite：156 tests、990 assertions，通过，无 skips（seed 855）。
+- Ruby 3.4.11 最终完整本地 suite：156 tests、990 assertions，通过，无 skips（seed 13099）。
+- Go 固定参考 Go→Go 基线、双向 TCP/UDP 互通：两个 Ruby 版本各 3 tests、15 assertions，通过，无 skips。
+- CLI 客户端/服务端进程通信和 SIGTERM：1 test、7 assertions，通过。
+- CLI admission 的 EMFILE / ThreadError 故障注入：2 tests、10 assertions，通过；已有连接保持
+  可用，未归属 socket 关闭，后续接入恢复。
+- 默认 stress：16 并发 × 20 次、每条 32 KiB；320 条 stream 的 payload 全部一致，
+  最终清理后只剩主线程，fd 从 7 回到 7。修复 graceful shutdown 后已再验证此场景。
+  这是本地回环验证，不是生产吞吐承诺，也未与 Go 做性能比较。
+- 两个 Ruby 版本的隔离包验证：临时目录构建 gem、离线安装 8 个运行依赖/项目 gem、
+  编译 OpenSSL extension、隔离 `require` 和两个 CLI `--help`，均通过。
+- 全库 RuboCop：Ruby 3.4 和 4.0 均检查 74 个 Ruby 文件，无违规。
+
+两个版本在 `-w` 下的 CLI 线程创建故障注入用例会产生预期的方法临时替换警告；没有未处理
+worker 异常。完整证书链用例验证客户端仅信任 root 即可验证 leaf+intermediate，同时拒绝
+缺失 intermediate 和不匹配的 hostname。
+
+以上为本机最终 gate 记录。Linux 和 GitHub 远端 CI 未执行，不能从本机结果推定通过。
+
+### 并发与回收测量
+
+同一进程包含 Ruby 客户端、Ruby 服务端与 echo fixture，50 ms 间隔采样 threads/fd/RSS；
+采样峰值可能低于瞬时峰值。表格中的内存和连接数是整套本地场景的消耗，不是单个部署端的消耗。
+
+| 场景 | Stream 数 / 每条 payload | 秒 | p95 / p99 ms | 采样峰值线程 / fd / RSS KiB | 原始 JSON |
+| --- | --- | --- | --- | --- | --- |
+| 1 并发 | 20 / 32 KiB | 0.023 | 1.969 / 4.002 | 9 / 16 / 55,536 | [c1](validation/stress-c1.json) |
+| 32 并发 | 640 / 32 KiB | 0.577 | 35.466 / 52.739 | 229 / 275 / 119,984 | [c32](validation/stress-c32.json) |
+| 128 并发 | 2,560 / 32 KiB | 3.084 | 203.655 / 286.761 | 890 / 1,039 / 238,352 | [c128](validation/stress-c128.json) |
+| 10,000 顺序连接 | 10,000 / 64 B | 4.547 | 0.564 / 0.866 | 12 / 18 / 56,576 | [sequential](validation/stress-sequential-10000.json) |
+
+以上四个场景均数据一致、0 错误；结束后 threads 为 1，fd 从 7 回到 7。10,000 顺序连接
+只创建 1 个 TLS session，证明该场景复用生效。不同并发下尾延迟和资源消耗明显增长，
+不能把这些数字解释为固定性能保证。
+
+初次 32 并发尝试被当前 shell 的 soft NOFILE=256 限制阻塞，出现拨号失败/EOF/timeout，
+并未通过。后续仅为验证子进程执行 `ulimit -n 4096`，再完成 32/128 并发与 10,000 顺序场景。
+实际采样峰值 fd 为 275/1,039，确认原限制不足。stress 脚本现在先检查描述符预算，条件
+不足直接解释并退出；库本身不修改用户进程的资源上限。
+
+## 扩展测量
+
+```sh
+ulimit -n 4096
+ANYTLS_STRESS_CONCURRENCY=64 ANYTLS_STRESS_ITERATIONS=100 \
+  ANYTLS_STRESS_BYTES=32768 bundle exec rake stress
+```
+
+压力参数有上限；默认测试不是无限运行守护进程。报告零字节损坏、零未处理错误、所有 worker
+有界退出和连接资源回收，再报告吞吐与延迟。不设置脱离部署环境的吞吐合格线；回归比较须固定
+机器、运行时、证书类型、并发、消息大小和测试时长。
+
+关键失败用例覆盖拆分 header/body、短写与 TLS wait 方向、写入预算、未知命令、错误密码、
+证书与名称不匹配、目标拨号失败、断连、缓慢消费、close 与等待交错。
+mock 只证明状态与协议不变量；真实 TLS 测试证明本地适配器和端到端路径；二者都不代表
+真实公网、生产路由、任意防火墙/代理环境或所有 OpenSSL 版本验收。

data/docs/validation/runtime-ruby34.json

@@ -0,0 +1,8 @@
+{
+  "ruby": "ruby 3.4.11 (2026-09-23 revision 592f1ffdb3) +PRISM [arm64-darwin25]",
+  "ruby_executable": "/opt/homebrew/Cellar/ruby@3.4/3.4.11/bin/ruby",
+  "ruby_engine": "ruby",
+  "platform": "arm64-darwin25",
+  "openssl_gem": "4.0.2",
+  "openssl_library": "OpenSSL 3.6.4 25 Aug 2026"
+}

data/docs/validation/runtime-ruby40.json

@@ -0,0 +1,8 @@
+{
+  "ruby": "ruby 4.0.7 (2026-09-15 revision 229531a6cf) +PRISM [arm64-darwin25]",
+  "ruby_executable": "/opt/homebrew/Cellar/ruby/4.0.7/bin/ruby",
+  "ruby_engine": "ruby",
+  "platform": "arm64-darwin25",
+  "openssl_gem": "4.0.2",
+  "openssl_library": "OpenSSL 3.6.4 25 Aug 2026"
+}

data/docs/validation/stress-c1.json

@@ -0,0 +1,25 @@
+{
+  "ruby": "ruby 4.0.7 (2026-09-15 revision 229531a6cf) +PRISM [arm64-darwin25]",
+  "openssl": "OpenSSL 3.6.4 25 Aug 2026",
+  "concurrency": 1,
+  "streams": 20,
+  "bytes_per_stream": 32768,
+  "seconds": 0.023,
+  "mib_per_second": 54.88,
+  "p95_ms": 1.969,
+  "p99_ms": 4.002,
+  "sampled_peak_threads": 9,
+  "remaining_threads": 1,
+  "baseline_fds": 7,
+  "sampled_peak_fds": 16,
+  "remaining_fds": 7,
+  "baseline_rss_kib": 36656,
+  "sampled_peak_rss_kib": 55536,
+  "client_stats_before_close": {
+    "sessions": 1,
+    "idle_sessions": 1,
+    "creating_sessions": 0,
+    "created_sessions": 1
+  },
+  "errors": 0
+}

data/docs/validation/stress-c128.json

@@ -0,0 +1,26 @@
+{
+  "ruby": "ruby 4.0.7 (2026-09-15 revision 229531a6cf) +PRISM [arm64-darwin25]",
+  "openssl": "OpenSSL 3.6.4 25 Aug 2026",
+  "concurrency": 128,
+  "streams": 2560,
+  "bytes_per_stream": 32768,
+  "descriptor_soft_limit": 4096,
+  "seconds": 3.084,
+  "mib_per_second": 51.878,
+  "p95_ms": 203.655,
+  "p99_ms": 286.761,
+  "sampled_peak_threads": 890,
+  "remaining_threads": 1,
+  "baseline_fds": 7,
+  "sampled_peak_fds": 1039,
+  "remaining_fds": 7,
+  "baseline_rss_kib": 36656,
+  "sampled_peak_rss_kib": 238352,
+  "client_stats_before_close": {
+    "sessions": 128,
+    "idle_sessions": 128,
+    "creating_sessions": 0,
+    "created_sessions": 128
+  },
+  "errors": 0
+}

data/docs/validation/stress-c32.json

@@ -0,0 +1,26 @@
+{
+  "ruby": "ruby 4.0.7 (2026-09-15 revision 229531a6cf) +PRISM [arm64-darwin25]",
+  "openssl": "OpenSSL 3.6.4 25 Aug 2026",
+  "concurrency": 32,
+  "streams": 640,
+  "bytes_per_stream": 32768,
+  "descriptor_soft_limit": 4096,
+  "seconds": 0.577,
+  "mib_per_second": 69.329,
+  "p95_ms": 35.466,
+  "p99_ms": 52.739,
+  "sampled_peak_threads": 229,
+  "remaining_threads": 1,
+  "baseline_fds": 7,
+  "sampled_peak_fds": 275,
+  "remaining_fds": 7,
+  "baseline_rss_kib": 36720,
+  "sampled_peak_rss_kib": 119984,
+  "client_stats_before_close": {
+    "sessions": 32,
+    "idle_sessions": 32,
+    "creating_sessions": 0,
+    "created_sessions": 32
+  },
+  "errors": 0
+}

data/docs/validation/stress-sequential-10000.json

@@ -0,0 +1,26 @@
+{
+  "ruby": "ruby 4.0.7 (2026-09-15 revision 229531a6cf) +PRISM [arm64-darwin25]",
+  "openssl": "OpenSSL 3.6.4 25 Aug 2026",
+  "concurrency": 1,
+  "streams": 10000,
+  "bytes_per_stream": 64,
+  "descriptor_soft_limit": 4096,
+  "seconds": 4.547,
+  "mib_per_second": 0.268,
+  "p95_ms": 0.564,
+  "p99_ms": 0.866,
+  "sampled_peak_threads": 12,
+  "remaining_threads": 1,
+  "baseline_fds": 7,
+  "sampled_peak_fds": 18,
+  "remaining_fds": 7,
+  "baseline_rss_kib": 36832,
+  "sampled_peak_rss_kib": 56576,
+  "client_stats_before_close": {
+    "sessions": 1,
+    "idle_sessions": 1,
+    "creating_sessions": 0,
+    "created_sessions": 1
+  },
+  "errors": 0
+}

data/lib/anytls/address.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+
+module AnyTLS
+  # SOCKS 目标地址值；端口零也可表示尚未绑定的 UDP 端点。
+  Address = Data.define(:host, :port) do
+    def initialize(host:, port:)
+      raise TypeError, "host must be a String" unless host.is_a?(String)
+      raise TypeError, "port must be an Integer" unless port.is_a?(Integer)
+      raise ArgumentError, "port must be between 0 and 65535" unless (0..65_535).cover?(port)
+      unless host.ascii_only? && host.bytesize.between?(1, 255) && !host.match?(%r{[\x00-\x20\x7f/@%?\[\]\\#]})
+        raise ArgumentError, "host must be an ASCII IP address or domain of 1 to 255 bytes"
+      end
+
+      begin
+        ip = IPAddr.new(host)
+        host = ip.to_s
+      rescue IPAddr::InvalidAddressError
+        raise ArgumentError, "invalid IP address" if host.include?(":")
+      end
+      super(host: host.dup.freeze, port:)
+    end
+
+    def ip?
+      !ip_address.nil?
+    end
+
+    def ipv4?
+      ip_address&.ipv4? || false
+    end
+
+    def ipv6?
+      ip_address&.ipv6? || false
+    end
+
+    def domain?
+      !ip?
+    end
+
+    def to_s
+      ipv6? ? "[#{host}]:#{port}" : "#{host}:#{port}"
+    end
+
+    private
+
+    def ip_address
+      IPAddr.new(host)
+    rescue IPAddr::InvalidAddressError
+      nil
+    end
+  end
+end