notes

4.0 KB

1. \* hl:http1 — the native WebSocket server. Subclass it (`inherit
2. NativeWebSocketServer`) and answer the declared events below; each
3. connected peer arrives as a WsClient (send/ping/close). AUTO-LISTEN: the
4. file root IS the constructor and ends with listen(), so
5. `new NativeWebSocketServer(port = 8888)` serves immediately. *\
7. /* Mission 064 (decision D9): the h1 plugin performs the RFC 6455 Upgrade/101
8. handshake and framing (shared core plugins/http/ws_common.zig); this
9. wrapper maps the native event stream onto on/emit, mirroring
10. NativeHttpServer. A SUBCLASS does not inherit this run body and calls
11. listen() from its own root. */
13. \* A peer completed the upgrade and is connected. *\
14. emit connect(
15. WsClient client \\ the new peer — send/ping/close
16. )
18. \* A complete text (or binary) message arrived from a peer. *\
19. emit message(
20. WsClient client \\ who sent it
21. String data \\ the message payload
22. )
24. \* The peer answered a client.ping(). *\
25. emit pong(
26. WsClient client \\ who answered
27. )
29. \* A connection ended — the peer is already unregistered. *\
30. emit close(
31. WsClient client \\ who left
32. )
34. \* OPTIONAL: plain HTTP answered on the same port, exactly as
35. NativeHttpServer's request. *\
36. emit request(
37. Hybrid req \\ method, path, headers, body, bytes, params, respond
38. )
40. Number port = 8080 \\ the port listen() binds
41. String host = "0.0.0.0" \\ the interface to bind
42. Number threads = 4 \\ I/O worker threads
43. Boolean listening = false \\ true after a successful bind
44. Hybrid clients = {} \\ live WsClients by connection id
45. Number #srcId = 0
46. Number #wsSrcId = 0
48. \* Bind the configured port and start the WebSocket engine (idempotent). *\
49. listen() {
50. if (listening == true) {
51. return null
52. }
53. srv = __native("http1.create_server", port, host, "", "", threads)
54. if (srv == null) {
55. // A REFUSAL, NOT PROSE (mission 286) — same reason as NativeHttpServer's.
56. hlError("hl:http1: listen() failed: could not bind port " + port + " on " + host + " — the port is already taken. The line just above, 'bind() failed on port " + port + "', names the process holding it: stop that process, or start this app on another port (--port N, or HL_PORT=N)")
57. }
58. wsev = __native("http1.ws_events")
59. listening = true
60. #srcId = __native("eventloop.register", srv, "request")
61. #wsSrcId = __native("eventloop.register", wsev, "wsEvent")
62. }
64. \* One text frame to EVERY connected peer; answers how many received it. *\
65. broadcast(
66. String text \\ the frame to send
67. ) {
68. return __native("http1.ws_broadcast", text)
69. }
71. \* Stop this server: both event sources retired, workers joined, listener
72. closed — the port is free again. Answers false when not listening. *\
73. close() {
74. if (listening == false) {
75. return false
76. }
77. listening = false
78. __native("eventloop.unregister", #srcId)
79. __native("eventloop.unregister", #wsSrcId)
80. return __native("http1.close", port)
81. }
83. // Raw native events ({ kind, id, data, binary, code }) re-emitted as the
84. // documented surface — emit is the universal primitive.
85. on wsEvent(ev) {
86. key = "c" + ev.id
87. if (ev.kind == "connect") {
88. client = new WsClient(ev.id, ev.cookie, ev.host != '' ? ev.host : null, headerHash(ev.headers)) // the upgrade's cookie, host and headers ride with the connection (creator, 2026-09-12; tickets #74, #105)
89. clients[key] = client
90. emit connect(client)
91. }
92. if (ev.kind == "message") {
93. client = clients[key]
94. if (client != null) {
95. emit message(client, ev.data)
96. }
97. }
98. if (ev.kind == "pong") {
99. client = clients[key]
100. if (client != null) {
101. emit pong(client)
102. }
103. }
104. if (ev.kind == "close") {
105. client = clients[key]
106. clients[key] = null
107. if (client != null) {
108. emit close(client)
109. }
110. }
111. }
113. // The upgrade's headers arrive as `name: value` lines (names already lowercase);
114. // a connection is handed them as a hash (ticket #105).
115. headerHash(lines) {
116. let nl = "
117. "
118. let out = {}
119. if (lines == null || lines == '') { return out }
120. for (line of lines.split(nl)) {
121. let colon = line.indexOf(': ')
122. if (colon > 0) { out[line.slice(0, colon)] = line.slice(colon + 2) }
123. }
124. return out
125. }
127. // Run body: bind the configured port (idempotent, like NativeHttpServer).
128. listen()