93 lines
4.5 KiB
Markdown
93 lines
4.5 KiB
Markdown
---
|
||
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`))*.
|