tickets

4.2 KB

1. \* hl:http1 — the native HTTP/1.1 server. Subclass it (`inherit
2. NativeHttpServer`) and answer `on request(req)` with a Response.
3. AUTO-LISTEN: the file root IS the constructor and its last statement is
4. listen(), so `new NativeHttpServer(port = 8888)` binds 8888 with no
5. explicit call. *\
7. /* Split from the former multi-class server.hl (mission 027). listen() is
8. idempotent (the `listening` guard). A SUBCLASS does NOT inherit this run
9. body — parent run bodies never run — so subclasses call listen() from
10. their own root. No base `on request` handler here: the loop dispatches to
11. the concrete instance's handlers, and old-form inheritance copies
12. handlers — a base default would double-fire (mission 052). */
14. \* One HTTP request reached this server — answer a Response (or hold
15. req.respond for the streaming/deferred forms). *\
16. emit request(
17. Hybrid req \\ method, path, headers, body, bytes, params, respond
18. )
20. Number port = 8080 \\ the port bind() takes
21. String host = "0.0.0.0" \\ the interface to bind
22. String tls_cert = null \\ PEM certificate path — with tls_key, serve https
23. String tls_key = null \\ PEM key path
24. Number threads = 4 \\ I/O worker threads
25. Boolean listening = false \\ true after a successful bind
26. Number #srcId = 0
28. handleError(err) {
29. console.log("Server error: " + err)
30. }
32. \* Bind the configured port (idempotent — an extra listen() is harmless).
34. A FAILED BIND IS A REFUSAL, NOT A LINE OF PROSE (mission 286). This used
35. to print `listen() failed: …` on stderr and return, so the process stayed
36. alive with no socket and — because the event loop was still running for
37. whatever else had registered — exited 0 or never exited at all. Every
38. supervisor, deploy script and CI step was told the server started. A
39. server that cannot serve says so and fails; the located form is below. *\
40. listen() {
41. if (listening == true) {
42. return null
43. }
44. if (this.bind() != true) {
45. 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)")
46. }
47. return null
48. }
50. \* The bind itself, without the idempotence guard: a subclass that answers
51. for its own double-listen policy (hl:web refuses one) still needs the one
52. place where the socket is actually opened.
54. ANSWERS true/false RATHER THAN RAISING (mission 286), because the caller
55. owns the wording AND the location: hl:web can point its refusal at the
56. manifest member that chose the port, which this file cannot see. Every
57. caller must treat false as fatal — there is no third answer. *\
58. bind() {
59. srv = __native("http1.create_server", port, host, tls_cert, tls_key, threads)
60. if (srv == null) {
61. return false
62. }
63. listening = true
64. #srcId = __native("eventloop.register", srv, "request")
65. return true
66. }
68. \* Turn ON the RFC 6455 WebSocket engine for the port this server already
69. bound: an Upgrade is answered inline in the I/O worker and
70. the raw stream arrives at your own `on wsEvent` — WebSockets on the same
71. port, no second listener. Separate from bind() because a plain HTTP
72. server has no reason to start the engine thread. *\
73. sockets() {
74. __native("eventloop.register", __native("http1.ws_events"), "wsEvent")
75. }
77. \* Stop this server: the event source is retired (the loop can end by
78. itself) and the native side joins the workers and closes the listener —
79. the port is immediately free for a new bind(). Answers false when the
80. server was not listening.
82. SAFE FROM INSIDE A HANDLER (mission 260), and immediate — never deferred.
83. The request you are answering is untouched: its socket is already your
84. `req.respond` handle, so returning a Response after close() still reaches
85. the client. A request that was parsed but can no longer be dispatched
86. (the source is gone) is refused `503 Service Unavailable`; a connection
87. accepted but not yet parsed is simply closed. *\
88. close() {
89. if (listening == false) {
90. return false
91. }
92. listening = false
93. __native("eventloop.unregister", #srcId)
94. return __native("http1.close", port)
95. }
97. // Run body: the constructor's last act — bind the configured port.
98. listen()