Files
marqdo/doc/design/ext-web-net.md
cflmyandCursor 7645dd4c1f Extend network stack: session/auth, WebSocket, cookie/multipart primitives
Add the network-extension wave to lib/net and the web ABI plugin:
- lib/net cookie_parse / multipart_parse host primitives (EN/ZH)
- plugins/web session store + /admin login gate + WebSocket client/server
- ext/web author surface (EN/ZH) for session, auth, ws
- form update flow and page-level validation echo tests
- fix string escapes: \xHH, \u{...}, unknown escapes kept verbatim
- map Chinese component slots (导航/侧栏/页脚) so sidebar renders
- resolve relative static/db paths against the entry script dir (entry_dir)
- new tutorial chapter 14, EN/ZH example sites, and gold tests

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-25 14:58:46 +08:00

11 KiB
Raw Permalink Blame History

网络扩展波次: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

共识:

  1. cookie 解析/管理(RFC 6265)在 Python/Go 都是标准库(http.cookies、net/http/cookiejar)。
  2. multipart/form-data 解析在 Go 是标准库(net/http),在 Python 是第三方 multipart。
  3. WebSocket 几乎总在扩展/第三方(Node ws、Python websockets、Go gorilla/websocket),很少进语言标准库。
  4. 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:hidden id + db.update(form.rs from_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