Files
marqdo/ext/web/route/index.mq.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- 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。
2026-11-18 10:29:26 +08:00

9.7 KiB
Executable File

markup, title, description, import
markup title description import
occlusion ext/web/route Declared Endpoint / Document route registration (ADR 0007).
cap table
ext/web/_capability/index.mq.md lib/table.mq.md

Routes declare the HTTP surface. Prefer Document/Endpoint metadata and serve for whole sites; use route handles only for explicit app assembly. To obtain an app use web.app on the facade; to discover a site's routes without a live app use web.inspect with root. A fresh call without app/root cannot inspect the private state of another running server.

marqdo call ext/web/route/index.mq.md new 'app={}' 'path="/hello"' 'page={"title":"Hello","body":"Hi"}' --effects plugin --session handbook --toget route --json
marqdo call ext/web/route/index.mq.md register 'route=$route' --effects plugin --session handbook --json

The returned registration is a value, not a listening server. Middleware and Endpoint handlers remain explicit; schema/auth resources live in their own packages. Update both route facades and HTTP artifact tests for registration changes; never introduce undeclared user URLs as a hidden convenience.

new

参数 类型 默认 说明
app any required app handle
path text required URL path
method text "GET" HTTP method
page any None Document or None
fn text "" endpoint member
request text "json" request kind
response text "json" response kind
auth text "" auth tag
class text "" route class
返回 类型 说明
result any route handle

Use app, path, method="GET", page=None, fn="", request="json", response="json", auth="", class="" as the inputs for this operation.

Build a declared route handle for app at path with method="GET" .

page=None holds a Document; fn="" names an Endpoint lib.member.

request="json", response="json", auth="", and class="" document the contract. Optional class values: execute, short, read, control (empty → heuristic / legacy_serial). This tool does not register yet — call register or use the facade web.route which registers in one step.

We Load the native plugin required by this operation.

out =

_type app path method page fn request response auth class
route app path method page fn request response auth class

Return out.

register

参数 类型 默认 说明
route any required route handle
app any None app or None
返回 类型 说明
result any registration result

Use route, app=None as the inputs for this operation.

Register declared route handle route on an app. Optional app=None falls back to the app stored on the route object so stepwise agent sessions can omit it. Page routes call web_app_route; Endpoint fn routes call web_app_invoke with method and body/return contract fields pulled from the handle. User routes must already be declared on this handle — this tool never invents paths. Prefer this free tool under --effects plugin rather than a method chain when driving registration from marqdo call. Soft-fails with ok=False when neither page nor fn is present, so callers can detect incomplete declarations early.

We Load the native plugin required by this operation. We retain a = app.

  1. a == None We retain a = Read app field).

_ = 1 We retain page = Read page field). We retain fn = Read fn field).

  1. page We retain path = Read path field). Return [Register declared route handle route on an app](web_app_route(app=a, path=path, page=page)).
  2. fn We retain path = Read path field). We retain method = Read method field). We retain request = Read request field). We retain response = Read response field). We retain class = Read class field). Return [Register declared route handle route on an app](web_app_invoke(app=a, path=path, method=method, fn=fn, body=request, return=response, class=class)).

Return [Set the ok field in the new record](table.put(in=None, at="ok", value=False)).

use

参数 类型 默认 说明
middleware any required middleware table
route any required route handle
返回 类型 说明
result any use result

Use middleware, route as the inputs for this operation.

Attach middleware table middleware to declared route handle route (|header|value| or named capability rows). Prefer first-class middleware tables over configure junk drawers. Call this free tool with --effects plugin.

We Load the native plugin required by this operation. Return [Attach middleware table middleware to declared route handle route (|header|value| or named capability rows)](web_route_use(route=route, middleware=middleware)).

route

参数 类型 默认 说明
app any required Application handle created by the public web app constructor
path any required URL path declared for this route
method any "GET" HTTP request method for the declared route
page any None Initial Document/page resource, or None for explicit later route mounts
fn any "" Endpoint member path; empty when mounting a Document page
request any "json" Request body format passed to the native Endpoint dispatcher
response any "json" Response format passed to the native Endpoint dispatcher
auth any "" Explicit route authentication policy label
class any "" Execution class: execute, short, read or control; empty keeps native heuristics
返回 类型 说明
result any Declared route handle retaining app, path, method, page or endpoint and dispatch fields

Use app, path, method="GET", page=None, fn="", request="json", response="json", auth="", class="" as the inputs for this operation.

Declared route handle for author method chains. Prefer web.route / Artifact type: endpoint discovery via web.serve. Optional class: execute | short | read | control (empty → heuristic / legacy_serial).

We Load the native plugin required by this operation.

out =

_type app path method page fn request response auth class
route app path method page fn request response auth class

Return out.

use

参数 类型 默认 说明
middleware any required middleware table
返回 类型 说明
result any use result

Use middleware as the inputs for this operation.

Attach middleware table to this route (|header|value| or named capability rows). Prefer explicit tables authors can read; do not restore a configure bag for headers and cors.

We Load the native plugin required by this operation. Return [Attach middleware table to this route (|header|value| or named capability rows)](web_route_use(route=self, middleware=middleware)).

register

参数 类型 默认 说明
app any None app or None
返回 类型 说明
result any registration result

Use app=None as the inputs for this operation.

Register this declared route on an app handle. When optional app is None, use the app stored on this route object so author chains can omit the argument after construction. Document pages call web_app_route with the stored path and page handle. Endpoint members call web_app_invoke with path, method, and the request/response/class contract fields from this route. Prefer Artifact discovery via web.serve for whole sites; use this method when assembling routes in memory for tests or advanced mounts. Returns a soft failure map when neither page nor fn is set, so callers can detect an incomplete declaration without a hard crash. Never invents an undeclared path — registration only publishes what this handle already carries.

We Load the native plugin required by this operation. We retain a = app.

  1. a == None We retain a = Read app field).

_ = 1 We retain page = Read page field). We retain fn = Read fn field).

  1. page We retain path = Read path field). Return [Register this declared route on an app handle](web_app_route(app=a, path=path, page=page)).
  2. fn We retain path = Read path field). We retain method = Read method field). We retain request = Read request field). We retain response = Read response field). We retain class = Read class field). Return [Register this declared route on an app handle](web_app_invoke(app=a, path=path, method=method, fn=fn, body=request, return=response, class=class)).

Return [Set the ok field in the new record](table.put(in=None, at="ok", value=False)).