# xServer

**Repository Path**: xywhsoft/xserver

## Basic Information

- **Project Name**: xServer
- **Description**: 使用 C 语言构建跨平台的 HTTP、WebSocket、TCP、UDP 或自定义网络协议服务器程序，像脚本一样简单易用，支持多 HOST；支持 TLS 1.3。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-08-15
- **Last Updated**: 2026-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# xs3

**xs 是 xrt 的落地化部署工具。** 它把 xrt 的网络、协议、TLS、并发、数据能力装配成一个由配置文件驱动的可执行程序，并在运行时把 C 脚本编译进进程。xrt 才是主要的那个；xs 只负责部署，不提供框架、不提供治理、不教应用怎么做事。

当前状态：**生产就绪**——五大协议（http(+https)/ws(+wss)/tcp(+tcps)/udp/custom）、期望状态热重载（latest-wins/整代候选/原子发布/自动排空回收）、可选库门控（sqlite、xtp、xllm、xmail 系列、md4c、xacme，可组合、支持依赖自动展开与 all 全选）、dev_inc/dev_lib 应用 SDK 目录、静态层四旋钮、Windows/Linux 双平台回归与四层测试体系（冒烟/功能/压力/攻防演练 6h 704 轮 0 失败）。遗留：xadmin 试点。
- 协议：HTTP 每请求虚拟主机路由（脚本+静态根）、WS 握手期路由并固定 host/脚本、TCP/TCP+TLS、UDP、custom 手动装配
- 热重载：独立 controller、提交前 latest-wins ticket、reload-all 共享不可变配置 revision、候选 listener 先 bind 但不接入、host/server/all 均以完整 server generation 原子发布；旧代停止新接入后由终态引用自然排空，协议回调以连接记录和具体流的临时引用抵御同步 Close 重入，`ServiceUnit` 与最终析构交给专用 reaper，无泄漏、无宽限/超时强拆
- 可选库：`build.bat all`（全部可选库）/ `bash build.sh sqlite xtp xllm xsmtp ...`，参数可组合、可去重，邮件协议库自动携带 xmail 基础库；同一扩展清单控制原生编译、VFS 头文件和 TCC 符号导入
- 测试：`test.bat` / `bash test.sh`（正式构建、动态端口冒烟、功能边界、generation 生命周期、明文/TLS reload 矩阵与失败清理）、`tools/func_test.py`（配置失败清理、监听半启动回滚、虚拟主机/静态根、header/chunked 边界、静态发送中断、嵌套 TCC 并发、ticket 环碰撞）、`tools/lifecycle_reload_test.py`（旧 keep-alive、初始化发布屏障、拓扑 lease 与 Root 换代）、`tools/reload_matrix_test.py`（HTTP(S)/TCP(S)/UDP/WS(S) 同端点换代及跨服务 lease 回收）、`tools/pressure_test.py`、`tools/drill.py`；全部使用动态端口和临时配置，压力/演练进程会等待回收，重载破坏样本只操作临时脚本副本。

热换安全边界：绑定端点改变时候选可先 bind，但在拓扑事务提交前拒绝接入；同一端点由稳定 listener 槽位转交给新 generation。所有 Accept 与拓扑写锁线性化，TLS 还把 ClientHello 选中的 generation cookie 带到 Accept，reload-all 不会暴露半新半旧状态。旧连接继续持有旧代，最后一个终态引用归零后自动释放。协议类型、TLS 形态、backlog、recv_limit 等 listener 固化字段若在同端点改变会明确拒绝并要求重启。`xsReloadHost*` 是指定 host 的管理面入口，内部也重建并发布它所属的完整 server generation，不原地改指针；custom 因裸资源无统一终态 lease，不支持在线卸载。公开 server 查找返回显式 lease，必须 `xsServerRelease`。

TCC 宿主吸收了 xlang（demo6）的成熟经验并推进到**单文件交付**：`res/tcc`（VFS 构建目录）在构建期整体 LZMA 打包进二进制（SDK 头 + 精简 winapi/linux 头 + libtcc1.a + 导入库，7.3MB → 1.0MB），运行时从内置 VFS 读取——**xs 不附带任何磁盘 TCC 环境**。新增内置库 = 放入 `res/tcc` 重新构建。中文路径由 UTF-8 宽字符 IO 全链路保障。

## xs 做什么

1. 五个协议入口：`http / ws / tcp / udp / custom`（custom 全手动）
2. xrt 环境导入 TCC（脚本直接调用 xrt API）
3. 内置编译可选的扩展库（sqlite、libtcc 等，宏门控），一并导入 TCC
4. 协议初始化能力：除 custom 外，握手、解析、分帧由 xs + xrt 完成
5. 基于配置文件提供服务（`xs.json`，预设字段进结构体，其余全归应用）

## xs 不做什么

- 不做 bus、内置 XTP 服务驱动、管理面、调试面、任何治理；XTP2 编解码器作为可选独立库提供，连接由应用管理
- 不做 HTTP 便利封装、路由、session、权限——那是 xadmin 们的事
- 不做沙盒与权限限制——C 语言限制不住，一切对脚本开放
- 本阶段不使用 xhttp / xws（只基于已压实的 xrt http core 与 websocket core）

## 路线定位

xs3 是 C 语言版 xs 的完全重写，也是双轨（C 版 / xlang 版）中先行定性的技术路线：未来 xlang 版将参照 xs3 沉淀的三样东西——**透传契约（回调收 xrt 原生对象）、结构体 ABI + 全开放访问、generation 生命周期**——决定自己的形态。

## 依赖

- [xrt](../xrt)：网络 / 协议 / TLS / 并发 / value / JSON / 模板 / 压缩（锁定版本随发）
- TCC 0.9.28rc：运行时 C 编译器（兼容性已验证，见设计文档附录）

## 构建与可选扩展

Windows（需要 GCC、windres、Python 3.10+）：

```bat
build.bat
build.bat sqlite
build.bat xtp
build.bat sqlite xtp
build.bat sqlite xtp xllm
build.bat all
```

Linux 使用相同参数，例如 `bash build.sh sqlite xtp xllm xsmtp`；需要 GCC 与 Python 3.10+。不传参数只包含固定的 xrt/libtcc 等基础能力。参数顺序无关、重复自动去重、名称不区分大小写，未知库名报错退出，不会悄悄生成错误变体。

`build.bat --list-extensions` 查看可选库；`build.bat sqlite xtp --dry-run` 查看实际构建命令。产物默认仍为 `release/xs.exe` 或 `release/xs`，可用 `--output` 指定其他位置。构建中间文件按平台和库组合隔离到 `.build/`，不会重写 `src/script/tcc_builtin_resources.c` 旧快照。

启用后，脚本直接 `#include <sqlite3.h>` / `#include <xtp2.h>` / `#include <xllm.h>`，无需再定义 `XTP2_IMPLEMENTATION`。脚本可用 `XS_USE_SQLITE`、`XS_USE_XTP2`、`XS_USE_XLLM` 判断当前宿主能力，嵌套 `xsCreateTCC()` 环境也一致。

后续库在 [扩展清单](/D:/GIT/xserver/tools/extensions.json) 登记源码、头文件、宏和符号清单，不需要修改两个平台的构建脚本或 TCC 宿主分支。参见[可选扩展库说明](/D:/GIT/xserver/docs/可选扩展库.md)。

## 单文件发布（站点 VFS）

把 `xs.json` 与整个站点（wwwroot、C 源码、TLS 证书）打成一个 LZMA 归档**追加**到 xs 末尾，得到一个可直接部署的单文件 exe：

```bat
release\\xs.exe pack <站点目录> -o app.exe    # 站点目录须含 xs.json；基底 = 当前 xs
app.exe                                      # 无参启动：自动从包内读配置、出文件
```

- 压缩：逐条 LZMA（无收益自动 STORE）；`xs pack --list app.exe` 查看条目清单
- **磁盘优先**：放同名文件到 exe 旁即覆盖包内版本（热修 CSS/证书免重打包），删除即恢复包内
- `xs pack --extract app.exe -d out/` 解包取证；`xs pack --strip` 还原未打包二进制
- `xs --no-vfs` 忽略应用包强制目录模式（调试用）
- 归档探测零成本（读自身末尾 24B）；索引启动装载后不可变、内容首次访问惰性解压常驻缓存

格式与设计细节见 [docs/站点VFS设计.md](docs/站点VFS设计.md)；端到端测试 `python tools/test_site_vfs.py`。

## 开源许可

本项目自有代码以 MIT 授权（见 [LICENSE](/D:/GIT/xserver/LICENSE)）。仓库捆绑的第三方组件各自保留原许可：

| 组件 | 位置 | 许可 |
| --- | --- | --- |
| Tiny C Compiler（mob 快照 + 本地 VFS/UTF-8 IO 修改） | `tcc/` | LGPL-2.1-or-later，全文见 `tcc/COPYING`，修改清单见 `tcc/README.md` |
| LZMA SDK（Igor Pavlov） | `tcc/LzmaDec.c` 等 | 公有领域 |
| SQLite | `lib/sqlite3.c` | 公有领域 |
| MD4C（Martin Mitáš） | `lib/md4c/` | MIT |

TCC 以静态链接编入单一二进制。按 LGPL-2.1 要求，发布二进制时须让接收方能够用修改版 TCC 重新链接出完整程序——本仓库公开全部源码与构建脚本（`build.bat` / `build.sh`），即满足该要求；修改过的 TCC 部分保持 LGPL 并随源码提供。项目自有代码与用户脚本的许可均不受 TCC 许可影响。