notes

3.3 KB

1. \* hl:http1 — the OUTGOING WebSocket client (ticket #109). Subclass it
2. (`inherit WebSocketClient`) and answer `on open()`, `on message(text)`
3. and `on close(code)`. AUTO-CONNECT: the file root IS the constructor and
4. its last statement is connect(), so `new WebSocketClient(url = "ws://…")`
5. dials immediately, mirroring NativeHttpServer's AUTO-LISTEN. `wss://`
6. uses the same client TLS as hl:fetch: the system trust store, hostname
7. verification always on, and `caFile` names an EXTRA anchor for a
8. self-signed test fixture (never a replacement for the system store). *\
10. /* Ping/pong is entirely automatic (mission 091's liveness sweep, mirrored
11. here): a quiet connection is pinged and dropped if the pong doesn't
12. answer in time, and any inbound ping is answered with a pong — neither
13. ever reaches `.hl`, the protocol requires them and they are not
14. application information. RECONNECT IS NEVER AUTOMATIC: a dropped
15. connection reaches you as exactly one `close` event and nothing here
16. dials again on its own — call connect() again yourself, e.g. from your
17. own `on close`, if you want a reconnect policy. */
19. \* The connection is open and ready for send(). *\
20. emit open()
22. \* One complete text (or binary) message arrived from the peer. *\
23. emit message(
24. String data \\ the message payload
25. )
27. \* The connection ended — at most one `open` ever preceded it (a connection
28. that never opened still gets exactly one `close`: 1006 for a dial that
29. never reached a peer, 1002 for a handshake the peer answered but got
30. wrong). *\
31. emit close(
32. Number code \\ the WebSocket close code (RFC 6455 §7.4)
33. )
35. String url = null \\ "ws://host[:port][/path]" or "wss://…"
36. Hybrid headers = {} \\ extra headers on the Upgrade request
37. String caFile = null \\ wss:// only — an extra trust anchor, exactly hl:fetch's field of the same name
38. Boolean connected = false \\ true between `open` and `close`
39. Number #id = 0
40. Number #srcId = 0
42. \* Dial the configured url (idempotent — a connect() while already dialling
43. or open is a no-op: false). Ping/pong needs no call here; it is
44. automatic — see above. *\
45. connect() {
46. if (#id != 0) {
47. return false
48. }
49. id = __native("http1.wsc_connect", url, { headers = headers; caFile = caFile; })
50. if (id == null) {
51. hlError("hl:http1: WebSocketClient connect() needs a ws:// or wss:// url — got " + url)
52. }
53. #id = id
54. ev = __native("http1.wsc_events", id)
55. #srcId = __native("eventloop.register", ev, "wscEvent")
56. return true
57. }
59. \* One text frame to the peer; false when not open. *\
60. send(
61. String text \\ the frame to send
62. ) {
63. return __native("http1.wsc_send", #id, text)
64. }
66. \* Close this connection; `on close` still fires once the peer's echo (or a
67. timeout) completes the handshake. False when not open. *\
68. close() {
69. return __native("http1.wsc_close", #id)
70. }
72. // Raw native events ({ kind, data, code }) re-emitted as the documented
73. // surface — emit is the universal primitive (mirrors NativeWebSocketServer).
74. on wscEvent(ev) {
75. if (ev.kind == "open") {
76. connected = true
77. emit open()
78. }
79. if (ev.kind == "message") {
80. emit message(ev.data)
81. }
82. if (ev.kind == "close") {
83. connected = false
84. __native("eventloop.unregister", #srcId)
85. #id = 0 // connect() again is allowed from here — reconnect is the caller's choice, never automatic
86. emit close(ev.code)
87. }
88. }
90. // Run body: the constructor's last act — dial the configured url.
91. connect()