- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
11 KiB
Executable File
网络扩展波次:ext/web 鉴权 · WebSocket · 标准库网络原语
| 状态 | Draft(本波次锁定设计) |
| 日期 | 2026-08-24 |
| 相关 | ext-web.md · ext-abi.md · stdlib-modules.md · ext-cli.md |
| 目标 | 补齐 ext/web 登录鉴权(session/cookie)、WebSocket 端点;为网络扩展所需的基础设施解析原语适当补强 lib/net(标准库)。 |
0. 一句话
领域能力(鉴权、WebSocket 服务器)全部走 ABI 插件 plugins/web;纯解析基础设施(cookie / multipart 解析、WS 客户端)按需进入标准库 lib/net,因为标准库需要支撑扩展库开发。
1. 边界判定:什么进标准库 lib/net,什么进扩展
1.1 跨语言调研结论
| 语言 | 标准库 | 扩展/生态 | 边界准则 |
|---|---|---|---|
| Python | urllib(URL/基础 HTTP)、http.cookies(cookie 解析器在标准库) |
requests/httpx(session/连接池/便利层) |
标准库 = 基础设施原语(解析器);便利层 = 第三方 |
| Node.js | http/https/http2(低层流式,不解析 body) |
express、ws、formidable | 足够 fancy 就不进核心;核心只放几乎人人要用的低层原语;先 userland 验证再拉进 core |
| Go | net/http(服务器+客户端都在标准库)、net/http/cookiejar(RFC 6265 cookie jar 在标准库) |
golang.org/x/net(publicsuffix 等演进性) |
HTTP 是「与 stdin 同级」的核心能力;cookie 解析/管理进标准库;持久化等演进性能力在外 |
| Rust | 极小 std(无 HTTP) | http(词汇)→ hyper(传输)→ reqwest(便利) |
分层;HTTP 因生态多样不进 std |
共识:
- cookie 解析/管理(RFC 6265)在 Python/Go 都是标准库(
http.cookies、net/http/cookiejar)。 - multipart/form-data 解析在 Go 是标准库(
net/http),在 Python 是第三方multipart。 - WebSocket 几乎总在扩展/第三方(Node
ws、Pythonwebsockets、Gogorilla/websocket),很少进语言标准库。 - session 是领域级便利,几乎所有语言都在框架层(express-session、Django session),不在语言标准库。
1.2 Marqdo 判定(锁定)
| 能力 | 类型 | 归属 | 理由 |
|---|---|---|---|
cookie.parse / cookie.parse_response |
基础设施解析 | lib/net(标准库) |
对齐 Go/Python 标准库;ext/web 鉴权依赖 |
multipart.parse |
基础设施解析 | lib/net(标准库) |
对齐 Go 标准库;ext/web 文件上传依赖 |
ws.connect(客户端) |
基础连接 | plugins/web(ABI)+ ext/web |
WS 栈(tokio-tungstenite)已在 web 插件依赖链;核心 Cargo.toml 锁定 rustc 1.81 不宜再引入 WS 栈;符合「尽量只 ABI」 |
web.session_*(session 管理) |
领域 | plugins/web(ABI)+ ext/web |
session 是框架层便利,不进标准库 |
/admin 登录鉴权 |
领域 | plugins/web(ABI)+ ext/web |
网站领域能力 |
web_ws(服务器端点) |
领域 | plugins/web(ABI)+ ext/web |
WebSocket 服务器是网站能力 |
实现约束(用户要求):
- 标准库新增的解析原语(cookie/multipart)是纯函数、无网络 I/O,作为 L0.5 宿主原语进
src/host/(与url_encode同模式),由lib/net薄包装——这符合「标准库需要支持扩展库开发」。 - 涉及网络 I/O 的 WS 能力(客户端 + 服务器端点)一律进
plugins/web(ABI v2),由ext/web/ext/web/网页.mq.md包装。核心运行时(rustc 1.81 锁定)不再新增 WS 栈依赖。 - 网站领域能力(session、鉴权中间件)一律进
plugins/web(ABI v2),由ext/web包装。 - 禁止:为这些能力修改核心语法;禁止在
src/host/塞领域逻辑。
2. 标准库 lib/net 新增(基础设施原语)
2.1 cookie.parse / 解析Cookie
- 形参:
text(Cookie:请求头或Set-Cookie:响应头) - 结果:
[{name, value, path, domain, expires, max_age, secure, http_only, same_site}] - 行为:RFC 6265 解析;
Set-Cookie多 cookie 分条;无属性则字段为空。
英文(lib/net.mq.md):
## cookie_parse
+ `text`
**> host_cookie_parse text=`text`**
中文(lib/网络.mq.md):
## 解析Cookie
+ `内容`
**> host_cookie_parse text=`内容`**
2.2 multipart.parse / 解析多部分
- 形参:
body(文本)、boundary - 结果:
[{name, filename, content_type, value}](value为字段值;文件字段用filename+content_type+value(base64 或文本)) - 行为:解析
multipart/form-data正文;字段名 → value;文件字段带 filename。
英文:
## multipart_parse
+ `body`
+ `boundary`
**> host_multipart_parse body=`body` boundary=`boundary`**
中文:
## 解析多部分
+ `正文`
+ `边界`
**> host_multipart_parse body=`正文` boundary=`边界`**
2.3 WebSocket 客户端 — 见 §3.4(plugins/web ABI)
WS 客户端为领域能力,放 plugins/web(ABI)而非标准库,理由见 §1.2。lib/net 不新增 WS 客户端包装,避免标准库依赖 ext 插件。
3. plugins/web(ABI v2)新增:领域能力
3.1 Session 存储(web_session_*)
插件进程内 static 内存存储(HashMap<session_id, HashMap<String,Value>>),与 web_listen 同生命周期。
| ABI 名 | 形参 | 结果 |
|---|---|---|
web_session_new |
可选 ttl_sec |
{id}(新 session id) |
web_session_set |
id, key, value |
{ok:true} |
web_session_get |
id, key |
值或 {ok:false} |
web_session_del |
id, key |
{ok:true} |
web_session_destroy |
id |
{ok:true} |
3.2 /admin 登录鉴权(web_auth_*)
- 作者面:
web.auth类(网页.鉴权),形参admin_users(|用户名|密码|表)、可选session_ttl。 listen时若配置了 auth:/admin*未登录 → 跳转/admin/login;登录页POST→ 校验admin_users表 → 写 session cookie → 重定向。- 登出:
/admin/logout→ 销毁 session。
| ABI 名 | 形参 | 结果 |
|---|---|---|
web_auth_login |
username, password, users, session_ttl |
{ok:true, session_id} 或 {ok:false} |
web_auth_check |
session_id, users |
{ok:true} 或 {ok:false} |
web_auth_logout |
session_id |
{ok:true} |
3.3 WebSocket 服务器端点(web_ws_route)
- 作者面:
app.route_ws/应用.路由实时,形参path、可选echo=True。 listen时{path}升级为 WS:echo=True回发原文;否则接收并丢弃(扩展点)。
| ABI 名 | 形参 | 结果 |
|---|---|---|
web_app_route_ws |
app, path, echo |
{app}(登记 WS 端点) |
3.4 WebSocket 客户端(web_ws_connect)
- 作者面:
web.ws/网页.实时,形参url、message、可选headers、timeout_sec。 - 行为:客户端连接一次 WS,发
message,收全部服务器回文后关闭。单请求-响应式(非长驻),与 Marqdo 同步模型一致。
| ABI 名 | 形参 | 结果 |
|---|---|---|
web_ws_connect |
url, message, headers(map), timeout_sec |
{ok:true, messages:[…]} 或 {ok:false, error} |
英文(ext/web/web.mq.md):
# ws
+ `timeout_sec`=30
## connect
+ `url`
+ `message`
+ `headers`=None
中文(ext/web/网页.mq.md):
# 实时
+ `超时秒`=30
## 连接
+ `地址`
+ `消息`
+ `headers`=None
plugins/web用tokio-tungstenite(与 axum WS 同栈,版本兼容 rustc 1.81)。
4. ext/web 作者面新增
4.1 英文面(web.mq.md)
# auth
+ `users` # |用户名|密码| 表
+ `session_ttl`=3600
## login
+ `username`
+ `password`
## check
+ `session_id`
## logout
+ `session_id`
# app 新增 ## route_ws:
## route_ws
+ `path`
+ `echo`=True
4.2 中文面(网页.mq.md)
# 鉴权
+ `用户表`
+ `会话时长`=3600
## 登录
+ `用户名`
+ `密码`
## 校验
+ `会话id`
## 登出
+ `会话id`
# 应用 新增 ## 路由实时:
## 路由实时
+ `路径`
+ `回显`=真
4.3 用法示例(英文)
# main
`admins` =
| 用户名 | 密码 |
|--------|------|
| admin | secret |
*store = > db.open *
*page = > web.page title="Site" *
*app = > web.app page=`page` db=`store` admin=True host=127.0.0.1 port=18081 *
*app = > `app`.route_ws path="/live" echo=True *
*app = > web.auth users=`admins` *
> `app`.listen
*echo = > web.ws.connect url="ws://127.0.0.1:18081/live" message="hi" *
5. form 完善(现有功能验证 + 补测试)
现状已具备(无需改代码,需验证):
action=update:hiddenid+db.update(form.rsfrom_schema/submit已实现)- 校验失败页级回显:
submit_and_respond→render_page_ex(http.rs 已实现)
本波次为 update 流程和页级回显补 gold 测试,确认端到端可用。
6. 测试与验收
| 测试 | 内容 |
|---|---|
tests/ext/web-net-smoke.mq.md |
session new/set/get/del + auth login/check/logout + route_ws/app.auth 登记 + ws 连接失败路径(离线) |
tests/lib/net-cookie.mq.md |
cookie_parse 解析 |
tests/lib/net-multipart.mq.md |
multipart_parse 解析 |
tests/ext/web-admin-smoke.mq.md |
form action=update 全流程 + 校验失败 errors 回显 |
| 现有 gold | 全量回归(树遍历 + 字节码) |
验收:cargo test --test gold 全绿(除网络 live),双后端一致。
6.1 字典操作约束(作者面)
Marqdo 原生字典操作:GFM 横表构造、脚注取元 变量[^键] 读取。ext/web 作者面不使用 json.get / json.set 做字典读取/改写——所有字段读取一律 self[^键](或实例变量 [^键]),避免"用 json 标准库做字典操作"的反模式。json.parse / json.stringify 仅用于文本 ↔ 结构化数据的序列化转换(如 HTTP body 解析),不用于本地字典读写。
6.2 相对路径按入口脚本解析(host_query entry_dir)
static_dir(如 public)与相对 db 路径(如 sqlite:data/site.db)此前按进程 cwd 解析——从仓库根目录跑 examples/*/index.mq.md 时,/static 404、db 会建到根目录,这是错误行为。
本波次修复:宿主新增 host_query("entry_dir")(返回入口 .mq.md 所在目录的绝对路径,回退 cwd),plugins/web 的 web_listen 将相对 static_dir、db_url_of 将相对 db 路径统一 entry_dir().join(...) 到绝对路径。于是无论从仓库根目录还是示例目录运行,静态资源与数据库都落在脚本目录下。绝对路径不受影响;host_query 不可用时回退旧 cwd 行为。
7. 非本波次
- Postgres / Redis / S3 驱动(roadmap W4,另行)
- WS 广播房间、多客户端(先 echo 单连接)
- session 持久化到 SQLite / 文件(先内存)
- 复杂权限 / RBAC