@procedures/client 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @procedures/client
 
+## 0.7.0
+
+### Minor Changes
+
+- 841d083: An NDJSON stream over HTTP gets keep-alive lines. Before, a proxy or a client with an idle timeout (for example 300 s) closed a long procedure that was quiet for that time.
+  
+  - `HttpServerTransport` writes a keep-alive line, a blank line, after each quiet time of the new option `keepAlive` (default `seconds(15)`, `TIMER_DEFAULTS.httpServer.keepAliveMs`). Each line starts the time again. No keep-alive line comes after the `done` line, an `error` line, an abort or a closed connection. `keepAlive: false` turns it off.
+  - The new option `clock` of `HttpServerTransport` is the clock of the keep-alive timers. A test gives the `fakeClock` of `@mark1russell7/service/testing`.
+  - A keep-alive line has no `seq`, so the sequence check of the reader sees no gap. `WIRE-PROTOCOL.md` specifies the line: it is an additive change of protocol v1, because each reader skipped a blank line before.
+  - New `writeNdjsonStream(res, items, options?)` in `@procedures/client/node`. It writes the NDJSON stream response of protocol v1 for a `ServerResponse` of `node:http`, without Express. It writes the headers, the `item`, `done` and `error` lines with `seq`, and the keep-alive lines. It waits for `drain` when the buffer is full, and it stops when the connection closes or `signal` aborts. Its options are `signal`, `keepAlive`, `errorOf` and `clock`. `HttpServerTransport` uses it, so the two write the same bytes.
+  - `HttpTransport` gives each item of an NDJSON stream the metadata key `stream` with the value `true` (the new constant `STREAM_ITEM_METADATA_KEY`). The error item that ends the stream has it too. The key does not cross the wire, and the client removes a key `stream` that the peer sent.
+  - When the client goes away while the handler is quiet, the writer of the stream stops at once. Before, it waited for the next item of a handler that ignores its signal.
+
+### Patch Changes
+
+- 389b054: A token check no longer tells the length of the token through its time. The peer compares the SHA-256 digests of the two tokens with `timingSafeEqual`. The `tokenMatches` of the client, which runs in a browser too, compares each character of the expected token for each presented token. Before, a token of another length returned at once. The re-audit of jarvis found it.
+
 ## 0.6.0
 
 No changes in this release.

package/README.md

@@ -567,13 +567,52 @@ await server.stop()
 new HttpServerTransport(server: Server, options: HttpServerTransportOptions)
 
 interface HttpServerTransportOptions {
-  port: number;
-  hostname?: string;
+  app: Express;                  // required
+  httpServer?: HttpServer;       // an existing server: the transport does not listen
+  port?: number;                 // default: 3000
+  host?: string;                 // default: "127.0.0.1"
+  basePath?: string;             // default: "/api"
   urlStrategy?: HttpUrlStrategy;
-  cors?: boolean | CorsOptions;
+  cors?: boolean;
+  corsOptions?: { origin?: string | string[]; methods?: string[]; allowedHeaders?: string[]; credentials?: boolean };
+  bodyLimit?: number;            // default: 1 MiB
+  keepAlive?: Duration | false;  // default: seconds(15)
+  clock?: Clock;                 // the clock of the keep-alive timers
+}
+```
+
+A client that accepts `application/x-ndjson` gets a stream as NDJSON lines ([WIRE-PROTOCOL.md](../documentation/WIRE-PROTOCOL.md)).
+
+- After each quiet time of `keepAlive`, the server writes a keep-alive line: a blank line. Thus a proxy or a client with an idle timeout does not close a long, quiet stream.
+- Each line starts the quiet time again. No keep-alive line comes after the end, an error, an abort or a closed connection.
+- `keepAlive: false` turns the keep-alive lines off.
+- The HTTP client skips each blank line. Each item that it reads from an NDJSON stream has the metadata key `stream: true` (`STREAM_ITEM_METADATA_KEY`).
+
+A server without Express writes the same lines with `writeNdjsonStream` of `@procedures/client/node`:
+
+```typescript
+import { createServer } from "node:http";
+import { seconds } from "@procedures/client";
+import { writeNdjsonStream } from "@procedures/client/node";
+
+async function* progress() {
+  for (let step = 1; step <= 3; step++) {
+    await new Promise((resolve) => setTimeout(resolve, 60_000)); // a quiet minute: 4 keep-alive lines
+    yield { step };
+  }
 }
+
+createServer((req, res) => {
+  // The headers, the item, done and error lines with seq, the keep-alive lines and the backpressure
+  void writeNdjsonStream(res, progress(), {
+    keepAlive: seconds(15),
+    errorOf: (error) => ({ code: "UNAVAILABLE", message: String(error), retryable: true }),
+  });
+}).listen(3000);
 ```
 
+The promise of `writeNdjsonStream` resolves when the response ends. A closed connection or an abort of `signal` stops the stream, and the iterator of the items gets `return()`.
+
 #### WebSocket Server Transport
 ```typescript
 new WebSocketServerTransport(server: Server, options: WebSocketServerTransportOptions)
@@ -642,7 +681,7 @@ import { ... } from "@procedures/client/events";
 |---|---|
 | `@procedures/client` | Node. The browser entry and the server transports. Its `WebSocketTransport` uses the global `WebSocket`. |
 | `@procedures/client/browser` | A browser bundle. It does not import `http` or `ws`. |
-| `@procedures/client/node` | Node. A `WebSocketTransport` whose sockets are of the `ws` package: a drop ends a socket at once. |
+| `@procedures/client/node` | Node. A `WebSocketTransport` whose sockets are of the `ws` package: a drop ends a socket at once. `writeNdjsonStream`: the NDJSON stream response of `HttpServerTransport`, for a `ServerResponse` of `node:http`. |
 | `@procedures/client/register` | It registers the core procedures in the global registry. |
 
 ## Procedure Discovery