- 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。
285 lines
11 KiB
Markdown
Executable File
285 lines
11 KiB
Markdown
Executable File
# 网络扩展波次:`ext/web` 鉴权 · WebSocket · 标准库网络原语
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **Draft(本波次锁定设计)** |
|
||
| 日期 | 2026-08-24 |
|
||
| 相关 | [ext-web.md](ext-web.md) · [ext-abi.md](ext-abi.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-cli.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`):**
|
||
```markdown
|
||
## cookie_parse
|
||
+ `text`
|
||
|
||
**> host_cookie_parse text=`text`**
|
||
```
|
||
|
||
**中文(`lib/网络.mq.md`):**
|
||
```markdown
|
||
## 解析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。
|
||
|
||
**英文:**
|
||
```markdown
|
||
## multipart_parse
|
||
+ `body`
|
||
+ `boundary`
|
||
|
||
**> host_multipart_parse body=`body` boundary=`boundary`**
|
||
```
|
||
|
||
**中文:**
|
||
```markdown
|
||
## 解析多部分
|
||
+ `正文`
|
||
+ `边界`
|
||
|
||
**> 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`):**
|
||
```markdown
|
||
# ws
|
||
+ `timeout_sec`=30
|
||
|
||
## connect
|
||
+ `url`
|
||
+ `message`
|
||
+ `headers`=None
|
||
```
|
||
|
||
**中文(`ext/web/网页.mq.md`):**
|
||
```markdown
|
||
# 实时
|
||
+ `超时秒`=30
|
||
|
||
## 连接
|
||
+ `地址`
|
||
+ `消息`
|
||
+ `headers`=None
|
||
```
|
||
|
||
> `plugins/web` 用 `tokio-tungstenite`(与 axum WS 同栈,版本兼容 rustc 1.81)。
|
||
|
||
---
|
||
|
||
## 4. `ext/web` 作者面新增
|
||
|
||
### 4.1 英文面(`web.mq.md`)
|
||
|
||
```markdown
|
||
# auth
|
||
+ `users` # |用户名|密码| 表
|
||
+ `session_ttl`=3600
|
||
|
||
## login
|
||
+ `username`
|
||
+ `password`
|
||
|
||
## check
|
||
+ `session_id`
|
||
|
||
## logout
|
||
+ `session_id`
|
||
```
|
||
|
||
`# app` 新增 `## route_ws`:
|
||
```markdown
|
||
## route_ws
|
||
+ `path`
|
||
+ `echo`=True
|
||
```
|
||
|
||
### 4.2 中文面(`网页.mq.md`)
|
||
|
||
```markdown
|
||
# 鉴权
|
||
+ `用户表`
|
||
+ `会话时长`=3600
|
||
|
||
## 登录
|
||
+ `用户名`
|
||
+ `密码`
|
||
|
||
## 校验
|
||
+ `会话id`
|
||
|
||
## 登出
|
||
+ `会话id`
|
||
```
|
||
|
||
`# 应用` 新增 `## 路由实时`:
|
||
```markdown
|
||
## 路由实时
|
||
+ `路径`
|
||
+ `回显`=真
|
||
```
|
||
|
||
### 4.3 用法示例(英文)
|
||
|
||
```markdown
|
||
# 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 |