单文件交付
xs pack 把站点、源码、证书打进 exe 即完成部署——磁盘文件永远优先(热修免重打包)。TCC 编译器与 SDK 头已内嵌 VFS,目标机零安装。
协议、密码学、并发、调试全部自研并内建 —— 不是绑定,是装进同一个文件。
xs pack 把站点、源码、证书打进 exe 即完成部署——磁盘文件永远优先(热修免重打包)。TCC 编译器与 SDK 头已内嵌 VFS,目标机零安装。
devfile 由内嵌 TCC 在进程内编译为原生机器码,经符号表直调 3057 个宿主 API —— 零解释器、零 FFI 开销。
改 C 源码即时生效:全量候选先编译、成功才换代,失败旧代原样服务;旧代引用归零后由 GC 线程安全回收。
不依赖 OpenSSL:X25519 / P-256 / P-384、AES-GCM、ChaCha20-Poly1305、会话恢复、X.509 链验证与 CRL,服务端/客户端双端。
http / https、ws / wss、tcp / tcps、udp 四类服务统一生命周期;vhost、SNI 证书选择、静态层、连接接管内建。
IOCP / epoll / kqueue / io_uring / select 五后端事件循环,工作窃取线程池、协程、channel、future 一应俱全。
canary / UAF 隔离 / 故障注入 / 环形事件日志 / TEXT 与 JSON 泄漏报告 —— 生产进程即可开启,无需换构建。
十一个可选库(sqlite / 邮件全家 / 大模型 / Markdown / 证书签发…共 700 符号)按需编入,all 一键全选;新增扩展只需一个 json 条目 + 一张 import 表,宿主零代码改动。
webview 扩展 + class: "app" 节点 = 本地 HTTP + WebView2 窗口;配合 xs pack 单文件发布,产物是双击即用的桌面 exe。无环境自动降级 headless。
内置 ACME 守护:到期前 30 天自动 DNS-01 续签 + 热替换(连接不断);directories[] 多 CA 回退链——Let's Encrypt 挂了自动切 litessl,恢复后自动回归。
信任模型说明:脚本为可信的原生代码(无沙箱),面向运维可控的部署场景 —— 能力全开放,边界由你定义。
热重载是期望状态协调器:不可变快照 → 全量预编译 → 原子发布 → 双代并行 → 引用归零回收。
编译失败时提交被直接拒绝 —— 回滚是语义保证,不是补救措施。
ServiceSwap → xsSwapTake 完成运行状态交接。
以下示例取自仓库真实代码。XServer 不包装对象模型 —— 你直接操作 xrt 原生结构,编译器与类型系统就是你的框架。
/* route.h —— URI × 方法 槽位式注册(真实源码节选) */
static void RouteHTTP_Init(void)
{
G_StaticRouteTableHTTP = xrtMapCreate(sizeof(RouteInfoHTTP));
/* 静态路由:精确 URI */
AddStaticRouteHTTP("/api/v1/items", XHTTP_METHOD_GET, Handle_API_List);
AddStaticRouteHTTP("/api/v1/items", XHTTP_METHOD_POST, Handle_API_Add);
/* 动态路由:{id} 段捕获,方法掩码可自由组合 */
AddDynamicRouteHTTP("/api/v1/items/{id}",
XHTTP_METHOD_GET, Handle_API_Item);
AddDynamicRouteHTTP("/api/v1/items/{id}",
XHTTP_METHOD_PUT | XHTTP_METHOD_PATCH, Handle_API_Item_Update);
AddDynamicRouteHTTP("/api/v1/items/{id}",
XHTTP_METHOD_DELETE, Handle_API_Item_Delete);
/* 注册完成后一次性编译成不可变 pattern,匹配耗时与路由数无关 */
(void)RouteHTTP_Compile();
}
/* route_http/basic.h —— xvalue 构造 JSON(真实源码节选) */
static void Handle_JSON(XS_HttpReq* pReq,
const RouteParamHTTP* arrParam, uint32 iParamCount)
{
const XS_HostInfo* pHost = pReq->host;
xvalue* pObject = xrtValueObject();
(void)arrParam; (void)iParamCount;
xrtValueObjectSetNew(pObject, XRT_STR_LITERAL("server"),
xrtValueString(XRT_STR_LITERAL("xs3 demo")));
xrtValueObjectSetNew(pObject, XRT_STR_LITERAL("ok"),
xrtValueBool(true));
xrtValueObjectSetNew(pObject, XRT_STR_LITERAL("host"),
xrtValueString(xrtStrView((pHost->Name ? pHost->Name : "?"))));
(void)ReplyJSON(pReq, 200, pObject);
xrtValueRelease(pObject);
}
/* ws / wss 契约回调:xs 完成握手与分帧,你只写业务 */
static void WsOpen(XS_HostInfo* pHost, xwsstream* pWs)
{
xrtWsStreamText(pWs, xrtStrView("connected"));
}
static void WsText(XS_HostInfo* pHost, xwsstream* pWs, xstrview tText)
{
/* 掩码、分片重组、控制帧、消息上限全部由 xrt 层处理 */
(void)xrtWsStreamText(pWs, tText); /* echo */
}
static void WsBinary(XS_HostInfo* pHost, xwsstream* pWs, xbytesview tData)
{
xvalue* pMsg = xrtValueObject();
xrtValueObjectSetNew(pMsg, XRT_STR_LITERAL("size"),
xrtValueInt64((int64)tData.Size));
(void)xrtWsStreamBinary(pWs, tData);
xrtValueRelease(pMsg);
}
/* 热重载状态交接:旧代导出快照,新代取回续跑(契约 API) */
static bool ServiceSwap(XS_HostInfo* pHost, xvalue** ppShared)
{
xvalue* pState = xrtValueObject();
xrtValueObjectSetNew(pState, XRT_STR_LITERAL("counter"),
xrtValueInt64(G_iCounter));
*ppShared = pState; /* 无破坏快照:导出后旧代仍可服务 */
return true;
}
static void ServiceInit(XS_HostInfo* pHost)
{
xvalue* pState = xsSwapTake(pHost); /* 仅新代 Init 内有效 */
if ( pState != NULL ) {
G_iCounter = xrtValueInt64(
xrtValueObjectGet(pState, "counter"));
xrtValueRelease(pState);
}
}
/* 触发重载:期望状态协调,返回稳定 ID 可查询终态 */
XS_ReloadId iId = xsReloadHostSubmit(pHost);
routebench 实测:单连接 keep-alive 顺序请求,每配置 3 轮 × 10,000 次取均值,同机对比五种服务栈。
pattern 批量编译 + 与路由数无关的匹配,让万级路由下时延仅 +41%;对照栈中 FastAPI 退化 +935%、PHP +492%。
没有 IPC、没有序列化边界 —— 脚本经符号表按地址直调宿主,函数调用就是函数调用。
链接成功才原子替换产物 —— 构建失败永远保留上一个可用的 xs.exe。
xs.exe 5.2 MB 唯一的二进制 xs.json 服务 · 端口 · TLS · vhost main.c 应用入口(ServiceInit) route.h 路由注册清单 modules/ 复用模块(http/db/template…) route_http/ 请求处理器 page/ 受控页面(wwwroot 之外) template/ xrtTemplate 模板 db/ SQLite 数据文件 wwwroot/ 静态资源根
一条命令按需裁剪变体,双平台(Windows / Linux):
build.bat
build.bat all
把 xs.exe 和源码目录拷到目标机 —— 无运行时安装、无 DLL、无头文件依赖,编译器已在 exe 里。
把 xs.json、wwwroot、C 源码、TLS 证书打进一个 LZMA 归档追加到 xs 末尾——无参启动自动从包内读配置、出文件。磁盘同名文件永远优先,放一个文件到 exe 旁即热修,删掉即恢复包内版本。
# 1. 打包(站点目录须含 xs.json,逐条 LZMA)
xs.exe pack site/ -o app.exe
# 2. 部署:拷走这一个文件就完成了
app.exe
# 3. 热修:放同名文件到 exe 旁即覆盖包内
echo ... > app.exe/wwwroot/index.html
在 xs.json 里声明 class: "app" 服务节点——本地 HTTP 服务与 WebView2 桌面窗口同进程:启动显示加载窗,服务就绪自动打开界面,关窗即优雅停机。
扩展 = 一个 json 条目 + 一张 import 符号表 + 一个头文件。静态编入宿主,符号导出给脚本,连嵌套 TCC 编译的插件也能用。
完整 SQLite 引擎静态编入,VFS 暴露头文件。prepared statement、参数绑定、事务 —— demo 的 REST CRUD 即基于它。
sqlite3_open_v2("db/main.db", &db, flags, NULL);
有序字节流上的二进制应用层协议:REQUEST / RESPONSE / PUSH / EVENT 四型消息,完整 limits 体系,libFuzzer 验证。
xtp2_feed(&st, buf, len); /* 增量解析,零分配 */
大模型调用核心库与会话治理层:请求与多模态构造、Chat Completions / Responses / Anthropic 三方言、SSE 解码、重试取消;xllm-session 补上下文预算、压缩与 journal。
xllmRequestAddTextMessage(&req, XLLM_ROLE_USER, "hi");
xmail MIME 基础层(编解码/地址/消息树/构造/传输)加三个协议客户端;选任一协议自动携带 xmail,共享传输与 SASL,TLS 由宿主 xrt 提供。
xrtSmtpClientMail(&st, "from@x", 1, "to@y");
符合 CommonMark 的 Markdown 解析与 HTML 渲染:md_parse 回调式事件流 + md_html 一步渲染,表格/删除线/任务列表经 flag 开启。
md_html(md, len, sink, ctx, 0, 0);
ACME 证书客户端:账户/订单/dns-01 挑战/证书获取一站式(xacmeClientIssue),内建阿里云 DNS provider,磁盘存储与续签检查齐备。
s = xacmeClientIssueStored(&c, d, 1, &dns, st, 30, &b);
QR 码生成器(Nayuki,MIT):编码、模块矩阵读取一步到位;PNG 输出层(1-bit 灰度,IDAT 走 xrt zlib 流),2FA/收款码/API 端点/邮件内嵌即拿即用。
png = qrcodegen_png(qr, 4, 4, &size);
JWT (RFC 7519) 签发与验证:HS256/384/512、RS 三规格(PKCS#8/PKCS#1 双封装)、ES256(DER,与 OpenSSL 互认)、JWKS 选钥、公钥缓存;错误码一行可读,aud 支持数组。
claims = xjwtVerify(token, pem, &check);
OAuth 2.0 (RFC 6749) 客户端:五家 provider 预设、PKCE、token 刷新、nonce/state 一次性焚毁;传输回调注入(附 xrt TLS 便捷实现)。与 xjwt 数据耦合零依赖,脚本层 8 行胶水组成 OIDC 登录。
tok = xoauth2CompleteLogin(&oauth, code, state);
AI 应用栈顶石(xllm 之上):工具注册与执行、工作区策略、子 Agent 类型、通知流与压缩调度。agent-demo 实战——审批闸门 + 轨迹 + diff 面板全流程浏览器验收。
xworkAgentRegisterBuiltinTools(agent);
WebView2 桌面窗口 + class: "app" 服务节点:启动加载窗 → 服务就绪开界面 → 关窗优雅停机。与单文件发布组合 = 双击即用的单 exe 桌面应用;无环境自动 headless。
if (xsWebviewAvailable()) openDesktop();
指定源文件、VFS 头与 import 表即可 —— 注册中心带路径逃逸检查、宏去重与命名冲突检测,并有单测与运行时探针双重验证。
{ "name": "mylib", "macro": "XS_USE_MYLIB" }