lib-winsock：Web 全栈

> 解读对象：Fun 标准库中体量最大的 `lib-winsock.fun`(660 行)，以及它的两位搭档——`lib-ajax`(361 行，HTTP 客户端) 与 `lib-jsonrpc`(97 行，RPC 服务端)。三件套合计 1100 行出头，却覆盖了 TCP/UDP/HTTP 服务端/WebSocket/代理隧道/异步 AJAX/JSON-RPC，构成这门 Windows 脚本语言的全部 Web 能力。
>
> **版本基线**：正文以 2026-08-31 开源快照的单体 `lib-winsock.fun`(660 行) 为叙事基线；2026-09-13 上游提交 688b12d 已将其重构为 base(542 行)/win(319 行)/lnx(629 行) 三件套并移植到 Linux。正文描述的 Windows 消息泵机制依然成立，新增内容见文末第七节增补。

## 一、世界观：一切事件皆是窗口消息

理解 lib-winsock 的钥匙只有一个 API：`WSAAsyncSelect(socket, hwnd, message, events)`。它把 socket 的可读、可写、可连接、对端关闭等事件，统统转换成投递给某个窗口的消息。于是这个库没有 select 循环、没有 epoll、没有事件线程——**网络事件和按钮点击、定时器共用同一个消息泵**。这与 lib-async(用 `PostMessage` 派发异步回调)、lib-ui(窗体消息)、lib-jsonrpc(窗体即服务器) 是同一个宇宙观：Windows 消息循环就是 Fun 的事件循环。

`bindMessage` 把这一招封装成型：监听者用位或拼出关心的事件集(`FD_Read bit or FD_Accept bit or FD_Close`，客户端再补上 `FD_CONNECT`)，一行注册，之后所有网络活动都从同一个 `OnMessage(hwnd, msg, wParam, lParam)` 入口进来，`wParam` 是 socket 句柄，`lParam` 是事件类型，一个 `case` 分发完毕。

## 二、指针体操：用字符串操作 C 结构体

FFI 层没有结构体概念，库的对策是把 C 结构当字符串切。`hostent2ip`(解析 DNS 返回的 hostent) 是代表作：三次 `move` 在真实内存与字符串缓冲之间搬运数据，手工走完 `hostent → h_addr_list → in_addr` 的三级指针链；`Addr16` 则逆向拼装 `sockaddr_in`，顺手把端口做了字节序交换(`port >> 8 + port mod 256 << 8`，htons 的手写内联版)。这类代码密集分布在辅助函数区，恰好解释了系列前篇 lib-cstruct 存在的必要性——**当字符串就是内存，pack/unpack 就是刚需**。

## 三、HTTP 服务端：一张客户端状态表

`Server.HTTP` 类的骨架是字典 + 状态机。accept 进来的连接以 `'@' & sock` 为键存进 `clients` 表；每次 `FD_Read` 触发 `receive`，数据追加到该连接的 `text` 缓冲，然后两步分帧：先正则抓 `Content-Length` 定长，再判断缓冲里 `\r\n\r\n` 之后的 body 是否攒够——攒够才进 `onReceive`，顺带一个 `loop` 处理粘包(一次 recv 可能带回多个请求)。

几个工程细节看得出实战打磨：自定义请求头 `FX-Queue: true` 可让请求进入串行队列逐个处理；`check()` 维护了一张错误码表，10053/10054 等死亡连接就地清理；连接表超过一万条而活跃数骤降时，触发一次重建压缩。性能上它自然是 nginx 的玩具级对照，但 Keep-Alive、404/ContentType/状态码，一样不少——**一个能跑在 300KB 解释器里的 HTTP 1.1 子集**。

## 四、WebSocket：握手与帧的全套手搓

服务端对 `Upgrade: websocket` 请求的处理流程完整复刻了 RFC 6455: 从请求头抠出 `Sec-WebSocket-Key`，拼上魔法 GUID `258EAFA5-E914-47DA-95CA-C5AB0DC85B11`，SHA1 摘要转 base64 作为 `Sec-WebSocket-Accept` 回给客户端(好在 Fun 的字符串内建了 `.sha1()`)；若协商了 `permessage-deflate`，后续帧还会先 `inflate` 解压。帧解析器逐字段手搓：首字节取操作码，次字节与 `0x80` 判掩码位、与 `0x7f` 取长度，126/127 分支走 16 位/64 位扩展长度，掩码四字节循环异或解密——连 `wsEncode` 都做了两版：`fromByte` 快路径失败时回退到正则逐字符替换的 `wsEncodeX`。UDP 这边也没偏心：支持广播与 IGMP 组播(`ADD_MEMBERSHIP`)，`recvfrom` 顺手解出发送方 IP。

## 五、客户端与消费方：ajax 与 jsonrpc

`lib-ajax` 是 Web 客户端一侧：用 COM 创建 `Msxml2.ServerXMLHTTP`，`get()` 方法二十多个参数覆盖 UA/Referer/Cookie/代理(含 `setProxyCredentials`)、超时与自定义头；请求体超过 4KB 自动 `deflate` 压缩，响应按 codepage 或 ADO Stream 转码。加上 `onreadystatechange` 用 `@toEvent` 挂回 Fun 闭包，它就是 2005 年前端 Ajax 概念的服务器版转世。

最优雅的消费者是 `lib-jsonrpc`：`class JsonRpc = Form()`——**窗体类本身继承出 RPC 服务器**，98 端口挂 HTTP，收到请求后按方法名查 `Rpc_XXX` 成员调用。一个带窗口、能被浏览器远程调用的桌面服务，注册成本是给类加一个 `Rpc_` 前缀方法。

## 六、结语：限制即风格

lib-winsock 的所有"缺点"——单线程、Windows 独占、8KB 缓冲、无 TLS——都源自同一个设计决定：不引入任何超出解释器的东西，把一切交给消息泵。（编者按 2026-10-17：其中「Windows 独占」已过时。2026-09-13 的 688b12d 已拆出 `lib-winsock-base.fun` 与 `lib-winsock-lnx.fun`，Linux 用 libc socket 加 `poll(2)`；此后 `http-server.fun` 也可在 Linux/macOS 上直接跑，详见文末第七节。）作为生产 Web 服务器它毫无竞争力，但作为教学样本它近乎完美：从 `socket/bind/listen/accept` 到 HTTP 分帧再到 RFC 6455 逐字节握手，每一层都摊开在几百行可读脚本里，没有一个黑盒。如果你的第一门"网络编程课" 用的是 libwin32 + 脚本语言，而不是 C 语言 + 神秘的 errno，大概会少走很多弯路——这或许就是作者把 22 个 ws2_32 签名串全部写在一屏之内的心情。

## 七、增补：一次跨平台重构，把协议留在了原地(2026-09-13)

上游提交 688b12d 把 660 行单体拆成了三层：`lib-winsock-base.fun`(542 行) 收编全部平台无关的协议与簿记——正文三、四两节里的 HTTP 解析与拼装、WebSocket 握手与掩码帧、FX-Queue、连接状态表，统统搬进一个 `HttpBase` 基类；`lib-winsock.fun` 瘦身到 319 行，只剩 WSAAsyncSelect 与消息泵的布线，外加钩子实现；新文件 `lib-winsock-lnx.fun`(629 行) 则是完整的 Linux 后端。基类与后端之间只隔一张极窄的钩子表：`SendOnce / Read / CloseSock / ShutdownSock / Delay / Fatal`——六个函数，就是"把 socket 系统调用挡在门外" 的全部接口面。

Linux 后端没有照抄 Windows 的事件模型，而是换了一颗泵：BSD sockets 加一个朴素的 `poll(2)` 循环，回调在循环里内联执行，**全程零线程**。注释里交代了原因——Fun 的每函数变量栈不可跨线程重入，所以宁可阻塞调用线程，也不引入并发。有趣的是，`sockaddr_in` 在 x86_64 Linux 上恰好与 WinSock 的 16 字节布局逐字节一致(端口/地址同为网络序)，于是第二节的 `Addr16 / Addr2IP` 指针体操原样复用；DNS 换 `getaddrinfo`，错误码换 `__errno_location + strerror`，libc 的 FFI 签名一行一个：`'libc.so.6'.getapi('poll', 'iii:i')`。

base 层还沉淀出一个 `Scheduler`，构成无线程的"简版异步"：`Post` 把闭包推进任务队列，`After / Every` 挂一次性/重复定时器；`Tick()` 在遍历前先换上新数组再扫旧数组——回调里再注册的定时器落进新数组，教科书式的快照手法；`NextIn()` 返回下一个定时器的剩余毫秒数，直接喂给 poll 的超时参数，**网络事件与定时任务由同一个循环驱动**。Windows 侧暂未接入它(那边异步仍走 WSAAsyncSelect/SetTimer)，Linux 侧已可用。

两个语言细节值得一提。其一，Fun 不允许嵌套类继承顶层类，所以 `HttpBase` 必须放顶层，各后端用 `class HttpServer = HttpBase()` 定义后再以 `Server.HTTP = HttpServer` 赋值"重暴露" 回 Server 命名空间——继承靠顶层，封装靠赋值。其二，调用可能被覆写的方法要写成 `this.m()`，这是 Fun 的"虚调用" 约定，漏掉 `this.` 就绕过了多态。

回到第一节的断言——"Windows 消息循环就是 Fun 的事件循环"。重构之后，这句话在 Linux 侧的对应版本是"poll 循环就是事件循环"，而"一切事件皆有泵" 的世界观原封未动，变的只是泵的型号。对读者而言这反而是加成：同一份 HTTP/WS 手搓协议代码，配两种事件递送模型(消息泵 vs poll 循环) 可供对照，教材价值翻了倍。