@procedures/http 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# @procedures/http
+
+## 0.4.0
+
+### Minor Changes
+
+- ff87747: `http.ndjson` and `http.sse` send a POST too. Their inputs have `method` (`GET` or `POST`), `json` (a body of JSON) and `body` (a body of text), as `http.request` has them. The default method is `POST` with a body, and `GET` without one. An LLM API sends its answer to a POST as server-sent events: `http.sse` now reads such a stream.
+  
+  A POST of a stream gets the host check, the size limit of the request body, `timeoutMs`, `idleTimeoutMs` and the deadline of the call. Two bodies, or a `GET` with a body, fail before the request.
+  
+  A POST can change remote data, so the two streams now declare `writes: ["network"]`, as `http.json` does. Before, they declared `writes: []`.
+
+### Patch Changes
+
+- Updated dependencies [d919678]
+- Updated dependencies [057d69a]
+- Updated dependencies [b2a1a1e]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [afd6a19]
+- Updated dependencies [057d69a]
+- Updated dependencies [4e751da]
+  - @procedures/client@0.4.0
+
+## 0.3.0
+
+### Minor Changes
+
+- a6b01a9: The new package `@procedures/http` (roadmap R38) has four procedures: `http.request` (each method, a body of text, JSON or base64, and a response as text, JSON or base64), `http.json` (a GET or a POST of JSON), `http.ndjson` (a stream of the JSON values of the lines) and `http.sse` (a stream of server-sent events). `http.request` and `http.json` declare `reads: ["network"]` and `writes: ["network"]`. The two streams send only a GET, so they declare `writes: []`, and they declare `stream: { unbounded: true }`.
+  
+  The default module reaches each public host and refuses loopback, private, link-local, shared, multicast and reserved addresses. `createHttpModule({ allow, publicHosts, maxRequestBytes, maxResponseBytes, resolve })` gives the procedures with more hosts: host names, wildcards, IP addresses and CIDR ranges, each with an optional port. The check resolves the host name, and the connection uses only the addresses that passed the check. Each redirect gets the same check. A refusal has the code `FORBIDDEN` and the new reason `host-not-allowed` (the type `ForbiddenReason` of `@procedures/client`).
+  
+  A call stops at the earliest of its deadline, the abort of the caller and `timeoutMs`. A stream also stops after `idleTimeoutMs` without data. The body of a response has a limit of 10 MiB by default, and the limit counts the decoded bytes of a compressed body.
+
+### Patch Changes
+
+- Updated dependencies [ddea529]
+- Updated dependencies [b2a3e3a]
+- Updated dependencies [a8c47f1]
+- Updated dependencies [381ce3a]
+- Updated dependencies [0c627f8]
+- Updated dependencies [ae7f05f]
+- Updated dependencies [7873940]
+- Updated dependencies [a70d445]
+- Updated dependencies [bc70357]
+- Updated dependencies [07cc998]
+- Updated dependencies [a6b01a9]
+- Updated dependencies [c799cdd]
+- Updated dependencies [540f8d9]
+- Updated dependencies [b6daaec]
+- Updated dependencies [5b9264e]
+- Updated dependencies [956e88b]
+- Updated dependencies [ff62281]
+- Updated dependencies [d81d0ed]
+- Updated dependencies [aa67cc7]
+- Updated dependencies [061fa22]
+- Updated dependencies [cfb9d69]
+- Updated dependencies [43f7de5]
+- Updated dependencies [b07bb50]
+- Updated dependencies [4a3bfa1]
+- Updated dependencies [bd0b626]
+- Updated dependencies [a6be873]
+- Updated dependencies [fb30718]
+- Updated dependencies [c5528e4]
+- Updated dependencies [fee5d9c]
+- Updated dependencies [21f7743]
+- Updated dependencies [31a0b46]
+  - @procedures/client@0.3.0

package/README.md

@@ -14,10 +14,10 @@ HTTP requests as procedures. A host allowlist refuses loopback, private and link
 |---|---|---|
 | `http.request` | It sends a request with each method and gives the status, the headers and the body. | reads and writes `network` |
 | `http.json` | It sends a GET or a POST of JSON and gives the parsed body. | reads and writes `network` |
-| `http.ndjson` | It sends a GET and gives a stream of the JSON values of the lines. | reads `network` |
-| `http.sse` | It sends a GET and gives a stream of server-sent events. | reads `network` |
+| `http.ndjson` | It sends a GET or a POST and gives a stream of the JSON values of the lines. | reads and writes `network` |
+| `http.sse` | It sends a GET or a POST and gives a stream of server-sent events. | reads and writes `network` |
 
-- `http.request` and `http.json` can change remote data with a POST, a PUT or a DELETE, so they declare a write. The two stream procedures send only a GET, so they change nothing.
+- Each procedure can change remote data with a POST, so each procedure declares a write. `http.request` also sends a PUT or a DELETE.
 - `http.ndjson` and `http.sse` declare `stream: { unbounded: true }`, because a server can send a stream without an end. A face that collects a stream refuses them or stops them at its limits.
 
 ```ts
@@ -27,6 +27,29 @@ await client.call(["http", "json"], { url: "https://api.github.com/repos/nodejs/
 await client.call(["http", "request"], { url: "https://example.com/upload", method: "PUT", body: "text" });
 ```
 
+### The streams of a POST
+
+An LLM API sends its answer to a POST as server-sent events. `http.sse` and `http.ndjson` take the same request fields as `http.request`:
+
+| Field | Meaning |
+|---|---|
+| `method` | `GET` or `POST`. The default is `POST` with `body` or `json`, and `GET` without them. |
+| `json` | A body of JSON. The procedure sets `content-type: application/json`. |
+| `body` | A body of text. The procedure sets `content-type: text/plain; charset=utf-8`. |
+| `headers` | The headers of the request. A header of the input replaces a header that the procedure sets. |
+
+```ts
+const events = client.stream(["http", "sse"], {
+  url: "https://api.example.com/v1/chat",
+  headers: { authorization: `Bearer ${key}` },
+  json: { prompt: "Hello", stream: true },
+});
+for await (const event of events) console.log(event.data);
+```
+
+- A POST of a stream gets the same host check, size limit of the request, time limits and deadline as the other requests.
+- Two bodies, or a `GET` with a body, fail before the request.
+
 ## The hosts
 
 The default module (`httpModule`) reaches each public host. It refuses these addresses:
@@ -106,6 +129,7 @@ const registry = createRegistry(createHttpModule({ allow: ["localhost:11434", "1
 - The parse obeys the rules of the HTML standard. A line ends at CR, LF or CRLF. A blank line sends an event. A line that starts with a colon is a comment.
 - An event has `event` (`message` by default), `data`, the last event ID `id` and `retry`.
 - The procedure does not connect again after the end of the stream. To continue, a caller sends the last ID in `lastEventId`.
+- A redirect of a POST obeys the rules of the redirects. A 303, or a 301 or 302, continues with a GET without the body.
 
 ## Limits of this package