Files
marqdo/ext/net/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

3.2 KiB
Executable File

markup, title, import
markup title import
occlusion Network resources — URL data and WebSocket exchanges
url_api socket_api
ext/net/url.mq.md ext/net/websocket.mq.md

This package provides URL encoding, the small HTTP result constructor, and a native WebSocket request/response resource. For HTTP clients with status, timeout, response limits and downloads, read the standard library net.mq.md directly. The HTTP leaf here constructs a result record; its name does not imply an implemented HTTP client. 绑定服务端运输使用 websocket.route;中文入口是实时绑定,它与一次客户端 exchange 的生命周期不同。

URL encoding is pure and needs no plugin. This command is ready to run from the repository root:

marqdo call ext/net/index.mq.md encode 'text="Marqdo notes/one"' --json

WebSocket exchanges need the native web plugin and an explicitly chosen server. Build the plugin with scripts/build-web-plugin.sh, then supply a controlled endpoint to exchange. No example opens a public socket implicitly. The resource closes after one bounded exchange; it is not a persistent subscription API. Read the returned ok/error as well as the reply data before using the outcome.

Develop URL transformations by composing the public standard library; native transport belongs in the web plugin. Preserve timeout units, byte/reply caps and close behavior. Add controlled local server tests for transport failures and timeouts instead of treating an empty reply as success.

encode

参数 类型 默认 说明
text text required Text component to percent-encode; this does not fetch a URL
返回 类型 说明
result text Encoded URL component returned by the public encoding helper

The input text is content for an encoded component, not an already assembled URL to navigate. Keeping this transformation separate makes it possible to build request data without network permission. We return Percent-encode the selected component so the caller can place it in the intended path or query according to its own URL structure.

exchange

参数 类型 默认 说明
url text required Explicit ws/wss endpoint controlled by the caller
message text "" Single outgoing text message
timeout_sec number 30 Positive exchange timeout in seconds
返回 类型 说明
result any Native exchange result; failures carry ok=false/error instead of an empty successful reply

The caller supplies url, optionally message="" and timeout_sec=30. This tool performs a real exchange, so it needs plugin permission and an available endpoint. The native leaf caps replies and frame sizes and closes the connection before returning; it does not retry a send.

We create socket = Configure a bounded WebSocket receiver, then return [Send the message and collect the bounded reply](> socket.connect url=url message=message ). Inspect the actual result before deciding whether a follow-up request is appropriate.