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

93 lines
4.5 KiB
Markdown
Raw Permalink 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.
---
markup: occlusion
title: ext/net/websocket
description: WebSocket client Resource (ADR 0007).
import:
plugin: lib/plugin.mq.md
sys: lib/sys.mq.md
table: lib/table.mq.md
---
This resource performs one bounded native WebSocket exchange and closes it. The [network entry](index.mq.md) shows the input contract and the distinction from pure URL encoding. Configure a controlled ws/wss endpoint and inspect ok/error, timeout and reply data before acting. New transport behavior belongs in the web plugin, with local tests for failed connections and oversized replies; this resource is not a persistent subscription service.
## _load
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | No business value on completion; a missing native plugin reports the cause and exits this run. |
Resolve and load the native web plugin before resource operations; missing binaries stop this run.
We retain **`p` = [Locate the installed native plugin](plugin.native_path(name="web"))**.
1. `p`
We **[Load the native plugin required by this operation](plugin.load(path=`p`))**.
2. *
We **[Print the prepared message](print(text="ext/net: native web plugin not found"))**.
We **[End this run with the selected exit status](sys.exit(code=1))**.
Return *None*.
## route
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| app | any | required | Prepared application returned by web.prepare |
| path | text | required | Declared WebSocket path, including optional path captures |
| mode | text | "echo" | echo, drain, broadcast or room |
| room_key | text | "" | Room template required by room mode |
| presence | bool | False | Publish native room presence messages |
| require_auth | any | None | None keeps private broadcast/room defaults; False explicitly opens a local demo |
| on_message | text | "" | Optional declared Marqdo callback member |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | Updated app with this explicitly declared WebSocket route |
Use `app`, `path`, `mode`="echo", `room_key`="", `presence`=False, `require_auth`=None and `on_message`="" to bind a server transport before web.listen. This function belongs to the network resource; it does not change Document layout or start a socket. Retain the returned app because native resource updates produce a new value. Room mode requires a room_key template; captures such as {id} select the room at request time. Broadcast and room routes require login unless the caller explicitly opts out. Public local demos should say why require_auth=False is intentional. Presence and callbacks retain the native transport's bounded message handling; they are not a client subscription object.
We **[Load the native transport implementation](_load())**.
Return *[Register this declared WebSocket transport](web_app_route_ws(app=`app`, path=`path`, echo=None, mode=`mode`, room_key=`room_key`, on_message=`on_message`, presence=`presence`, require_auth=`require_auth`))*.
# ws
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| timeout_sec | any | 30 | Request/response timeout in seconds |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | WebSocket client helper. |
Use `timeout_sec`=30 as the inputs for this operation.
WebSocket client helper.
We **[Load the native plugin required by this operation](_load())**.
`out` =
| timeout_sec | _type |
|-------------|-------|
| `timeout_sec` | ws |
Return *out*.
## connect
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| url | any | required | Resource connection URL; scheme selects the documented backend |
| message | any | "" | Outgoing WebSocket or application message |
| headers | any | None | HTTP request header record or None |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Single request–response: connect to `url`, send `message`, collect up to 256 server text replies (each up to 1 MiB), close. Transport errors and timeouts return `{ok:false, error}` instead of looking like an empty successful reply. |
Use `url`, `message`="", `headers`=None as the inputs for this operation.
Single request–response: connect to `url`, send `message`, collect up to 256 server text replies (each up to 1 MiB), close. Transport errors and timeouts return `{ok:false, error}` instead of looking like an empty successful reply.
We retain **`timeout` = [Read timeout_sec field](access(`self`, "timeout_sec"))**.
Return *[Single request–response: connect to url, send message, collect up to 256 server text replies (each up to 1 MiB), close](web_ws_connect(url=`url`, message=`message`, headers=`headers`, timeout_sec=`timeout`))*.