Files
marqdo/ext/net/index.mq.md

64 lines
3.2 KiB
Markdown

---
markup: occlusion
title: Network resources — URL data and WebSocket exchanges
import:
url_api: ext/net/url.mq.md
socket_api: ext/net/websocket.mq.md
---
This package provides [URL encoding](url.mq.md), the small [HTTP result constructor](http.mq.md),
and a native [WebSocket request/response resource](websocket.mq.md). 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;中文入口是[实时绑定](实时.mq.md),它与一次客户端 exchange 的生命周期不同。
URL encoding is pure and needs no plugin. This command is ready to run from the repository root:
```sh
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](url_api.encode(text=`text`))*
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](socket_api.ws(timeout_sec=`timeout_sec`))**,
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.