net_interface

分层

XRT_FEATURE_NET_INTERFACE 只依赖网络地址基础层，公开头文件为 <xrt/net_interface.h>。它负责接口名称与索引互转、接口快照、MTU、硬件地址、 接口标志、单播地址和前缀长度，不引入 Socket、Engine、线程、DNS 或容器。

启用该模块后，xrtNetAddrParse 和 xrtNetAddrParseEndpoint 同时接受 IPv6 数字 Scope 与接口名称 Scope，例如 fe80::1%eth0 和 [fe80::1%eth0]:8080。解析结果仍只保存稳定的数字接口索引， xrtNetAddrText 因此保持无系统查询的规范数字输出。

名称与索引

Windows 的规范名称来自系统适配器名称，显示名称是 UTF-8 接口别名；POSIX 两者 都是 if_name。xrtNetInterfaceIndex 同时接受规范名称和显示名称。 Windows 分别保存 IPv4 与 IPv6 索引；POSIX 两者通常相同。UNSPEC 查询优先 IPv6 索引，再使用 IPv4 索引。

索引零不是有效结果。找不到名称或索引时分别报告 XNET_ERROR_INTERFACE_INDEX 与 XNET_ERROR_INTERFACE_NAME。 xrtNetInterfaceName 与其他文本 API 一样支持空输出测量；缓冲不足时安全截断、 补零、返回完整所需长度并报告 XNET_ERROR_BUFFER。

接口快照

快照使用一次 XRT 分配保存接口数组、地址数组、名称和硬件地址。所有视图都借用 快照，释放后立即失效；Free 可对空列表重复调用。失败不会修改输出。 接口和地址顺序由操作系统决定，调用方不得把顺序当作身份。

PrefixLength 为 IPv4 的 0..32 或 IPv6 的 0..128；平台不能可靠提供连续 掩码时使用 XNET_INTERFACE_PREFIX_UNKNOWN。地址端口恒为零。链路本地 IPv6 地址缺少原生 Scope 时，快照使用该接口的 IPv6 索引补齐。

标志只暴露跨平台稳定交集：UP、RUNNING、LOOPBACK、BROADCAST、 POINT_TO_POINT 和 MULTICAST。某个平台没有可靠来源的标志保持未设置， 不能把未设置解释为能力一定不存在。

本机信息便捷层

xrtNetLocalAddress 从接口快照中选择适合启动日志、节点报告和诊断页展示的 单播地址。它依次偏好 UP、RUNNING、非回环、非链路本地接口；条件相同时 UNSPEC 优先 IPv6。该结果不是公网出口地址，也不代表系统默认路由，不能直接 替代服务监听、客户端源地址或多网卡路由策略。需要精确选择时应遍历 xrtNetInterfaces。

xrtNetLocalHardware 返回原始硬件地址，不把地址长度写死为 6 字节。空输出和零 容量只查询所需大小；缓冲不足时不写入，返回完整所需大小并报告 XNET_ERROR_BUFFER。没有带有效硬件地址的接口时报告 XNET_ERROR_INTERFACE_HARDWARE。

xrtNetHostName 使用动态平台缓冲读取完整主机名。它支持空输出测量；缓冲不足时 安全截断、补零并返回完整所需长度。主机名只是本机标签，不保证能够通过 DNS 解析，也不等于 HTTP Host、TLS SNI 或服务绑定名。

文本便捷函数

启用 XRT_FEATURE_NET_INTERFACE_TEXT 后可以直接使用：

String 函数返回由 xrtFree 释放的字符串。硬件地址文本使用大写、无分隔符的 紧凑 HEX；需要冒号、短横线或其他展示格式时应读取原始字节后自行格式化。 文本层依赖 NET_INTERFACE 与 CODEC_HEX，基础接口快照和二进制便捷查询不会 因此引入 HEX 编解码。

裁剪与依赖

只选择 XRT_MODULE_NET_INTERFACE 时不会带入 TCP、UDP、异步运行时或 HTTP。 XRT_MODULE_NET_INTERFACE_TEXT 是独立裁剪的小型易用层。 模块测试只枚举本机系统接口并解析本机接口名称，不发送报文，也不访问外部地址。 底层示例位于 examples/network/interface/main.c，便捷层示例位于 examples/network/local_info/main.c。

设计契约

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 及其文本形态）。本机诊断函数是确定性偏好查询，不代表公网出口、默认路由或服务监听策略。缓冲输出统一采用两段式：空缓冲查询所需大小，缓冲不足不写入并报告完整所需大小。