@dokebi/websocket 0.4.5 → 0.4.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AI.md +23 -2
- package/README.md +1 -1
- package/dist/client.d.ts +1 -0
- package/dist/client.js +4 -0
- package/dist/gateway.js +11 -5
- package/dist/index.js +1 -1
- package/package.json +6 -1
package/AI.md
CHANGED
|
@@ -106,10 +106,31 @@ sessionStorage.setItem('cid', clientId);
|
|
|
106
106
|
const socket = new WebSocket(`/ws?clientId=${clientId}&dokebiVersion=${BUILD_VERSION}`);
|
|
107
107
|
socket.onmessage = ({ data }) => handle(JSON.parse(data)); // replies and broadcasts are both { type, data } text
|
|
108
108
|
socket.onopen = () => reloadState(); // after reconnecting, read what was missed from the server
|
|
109
|
-
setInterval(() => socket.send('{"$dokebi":"ping-v1"}'), 15000);
|
|
109
|
+
setInterval(() => socket.send('{"$dokebi":"ping-v1","pong":true}'), 15000); // keeps it open under idleTimeoutMs; asks for a pong
|
|
110
110
|
```
|
|
111
111
|
|
|
112
|
-
-
|
|
112
|
+
- **A dead server (0.4.6, [D-0232](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0232-websocket-pong.md)).** A server that died without closing (a silent network drop, a dev reload that left the TCP connection open) leaves the client's socket "open" until TCP gives up, often 15 minutes; protocol pings do not help, because Node's and browsers' `WebSocket` answer them out of sight of the script. A ping that asks — `{"$dokebi":"ping-v1","pong":true}` — is answered with `{"$dokebi":"pong-v1"}` (sealed on a sealed connection; never a route's message). A plain `ping-v1` stays unanswered (pages before @dokebi/seal 0.4.5 would report the answer as an unknown frame), and a gateway before 0.4.6 answers neither. When nothing at all (no pong, no other frame) arrived for twice the ping interval, the server is gone: reconnect at once, without waiting for `close()` to finish. `@dokebi/websocket-client` (0.1.0, [D-0234](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0234-websocket-client-package.md); no dependencies — a process that only connects installs it alone, not this package's server stack; this package re-exports it as `@dokebi/websocket/client`) does this for any WHATWG `WebSocket` (Node's own, `ws`, a browser's): `heartbeat(socket, { intervalMs, onSilent, requirePong })` pings and calls `onSilent` once; silence counts only after the first pong (an older server is not taken for a dead one) unless `requirePong: true`. `isControlFrame(data)` tells a `$dokebi` frame from a message, and `PING_FRAME`, `PING_PONG_FRAME` and `PONG_FRAME` are the frames. The @dokebi/seal client does the same by itself (close 4001, reconnect).
|
|
113
|
+
|
|
114
|
+
```ts snippet
|
|
115
|
+
import { heartbeat, isControlFrame } from '@dokebi/websocket-client';
|
|
116
|
+
|
|
117
|
+
function connectAgent(): void {
|
|
118
|
+
const socket = new WebSocket(CENTER_URL);
|
|
119
|
+
socket.addEventListener('message', ({ data }) => {
|
|
120
|
+
if (!isControlFrame(data)) handle(JSON.parse(String(data)));
|
|
121
|
+
});
|
|
122
|
+
heartbeat(socket, {
|
|
123
|
+
intervalMs: 15_000,
|
|
124
|
+
requirePong: true, // the center runs @dokebi/websocket 0.4.6 or later
|
|
125
|
+
onSilent: () => {
|
|
126
|
+
socket.close(4001, 'Server silent');
|
|
127
|
+
connectAgent(); // now, not on the close event of a dead connection
|
|
128
|
+
},
|
|
129
|
+
});
|
|
130
|
+
}
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
- Broadcasts arrive as the bytes the server sent: a text frame when UTF-8 (`defineSocket`'s `{ type, data }` JSON), otherwise a binary frame. There is no envelope to unwrap (`delivery-v1`) and no ACK to send. The old browser entry `DeliveryReceiver` was removed in 0.2.0 (`@dokebi/websocket/client` is now the heartbeat above, 0.4.6, re-exported from `@dokebi/websocket-client` since 0.4.7). Use only the standard `WebSocket` API. The `{"$dokebi":"ack-v1"}` that old pages send is ignored, not closed (debug `ACK_IGNORED`).
|
|
113
134
|
- Broadcasts sent while disconnected or while closed as a slow consumer never come again. The screen reads the latest state from the server after reconnecting.
|
|
114
135
|
- Close codes: 4426 reload, 4409 `Replaced` (the same tenant, member and clientId connected again, on any server: the newest connection wins and the older one is closed; with a hub before that rule the newer one is refused instead, 4409 `Duplicate client`), 4408 idle, 1013 hub unavailable, slow consumer, or a replay nonce store that is full (D-0075) or failed (D-0096) (`Try again later`), 1012 server shutting down, 1011 unhandled handler error, 4415 sealed host but no `dokebi.seal` offered, 4400 sealed frame refused (§4a). 4400 and 4415 repeat on reconnect, so do not reconnect. Never reconnect after 4409 with the same clientId: it would replace the newer connection of that clientId, and the two would replace each other in turn. A tab that must stay live (a duplicated tab copies sessionStorage) takes a new clientId and connects again. A tab whose old socket was half open (a network switch) is not affected: its new connection is the newer one.
|
|
115
136
|
|
package/README.md
CHANGED
|
@@ -75,7 +75,7 @@ stop blocks new work, waits for received handlers and broadcasts being sent, the
|
|
|
75
75
|
- `defineSocket({ presence: true })` sends `{ type: 'presence', data: { tenant, joined, left } }` to each connection. Given a function, that function handles it as `(change, socket)`.
|
|
76
76
|
- The first notice a server receives may list connections that existed before as `joined`. Screens should read the list again when this message arrives.
|
|
77
77
|
|
|
78
|
-
**Is the page alive (`idleTimeoutMs`):** the browser's network layer answers WebSocket pings, so even a page frozen in bfcache or with stopped scripts looks alive. With `idleTimeoutMs` (default 0, off), a connection whose client sent nothing for that long is closed with `4408 Idle`. The client sends `{"$dokebi":"ping-v1"}` periodically from page script to show it is alive. This control frame never reaches the route.
|
|
78
|
+
**Is the page alive (`idleTimeoutMs`):** the browser's network layer answers WebSocket pings, so even a page frozen in bfcache or with stopped scripts looks alive. With `idleTimeoutMs` (default 0, off), a connection whose client sent nothing for that long is closed with `4408 Idle`. The client sends `{"$dokebi":"ping-v1"}` periodically from page script to show it is alive. This control frame never reaches the route. With `"pong": true` in it (0.4.6, D-0232) the gateway answers `{"$dokebi":"pong-v1"}`, so a client hears a server that died while its TCP connection stayed open: `heartbeat` of `@dokebi/websocket-client` (a client installs that alone; also re-exported as `@dokebi/websocket/client`) pings and reports twice the interval of silence.
|
|
79
79
|
|
|
80
80
|
**Connection lifecycle logs:** at debug it logs connect (`WebSocket connected`: connection ID, tenant, member, clientId, remote address, User-Agent, `Sec-Purpose`) and close (`WebSocket closed`: close code, reason, duration).
|
|
81
81
|
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from '@dokebi/websocket-client';
|
package/dist/client.js
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
// @dokebi/websocket/client (D-0232): the client side now lives in @dokebi/websocket-client, which a
|
|
2
|
+
// client installs alone, without this package's server stack (D-0234). Kept here so imports of
|
|
3
|
+
// `@dokebi/websocket/client` keep working.
|
|
4
|
+
export * from '@dokebi/websocket-client';
|
package/dist/gateway.js
CHANGED
|
@@ -3,6 +3,7 @@ import { randomUUID } from 'node:crypto';
|
|
|
3
3
|
import { setTimeout as delay, setImmediate as immediate } from 'node:timers/promises';
|
|
4
4
|
import { diagnostics } from '@dokebi/core/libraries';
|
|
5
5
|
import { runBeforeHijack } from '@dokebi/web/points';
|
|
6
|
+
import { PONG_FRAME } from '@dokebi/websocket-client';
|
|
6
7
|
import { WebsocketError } from './errors.js';
|
|
7
8
|
import { PLAIN_PROTOCOL, SEAL_PROTOCOL, } from './types.js';
|
|
8
9
|
/** `WebSocket.OPEN` of ws (a constant, so ws itself loads only when a route needs it). */
|
|
@@ -923,7 +924,7 @@ export class Gateway {
|
|
|
923
924
|
this.#refuse(value, id, error);
|
|
924
925
|
return;
|
|
925
926
|
}
|
|
926
|
-
if (text.charCodeAt(0) === 123 && this.#control(text, id))
|
|
927
|
+
if (text.charCodeAt(0) === 123 && this.#control(text, id, value))
|
|
927
928
|
return;
|
|
928
929
|
if (!this.#authorized(value) || !value.registration)
|
|
929
930
|
return;
|
|
@@ -932,7 +933,7 @@ export class Gateway {
|
|
|
932
933
|
return;
|
|
933
934
|
}
|
|
934
935
|
// Control frames are answered here, outside the route's message queue.
|
|
935
|
-
if (bytes[0] === 123 && this.#control(bytes.toString(), id))
|
|
936
|
+
if (bytes[0] === 123 && this.#control(bytes.toString(), id, value))
|
|
936
937
|
return;
|
|
937
938
|
if (this.#closing)
|
|
938
939
|
return;
|
|
@@ -970,7 +971,7 @@ export class Gateway {
|
|
|
970
971
|
* Answers a `$dokebi` control frame (ping-v1, ack-v1); false when `text` is not one, so the
|
|
971
972
|
* route gets it.
|
|
972
973
|
*/
|
|
973
|
-
#control(text, id) {
|
|
974
|
+
#control(text, id, value) {
|
|
974
975
|
let control;
|
|
975
976
|
try {
|
|
976
977
|
control = JSON.parse(text);
|
|
@@ -978,9 +979,14 @@ export class Gateway {
|
|
|
978
979
|
catch {
|
|
979
980
|
// dokebi-check: allow empty-catch a frame that is not JSON is the route's payload; the route owns its parsing
|
|
980
981
|
}
|
|
981
|
-
|
|
982
|
-
|
|
982
|
+
if (control?.$dokebi === 'ping-v1') {
|
|
983
|
+
// The client is alive (idleTimeoutMs). A ping that asks (`pong: true`, D-0232) is answered,
|
|
984
|
+
// so a client hears a dead server; a plain ping stays silent (pages before 0.4.6 of
|
|
985
|
+
// @dokebi/seal report an unknown frame). Sealed like every frame; #send logs its failures.
|
|
986
|
+
if (control.pong === true)
|
|
987
|
+
void this.#send(value, PONG_FRAME);
|
|
983
988
|
return true;
|
|
989
|
+
}
|
|
984
990
|
// A page loaded before D-0057 still acknowledges broadcasts: nothing to do, and no
|
|
985
991
|
// reason to close it. Counted at debug until it reloads.
|
|
986
992
|
if (control?.$dokebi === 'ack-v1') {
|
package/dist/index.js
CHANGED
|
@@ -59,7 +59,7 @@ class WebsocketRuntime {
|
|
|
59
59
|
/** Factory input: `{ app, options? }`. Options default to `app.config['dokebi-websocket']`. */
|
|
60
60
|
export const createPlugin = definePlugin({
|
|
61
61
|
name: 'dokebi-websocket',
|
|
62
|
-
version: '0.4.
|
|
62
|
+
version: '0.4.7',
|
|
63
63
|
core: '^0.4.2',
|
|
64
64
|
options,
|
|
65
65
|
contributes: [realtime],
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@dokebi/websocket",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.7",
|
|
4
4
|
"description": "WebSocket routes on @dokebi/web with rooms and broadcast across servers through @dokebi/websocket-hub.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"dokebi",
|
|
@@ -22,6 +22,10 @@
|
|
|
22
22
|
"./dependency": {
|
|
23
23
|
"types": "./dist/dependency.d.ts",
|
|
24
24
|
"import": "./dist/dependency.js"
|
|
25
|
+
},
|
|
26
|
+
"./client": {
|
|
27
|
+
"types": "./dist/client.d.ts",
|
|
28
|
+
"import": "./dist/client.js"
|
|
25
29
|
}
|
|
26
30
|
},
|
|
27
31
|
"files": [
|
|
@@ -40,6 +44,7 @@
|
|
|
40
44
|
"test": "node -e \"require('node:fs').rmSync('.tmp/tests',{recursive:true,force:true})\" && tsc -p tsconfig.test.json && node --test \".tmp/tests/tests/*.test.js\""
|
|
41
45
|
},
|
|
42
46
|
"dependencies": {
|
|
47
|
+
"@dokebi/websocket-client": "^0.1.0",
|
|
43
48
|
"@fastify/websocket": "11.3.4",
|
|
44
49
|
"ws": "8.22.0"
|
|
45
50
|
},
|