net

设计契约

XRT_FEATURE_NET 是网络体系最底层的独立裁剪单元，只依赖 core。这一层不创建 Socket，不执行 DNS，也不依赖线程、任务或协程；它负责稳定的 IP 地址表示、数字地址与端点解析、规范输出、地址分类和平台 sockaddr 转换。

公开头文件不包含 Winsock 或 POSIX Socket 头文件。xnetaddr 因此可以直接进入 FFI 值类型、容器键、配置结构和协议对象，不会把平台 ABI 扩散到上层。Windows 网络运行时由后续 Socket 操作按需初始化，使用者不需要配对调用启动与清理函数。

Port 使用主机字节序，Address 始终使用网络字节序。IPv4 只使用前 4 字节；Scope 只对 IPv6 有意义。地址族常量是 XRT 自己的稳定值，不能与 AF_INET、AF_INET6 混用。

网络缓冲

XRT_FEATURE_NET_BUFFER 依赖 XRT_FEATURE_NET，提供 TCP、UDP、TLS、HTTP 和 WebSocket 共用的可变尺寸缓冲底座。缓冲只在实际收到或排队数据时持有块；默认池尺寸类为 512、2048、8192、32768 字节，超过最大类的请求按实际大小单独分配；默认总缓存硬上限 2 MiB 且缓存属于 Worker 而非连接——一万个空闲连接不会因此各自占用 8K。

线程：池与缓冲是线程归属对象，不在热路径加锁；同一时刻只能由所属 Worker 操作。跨线程长期保存数据时使用不绑定池的缓冲（Init 传空池）、复制到调用方内存，或让所属 Worker 执行最终释放。

所有权：四种追加形态按复制/借用/接管/自定义释放区分；Take/Ref 只有成功才转移所有权，失败时数据仍归调用方。xnetspan 只借用块内数据——任何追加、提交、消费、Pullup、Move 或 Clear 后必须重新获取。

地址列表与 DNS

数字地址语法不包含主机名解析；DNS 与不可变地址列表属于 XRT_FEATURE_NET_DNS。列表是解析结果的不可变共享快照：复制、校验、去重调用方地址后建立，Ref 增引用、Destroy 配对释放，端口统一替换用 WithPort。

网络缓冲

XRT_FEATURE_NET_BUFFER 依赖 XRT_FEATURE_NET，提供 TCP、UDP、TLS、HTTP 和 WebSocket 共用的可变尺寸缓冲底座。它保留旧版 xnetchain 的分块、Span 和引用数据优势，但删除“每个连接常驻固定 8K 缓冲”的模型。

缓冲只在实际收到或排队数据时持有块。默认池尺寸类为 512、2048、8192、32768 字节；超过最大类的请求按实际大小单独分配。默认总缓存硬上限为 2 MiB，并且缓存属于 worker，而不是连接：一万个空闲连接不会因此各自占用 8K。

Socket 原语

XRT_FEATURE_NET_SOCKET 只依赖 XRT_FEATURE_NET。这一层拥有平台 Socket 句柄，但不包含事件循环、线程、协程、隐藏收发缓冲、TCP 重连或 UDP 队列；TCP/UDP 客户端与服务器模型在它和事件端口之上组合。

错误与线程：收发族返回 xnetresult 三态（OK/AGAIN/CLOSED/ERROR），系统调用失败经 xrtGetError() 报告且保留平台错误码（XNET_ERROR_SOCKET_* 域码 + SystemCode）。Socket 无内部锁——同一 Socket 的收发应由单执行流执行；xnetsocket 是不透明指针，句柄值可为 0（视同空）。NATIVE 后缀在 Windows 上即 IOCP 兼容句柄。

网络事件端口

XRT_FEATURE_NET_PORT 依赖 Socket、单调截止时间和 Mutex，提供 backend-neutral 事件端口核心；具体后端使用独立裁剪宏。XRT_FEATURE_NET_PORT_SELECT 提供全平台 select fallback，XRT_FEATURE_NET_PORT_EPOLL 提供 Linux 原生 readiness，XRT_FEATURE_NET_PORT_KQUEUE 提供 Darwin/BSD 原生 readiness，XRT_FEATURE_NET_PORT_IOCP 提供 Windows 原生完成式 IO，XRT_FEATURE_NET_PORT_URING 提供 Linux 原生完成式 IO。readiness 与 completion 使用同一组事件、截止时间、错误和所有权口径，但不会被强迫伪装成相同执行模型。

端口由创建线程拥有：Watch、提交、取消、等待和销毁只能由拥有线程执行；查询函数以及 Post、Wake 可跨线程调用，调用方仍须保证端口对象存活。

嵌入式任务投递

xnetpost 是嵌入调用方结构的无分配任务节点：xrtNetPostInit 初始化，xrtNetPost 投递到指定 Worker 队列，出队前 xrtNetPostPending 为真。与 xrtNetEnginePost 相比它不分配节点，适合高频、固定生命周期的任务；同一 xnetpost 在出队并执行完成前不能再次投递。调用方必须通过网络对象引用保证 Worker 和 xnetpost 存活到回调返回。

网络 Engine

启用 XRT_FEATURE_NET_ENGINE 后，Engine 在事件端口之上提供固定 Worker、 有界跨线程命令、可取消 Timer 和统一 Completion 分发。它不实现 TCP、UDP、DNS 或应用协议，因此自定义传输与 XRT 高层传输可以建立在同一套运行时契约上。

标准 Engine 的平台闭包为 Windows IOCP + select、Linux epoll + select、Darwin/BSD kqueue + select、其他 POSIX 平台当前 select。Linux 的精细裁剪构建也允许 io_uring + select，不要求同时编入 epoll；此时调用方必须显式选择 XNET_PORT_URING，AUTO 仍只在已经编译的稳定默认后端中选择。显式 XNET_PORT_SELECT 可用于受限环境、诊断和后端差异回归；具体端口后端仍可脱离 Engine 独立裁剪。

名称解析（Resolver）

Resolver 提供独立于 Engine 的异步名称解析：自带工作线程池、成功/失败结果缓存与并发上限。同一规范化主机与地址族只执行一次底层查询，并发请求共享同一查询组。xrtNetResolveAsync 把查询包装为 Future。Op（xnetresolveop）是引用计数对象：回调在 Resolver Worker 上恰好执行一次，回调后仍可查询状态与结果，跨线程保留须先 xrtNetResolveOpRef。

网络接口与本机信息

接口族回答三类问题：名字与接口索引互查（InterfaceIndex/InterfaceName）、整机一致快照（Interfaces）、本机诊断偏好（LocalAddress/LocalHardware/HostName 及其文本形态）。本机诊断函数是确定性偏好查询，不代表公网出口、默认路由或服务监听策略。缓冲输出统一采用两段式：空缓冲查询所需大小，缓冲不足不写入并报告完整所需大小。

API 速览

xrtNetLookup 只解析主机，返回的所有端口均为零，适合作为缓存、连接竞速和自定义 Resolver 的底层结果。xrtNetResolve 在同一完整查询基础上写入调用方端口，适合直接建立端点；两者都返回系统顺序中的全部 IPv4/IPv6 地址并去重。

两类查询都不使用固定 64 项临时数组，也不把主机名复制到固定 256 字节字段。数字 IPv4、IPv6 和方括号 IPv6 不进入系统 DNS。Family 可以是 UNSPEC、IPV4 或 IPV6；单地址端点场景使用 xrtNetResolveOne，失败时输出保持不变。

地址列表不可变且引用计数安全。xrtNetAddrListCreate 校验、复制并按完整端点去重外部地址；xrtNetAddrListWithPort 保持地址顺序并统一端口，端口未变化时直接增加原列表引用，否则返回独立列表。Get 返回的地址只在对应列表引用存活期间有效；缓存或异步解析器可以通过 Ref 与调用方共享同一完整结果。

xrtNetReverse 使用 NI_NAMEREQD。没有 PTR 名称时明确失败，不把数字地址回退伪装成主机名。名称服务失败使用 XNET_ERROR_DNS_RESOLVE、XNET_ERROR_DNS_REVERSE 或 XNET_ERROR_DNS_RESULT，SystemCode 保存平台 getaddrinfo/getnameinfo 返回码。

完整示例位于 examples/network/dns/main.c。

分层

xrtNetLookup 是端口无关的同步 DNS 原语，结果端口全部为零。xrtNetResolve 是常见端点场景的同步便捷函数。Resolver 只执行 Lookup，因此缓存键是规范化主机名与地址族，端口不会造成重复 DNS 查询。TCP 建连时复制候选地址并写入目标端口即可。

配置

xrtNetResolverConfigInit 写入默认值：2 个 Worker、8192 个在途请求、4096 个唯一查询、256 个缓存项、60 秒成功 TTL、5 秒失败 TTL，以及 1024 字节主机名上限。

RequestLimit 限制已经受理但尚未完成回调的调用方操作。QueryLimit 限制排队和运行中的唯一底层查询；同一主机名和地址族的请求会共享查询，但仍分别占用请求限额。所有限额都是硬边界，达到边界时提交返回空指针并设置 XERR_AGAIN。

SuccessTTL 或 FailureTTL 为零时关闭对应缓存。CacheEntries 为零时完全关闭缓存。TTL 使用 xrtTimer 的单调秒刻度，不受系统时间回拨影响。

Lookup 可替换默认的 xrtNetLookup。自定义过程可能被多个 Worker 并发调用，必须线程安全；返回值必须是非空、端口为零、符合请求地址族的 xnetaddrlist，失败时必须设置结构化错误。LookupData 在 Resolver 销毁返回前必须保持有效。

查询合并与缓存

主机名按 DNS 的 ASCII 大小写规则规范化，尾随根点保留，因此 Example.COM 与 example.com 共享查询，example.com. 仍是独立的绝对名称。活动查询和缓存都使用哈希索引；缓存保存完整不可变地址列表或完整失败错误，不会退化为只缓存第一个地址。

规范化临时区按主机名长度选择栈内快速路径或受 HostLimit 约束的精确分配。唯一查询组和缓存项都把规范化主机名保存在对象尾部，不为键再建立独立堆节点；常见短主机名的缓存命中只创建调用方操作，不产生临时主机名分配。缓存内存仍由 CacheEntries、HostLimit 和两类 TTL 共同约束，不存在每个 Resolver 预留固定主机缓冲的成本。

缓存命中也不会在提交函数内直接调用用户回调。所有已受理操作的回调都在 Resolver Worker 上执行一次，避免缓存命中、取消和真实查询使用不同线程语义。回调应保持短小；需要切换到网络 Worker、任务池或 UI 线程时，应在回调中投递后续工作。

操作生命周期

操作状态依次为 PENDING、可选的 RUNNING，以及 RESOLVED、FAILED、CANCELLED 之一。终态不可改变。Result 成功时返回增加引用的完整列表；调用方使用 xrtNetAddrListDestroy 释放。Error 返回由操作引用保护的借用错误。

取消是协作式的。排队查询的最后一个订阅者取消后，底层查询不会执行；已经进入系统 getaddrinfo 的调用无法跨平台强制中断，但取消的调用方会独立进入 CANCELLED，底层查询可继续为其他订阅者或缓存生成结果。取消回调仍由 Resolver Worker 执行。

调用方可以在提交后立即释放自己的操作引用，Resolver 会持有到回调结束。回调参数是借用引用；需要在回调后继续保存时调用 xrtNetResolveOpRef。

销毁与统计

xrtNetResolverDestroy 停止接收新请求，排空所有已经受理的查询和回调，然后等待 Worker 及线程清理退出。它不能从 Resolver 自己的回调中调用；调用方必须把销毁与 Resolve、Clear、Stats 以及第二次销毁等 Resolver 所有者操作串行化。仅成功时消费创建者拥有权；失败保留原指针供重试。成功后的创建者指针不得再次传入任何 API。操作对象仍可继续保存和读取终态；内部 Resolver 外壳会由最后一个操作引用释放。自身回调可使用 xrtNetResolverTryDestroy 请求退休并取得 BUSY，由外部所有者稍后重试。

xrtNetResolverClear 清空成功与失败缓存，不影响活动查询和已经交付的共享结果。xrtNetResolverStats 返回提交、拒绝、命中、未命中、合并、底层查询、各终态以及当前队列深度的一致快照。

Future 便捷层

XRT_FEATURE_NET_RESOLVER_FUTURE 单独依赖 Resolver 与通用 Future：

成功 Future 的值是由 Future 持有的 xnetaddrlist，通过 xrtFutureValue 借用；Future 销毁时自动释放。查询失败直接保留 Resolver 操作中的结构化错误。xrtFutureCancel 会请求底层解析操作取消，最终状态由查询完成与取消之间的真实竞态决定，不会把取消请求本身伪装成已取消终态。

Future 可以使用通用同步等待、组合、延续和协程 Await API，不需要 DNS 模块重复建设另一套等待模型。

完整示例位于 examples/network/resolver/main.c 和 examples/network/resolver_future/main.c。