224 lines
9.7 KiB
Markdown
224 lines
9.7 KiB
Markdown
---
|
|
markup: occlusion
|
|
title: ext/web/route
|
|
description: Declared Endpoint / Document route registration (ADR 0007).
|
|
import:
|
|
cap: ext/web/_capability/index.mq.md
|
|
table: 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](../../web/web.mq.md); 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.
|
|
|
|
```sh
|
|
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](cap.load())**.
|
|
|
|
`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](cap.load())**.
|
|
We retain **a = app**.
|
|
1. `a` == None
|
|
We retain **`a` = [Read app field](access(`route`, "app"))**.
|
|
2. *
|
|
**_ = 1**
|
|
We retain **`page` = [Read page field](access(`route`, "page"))**.
|
|
We retain **`fn` = [Read fn field](access(`route`, "fn"))**.
|
|
1. `page`
|
|
We retain **`path` = [Read path field](access(`route`, "path"))**.
|
|
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](access(`route`, "path"))**.
|
|
We retain **`method` = [Read method field](access(`route`, "method"))**.
|
|
We retain **`request` = [Read request field](access(`route`, "request"))**.
|
|
We retain **`response` = [Read response field](access(`route`, "response"))**.
|
|
We retain **`class` = [Read class field](access(`route`, "class"))**.
|
|
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`))*.
|
|
3. *
|
|
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](cap.load())**.
|
|
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](cap.load())**.
|
|
|
|
`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](cap.load())**.
|
|
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](cap.load())**.
|
|
We retain **a = app**.
|
|
1. `a` == None
|
|
We retain **`a` = [Read app field](access(`self`, "app"))**.
|
|
2. *
|
|
**_ = 1**
|
|
We retain **`page` = [Read page field](access(`self`, "page"))**.
|
|
We retain **`fn` = [Read fn field](access(`self`, "fn"))**.
|
|
1. `page`
|
|
We retain **`path` = [Read path field](access(`self`, "path"))**.
|
|
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](access(`self`, "path"))**.
|
|
We retain **`method` = [Read method field](access(`self`, "method"))**.
|
|
We retain **`request` = [Read request field](access(`self`, "request"))**.
|
|
We retain **`response` = [Read response field](access(`self`, "response"))**.
|
|
We retain **`class` = [Read class field](access(`self`, "class"))**.
|
|
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`))*.
|
|
3. *
|
|
Return *[Set the ok field in the new record](table.put(in=None, at="ok", value=False))*.
|