diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a09c50..f232ea8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,7 @@ ### Added - **`ext/web` 样式装配(`web_style` / `网页.样式装配`)**: 样式即数据表格 —— GFM 样式表(`|选择器|属性|值|`,可用 `|媒体|` 列分组进 `@media` 块)经 `样式装配` 函数转成 CSS 文本,再拼装成完整主题。替代"整段手写 CSS 字符串"的写法,贯彻 文档即代码。见 [marqdo-blog](examples/marqdo-blog/styles/theme.mq.md)。 +- **网络能力调研(`doc/design/web-net-capabilities.md`)**: 盘点 `ext/web` + `plugins/web` + `lib/net` 现状,对照主流语言网络栈(FastAPI / Express / Flask / axum),给出「开发一个完整 Web 项目」所需能力的差距清单与分波次补强路线(W1 中间件+JSON → W2 数据层 → W3 安全硬化 → W4 内容标配 → W5 上传 → W6 进阶)。 ### Changed - **Frontmatter import syntax**: `import bind:target` / `导入 bind:target` (file `.mq.md` or short name `lib.member`). Removed legacy `> path.mq.md` / `> use` imports. See [module-namespace.md](doc/design/module-namespace.md). diff --git a/Cargo.lock b/Cargo.lock index 383c977..a0f9269 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -94,6 +94,18 @@ version = "1.0.104" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470" +[[package]] +name = "argon2" +version = "0.5.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3c3610892ee6e0cbce8ae2700349fcf8f98adb0dbfbee85aec3c9179d29cc072" +dependencies = [ + "base64ct", + "blake2", + "cpufeatures", + "password-hash", +] + [[package]] name = "ascii" version = "1.1.0" @@ -115,6 +127,18 @@ dependencies = [ "wait-timeout", ] +[[package]] +name = "async-compression" +version = "0.4.43" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3976abdc8fe7d1133d43d304afd42abdf5bc3e1319d263d223bde07b5efc4be8" +dependencies = [ + "compression-codecs", + "compression-core", + "pin-project-lite", + "tokio", +] + [[package]] name = "atomic-waker" version = "1.1.2" @@ -188,12 +212,27 @@ version = "0.22.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6" +[[package]] +name = "base64ct" +version = "1.8.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2af50177e190e07a26ab74f8b1efbfe2ef87da2116221318cb1c2e82baf7de06" + [[package]] name = "bitflags" version = "2.13.1" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b588b76d00fde79687d7646a9b5bdf3cc0f655e0bbd080335a95d7e96f3587da" +[[package]] +name = "blake2" +version = "0.10.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "46502ad458c9a52b69d4d4d32775c788b7a1b85e8bc9d482d92250fc0e3f8efe" +dependencies = [ + "digest", +] + [[package]] name = "block-buffer" version = "0.10.4" @@ -311,6 +350,23 @@ version = "1.0.5" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570" +[[package]] +name = "compression-codecs" +version = "0.4.38" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce2548391e9c1929c21bf6aa2680af86fe4c1b33e6cea9ac1cfeec0bd11218cf" +dependencies = [ + "compression-core", + "flate2", + "memchr", +] + +[[package]] +name = "compression-core" +version = "0.4.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc14f565cf027a105f7a44ccf9e5b424348421a1d8952a8fc9d499d313107789" + [[package]] name = "core-foundation-sys" version = "0.8.7" @@ -365,6 +421,7 @@ checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292" dependencies = [ "block-buffer", "crypto-common", + "subtle", ] [[package]] @@ -811,8 +868,10 @@ dependencies = [ name = "marqdo_plugin_web" version = "0.1.0" dependencies = [ + "argon2", "axum", "futures-util", + "getrandom 0.2.17", "rusqlite", "serde", "serde_json", @@ -897,6 +956,17 @@ version = "1.70.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe" +[[package]] +name = "password-hash" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "346f04948ba92c43e8469c1ee6736c7563d71012b17d40745260fe106aac2166" +dependencies = [ + "base64ct", + "rand_core 0.6.4", + "subtle", +] + [[package]] name = "percent-encoding" version = "2.3.2" @@ -1479,6 +1549,7 @@ version = "0.6.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840" dependencies = [ + "async-compression", "bitflags", "bytes", "futures-core", @@ -1496,6 +1567,7 @@ dependencies = [ "tokio-util", "tower-layer", "tower-service", + "tracing", ] [[package]] diff --git a/doc/design/web-net-capabilities.md b/doc/design/web-net-capabilities.md new file mode 100644 index 0000000..c02af19 --- /dev/null +++ b/doc/design/web-net-capabilities.md @@ -0,0 +1,262 @@ +# 网络能力调研:从「能跑」到「完整项目」 + +| | | +|---|---| +| 状态 | **调研结论(Draft)** | +| 日期 | 2026-08-26 | +| 相关 | [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [stdlib-modules.md](stdlib-modules.md) | +| 目标 | 盘点 `ext/web` + `plugins/web` + `lib/net` 现状,对照主流语言网络栈,给出「开发一个完整 Web 项目」所需能力的差距清单与补强路线 | + +--- + +## 0. 一句话结论 + +**当前 `plugins/web` 已覆盖「单页渲染 + SQLite 表单 CRUD + 简易 admin 门禁 + echo WebSocket + 中间件管道(CORS/安全头/gzip/请求体限制)+ JSON API + 数据层深化(连接池/事务/分页/查询表达力)」,足以支撑中小型内容站点与前后端分离 API;但距「完整项目」(博客/CMS/社区)仍缺四类能力:③ 安全硬化(密码哈希 / CSRF / 限流 / 会话持久化);④ 内容站点标配(SEO / 搜索 / RSS / 分页导航);① 中余下上传下载 / HTTPS / 日志 / 错误页。** 全部按「基础设施进 `lib/net`,领域能力进 `plugins/web` + `ext/web`」的既有边界补强。 + + +--- + +## 1. 现状盘点(2026-08-26 实测) + +### 1.1 `lib/net`(标准库,L0.5 宿主原语薄包装) + +| 能力 | 归属 | 现状 | +|---|---|---| +| `http_get` / `获取` | host `net.rs` (ureq) | ✅ GET,返回 `{status, body}` | +| `http_post` / `提交` | host `net.rs` | ✅ POST,默认 JSON CT | +| `http_request` / `请求` | host `net.rs` | ✅ 通用 method+body+headers | +| `http_post_sse` / `提交流式` | host `net.rs` | ✅ OpenAI 兼容 SSE 流式消费 | +| `openai_sse_parse` / `解析流式` | host `net.rs` | ✅ 离线 SSE 解析 | +| `url_encode` / `编码地址` | host `net.rs` | ✅ URL 编码 | +| `cookie_parse` / `解析Cookie` | host `net.rs` | ✅ RFC6265 子集(请求头/响应头) | +| `multipart_parse` / `解析多部分` | host `net.rs` | ✅ multipart/form-data 解析 | + +**标准库网络原语已比较齐备**:客户端 GET/POST/SSE、URL 编码、cookie、multipart 都有。缺的是**响应元信息(响应头/Set-Cookie 取出)、上传(multipart 文件)与下载(二进制)**。 + +### 1.2 `plugins/web`(ABI v2,领域能力) + +**服务器侧已实现:** + +| 域 | ABI | 能力 | +|---|---|---| +| 页面 | `web_page_new` · `web_compose_components` · `web_compose_main` · `web_page_query` · `web_page_order` · `web_page_link_prefix` · `web_page_css` · `web_page_detail` | 页面装配、列表/排序、CSS、详情页 | +| 样式 | `web_style` | GFM 表 → CSS(`make_style`/`样式装配`) | +| 表单 | `web_form_new/fields/rules/validate/render/submit/from_schema` · `web_compose_form` | 字段表、校验表、渲染、提交、schema→form | +| 数据库 | `web_db_new/init/insert/select/get/update/delete/exec/table_info/list_tables` | SQLite CRUD + where + order + limit | +| 应用 | `web_app_new/route/mount_form/static/auth` · `web_app_route_ws` | 路由、静态目录、admin、鉴权、WS 端点 | +| 会话 | `web_session_new/set/get/del/destroy` | 内存 TTL 会话 | +| 鉴权 | `web_auth_login/check/logout/new` · `web_app_auth` | `/admin` 登录门禁 | +| WebSocket | `web_ws_connect`(客户端)· `web_app_route_ws`(服务器) | 单请求-响应式客户端 + echo 服务器 | + +**关键实现事实(决定差距):** + +- **中间件层已落地**(W1):`app.configure`/`应用.装配` 通过 GFM 表装配 CORS、安全响应头、gzip 压缩、请求体上限、JSON API 路由,`监听` 时统一挂到 axum `Router`(`middleware.rs`)。「配置即数据、装配即函数」。 +- **JSON API 已落地**(W1):`|路径|方法|表|条件|排序|上限|` 表声明端点,响应 `application/json`,支持 DB 查询 + 排序 + 上限。 +- **数据层深化已落地**(W2):进程级**连接池**(WAL + `busy_timeout` + `foreign_keys`)+ **事务** API(`db.事务` → `txn.insert/提交/回滚`,`txn` 句柄带 `_type` 走 Marqdo 类分发)+ **结果集裸查询**(`db.query` 返回 `{rows, count}`)+ **分页**(`select`/`paginate` 支持 `offset`,返回 `{rows, total}`)+ **查询表达力**(where 支持 OR 组 / `in` / `between` / `is null` / `like`)+ **聚合计数**(`db.count`)。 +- **无文件上传**:无 multipart extractor,`multipart_parse` 只在标准库侧做了纯解析,服务器没接收。 +- **会话为进程内内存**:重启即失效、多 worker 不共享;session id 非加密强度;密码明文存储比对。 +- **无 HTTPS**:仅 `TcpListener::bind` HTTP。 +- **无迁移机制**:schema 版本表 + 迁移脚本缺失;索引/唯一/外键声明待增强(init 表增强)。 +- **WebSocket 仅 echo**:无广播/房间/多客户端/业务分发。 +- **尚无自定义 404/500 错误页、无访问日志、无 ETag/Cache-Control 缓存头、无重定向增强。** + +--- + + +## 2. 主流网络栈对照(联网调研 2026-08) + +### 2.1 分层共识(决定「标准库 vs 扩展」边界) + +| 语言 | 标准库网络能力 | 扩展/框架能力 | 边界准则 | +|---|---|---|---| +| Python | `urllib`(HTTP 客户端)、`http.cookies`(cookie 解析器)、`http.server`(简易服务器)、`email` 多部分解析 | `requests`/`httpx`(连接池/session)、`FastAPI`/`Flask`(中间件/校验/模板) | 解析器进标准库;便利层/框架层在第三方 | +| Node.js | `node:http`(低层流式,**不解析 body**)、`node:https` | express、fastify、ws、formidable | 低层原语进核心;fancy 功能 userland 验证后再进 core | +| Go | `net/http`(服务器+客户端**都在标准库**)、`net/http/cookiejar`(RFC6265)、`net/smtp` | `golang.org/x/net`(演进性)、gin/echo | HTTP 与 stdin 同级的核心能力;cookie 解析进标准库 | +| Rust | 极小 std(无 HTTP) | `hyper`→`reqwest`→`axum` | 分层;HTTP 生态多样不进 std | + +**对本项目的三处判定(与 [ext-web-net.md](ext-web-net.md) 一致并延伸):** + +1. **纯解析原语**(cookie / multipart / url)→ `lib/net` 标准库。✅ 已达成。 +2. **HTTP 服务器结构能力**(JSON / 中间件 / 上传下载 / HTTPS / 缓存头)→ `plugins/web`(ABI)。这是 axum 本身就在依赖链里的,不需要新增核心依赖。 +3. **领域能力**(session / auth / 分页 / 搜索 / RSS / SEO / 限流)→ `plugins/web` + `ext/web` 作者面。 + +### 2.2 「完整 Web 框架」能力清单(FastAPI / Express / Flask / axum 共通项) + +| 能力 | FastAPI | Express | Flask | axum | 说明 | +|---|---|---|---|---|---| +| 路由(含动态参数) | ✅ | ✅ | ✅ | ✅ | 三框架全支持;marqdo 已有动态路由 `/post/{slug}` | +| 中间件管道 | ✅ | ✅ | ✅ | ✅(tower) | **marqdo 缺失** — 最根本缺口 | +| CORS | ✅ 内置 | ✅ 中间件 | ✅ flask-cors | ✅ tower-http | 缺失 | +| JSON 请求/响应 | ✅ 原生 | ✅ | ✅ | ✅ | 缺失 | +| 校验(schema/字段) | ✅ Pydantic | 手动(zod) | 手动 | ✅ extractor | marqdo 有 form 校验表(够用) | +| 静态文件 | ✅ Starlette | ✅ | ✅ | ✅ | ✅ 已有 | +| 模板/渲染 | ✅ Jinja | ✅ | ✅ | ✅ | marqdo 用 GFM 表装配(自研) | +| 会话 | ✅ | ✅ express-session | ✅ | ✅ | 有(内存,待持久化) | +| 鉴权 | ✅ OAuth2/APIKey | ✅ | ✅ | ✅ | 有(admin 门禁,待硬化) | +| 文件上传 | ✅ | ✅ multer | ✅ | ✅ | 缺失 | +| WebSocket | ✅ | ✅ ws | ✅ Flask-SocketIO | ✅ | 有(echo,待广播) | +| 安全头 | ✅ | ✅ helmet | ✅ | ✅ tower-http | 缺失 | +| 限流 | ✅ | ✅ | ✅ | ✅ | 缺失 | +| 日志 | ✅ | ✅ morgan | ✅ | ✅ | 缺失 | +| gzip 压缩 | ✅ | ✅ | ✅ | ✅ | 缺失 | +| 分页 | 手动 | 手动 | ✅ paginate | ✅ | marqdo 缺失(db 层无 offset) | +| 迁移 | ✅ alembic | ✅ | ✅ | ✅ sqlx | 缺失 | +| 测试工具 | ✅ TestClient | ✅ supertest | ✅ | ✅ | 缺失(依赖 gold 测试) | +| HTTPS/TLS | 反代 | 反代 | 反代 | ✅ rustls | 缺失(通常反代承担) | + +--- + + +## 3. 差距分析:按「完整项目」四类需求 + +### 3.1 类 A:结构化 HTTP 基础设施(做 API / 前后端分离 / SPA 支撑) + +| # | 缺失能力 | 影响 | 归属 | 优先级 | +|---|---|---|---|---| +| A1 | **JSON 请求/响应**(`Json` extractor、`application/json` 响应、body 大小限制) | ✅ **已实现(W1)**:`接口` 表声明 JSON API 端点;`请求体上限` 配置 body 限制 | `plugins/web` | **P0 ✅** | +| A2 | **中间件管道**(`app.configure` / `应用.装配`:CORS、安全头、压缩、请求体限制统一挂载) | ✅ **已实现(W1)**:`middleware.rs` 装配 GFM 表并 `app.layer` 挂到 axum | `plugins/web` | **P0 ✅** | +| A3 | **CORS 支持**(`Access-Control-Allow-Origin` 可配) | ✅ **已实现(W1)**:`跨域` 表 `|允许来源|方法|头|暴露头|凭证|` | `plugins/web` | P1 ✅ | +| A4 | **安全响应头**(CSP / X-Frame-Options / X-Content-Type-Options / HSTS / Referrer-Policy / 去 `X-Powered-By`) | ✅ **已实现(W1)**:`安全` 表 `|头|值|` | `plugins/web` | P1 ✅ | +| A5 | **文件上传接收**(multipart extractor → 校验类型/大小 → 落盘)与**下载**(`Content-Disposition`) | 头像/附件/图片上传是博客/CMS 刚需 | `plugins/web` | P1 | +| A6 | **HTTPS / TLS**(rustls 终止或反代提示) | 生产部署安全 | `plugins/web`(或文档指引反代) | P2 | +| A7 | **gzip / br 压缩** + **ETag / Cache-Control 缓存头** | gzip ✅ **已实现(W1,`压缩=真`)**;ETag/Cache-Control 待补 | `plugins/web`(tower-http 现成) | P2 | +| A8 | **访问日志**(请求方法/路径/状态/耗时) | 排障、审计 | `plugins/web`(tower-http TraceLayer) | P2 | +| A9 | **自定义 404/500 错误页** | 用户体感 | `plugins/web` | P2 | +| A10 | **重定向增强**(permanent/自定义状态码) | 301 SEO | `plugins/web` | P3 | + +### 3.2 类 B:数据层深化(内容站点/社区的根基) + +| # | 缺失能力 | 影响 | 归属 | 优先级 | +|---|---|---|---|---| +| B1 | **连接池 / busy_timeout / WAL** | 高并发下 `database is locked`、每请求重连开销 | `plugins/web`(db.rs) | **P0 ✅** | +| B2 | **事务 API**(`begin` / `commit` / `rollback`,或 `with_transaction` 包装) | 批量/多表写无原子性 | `plugins/web` | **P0 ✅** | +| B3 | **结果集型裸查询**(exec 返回 rows) | count / join / group / 子查询完全不可用 | `plugins/web` | P1 ✅ | +| B4 | **分页**(db 层 `limit`+`offset`;页面层上一页/下一页) | 列表页只能限量 | `plugins/web` + `ext/web` | P1 ✅(db 层;页面 UI 属 D4) | +| B5 | **查询表达力**:OR / IN / BETWEEN / IS NULL / LIKE 转义 / 括号组合 | where 只能 AND | `plugins/web` | P1 ✅ | +| B6 | **迁移机制**(schema 版本表 + 迁移脚本) | 无法演进表结构 | `plugins/web` + `ext/web` | P2 | +| B7 | **索引 / 唯一 / 外键声明**(init 表增强) | 完整性、查询性能 | `plugins/web` | P2 | +| B8 | **聚合辅助**:count / group 便捷 API | 统计面板、标签计数 | `plugins/web` | P2 ✅(`db.count`) | +| B9 | **全文搜索**(SQLite FTS5) | 站内搜索刚需 | `plugins/web`(FTS5 现成) | P2 | +| B10 | **时间戳 / 审计字段自动维护** | 博客发布日期、更新时间 | `plugins/web` | P3 | + +### 3.3 类 C:安全硬化(能上线的前提) + +| # | 缺失能力 | 影响 | 归属 | 优先级 | +|---|---|---|---|---| +| C1 | **密码哈希**(argon2/bcrypt/sha+盐,替代明文) | 任何人读到库即得全部口令 | `plugins/web`(argon2 在依赖链) | **P0** | +| C2 | **CSRF 防护**(session-bound token,写操作校验) | 表单 POST 可被跨站伪造 | `plugins/web` | **P0** | +| C3 | **登录限速/失败锁定**(每 IP/用户名 5 次/15min) | 登录接口可被爆破 | `plugins/web` | P1 | +| C4 | **会话持久化**(SQLite/文件,替代内存) | 重启全员登出、多 worker 失效 | `plugins/web` | P1 | +| C5 | **加密安全 session id**(CSPRNG + 碰撞重试) | 会话劫持 | `plugins/web`(getrandom) | P1 | +| C6 | **cookie 增强**:`Secure` 标志、签名、滑动过期 | HTTPS 下泄露、篡改、长会话断线 | `plugins/web` | P2 | +| C7 | **防暴力破解 / 会话上限 / 后台过期清理** | 内存膨胀、滥用 | `plugins/web` | P2 | +| C8 | **RBAC / 多角色**(作者/管理员/访客) | 多作者站点 | `plugins/web` + `ext/web` | P3 | + +### 3.4 类 D:内容站点标配(博客/CMS 特有) + +| # | 缺失能力 | 影响 | 归属 | 优先级 | +|---|---|---|---|---| +| D1 | **SEO**:每页 `
`)
+
+**不支持**:有序/无序列表、行内代码、粗体/斜体、链接、图片、表格、引用块、代码高亮。
+**结论**:博客正文的 Markdown 渲染是真实缺口 → D5(`markdown_parse` 纯解析原语进 `lib/net` 标准库,与 `cookie_parse`/`multipart_parse` 同模式,由 `plugins/web` 渲染层或 `ext/web` 作者面调用)优先级 **P0**。
diff --git a/doc/roadmap/ext-web.md b/doc/roadmap/ext-web.md
index 04d6633..cf98e43 100644
--- a/doc/roadmap/ext-web.md
+++ b/doc/roadmap/ext-web.md
@@ -2,7 +2,7 @@
| | |
|---|---|
-| 状态 | **W0–W3 骨架已落地;W4 待** |
+| 状态 | **W0–W3.5 + 安全硬化已落地;内容标配 W4 进行中** |
| 日期 | 2026-08-11 |
| **锁定设计** | [design/ext-web.md](../design/ext-web.md) |
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [ext-llm.md](../design/ext-llm.md) |
@@ -25,11 +25,13 @@
| **W0** | CATALOG + L1 + `web_listen` Hello | **done** |
| **W1** | env 端口;`page` 四栏;nav 表;static | **done** |
| **W2** | SQLite `define`/`migrate`/`all` | **done** |
-| **W3** | 三列绑定;变量名即表名;`/admin` CRUD+日志+布局 | **done**(登录鉴权仍简) |
+| **W3** | 三列绑定;变量名即表名;`/admin` CRUD+日志+布局 | **done** |
+| **W3s** | 安全硬化:argon2 密码哈希、CSRF、SQLite 会话持久化、CSPRNG、登录限速 | **done** |
| **W3.5** | 人写面首版:`web.assemble` + `` `表`.`字段` `` + `examples/man-write-site` | **done**(编排袋仍可再瘦) |
| **W4** | Postgres;Redis / S3 驱动 | pending |
+| **W4c** | 内容标配:SEO / Markdown / RSS / 分页 UI(见 [web-net-capabilities.md](../design/web-net-capabilities.md)) | in progress |
-验收金样:`tests/ext/web-smoke.mq.md`、`ext_cli_add_web`。
+验收金样:`tests/ext/web-smoke.mq.md`、`tests/ext/web-security-smoke.mq.md`、`ext_cli_add_web`。
---
diff --git a/ext/web/web.mq.md b/ext/web/web.mq.md
index 5c59790..6a0b3d9 100644
--- a/ext/web/web.mq.md
+++ b/ext/web/web.mq.md
@@ -139,9 +139,116 @@ Style tables live as `##` exports in site style modules; compose resolves them b
## insert
+ `table`
+ `rows`
+ + `txn`=None
*url = self[^url]*
-**> web_db_insert url=`url` table=`table` rows=`rows`**
+**> web_db_insert url=`url` table=`table` rows=`rows` txn=`txn`**
+
+## select
+ + `table`
+ + `where`=None
+ + `limit`=200
+ + `order`=None
+ + `txn`=None
+
+Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作|值|` (`=` `!=` `>` `>=` `<` `<=` `like` `in` `between` `is null`; add `|或|` = `是` to join a row with `OR`). `order` is a column name with optional `-` prefix for descending (`"created_at"`, `"-created_at"`), comma-separated for multiple keys. Pass `txn` to read inside an open transaction. For pages (with a total), use `paginate`.
+
+*url = self[^url]*
+*r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`*
+**r[^rows]**
+
+## paginate
+ + `table`
+ + `where`=None
+ + `limit`=200
+ + `order`=None
+ + `跳过`=0
+ + `txn`=None
+
+Like `select` but returns `{ rows, total }` — the total counts rows matching `where` regardless of `limit`/`跳过`, so you can render `上一页 / 下一页`. Set `跳过` to the number of rows to skip (e.g. page 2 with 10 per page ⇒ `跳过`=10).
+
+*url = self[^url]*
+**> web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=`跳过` txn=`txn`**
+
+## get
+ + `table`
+ + `id`
+ + `txn`=None
+
+*url = self[^url]*
+**> web_db_get url=`url` table=`table` id=`id` txn=`txn`**
+
+## update
+ + `table`
+ + `id`
+ + `row`
+ + `txn`=None
+
+*url = self[^url]*
+**> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`**
+
+## delete
+ + `table`
+ + `id`
+ + `txn`=None
+
+*url = self[^url]*
+**> web_db_delete url=`url` table=`table` id=`id` txn=`txn`**
+
+## exec
+ + `sql`
+ + `args`=None
+ + `txn`=None
+
+*url = self[^url]*
+**> web_db_exec url=`url` sql=`sql` args=`args` txn=`txn`**
+
+## query
+ + `sql`
+ + `args`=None
+ + `txn`=None
+
+Run bare SQL and return the result set — count / join / group / subqueries. Returns `{ rows, count }`.
+
+*url = self[^url]*
+**> web_db_query url=`url` sql=`sql` args=`args` txn=`txn`**
+
+## count
+ + `table`
+ + `where`=None
+ + `txn`=None
+
+Count rows matching a `where` filter (same syntax as `select`). Returns a number.
+
+*url = self[^url]*
+*r = > web_db_count url=`url` table=`table` where=`where` txn=`txn`*
+**r[^count]**
+
+## 事务
+
+Begin a transaction: borrows the pooled connection exclusively and returns a
+`txn` handle. Write inside it, then `提交` (commit) or `回滚` (roll back).
+Every statement runs on the same connection, so a batch is atomic.
+
+*url = self[^url]*
+**> web_db_begin url=`url`**
+
+# txn
+ + `txn`
+ + `url`
+
+A transaction handle from `db.事务`. All CRUD here runs on the transaction's
+connection; finish with `提交` or `回滚`.
+
+**self**
+
+## insert
+ + `table`
+ + `rows`
+
+*url = self[^url]*
+*txn = self[^txn]*
+**> web_db_insert url=`url` table=`table` rows=`rows` txn=`txn`**
## select
+ `table`
@@ -149,10 +256,11 @@ Style tables live as `##` exports in site style modules; compose resolves them b
+ `limit`=200
+ `order`=None
-Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作|值|` (`=` `!=` `>` `>=` `<` `<=` `like`). `order` is a column name with optional `-` prefix for descending (`"created_at"`, `"-created_at"`), comma-separated for multiple keys.
+Same filters as `db.select`; runs inside the transaction.
*url = self[^url]*
-**> web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order`**
+*txn = self[^txn]*
+*r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`*
**r[^rows]**
## get
@@ -160,7 +268,8 @@ Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作
+ `id`
*url = self[^url]*
-**> web_db_get url=`url` table=`table` id=`id`**
+*txn = self[^txn]*
+**> web_db_get url=`url` table=`table` id=`id` txn=`txn`**
## update
+ `table`
@@ -168,21 +277,38 @@ Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作
+ `row`
*url = self[^url]*
-**> web_db_update url=`url` table=`table` id=`id` row=`row`**
+*txn = self[^txn]*
+**> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`**
## delete
+ `table`
+ `id`
*url = self[^url]*
-**> web_db_delete url=`url` table=`table` id=`id`**
+*txn = self[^txn]*
+**> web_db_delete url=`url` table=`table` id=`id` txn=`txn`**
## exec
+ `sql`
+ `args`=None
*url = self[^url]*
-**> web_db_exec url=`url` sql=`sql` args=`args`**
+*txn = self[^txn]*
+**> web_db_exec url=`url` sql=`sql` args=`args` txn=`txn`**
+
+## 提交
+
+Commit the transaction and return its connection to the pool.
+
+*txn = self[^txn]*
+**> web_db_commit txn=`txn`**
+
+## 回滚
+
+Roll the transaction back (undo every write) and return its connection.
+
+*txn = self[^txn]*
+**> web_db_rollback txn=`txn`**
# form
+ `table`=None
@@ -258,6 +384,19 @@ Serve files from `dir` under `mount` (default `/static`). Path is resolved from
**> web_app_static app=`self` dir=`dir` mount=`mount`**
+## configure
+ + `cors`=None
+ + `security`=None
+ + `compress`=None
+ + `body_limit`=None
+ + `json`=None
+
+Each capability is declared as a data table and assembled at listen time. The `cors` parameter takes a `|允许来源|方法|头|暴露头|凭证|` table (one row per origin; an empty `允许来源` column means any origin). The `security` parameter takes a `|头|值|` response-header table (e.g. `X-Frame-Options`, `Content-Security-Policy`, `X-Content-Type-Options`, `Referrer-Policy`, `Strict-Transport-Security`). Set `compress` to `True` to gzip response bodies. `body_limit` is the max request body bytes (e.g. `1048576`). The `json` parameter takes a `|路径|方法|表|条件|排序|上限|` table of JSON API endpoints backed by DB queries (each returns `application/json`).
+
+Tables stay as data; `configure` assembles them. 配置即数据、装配即函数.
+
+**> web_app_middleware app=`self` cors=`cors` security=`security` compress=`compress` body_limit=`body_limit` json_routes=`json`**
+
## listen
Serve `/`, routed pages, `/_part/{id}` (home) and `{path}/_part/{id}` (routes), `/_form/{id}` (from mounts + page embeds), optional `/static` (or custom mount), and optional `/admin`.
@@ -313,6 +452,13 @@ Destroy the session.
**> web_auth_logout session_id=`session_id`**
+## hash_password
+ + `password`
+
+Hash a plaintext password for storage in admin user tables (argon2id). Store the returned `hash` in the `password` column; login verifies automatically.
+
+**> web_password_hash password=`password`**
+
# ws
+ `timeout_sec`=30
diff --git a/ext/web/网页.mq.md b/ext/web/网页.mq.md
index 338b2eb..05b0366 100644
--- a/ext/web/网页.mq.md
+++ b/ext/web/网页.mq.md
@@ -126,9 +126,113 @@ import sys:lib/sys.mq.md
## 插入
+ `表`
+ `行`
+ + `事务`=None
*url = self[^url]*
-**> web_db_insert url=`url` table=`表` rows=`行`**
+**> web_db_insert url=`url` table=`表` rows=`行` txn=`事务`**
+
+## 查询
+ + `表`
+ + `条件`=None
+ + `上限`=200
+ + `排序`=None
+ + `事务`=None
+
+简单条件:单行列→值映射(AND `=`),或 `|字段|操作|值|` 表(`=` `!=` `>` `>=` `<` `<=` `like` `in` `between` `is null`;加 `|或|` 为 `是` 可让该行与前一行用 `OR` 连接)。`排序` 是列名,`-` 前缀表示倒序(`"created_at"`、`"-created_at"`),可逗号分隔多列。传入 `事务` 可在已开启的事务内读取。要分页(带总数)用 `分页`。
+
+*url = self[^url]*
+*r = > web_db_select url=`url` table=`表` where=`条件` limit=`上限` order=`排序` offset=None txn=`事务`*
+**r[^rows]**
+
+## 分页
+ + `表`
+ + `条件`=None
+ + `上限`=200
+ + `排序`=None
+ + `跳过`=0
+ + `事务`=None
+
+同 `查询`,但返回 `{ rows, total }`——`total` 是满足 `条件` 的行数(不受 `上限`/`跳过` 影响),供渲染 `上一页 / 下一页`。`跳过` 为要跳过的行数(如每页 10 条的第 2 页 ⇒ `跳过`=10)。
+
+*url = self[^url]*
+**> web_db_select url=`url` table=`表` where=`条件` limit=`上限` order=`排序` offset=`跳过` txn=`事务`**
+
+## 获取
+ + `表`
+ + `id`
+ + `事务`=None
+
+*url = self[^url]*
+**> web_db_get url=`url` table=`表` id=`id` txn=`事务`**
+
+## 更新
+ + `表`
+ + `id`
+ + `行`
+ + `事务`=None
+
+*url = self[^url]*
+**> web_db_update url=`url` table=`表` id=`id` row=`行` txn=`事务`**
+
+## 删除
+ + `表`
+ + `id`
+ + `事务`=None
+
+*url = self[^url]*
+**> web_db_delete url=`url` table=`表` id=`id` txn=`事务`**
+
+## 执行
+ + `sql`
+ + `参数`=None
+ + `事务`=None
+
+*url = self[^url]*
+**> web_db_exec url=`url` sql=`sql` args=`参数` txn=`事务`**
+
+## 原生查询
+ + `sql`
+ + `参数`=None
+ + `事务`=None
+
+执行裸 SQL 并返回结果集——count / join / group / 子查询都行。返回 `{ rows, count }`。
+
+*url = self[^url]*
+**> web_db_query url=`url` sql=`sql` args=`参数` txn=`事务`**
+
+## 计数
+ + `表`
+ + `条件`=None
+ + `事务`=None
+
+统计满足 `条件` 的行数(语法同 `查询`)。返回数字。
+
+*url = self[^url]*
+*r = > web_db_count url=`url` table=`表` where=`条件` txn=`事务`*
+**r[^count]**
+
+## 事务
+
+开启一个事务:从连接池独占借用连接,返回 `事务` 句柄。在事务内写入,然后 `提交` 或 `回滚`。所有语句在同一连接上执行,整批写入是原子的。
+
+*url = self[^url]*
+**> web_db_begin url=`url`**
+
+# 事务
+ + `事务`
+ + `地址`
+
+数据库.事务 返回的句柄。这里的所有 CRUD 都在该事务连接上执行;结束时 提交 或 回滚。
+
+**self**
+
+## 插入
+ + `表`
+ + `行`
+
+*url = self[^地址]*
+*txn = self[^事务]*
+**> web_db_insert url=`url` table=`表` rows=`行` txn=`txn`**
## 查询
+ `表`
@@ -136,40 +240,59 @@ import sys:lib/sys.mq.md
+ `上限`=200
+ `排序`=None
-简单条件:单行列→值映射(AND `=`),或 `|字段|操作|值|` 表(`=` `!=` `>` `>=` `<` `<=` `like`)。`排序` 是列名,`-` 前缀表示倒序(`"created_at"`、`"-created_at"`),可逗号分隔多列。
+筛选语法同 `数据库.查询`;在事务内执行。
-*url = self[^url]*
-*r = > web_db_select url=`url` table=`表` where=`条件` limit=`上限` order=`排序`*
+*url = self[^地址]*
+*txn = self[^事务]*
+*r = > web_db_select url=`url` table=`表` where=`条件` limit=`上限` order=`排序` offset=None txn=`txn`*
**r[^rows]**
## 获取
+ `表`
+ `id`
-*url = self[^url]*
-**> web_db_get url=`url` table=`表` id=`id`**
+*url = self[^地址]*
+*txn = self[^事务]*
+**> web_db_get url=`url` table=`表` id=`id` txn=`txn`**
## 更新
+ `表`
+ `id`
+ `行`
-*url = self[^url]*
-**> web_db_update url=`url` table=`表` id=`id` row=`行`**
+*url = self[^地址]*
+*txn = self[^事务]*
+**> web_db_update url=`url` table=`表` id=`id` row=`行` txn=`txn`**
## 删除
+ `表`
+ `id`
-*url = self[^url]*
-**> web_db_delete url=`url` table=`表` id=`id`**
+*url = self[^地址]*
+*txn = self[^事务]*
+**> web_db_delete url=`url` table=`表` id=`id` txn=`txn`**
## 执行
+ `sql`
+ `参数`=None
-*url = self[^url]*
-**> web_db_exec url=`url` sql=`sql` args=`参数`**
+*url = self[^地址]*
+*txn = self[^事务]*
+**> web_db_exec url=`url` sql=`sql` args=`参数` txn=`txn`**
+
+## 提交
+
+提交事务,并把连接归还连接池。
+
+*txn = self[^事务]*
+**> web_db_commit txn=`txn`**
+
+## 回滚
+
+回滚事务(撤销所有写入),并归还连接。
+
+*txn = self[^事务]*
+**> web_db_rollback txn=`txn`**
# 表单
+ `表`=None
@@ -243,6 +366,19 @@ import sys:lib/sys.mq.md
**> web_app_static app=`self` dir=`目录` mount=`挂载`**
+## 装配
+ + `跨域`=None
+ + `安全`=None
+ + `压缩`=None
+ + `请求体上限`=None
+ + `接口`=None
+
+每项能力用数据表声明,`监听` 时统一装配。`跨域` 参数接受 `|允许来源|方法|头|暴露头|凭证|` 表(每来源一行;`允许来源` 留空表示允许任意来源)。`安全` 参数接受 `|头|值|` 响应头表(如 `X-Frame-Options`、`Content-Security-Policy`、`X-Content-Type-Options`、`Referrer-Policy`、`Strict-Transport-Security`)。`压缩` 为 `真` 时对响应体做 gzip 压缩。`请求体上限` 是请求体最大字节数(如 `1048576`)。`接口` 参数接受 `|路径|方法|表|条件|排序|上限|` JSON API 端点表(每个返回 `application/json`)。
+
+表仍是数据,`装配` 把它们变成能力。配置即数据、装配即函数。
+
+**> web_app_middleware app=`self` cors=`跨域` security=`安全` compress=`压缩` body_limit=`请求体上限` json_routes=`接口`**
+
## 监听
提供 `/`、路由页、首页 `/_part/{id}`、路由 `{路径}/_part/{id}`、`/_form/{id}`、可选静态目录,以及可选 `/admin`。
@@ -298,6 +434,13 @@ import sys:lib/sys.mq.md
**> web_auth_logout session_id=`会话id`**
+## 哈希密码
+ + `密码`
+
+将明文口令哈希为 argon2id 字符串,写入用户表的 `密码` 列;登录时自动校验。
+
+**> web_password_hash password=`密码`**
+
# 实时
+ `超时秒`=30
diff --git a/plugins/web/Cargo.toml b/plugins/web/Cargo.toml
index d1217c4..389f677 100644
--- a/plugins/web/Cargo.toml
+++ b/plugins/web/Cargo.toml
@@ -14,8 +14,10 @@ crate-type = ["cdylib"]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tokio = { version = "1", features = ["rt-multi-thread", "macros", "net", "sync", "time", "signal"] }
-axum = { version = "0.8", features = ["ws"] }
-tower-http = { version = "0.6", features = ["fs"] }
+axum = { version = "0.8", features = ["ws", "json", "query"] }
+tower-http = { version = "0.6", features = ["fs", "cors", "compression-gzip", "limit", "set-header", "trace", "propagate-header"] }
rusqlite = { version = "0.32", features = ["bundled"] }
tokio-tungstenite = "0.24"
futures-util = "0.3"
+argon2 = "0.5"
+getrandom = "0.2"
diff --git a/plugins/web/src/db.rs b/plugins/web/src/db.rs
index 1bcef22..076088e 100644
--- a/plugins/web/src/db.rs
+++ b/plugins/web/src/db.rs
@@ -1,10 +1,67 @@
-//! SQLite helpers for `# db` CRUD (`init` / `insert` / `select` / `get` / `update` / `delete` / `exec`).
+//! SQLite helpers for `# db` CRUD and W2 data-layer capabilities.
+//!
+//! - **连接池**:进程级 `Pool` 复用连接(WAL + busy_timeout + foreign_keys),
+//! 避免每请求重连与并发写 `database is locked`。
+//! - **事务**:`begin` 把连接从池中借出并独占,`commit` / `rollback` 后归还。
+//! - **查询表达力**:where 支持 OR 组、`in` / `between` / `is null`。
+//! - **分页**:`select` 支持 `offset`,返回 `{rows, total}`。
use rusqlite::{types::ValueRef, Connection, OptionalExtension, params_from_iter};
use serde_json::{json, Map, Value};
+use std::collections::HashMap;
use std::path::PathBuf;
+use std::sync::{Arc, Mutex};
-fn open(url: &str) -> Result {
+/// Process-wide pool: url → shared connection. Connections are reused across
+/// calls instead of reopening per request.
+static POOL: Mutex