notes

5.6 KB

1. // hl:fetch — the HTTP(S) client, function-module realm (mission 135).
2. // SERVER realm only: the browser has its own fetch, and hl:web's client bundle
3. // must keep using it rather than tunnelling requests through the server.
4. //
5. // import { fetch } from 'hl:fetch'
6. //
7. // res = fetch("https://api.example.com/users")
8. // res.status // 200
9. // res.ok // true
10. // res.headers["content-type"] // lowercased header names
11. // res.text() // the body as a String
12. // res.json() // the body parsed
13. //
14. // fetch(url, {
15. // method = "POST",
16. // headers = { authorization = "Bearer …" },
17. // json = { name = "Ada" }, // stringified, content-type set for you
18. // body = "raw bytes instead", // when you want to send it yourself
19. // timeoutMs = 5000, // the WHOLE exchange; default 30000
20. // maxRedirects = 5, // 0 returns the 3xx instead of following
21. // caFile = "/path/ca.pem", // an EXTRA trust anchor (see below)
22. // tag = "users" // echoed back, for completion events
23. // })
24. //
25. // TLS: certificate verification is ALWAYS ON — the system trust store plus a
26. // hostname check against the certificate. There is no verify-off switch, by
27. // design. To reach a server whose certificate the system does not know (a test
28. // fixture's self-signed pair, an internal CA), NAME it with `caFile`; that adds
29. // one anchor and leaves every other connection verified as before.
30. //
31. // PARALLELISM. `fetch()` starts the request and waits for the answer. To have
32. // several in flight at once, start them with `fetchStart()` — which never waits —
33. // and read them afterwards:
34. //
35. // pending = concurrent [ fetchStart(a), fetchStart(b), fetchStart(c) ]
36. // for (p of pending) { console.log(p.response().status) }
37. //
38. // (A `concurrent` arm runs to completion before its sibling starts, so an arm
39. // that waited on a socket would serialize the group. An arm that only starts a
40. // thread does not — which is why the wait is a separate call.)
41. //
42. // EVENTS. `completions()` is an ordinary event-loop source: register it and a
43. // finished fetch arrives as an event, so a server never waits for one at all.
44. //
45. // __native("eventloop.register", completions(), "fetched")
46. // on fetched(ev) { … } // { tag, url, status, ok, body, error, headers }
47. //
48. // STREAMING (the LLM-token mode). `stream = true` delivers the body INCREMENTALLY
49. // as chunk frames on the completions source instead of accumulating it — an SSE
50. // or NDJSON stream (OpenRouter, ollama, any OpenAI-style endpoint) arrives token
51. // by token; chunked transfer is decoded, anything else streams as read:
52. //
53. // __native("eventloop.register", completions(), "tok")
54. // p = fetchStart(url, { method = "POST", json = {…}, stream = true, tag = "llm" })
55. // on tok(ev) {
56. // if (ev.chunk != null) { …ev.chunk arrived… return null }
57. // …ev is the final { tag, status, ok, headers, error, aborted } — body is
58. // EMPTY, the chunks were the body…
59. //
60. // THE INTERRUPT: `fetchAbort("llm")` stops an in-flight stream mid-generation —
61. // the socket closes (the wire-level stop every LLM server understands), the
62. // final frame arrives with `aborted = true`.
63. // }
64. //
65. // A redirect is followed BEFORE streaming starts; only the final answer streams.
66. // `result()` still works: it waits for the stream's end and yields the summary.
67. //
68. // HTTP/1.1 only. An h2 client is a later slice (it needs client-side ALPN and a
69. // multiplexed connection pool); every request here sends `connection: close`.
71. // Start a request and wait for the answer. Equivalent to `fetchStart(…).response()`.
72. //
73. // EXCEPT in STREAM MODE, where waiting is the one thing a caller cannot want: the
74. // answer only ends when the stream does, so `stream = true` hands back the
75. // PendingFetch AT ONCE with its own event source already armed. That is what
76. // makes `on p.chunk` / `on p.done` work on nothing but the object — no global
77. // listener, no `completions()` registration, exactly as the module header and
78. // tests/native/plugins/049_fetch_stream.hl describe.
79. //
80. // (RESTORED 2026-08-29, mission 257: this branch was missing, so a streaming
81. // `fetch()` blocked until the stream ended and then returned a FetchResponse
82. // that no `on p.chunk` could ever fire on. Nothing caught it — every fetch test
83. // in the tree needed a fixture server that had gone missing too.)
84. fetch(url, options) {
85. let p = fetchStart(url, options)
86. if (options != null && options.stream == true) {
87. p.arm()
88. return p
89. }
90. return p.response()
91. }
93. // Start a request and return at once. The answer is read with `.response()`.
94. fetchStart(url, options) {
95. let o = options
96. if (o == null) {
97. o = {}
98. }
99. // `json = {…}` is the ergonomic half of "JSON both ways": serialize here,
100. // where JSON already lives, and let the native side add the content-type
101. // only when the caller did not set one.
102. if (o.json != null) {
103. o.body = JSON.stringify(o.json)
104. o.jsonBody = true
105. }
106. return {
107. #handle = __native("fetch.start", url, o);
108. } > new PendingFetch()
109. }
111. // The event-loop source of finished fetches. Calling it arms completion delivery
112. // for every fetch started from then on.
113. completions() {
114. return __native("fetch.completions")
115. }
117. // THE INTERRUPT (the LLM stop button): abort every in-flight fetch started with
118. // this `tag` — the socket is shut down, the peer sees the disconnect (an LLM
119. // server stops generating and billing), and the FINAL completion frame arrives
120. // with `aborted = true` and error "hl:fetch: aborted". Returns how many were
121. // aborted; 0 means nothing was in flight under that tag.
122. fetchAbort(String tag) {
123. return __native("fetch.abort", tag)
124. }