gitoria

3.6 KB

1. \* A request in flight. Handed back by fetch()/fetchStart() — never `new`ed.
2. The request is already on the wire when you hold one: it has a thread of
3. its own, holding one costs a socket, not a fiber. With stream = true the
4. events below arrive AT this object. *\
6. \* A decoded piece of the body, token by token (stream mode). *\
7. emit chunk(
8. String chunk \\ the decoded bytes as they arrived
9. )
11. \* The stream's final frame — body is EMPTY, the chunks were the body. *\
12. emit done(
13. Number status \\ the HTTP status
14. Boolean ok \\ true for 2xx
15. Hybrid headers \\ response headers
16. String error \\ '' or the failure text
17. Boolean aborted \\ true when abort() cut it
18. )
20. Hybrid #handle
21. Number #srcId = 0
23. // Has the answer arrived? Never waits — a poll for code that wants to do
24. // something else in the meantime.
25. done() {
26. return #handle.done()
27. }
29. // THE WAIT. Blocks the calling fiber until the answer is in, then hands back a
30. // FetchResponse. A failed fetch (refused connection, timeout, TLS verification,
31. // too many redirects) surfaces here as a located error routed to `on Error`, so
32. // a caller that wants to survive one writes an `on Error(e)` handler.
33. response() {
34. let r = #handle.result()
35. // An `on Error` handler that ABSORBED the failure leaves the call yielding
36. // null (the plugin-error contract every `hl:` module follows). Hydrating null
37. // would be a second, misleading error, so a caught failure answers null —
38. // exactly what `hl:fs`'s file() does.
39. if (r == null) {
40. return null
41. }
42. return r > new FetchResponse()
43. }
45. // STREAM MODE (the LLM-token flow). `fetch(url, { stream = true })` calls this
46. // before handing the instance out: the ticket's own event source is registered
47. // AT this instance and the fan-out below re-emits every frame at itself, so app
48. // code holds nothing but the object and its events — `on p.chunk`, `on p.done`.
49. arm() {
50. #srcId = __native("eventloop.register", #handle.events(), "__fetchEvent")
51. }
53. // THE FAN-OUT: a native frame in, a DECLARED event out. The frames are Hybrids
54. // ({ tag, url, chunk } or { tag, url, status, ok, body, error, headers, aborted });
55. // `chunk` and `done` above declare TYPED parameters, so each field is handed over
56. // BY NAME — `emit chunk(ev)` would bind a Hybrid to `String chunk` and fail every
57. // frame (mission 257: it did).
58. //
59. // NAMED, NOT POSITIONAL, and that distinction cost the creator a night (2026-08-30).
60. // 257 fixed the Hybrid-into-String bind by emitting POSITIONALLY — `emit
61. // chunk(ev.chunk)` — which type-checks and is still wrong: every handler in this
62. // language receives a PAYLOAD OBJECT and destructures it. His own working code is
63. // `on stream.chunk({ chunk })`, exactly as `on server.line({ line, stream })` reads
64. // for hl:proc and as his `emit ready(port = …)` writes it. Positional emission
65. // hands `{ chunk }` a String, and the app dies with "Cannot destructure non-object
66. // value" — a DIFFERENT error from the one 257 fixed, on the same line of his app.
67. // `name = value` is the form that satisfies the typed declaration AND keeps
68. // destructuring working. Do not "simplify" it back.
69. on __fetchEvent(ev) {
70. if (ev.chunk != null) {
71. emit chunk(chunk = ev.chunk)
72. return null
73. }
74. // the final frame — retire the source so the loop can end by itself
75. __native("eventloop.unregister", #srcId)
76. emit done(status = ev.status, ok = ev.ok, headers = ev.headers, error = ev.error, aborted = ev.aborted)
77. return null
78. }
80. \* THE STOP BUTTON: abort this fetch — the socket is shut down, the peer
81. sees the disconnect and stops generating, and `done` arrives with
82. aborted = true. (fetchAbort(tag) cuts a whole tag at once.) *\
83. abort() {
84. return #handle.abort()
85. }