Files
marqdo/ext/web/web.mq.md
T
cflmyandCursor d3b137c919 feat(anlian-mq): align site with Django anlian browse UX
Port original CSS/JS/assets, rebuild home as four sections with feed
fragments, expand schema (boards/notices/rooms/topics), and add
page.chrome HTML overrides plus invoke html returns so Marqdo can
render Django-class chrome without json glue.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 22:46:55 +08:00

992 lines
30 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: ext/web/web
description: Official web site classes (English). Tables + methods; no bag glue.
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
import table:lib/table.mq.md
---
## ensure_plugin
Load the ABI v2 `web` plugin once.
*p = > plugin.native_path name="web"*
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/web: native web plugin not found (build marqdo_plugin_web or marqdo ext add web)
> sys.exit code=1
****
## make_style
+ `name`=""
+ `table`
+ `strict`=False
Assemble a GFM style table into a CSS string. Two shapes are accepted:
`|选择器|属性|值|` rule rows (arbitrary selectors; rows sharing a selector are
merged, and a leading `|媒体|` column groups rows into `@media` blocks), or
`|属性|值|` property rows wrapped as `.name { … }`. Selectors starting with
`@keyframes name` emit keyframe blocks (`属性` = stop `from`/`to`/`N%`,
`值` = `prop: val` or use `@keyframes name from` + normal 属性/值). Quote CSS
values that contain `/` (e.g. `"16/9"`, `"1 / 5"`); bare `1 / 5` is integer
division and becomes a numeric cell — default mode warns, `strict=True` errors.
For complex themes prefer `page.css` (raw string, no table eval) or an external
`static/*.css` via `page.head`. Styles stay as data tables, `make_style` turns
them into CSS — 样式即数据、装配即函数.
> ensure_plugin
**> web_style name=`name` table=`table` strict=`strict`**
## make_images
+ `table`
Assemble a GFM image table into an HTML fragment (`div.mq-images` of
`<figure class="mq-img">` / `<img>`). Columns: `src`/`alt`/`title`/`class`/
`href`/`width`/`height`/`loading`/`caption` (ZH: `源`/`替代`/`标题`/`类`/
`链接`/`宽度`/`高度`/`加载`/`图注`). Images stay as data — 图片即数据、装配即函数.
> ensure_plugin
**> web_images table=`table`**
## make_head
+ `table`
Assemble a Head resource table into HTML (`<link>` / `<script>`). Useful for
preview; prefer `page.head` to attach resources to a page.
> ensure_plugin
**> web_head table=`table`**
## client_embed
+ `bridge`="/static/marqdo-bridge.js"
+ `wasm`="/static/marqdo_wasm.wasm"
+ `source`=""
+ `boot`=True
Return an HTML snippet that loads the official browser Marqdo bridge (route C/D).
With `boot` and non-empty `source` (URL path to `.mq.md`), emits `data-mq-wasm` / `data-mq-source-url` so the bridge **auto-mounts** (author zero JS).
Run `marqdo wasm build -o static` and `app.static dir=static`. Design: [browser-marqdo-wasm.md](../../doc/design/browser-marqdo-wasm.md) §16.
1. `boot`
1. `source` != ""
**"<script type=\"module\" src=\"" + bridge + "\" data-mq-wasm=\"" + wasm + "\" data-mq-source-url=\"" + source + "\"></script>"**
2. *
**"<script type=\"module\" src=\"" + bridge + "\"></script>"**
2. *
**"<script type=\"module\" src=\"" + bridge + "\" data-mq-no-boot=\"1\"></script>"**
## text_patch
+ `sel`
+ `text`
Shortcut: build a `set_text` effects map `{ set_text: { sel: text } }` for browser return values.
Prefer authoring with `lib/browser` + GFM tables in client `.mq.md` ([marqdo-dev](../../.cursor/skills/marqdo-dev/SKILL.md)).
*`m` = > table.put in=None at=sel value=text*
**> table.put in=None at="set_text" value=m**
## dom_patch
+ `set_text`=None
+ `set_value`=None
+ `set_attr`=None
+ `set_class`=None
+ `toggle_class`=None
+ `set_style`=None
+ `set_html`=None
+ `render_list`=None
+ `navigate`=None
+ `storage`=None
+ `ws`=None
+ `fetch`=None
+ `fetch_all`=None
+ `after`=None
+ `interval`=None
+ `clear_interval`=None
+ `focus`=None
+ `blur`=None
+ `scroll_into`=None
+ `canvas`=None
+ `audio`=None
+ `read_file`=None
+ `observe`=None
+ `unobserve`=None
+ `wire`=None
Merge browser effect keys into one return map (omit `None`). Route E/F effects included.
*`out` = > table.put in=None at="_mq" value=True*
1. `set_text` != None
*`out` = > table.put in=`out` at="set_text" value=set_text*
1. `set_value` != None
*`out` = > table.put in=`out` at="set_value" value=set_value*
1. `set_attr` != None
*`out` = > table.put in=`out` at="set_attr" value=set_attr*
1. `set_class` != None
*`out` = > table.put in=`out` at="set_class" value=set_class*
1. `toggle_class` != None
*`out` = > table.put in=`out` at="toggle_class" value=toggle_class*
1. `set_style` != None
*`out` = > table.put in=`out` at="set_style" value=set_style*
1. `set_html` != None
*`out` = > table.put in=`out` at="set_html" value=set_html*
1. `render_list` != None
*`out` = > table.put in=`out` at="render_list" value=render_list*
1. `navigate` != None
*`out` = > table.put in=`out` at="navigate" value=navigate*
1. `storage` != None
*`out` = > table.put in=`out` at="storage" value=storage*
1. `ws` != None
*`out` = > table.put in=`out` at="ws" value=ws*
1. `fetch` != None
*`out` = > table.put in=`out` at="fetch" value=fetch*
1. `fetch_all` != None
*`out` = > table.put in=`out` at="fetch_all" value=fetch_all*
1. `after` != None
*`out` = > table.put in=`out` at="after" value=after*
1. `interval` != None
*`out` = > table.put in=`out` at="interval" value=interval*
1. `clear_interval` != None
*`out` = > table.put in=`out` at="clear_interval" value=clear_interval*
1. `focus` != None
*`out` = > table.put in=`out` at="focus" value=focus*
1. `blur` != None
*`out` = > table.put in=`out` at="blur" value=blur*
1. `scroll_into` != None
*`out` = > table.put in=`out` at="scroll_into" value=scroll_into*
1. `canvas` != None
*`out` = > table.put in=`out` at="canvas" value=canvas*
1. `audio` != None
*`out` = > table.put in=`out` at="audio" value=audio*
1. `read_file` != None
*`out` = > table.put in=`out` at="read_file" value=read_file*
1. `observe` != None
*`out` = > table.put in=`out` at="observe" value=observe*
1. `unobserve` != None
*`out` = > table.put in=`out` at="unobserve" value=unobserve*
1. `wire` != None
*`out` = > table.put in=`out` at="wire" value=wire*
**out**
## list_html
+ `sel`
+ `tag`="li"
+ `items`
Build a `render_list` effect: `{ render_list: { sel: { tag, items } } }`.
*`spec` = > table.put in=None at="tag" value=tag*
*`spec` = > table.put in=`spec` at="items" value=items*
*`m` = > table.put in=None at=sel value=spec*
**> table.put in=None at="render_list" value=m**
# page
+ `title`="Marqdo Web"
+ `intro`=""
+ `shell_css`=None
+ `layout`=None
+ `asset_version`=None
> ensure_plugin
**> web_page_new title=`title` intro=`intro` shell_css=`shell_css` layout=`layout` asset_version=`asset_version`**
## shell_css
+ `mode`=full
Framework shell CSS mode for this page: `full` (default), `minimal` (vars only), or `off`/`none`.
*`out` = > table.put in=`self` at="shell_css" value=mode*
**out**
## layout
+ `layout`=sidebar
Page chrome layout: `sidebar` (default when a side slot exists), `stacked` (single column; no `has-sidebar` grid), `bare` (main only), or `rail`.
*`out` = > table.put in=`self` at="layout" value=layout*
**out**
## asset_version
+ `version`=""
Default `?v=` bump for head scripts/styles that omit a per-row `version` column.
*`out` = > table.put in=`self` at="asset_version" value=version*
**out**
## compose_components
+ `components`
Assemble nav / sidebar / footer from a page table (`|组件|样式|` or `|src|style|`).
Nav bind tables may include optional `媒体`/`media` (responsive show) and `当`/`when`
(`auth` / `guest` / `hide`) columns — see C4 conditional nav.
**> web_compose_components page=`self` components=`components`**
## compose_main
+ `main`
Assemble main from a bind table (`|属性|值|样式|` or `|front|back|css|`).
**> web_compose_main page=`self` main=`main`**
## query
+ `query`
Attach a DB where-condition map for the main bind. Values may contain `{param}`
placeholders that are resolved from dynamic-route params (e.g. `/post/{slug}`).
**> web_page_query page=`self` query=`query`**
## order
+ `order`
Set a default `ORDER BY` for the main bind (e.g. `-created_at` for newest first).
**> web_page_order page=`self` order=`order`**
## link_prefix
+ `prefix`
Prefix for card links in the main bind (default `/post/`). Cards whose bind has
an `href`/`链接` field become `<a href="{prefix}{href}">`.
**> web_page_link_prefix page=`self` prefix=`prefix`**
## css
+ `css`
Append a **raw** CSS string to the page's stylesheet (`styles_css`). Skips table-cell
expression evaluation — use for themes with `/`, `@keyframes`, or long media queries.
Hand-written theme alongside the assembled shell; or link `static/theme.css` via `head`.
**> web_page_css page=`self` css=`css`**
## detail
+ `detail`=True
Render the main bind's first row as a full article (title/meta/tags/body) instead
of a list of cards. Set on the dynamic post page so `/post/{slug}` shows one post.
**> web_page_detail page=`self` detail=`detail`**
## chrome
+ `nav_html`=""
+ `footer_html`=""
+ `body_class`=""
Override default header/footer list chrome with raw HTML (site navbar / footer). Optional `body_class` is appended to `<body class>`.
**> web_page_chrome page=`self` nav_html=`nav_html` footer_html=`footer_html` body_class=`body_class`**
## meta
+ `meta`
SEO / OpenGraph metadata as a data table (`|key|value|`). Keys such as `title`, `description`, `canonical`, `og:type` become `<head>` tags at render time. Special keys `icon` / `favicon` / `apple-touch-icon` emit `<link rel="…">` (not `<meta name>`).
**> web_page_meta page=`self` meta=`meta`**
## head
+ `table`
Assemble `<head>` resources from a GFM table (`|rel|href|type|sizes|media|as|crossorigin|defer|async|version|` or ZH `|关系|地址|…|推迟|异步|版本|`). `rel=script` / `module` become `<script>`; other rows become `<link>`. Classic scripts emit `defer` / `async` only when those columns are true (compat: missing `defer` stays synchronous). Non-empty `version` appends `?v=`; else page/app `asset_version` is used. Merges with any existing `head` on the page.
**> web_page_head page=`self` table=`table`**
## images
+ `table`
Assemble an image table (`|src|alt|title|class|href|width|height|loading|caption|`) into HTML and attach it as `images_html` (rendered in main before intro). Same table shape as module-level `make_images`.
**> web_page_images page=`self` table=`table`**
## paginate
+ `offset`=0
+ `limit`=10
+ `path`=/
List pagination for the main bind: sets DB `limit`/`offset` and renders previous/next navigation.
**> web_page_paginate page=`self` offset=`offset` limit=`limit` path=`path`**
## compose_form
+ `form`
+ `id`
+ `target`=None
Embed a form into the page main slot. Optional `target` / `form_slot` (CSS id, e.g. `#qd-note-form-mount`) injects the form **inside** that element in `intro` HTML instead of a sibling `.site-form` after `.main-intro` (GAP-11). Missing mount falls back to sibling. `listen` auto-registers `GET|POST /_form/{id}` from page/route forms (optional `app.mount_form`).
**> web_compose_form page=`self` form=`form` id=`id` target=`target`**
## render
+ `db`=None
Offline HTML for tests / previews.
1. `db`
*url = db[^url]*
**> web_render page=`self` url=`url`**
2. *
**> web_render page=`self`**
# style
+ `name`=""
Style tables live as `##` exports in site style modules; compose resolves them by path.
**self**
## process
+ `style`=None
+ `name`=None
+ `path`=None
**self**
# db
+ `url`="sqlite:site.db"
Open a database handle. URL schemes: `sqlite:path` (default), `postgres://…` / `postgresql://…` (same CRUD methods).
> ensure_plugin
**> web_db_new url=`url`**
## init
+ `name`
+ `fields`
Create a table from a schema table. Optional columns: `唯一`/`unique`, `索引`/`index` (creates UNIQUE / INDEX), `外键`/`fk`/`references` (e.g. `posts.id` or `posts(id)`). Columns named `created_at` / `updated_at` are filled automatically on insert/update when present.
*url = self[^url]*
**> web_db_init url=`url` name=`name` fields=`fields`**
## insert
+ `table`
+ `rows`
+ `txn`=None
*url = self[^url]*
**> 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]**
## migrate
+ `steps`
Apply versioned SQL migrations. `steps` is a `|version|sql|` / `|版本|SQL|` table. Applied versions are recorded in `_marqdo_migrations`. Re-running is a no-op for already-applied versions. SQLite only.
*url = self[^url]*
**> web_db_migrate url=`url` steps=`steps`**
## fts
+ `table`
+ `columns`
+ `name`=None
Create an FTS5 index on `table` for the listed content columns (CSV string or list). Default FTS name is `{table}_fts`. Keeps the index in sync via triggers. Requires integer `id` PK. SQLite only.
*url = self[^url]*
**> web_db_fts_create url=`url` table=`table` columns=`columns` name=`name`**
## search
+ `table`
+ `q`
+ `limit`=20
+ `name`=None
Full-text search (`MATCH`) against the FTS5 index from `fts`. Returns `{ rows, count }` with a `rank` column (bm25). SQLite only.
*url = self[^url]*
**> web_db_search url=`url` table=`table` q=`q` limit=`limit` name=`name`**
## 事务
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`
+ `where`=None
+ `limit`=200
+ `order`=None
Same filters as `db.select`; runs inside the transaction.
*url = self[^url]*
*txn = self[^txn]*
*r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`*
**r[^rows]**
## get
+ `table`
+ `id`
*url = self[^url]*
*txn = self[^txn]*
**> web_db_get url=`url` table=`table` id=`id` txn=`txn`**
## update
+ `table`
+ `id`
+ `row`
*url = self[^url]*
*txn = self[^txn]*
**> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`**
## delete
+ `table`
+ `id`
*url = self[^url]*
*txn = self[^txn]*
**> web_db_delete url=`url` table=`table` id=`id` txn=`txn`**
## exec
+ `sql`
+ `args`=None
*url = self[^url]*
*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
+ `action`=insert
+ `id`=None
Field table + rules table; submit writes through `# db`.
> ensure_plugin
**> web_form_new table=`table` action=`action` id=`id`**
## fields
+ `fields`
**> web_form_fields form=`self` fields=`fields`**
## rules
+ `rules`
**> web_form_rules form=`self` rules=`rules`**
## validate
+ `rules`=None
+ `data`
**> web_form_validate form=`self` rules=`rules` data=`data`**
## render
+ `id`=form
+ `data`=None
+ `errors`=None
**> web_form_render form=`self` id=`id` data=`data` errors=`errors`**
## submit
+ `data`
+ `db`
*url = db[^url]*
**> web_form_submit form=`self` data=`data` url=`url`**
# app
+ `page`
+ `db`=None
+ `admin`=False
+ `host`=127.0.0.1
+ `port`=18081
+ `admin_prefix`=/admin
+ `login_redirect`=None
+ `logout_redirect`=None
+ `shell_css`=None
+ `layout`=None
+ `asset_version`=None
Construct an app. `admin=True` mounts the built-in CRUD UI under `admin_prefix` (default `/admin`). When `admin=False`, that prefix is **not** reserved — you may `route` your own pages there. Optional `login_redirect` / `logout_redirect` override post-auth landing. Optional `shell_css` / `layout` / `asset_version` become defaults for pages that do not set their own (see `page.shell_css` / `page.layout` / `page.asset_version`).
> ensure_plugin
**> web_app_new page=`page` db=`db` admin=`admin` host=`host` port=`port` admin_prefix=`admin_prefix` login_redirect=`login_redirect` logout_redirect=`logout_redirect` shell_css=`shell_css` layout=`layout` asset_version=`asset_version`**
## route
+ `path`
+ `page`
Mount an assembled page at `path` (e.g. `/about`). `/` is the home `page=`.
**> web_app_route app=`self` path=`path` page=`page`**
## mount_form
+ `id`
+ `form`
Register `GET|POST /_form/{id}` for listen when the form is not already embedded via `page.compose_form`.
**> web_app_mount_form app=`self` id=`id` form=`form`**
## static
+ `dir`
+ `mount`=/static
Serve files from `dir` under `mount` (default `/static`). Path is resolved from the process working directory at listen time. If `dir` contains `favicon.ico` / `favicon.png` / `favicon.svg` and `icons` was not set, listen also serves `GET /favicon.ico` and injects a default `<link rel="icon">` on every page.
**> web_app_static app=`self` dir=`dir` mount=`mount`**
## icons
+ `table`
Register site icons from a GFM table (`|path|rel|type|sizes|url|` or ZH
`|路径|关系|类型|尺寸|地址|`). Listen serves each file at `url` (default
`/favicon.ico` for `.ico` icons, else `/icons/{filename}`), and injects matching
`<link>` tags into every page via `site_head`. See [web-assets-and-images.md](../../doc/design/web-assets-and-images.md).
**> web_app_icons app=`self` table=`table`**
## configure
+ `cors`=None
+ `security`=None
+ `compress`=None
+ `body_limit`=None
+ `json`=None
+ `access_log`=None
+ `cache_control`=None
+ `proxy`=None
+ `invoke`=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`). Set `access_log` to `True` to log `METHOD path status duration_ms` on stderr. `cache_control` sets a global `Cache-Control` header (e.g. `public, max-age=3600`). `proxy` takes a `|路径|上游|流式|去前缀|方法|环境头|超时|` table of streaming reverse-proxy routes. `invoke` takes a `|路径|方法|函数|正文|返回|` table that calls entry-module `lib.member` handlers per request.
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` access_log=`access_log` cache_control=`cache_control` proxy=`proxy` invoke=`invoke`**
## proxy
+ `path`
+ `upstream`
+ `stream`=True
+ `strip_prefix`=None
+ `methods`=None
+ `headers_from_env`=None
+ `timeout_ms`=120000
Same-origin reverse proxy to an upstream HTTP(S) URL. When `stream` is True (default), the response body — including `text/event-stream` SSE — is piped without buffering the full payload, and responses include `Cache-Control: no-cache, no-transform` plus `X-Accel-Buffering: no` for Nginx/CDN. `upstream` may contain `$ENV` / `${ENV}`. `headers_from_env` is `ENV=Header-Name` (comma-separated); secrets stay on the server. Prefer this over a side Python LLM proxy.
**> web_app_proxy app=`self` path=`path` upstream=`upstream` stream=`stream` strip_prefix=`strip_prefix` methods=`methods` headers_from_env=`headers_from_env` timeout_ms=`timeout_ms`**
## invoke
+ `path`
+ `fn`
+ `method`=POST
+ `body`=json
+ `return`=json
Call a user `##` on each HTTP request. `fn` must be `lib.member` imported on the entry module. `body` is `json` / `form` / `query` / `raw`; object keys map to named params (plus `payload`). Returns JSON by default.
**> web_app_invoke app=`self` path=`path` method=`method` fn=`fn` body=`body` return=`return`**
## listen
Serve `/`, routed pages, `/_part/{id}` (home) and `{path}/_part/{id}` (routes), `/_form/{id}` (from mounts + page embeds), optional `/static` (or custom mount), optional `/admin`, upload/download/WebSocket/RSS/sitemap/robots routes, redirects, proxy/invoke routes, and a custom 404 fallback. Production HTTPS should terminate at a reverse proxy; set `cookie_secure=True` when serving over TLS.
**> web_listen app=`self`**
## route_ws
+ `path`
+ `echo`=True
+ `mode`=None
Register a WebSocket endpoint at `path` (e.g. `/live`). `mode` is `echo` (default), `broadcast` (fan-out text to all sockets on this path), or `drain`. Legacy `echo=False` maps to `drain`. Connect from a client with `web.ws.connect`.
**> web_app_route_ws app=`self` path=`path` echo=`echo` mode=`mode`**
## auth
+ `users`
+ `session_ttl`=3600
+ `admin_prefix`=None
+ `login_redirect`=None
+ `logout_redirect`=None
+ `login_path`=None
Keep the app's `admin=True`, and gate `{admin_prefix}` (segment-boundary prefix) behind a login page (default `/admin`). Unauthenticated requests **redirect** to `login_path` (default `{admin_prefix}/login`, auto-excluded). Does **not** match `/admin-publish`-style siblings.
**> web_app_auth app=`self` users=`users` session_ttl=`session_ttl` admin_prefix=`admin_prefix` login_redirect=`login_redirect` logout_redirect=`logout_redirect` login_path=`login_path`**
## gate
+ `path`
+ `roles`=admin
+ `match`=prefix
+ `on_deny`=forbid
+ `exclude`=None
Require one of `roles` (CSV) for `path`. `match=prefix` uses segment boundaries; `exact` is equality. Trailing `*` on `path` means prefix. `on_deny=redirect` sends visitors to `login_path` (with `?next=`); `forbid` returns 403. `exclude` is CSV or list of open paths.
**> web_app_gate app=`self` path=`path` roles=`roles` match=`match` on_deny=`on_deny` exclude=`exclude`**
## gallery
+ `path`=/gallery
+ `storage`
+ `prefix`=uploads/
+ `title`=Gallery
+ `download_base`=/_media
Serve an HTML media gallery listing objects under `prefix` in `storage`, linking through `download_base`.
**> web_app_gallery app=`self` path=`path` storage=`storage` prefix=`prefix` title=`title` download_base=`download_base`**
## route_rss
+ `path`
+ `table`
+ `limit`=20
+ `order`=-created_at
+ `title`=Feed
+ `link`=/
+ `description`=""
Register an RSS 2.0 feed at `path` (e.g. `/feed.xml`) backed by a DB table.
**> web_app_route_rss app=`self` path=`path` table=`table` limit=`limit` order=`order` title=`title` link=`link` description=`description`**
## redirect
+ `from`
+ `to`
+ `permanent`=False
Register a redirect from `from` to `to`. `permanent=True` issues HTTP 301; otherwise 307.
**> web_app_redirect app=`self` from=`from` to=`to` permanent=`permanent`**
## error_page
+ `status`=404
+ `page`
Bind an assembled page for HTTP `404` or `500` responses.
**> web_app_error_page app=`self` status=`status` page=`page`**
## sitemap
+ `path`=/sitemap.xml
+ `base`=""
+ `table`=None
+ `loc`=path
+ `limit`=1000
+ `items`=None
Serve `sitemap.xml`. Prefer `table` + `loc` column from the DB, or pass an `items` table with `loc`/`路径` rows.
**> web_app_sitemap app=`self` path=`path` base=`base` table=`table` loc=`loc` limit=`limit` items=`items`**
## robots
+ `body`=None
+ `sitemap`=None
Serve `/robots.txt`. Omit `body` to emit a default Allow-all file, optionally with a `Sitemap:` line.
**> web_app_robots app=`self` body=`body` sitemap=`sitemap`**
## upload
+ `path`=/_upload
+ `field`=file
+ `storage`
+ `prefix`=uploads/
+ `max_bytes`=5242880
+ `types`=None
Mount `POST path` for multipart file upload. `storage` is a `# storage` handle or `file:…` / `s3://…` URL. Optional `types` is a `|type|ext|` / `|类型|扩展名|` allowlist (or a MIME CSV string). Success returns JSON `{ok,key,size,content_type}`.
**> web_app_upload app=`self` path=`path` field=`field` storage=`storage` prefix=`prefix` max_bytes=`max_bytes` types=`types`**
## download
+ `path`=/_media/{*key}
+ `storage`
+ `disposition`=attachment
Mount `GET path` to stream an object. Path must capture `key` (use `{*key}` for nested keys). `disposition` is `attachment` or `inline`.
**> web_app_download app=`self` path=`path` storage=`storage` disposition=`disposition`**
# auth
+ `users`
+ `session_ttl`=3600
Session/auth helper. Constructs a config object; `login` validates against the users table. To gate `/admin` on this app, use `app.auth users=…` instead.
> ensure_plugin
**> web_auth_new users=`users` session_ttl=`session_ttl`**
## login
+ `username`
+ `password`
Validate credentials against the users table and create a session. Returns `{ok, session_id, username, role}`.
*users = self[^users]*
*ttl = self[^session_ttl]*
**> web_auth_login username=`username` password=`password` users=`users` session_ttl=`ttl`**
## check
+ `session_id`
Returns `{ok, username, role}` when the session is valid.
**> web_auth_check session_id=`session_id`**
## logout
+ `session_id`
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`**
# cache
+ `url`="memory:"
Key–value cache. Use `memory:` for in-process (tests / single process) or `redis://host:6379/0` for Redis.
> ensure_plugin
**> web_cache_new url=`url`**
## get
+ `key`
*url = self[^url]*
**> web_cache_get url=`url` key=`key`**
## set
+ `key`
+ `value`
+ `ttl`=None
Optional `ttl` is seconds until expiry.
*url = self[^url]*
**> web_cache_set url=`url` key=`key` value=`value` ttl=`ttl`**
## del
+ `key`
*url = self[^url]*
**> web_cache_del url=`url` key=`key`**
## exists
+ `key`
*url = self[^url]*
**> web_cache_exists url=`url` key=`key`**
## ttl
+ `key`
*url = self[^url]*
**> web_cache_ttl url=`url` key=`key`**
# storage
+ `url`="file:data/blobs"
Object storage. `file:dir` stores blobs on disk (offline / gold). `s3://bucket?endpoint=http://127.0.0.1:9000&access_key=…&secret_key=…` talks to MinIO / S3.
> ensure_plugin
**> web_storage_new url=`url`**
## put
+ `key`
+ `body`=None
+ `path`=None
+ `content_type`="application/octet-stream"
Provide either `body` (text) or `path` (local file to upload).
*url = self[^url]*
**> web_storage_put url=`url` key=`key` body=`body` path=`path` content_type=`content_type`**
## get
+ `key`
*url = self[^url]*
**> web_storage_get url=`url` key=`key`**
## delete
+ `key`
*url = self[^url]*
**> web_storage_delete url=`url` key=`key`**
## list
+ `prefix`=""
*url = self[^url]*
**> web_storage_list url=`url` prefix=`prefix`**
# media
+ `storage`=None
Offline helpers for upload validation and saving into `# storage` (also used by HTTP `app.upload`).
> ensure_plugin
**> web_media_new storage=`storage`**
## validate
+ `filename`
+ `content_type`="application/octet-stream"
+ `size`
+ `max_bytes`=5242880
+ `types`=None
**> web_upload_validate filename=`filename` content_type=`content_type` size=`size` max_bytes=`max_bytes` types=`types`**
## save
+ `path`
+ `key`=None
+ `content_type`="application/octet-stream"
+ `prefix`=uploads/
+ `storage`=None
*st = storage*
1. `st` == None
*st = self[^storage]*
2. *
**> web_upload_save storage=`st` path=`path` key=`key` content_type=`content_type` prefix=`prefix`**
# ws
+ `timeout_sec`=30
WebSocket client helper.
> ensure_plugin
`out` =
| timeout_sec | _type |
|-------------|-------|
| `timeout_sec` | ws |
**out**
## connect
+ `url`
+ `message`=""
+ `headers`=None
Single request–response: connect to `url`, send `message`, collect all server text replies, close. Returns `{ok, messages}`.
*timeout = self[^timeout_sec]*
**> web_ws_connect url=`url` message=`message` headers=`headers` timeout_sec=`timeout`**