@procedures/client 0.19.0 → 0.21.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @procedures/client
 
+## 0.21.0
+
+No changes in this release.
+
+## 0.20.0
+
+### Minor Changes
+
+- 5f49860: The root of `@procedures/client` and the entry `@procedures/client/server` do not export the server transports (CLI-6 step 2). Thus the root imports no `http`, no `ws` and no `express`, and its declarations name none of them (CLI-61). This change is a break of the server stack, thus it is its own MINOR (decision D13). The PATCH 0.14.1 marked each removed name as `@deprecated`.
+  
+  - Removed from the root and from `./server`: `HttpServerTransport`, `HttpServerTransportOptions`, `HttpUrlStrategy`, `WebSocketServerTransport`, `WebSocketServerTransportOptions`, `WebSocketAuthHandler`, `WebSocketConnectionHandler` and `WebSocketMessage`. `@procedures/client/node` exports each of them, as before.
+  - Changed: `HttpUrlStrategy` takes a structural request, `UrlStrategyRequest`, not the `Request` of Express. `UrlStrategyRequest` has `method`, `path`, `url` and `headers`, and the optional `query` and `body`. A `Request` of Express agrees with it, and so does the `UrlRequest` of `procedureHandler`. `HttpServerTransport` still gives the strategy the request of Express. `@procedures/client/node` exports `UrlStrategyRequest`.
+  - Changed: the headers of `GuardedRequest` (the request of `checkBrowserRequest`) and of `hasAmbientCredentials` have the new structural type `GuardedHeaders`, not `IncomingHttpHeaders` of `node:http`. The headers of an `IncomingMessage` agree with it, so a call with a request of Node does not change.
+  - New: the root exports the types `RoutedRequest` and `GuardedHeaders`. `./server` exports `RoutedRequest`.
+  - New: the root is a browser entry (`client.browser`). The CI check bundles it for a browser, and a test examines the declarations of each entry other than `./node`. A project that checks the declarations of its libraries (`skipLibCheck: false`) and imports the root needs no `@types/express`.
+  
+  MINOR: before 1.0.0, a break of the public API raises the MINOR. The removal of exports and the new parameter type of `HttpUrlStrategy` break the API.
+  
+  Migration:
+  
+  - Import `HttpServerTransport`, `WebSocketServerTransport` and their types from `@procedures/client/node`.
+  - A URL strategy whose parameter has the type `express.Request` does not compile as an `HttpUrlStrategy`. Give the parameter the type `UrlStrategyRequest` of `@procedures/client/node`, or give it no type: `HttpUrlStrategy` gives it the type.
+  - A strategy that reads a part of the Express request outside `UrlStrategyRequest`, for example `req.params`, casts the request: `(req as express.Request).params`.
+  - Code that reads a header of `GuardedHeaders` without a declared property, for example `accept`, gets `string | string[] | undefined`. Examine the value with `typeof` before use.
+  - Before, an import of the root also loaded the types of Node (`@types/node`) into the program. A project that used `process`, `Buffer`, `URL`, `setTimeout` or a `node:` module without `@types/node` in its own configuration compiled only because of that. Such a project fails to compile after this release. Add `@types/node` to its development dependencies and `"types": ["node"]` to its `tsconfig.json`. In this repository, `@procedures/archive`, `@procedures/env`, `@procedures/gh`, `@procedures/http`, `@procedures/llm`, `@procedures/npm` and `@procedures/schedule` got the `node` feature of `cue-config` for this reason. Their APIs do not change.
+  
+  The migration steps of the known consumers:
+  
+  - The site: no change. It imports none of these names. It names `HttpServerTransport` and `WebSocketServerTransport` only in the text of its journey.
+  - MiniMongo: no change. It imports none of these names, and its host uses `runProcedureHost`. Its `vite.config.ts` maps the root to `@procedures/client/browser`. The map can stay, because the root is also a browser entry.
+  - Graph: no change. It imports none of these names.
+  - jarvis: no change. It imports none of these names.
+  - The procedures image of the harness of `systems` (`packages/harness/image/procedures/server-ws.mjs`) imports `WebSocketServerTransport` from the root. It pins `@procedures/client` 0.7.0. When it moves to this MINOR or a later version, import `WebSocketServerTransport` from `@procedures/client/node`.
+  - `headroom` (`packages/daemon/src/gateway.ts`) gives `checkBrowserRequest` of the root a request of `node:http`: no change.
+
 ## 0.19.0
 
 ### Minor Changes

package/README.md

@@ -297,7 +297,7 @@ interface WebSocketTransportOptions {
 // dead peer, its socket stays open until the kernel stops it (924.6 s in the cells of R36).
 import { WebSocketTransport } from "@procedures/client/node";
 
-// The server transports are in the Node entry too (CLI-6)
+// The server transports are only in the Node entry (CLI-6)
 import { WebSocketServerTransport } from "@procedures/client/node";
 
 // The server pings each connection, and closes one that misses 2 pongs (option heartbeat)
@@ -604,7 +604,7 @@ interface HttpServerTransportOptions {
   port?: number;                 // default: 3000
   host?: string;                 // default: "127.0.0.1"
   basePath?: string;             // default: "/api"
-  urlStrategy?: HttpUrlStrategy;
+  urlStrategy?: HttpUrlStrategy; // (req: UrlStrategyRequest) => Method | null
   cors?: boolean;
   corsOptions?: { origin?: string | string[]; methods?: string[]; allowedHeaders?: string[]; credentials?: boolean };
   bodyLimit?: number;            // default: 1 MiB
@@ -613,6 +613,8 @@ interface HttpServerTransportOptions {
 }
 ```
 
+A URL strategy gets a `UrlStrategyRequest`: the method, the path, the URL, the headers, the query and the body. The type is structural. A `Request` of Express agrees with it, and so does the `UrlRequest` of `procedureHandler`.
+
 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.
@@ -809,7 +811,7 @@ import { ... } from "@procedures/client/events";
 
 | Entry | Use |
 |---|---|
-| `@procedures/client` | Node. The browser entry. Its `WebSocketTransport` uses the global `WebSocket`. It also exports the server transports, but these exports are deprecated. The next MINOR removes them (CLI-6). |
+| `@procedures/client` | Node or a browser bundle. The browser entry, the URL strategies and the browser checks of the server. It imports no `http`, `ws` or `express`, and its declarations name none of them (CLI-6). 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. `writeNdjsonStream`: the NDJSON stream response of `HttpServerTransport`, for a `ServerResponse` of `node:http`. `procedureHandler` and `upgradeHandler`: the procedure faces of HTTP and WebSocket, without a framework. `HttpServerTransport` and `WebSocketServerTransport`: the server transports. |
 | `@procedures/client/register` | It registers the core procedures in the global registry. |