WebSocket: the ypy-ws extension
A WebSocket is a two-way connection: the server can send at any time, and the page can send without a new request.
ypy-ws connects it to the attributes you already use. An element opens the socket, incoming messages are swapped into
the page, and another element sends its values through it.
Use it when messages go both ways at a high rate, such as a chat. When the page only listens, ypy-sse or
ypy-stream is simpler, because they are plain HTTP.
Load it
<script src="ypy.min.js"></script>
<script src="ext/ypy-ws.js"></script>The extension is part of ypy.max.
Connect and send
<div ypy-ws:connect="/chat/7/socket" ypy-target="#log" ypy-swap="beforeend">
<ul id="log"></ul>
<form ypy-ws:send>
<input name="text" autocomplete="off" required>
<button>Send</button>
</form>
</div>-
ypy-ws:connectopens the socket on itsypy-trigger(defaultload). A relative URL, or one that starts withhttp://orhttps://, becomesws://orwss://. -
ypy-ws:sendsends the element's values onsubmitfor a form,changefor a field andclickfor anything else. Setypy-triggerto change that. It uses the nearestypy-ws:connectabove it. - The socket closes when the element with
ypy-ws:connectleaves the page.
Messages from the server
| The server sends | What happens |
|---|---|
| a text message that is not JSON | it is swapped into the target as HTML |
JSON with a content field |
content is swapped; the object may also carry target, swap and select for this message |
JSON with no content |
nothing is swapped; listen to ypy:ws:before:message:incoming to use it |
{"content": "<li>Ana: hello</li>", "target": "#log", "swap": "beforeend"}An empty message does not clear the target.
Messages to the server
ypy-ws:send collects what a request would: the form values and ypy-vals. It sends them as one JSON object. Fields
with several values, such as checkboxes, become arrays. The same YPY-* headers that a request would carry go in a
headers member.
{"text": "hello", "headers": {"YPY-Request": "true", "YPY-Current-URL": "https://example.com/chat/7"}}To send something else, set detail.message.data in ypy:ws:before:message:outgoing: it is sent as it is.
Messages sent before the socket is open wait in a queue and go out as soon as it opens.
Attributes
| Attribute | Value | Meaning |
|---|---|---|
ypy-ws:connect |
URL | open the WebSocket on the trigger |
ypy-ws:send |
none | send this element's values over the socket of the nearest ypy-ws:connect |
ypy-ws-connect, ypy-ws-send |
old spellings; copied to the new names with a console warning |
Events
| Event | Cancelable | detail |
Fires |
|---|---|---|---|
ypy:ws:before:connection |
yes | connection |
before a socket is made and before each reconnect; cancel it to stop (a ypy:ws:close with reason cancelled follows) |
ypy:ws:after:connection |
no | connection |
the socket opened; queued messages go out right after |
ypy:ws:close |
no | connection, reason, code |
the socket closed; reason is closed, cancelled or removed; code is null unless the server closed it |
ypy:ws:error |
no | connection, error, url |
a socket error, a failed send, a full queue, or a send with no open socket |
ypy:ws:before:message:outgoing |
yes | connection, message, cancelled, waitUntil |
before a send; edit message.headers or message.values, set message.data, or cancel |
ypy:ws:after:message:outgoing |
no | connection, message |
after the message was written to the socket |
ypy:ws:before:message:incoming |
yes | connection, message, cancelled, waitUntil |
before an incoming message is swapped; cancel it to ignore it |
ypy:ws:after:message:incoming |
no | connection, message |
after it was processed |
detail.waitUntil(promise) delays the send or the processing until the promise settles.
Settings
Set them in ypy.config.ws, or for one element with ypy-config='{"ws":{...}}'.
| Setting | Default | Meaning |
|---|---|---|
ws.reconnect |
true |
reconnect after a close with one of reconnectCodes |
ws.reconnectCodes |
1001, 1005, 1006, 1011, 1012, 1013, 1014 |
close codes that trigger a reconnect; any other ends the connection |
ws.reconnectDelay |
500 |
first wait, in ms or "2s"; doubles on each attempt |
ws.reconnectMaxDelay |
60000 |
longest wait |
ws.reconnectMaxAttempts |
unlimited | attempts in a row before giving up |
ws.reconnectJitter |
0.3 |
random spread of each wait (0 is off) |
ws.pauseOnBackground |
true |
close while the tab is hidden, reconnect when it shows |
ws.heartbeat |
0 (off) |
close and reopen when no message arrives for this long, such as 45s |
ws.maxOutgoingMessagesQueueSize |
100 |
messages that may wait for the socket; the next one fires ypy:ws:error |
ws.protocols |
none | sub-protocols for the WebSocket constructor |
The browser does not show protocol ping frames to the page, so with ws.heartbeat the server has to send a text message
now and then.
Server
Use any WebSocket server library, and keep the messages in the shapes above: the page sends the form values as JSON, plus
a headers object, and the server answers with {"content": "<html>", "target": "#sel", "swap": "beforeend"}, where
target and swap are optional. The rules for the HTML are the same as for any answer: escape what users wrote.
Check the Origin of the handshake on the server, and authenticate the request that opens the socket. A WebSocket
handshake is a GET, so ypy-csrf adds no token to it, and the browser's CORS rules for fetch do not
apply to it.
Notes
- Swaps from a socket do not use view transitions.
-
A server that closes the socket with a code outside
reconnectCodes(for example1000or1008) ends the connection for good. That is the way to tell the page not to come back.