@procedures/peer 0.10.0 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # @procedures/peer
 
+## 0.12.0
+
+### Minor Changes
+
+- 9ea2030: `runProcedureHost()` of `@procedures/server` is the one runner entry on `run()` of `@mark1russell7/service`, for `procedure-server`, `mark serve` and `mark --server` (server stack CLI-8, decisions D6, D7 and D17). This change is a break of the server stack, thus it is its own MINOR (decision D13).
+  
+  - New `runProcedureHost({ name, host, mode, profile, lockfile, log, run })`. It declares the parts of `createProcedureHost()` in one service, and starts `run()`. It gives `{ host, service, life }` when the startup ends.
+  - The mode `foreground` has the profile `localDev`: a second Ctrl-C exits at once. The mode `background` has the profile `daemon`: a repeat signal has no effect. Each run declares `onRepeatSignal`. `HOST_PROFILES` gives the profiles as data.
+  - The caps of the stages sum to 10 s. They replace the hard-exit timer of 10 s of the entries.
+  - The lockfile is a dependency of the service: its connect writes it before the listeners start, and its close removes it after the listeners close. New `lockfileHandle(data)` of `@procedures/peer/lockfile`.
+  - `runServer()` (the bin `procedure-server` and `mark serve`) and `startServerMode()` (`mark --server`) install no signal handler and no hard-exit timer. Their promise ends with the lifecycle.
+  - `mark --server` is the background host (decision D17). `procedure-server` and `mark serve` run in the foreground.
+  - The entries map their transports to a host with `peerHostOptions()` of `@procedures/peer` (CLI-7).
+  - `ServerRunOptions.run` and the second argument of `startServerMode()` take the options of `run()`, for a test: a process port and a clock.
+  - A random token of `procedure-server` has 32 bytes, as the token of `mark --server`.
+  - The one-shot commands of `mark` keep their interrupt. CLI-26 moves them under `run()`.
+  
+  The behavior that changes:
+  
+  - A second Ctrl-C of `mark --server` has no effect: the host ends its drain, in 10 s at most. A second Ctrl-C of `procedure-server` and `mark serve` exits at once with the code 1, as before.
+  - The process exits with the code of the lifecycle: 0 after a clean shutdown, and 1 after an error or a startup that failed.
+  - A random token of `procedure-server` has 64 hexadecimal characters, not 48.
+  
+  Migration steps:
+  
+  - The site, MiniMongo, Graph and jarvis: no change is necessary. They do not start these entries.
+  - A script that starts `procedure-server` or `mark serve` and stops it with a signal: no change is necessary. Wait for the exit, in 10 s at most.
+  - A program that embeds the server outside a service: use `startServer()`, which starts it as a peer, and `peer.stop()`.
+
+### Patch Changes
+
+- @procedures/client@0.12.0
+
+## 0.11.0
+
+### Minor Changes
+
+- 37c96a3: `createProcedureHost()` of `@procedures/peer` is one factory for each procedures server in Node. It gives the parts of a service of `@mark1russell7/service`, and `createPeer()` is a thin wrapper over it (server stack CLI-7, decisions D2, D3 and D4). This change is a break of the server stack, thus it is its own MINOR (decision D13).
+  
+  - New `createProcedureHost({ registry, policy, faces: { http, ws, mcp }, listen, collections })`. It gives `{ handler, upgrade, parts, dependencies, checks, controllers, info }` and `declare(svc)`. It starts nothing and installs no signal handler.
+  - The parts: the procedure server (its stop parts of CLI-5), the stop parts of each face, and an `httpTransport` of `@mark1russell7/service/http` for each listener that the host owns. The faces of a listener mount on its mount list, so they share one port.
+  - Without a listener, the app mounts `host.handler` and `host.upgrade` on its own listener.
+  - The request tracking: each call goes through `life.request`, with the route `<face> <procedure>`. One route pattern for each face (`http *`, `ws *`, `mcp *`) matches each call. The function of the pattern gives the idempotency of each call: `repeatable`, `keyed` (an idempotency key) or `once` (decision D3).
+  - Each call is a stream (decision D4). A stream stays in flight until its last item. A cut after the first item ends the stream with an error line, and the line tells the count of the items.
+  - The faces are factories: `httpFace()` and `wsFace()` of `@procedures/peer`, and the new `mcpFace()` of `@procedures/mcp-server`. A face of another package has the same shape.
+  - The collections come from the option `collections`. The host serves `collections.<name>.*`, and each storage is a dependency handle of the service.
+  - `createPeer()` is for a process that has no service of its own. It declares the parts of its host in a service of its own, and starts `run()` of `@mark1russell7/service` on `embeddedProcess()`, a process port that installs no signal handler and never ends the process. `stop()` asks that lifecycle for its shutdown. The new option `profile` gives the profile of that service, and the default is `PEER_PROFILE`.
+  - The WebSocket face refuses an upgrade that the server does not admit, with the path of each call: 401 without the token or for a refusal of the request hook, and 403 for a failed browser check. A request hook that admits a request without credentials lets the connection open.
+  - New exports of `@procedures/peer`: `createProcedureHost`, `httpFace`, `wsFace`, `LOCAL_LISTENER_KNOBS`, `peerHostOptions`, `PEER_PROFILE`, `faceHandler`, `callOperations`, `operationOfCall`, and their types. `Peer.getHost()` gives the host of a peer.
+  - `@procedures/mcp-server`: new `mcpFace()`. New option `httpOptions.mount` and method `McpServerTransport.handleHttp()`: a Streamable HTTP endpoint on a listener of another part. `McpServerTransport` takes each `RequestHandler`, not only a `Server`.
+  - `@procedures/client`: new `ProcedureServer.procedureOf(method)`, and `ProcedureServer.admits(credentials)`: the request hook, the token check and the authenticate function of a call, for a connection before its first call.
+  - `@procedures/peer` depends on `@mark1russell7/service` `^0.5.2`, for `embeddedProcess()` (SYS-27), and no longer on Express.
+  
+  The behavior that changes:
+  
+  - A peer has no `/health` and no `/api/health` route. The probes come from the runner. `checkServer()` of `@procedures/peer/lockfile` calls `host.info` with the token of the lockfile (a part of CLI-9).
+  - A peer has one token: the token of its transports, or else the token of its policy. Two different tokens throw at `createPeer()`. The token applies to each face.
+  - The token of a peer applies to the upgrade of each WebSocket connection, also for a transport with no token of its own.
+  - `peer.stop({ grace })`: the grace has no effect, and the option is deprecated. The profile of the peer gives the drain, and `PEER_PROFILE` aborts the calls in flight at the start of the drain, as `stop()` without a grace did.
+  - A refused browser request gets the error of wire v1: `FORBIDDEN` with a `reason`. Before, the peer sent its own JSON.
+  - A peer starts one time. A `start()` after `stop()` throws: create a new peer.
+  - A listener that the peer cannot use gives `The HTTP server cannot listen on <host>:<port>` or `The WebSocket server cannot listen on <host>:<port>`.
+  - `HttpTransportConfig.cors: true` gives the CORS of `procedureHandler`: each origin, without credentials.
+  
+  Migration steps:
+  
+  - The site and MiniMongo: no change is necessary, unless they read `/health` of a peer. Then call `host.info` with the token.
+  - The MCP host of Graph: no change is necessary. To share the port of the Graph host, mount `mcpFace()` on its listener.
+  - jarvis and Graph under `run()`: build the procedures with `createProcedureHost()`, and call `host.declare(svc)` in the service of the process. Give `listen` for a port of the host, or mount `host.handler` and `host.upgrade` on the listener of the app.
+  - A caller of `createPeer()` with a different token for each transport: give one token.
+  - A Docker `HEALTHCHECK` or a probe of Kubernetes that read `/health` of a peer: use the probes of the service. Give the service `probeServer({ port, server_retry_after })` on a port of its own, or mount `probeHandler(health, { prefix: "/health" })` on the port of the app. Both come from `@mark1russell7/service/http`, and they answer `/health/startup`, `/health/readiness` and `/health/liveness`. The lockfile check of a client calls `host.info` with the token of the lockfile.
+  - A test that read `/health` of a peer: call `host.info` with the token, or check the status 404.
+
+### Patch Changes
+
+- Updated dependencies [37c96a3]
+  - @procedures/client@0.11.0
+
 ## 0.10.0
 
 ### Patch Changes

package/README.md

@@ -17,7 +17,7 @@
 - **Automatic Discovery**: Peers exchange procedure manifests on connection
 - **Manifest Generation**: Generate TypeScript and JSON manifests from registered procedures
 - **Connection Management**: Track and manage multiple peer connections
-- **Express Integration**: Optional Express.js integration for HTTP transport
+- **One procedures host**: `createProcedureHost()` gives the parts of a service of `@mark1russell7/service` (CLI-7). It has no framework: the listener is the `httpTransport` of `@mark1russell7/service/http`.
 - **Zero Configuration**: Auto-register all procedures from the global registry
 
 ## Architecture
@@ -107,12 +107,49 @@ This package depends on:
 - `@procedures/client` - Core client/procedure system
 - `zod` - Schema validation
 - `zod-to-json-schema` - JSON schema generation
-- `express` (optional) - HTTP server for HTTP transport
+- `@mark1russell7/service` - The runner: the contracts of the parts, and `httpTransport` of `./http`
 
 ## Usage
 
+### The procedures host
+
+`createProcedureHost()` builds one procedures server with its faces, and gives the parts of a service. It starts nothing and installs no signal handler. The service of the process declares the parts, and only the entry of the process starts `run()` (decision D2).
+
+```typescript
+import { localDev, service } from "@mark1russell7/service";
+import { hostPolicy, seconds } from "@procedures/client";
+import { mcpFace } from "@procedures/mcp-server";
+import { createProcedureHost, LOCAL_LISTENER_KNOBS } from "@procedures/peer";
+
+const host = createProcedureHost({
+  registry,
+  policy: hostPolicy({ token }),
+  faces: { http: true, ws: true, mcp: mcpFace() },
+  listen: [{ port: 3000, knobs: LOCAL_LISTENER_KNOBS }],
+  collections: { notes: storage },
+});
+const svc = host
+  .declare(service("app").profile(localDev))
+  .readiness({ type: "debounce", interval: seconds(5), failAfter: 3, recoverAfter: 1 })
+  .liveness({ type: "window", failAfter: seconds(45) })
+  .startup(seconds(30));
+await svc.run();
+```
+
+- **The parts.** `host.parts` are the transports: the procedure server, the stop parts of each face, and an `httpTransport` for each listener. `host.dependencies` has one dependency handle for each storage. `host.controllers` has one route pattern for each face.
+- **The faces.** `http` and `ws` are the faces of this package (`httpFace()`, `wsFace()`). `mcp` takes `mcpFace()` of `@procedures/mcp-server`. A face of another package is a function with the same shape.
+- **The listeners.** The faces of a listener mount on its mount list, so they share one port. Without `listen`, the app mounts `host.handler` and `host.upgrade` on its own listener.
+- **The request tracking.** Each call goes through `life.request`, with the route `<face> <procedure>`. The function of the pattern gives the idempotency of each call: a repeatable procedure, a keyed call, or a call that runs one time (decision D3).
+- **The streams.** Each call is a stream, and a unary call is a stream of one (decision D4). A stream stays in flight until its end. A cut after the first item ends the stream with an error line.
+- **The collections.** The option `collections` gives the storages. The host serves `collections.<name>.*` for each one.
+- **No `/health` route.** The probes come from the runner (`probeHandler` or `probeServer`). A client checks a lockfile with `host.info` and the token of the lockfile.
+
 ### Creating a Server Peer
 
+`createPeer()` is for a process that has no service of its own: a test, or a host that a procedure starts (`server.create`). The peer builds a host with `createProcedureHost()`, declares its parts in a service of its own, and starts `run()` of `@mark1russell7/service` on a process port that installs no signal handler and never ends the process. `stop()` asks that lifecycle for its shutdown. A process that has a service of its own uses `createProcedureHost()` and `host.declare(svc)` in place of a peer.
+
+A peer has one token, and it starts one time. The WebSocket face refuses an upgrade that the server does not admit: 401 without the token or for a refusal of the request hook, and 403 for a failed browser check.
+
 ```typescript
 import { createPeer } from "@procedures/peer";
 
@@ -326,10 +363,12 @@ Create a new peer instance.
 - `registry?: ProcedureRegistry` - Custom procedure registry (default: global)
 
 **Returns:** Peer instance with methods:
-- `start(): Promise<void>` - Start all transports
-- `stop(): Promise<void>` - Stop all transports
+- `start(): Promise<void>` - Start the parts of the host. A peer starts one time.
+- `stop(options?: { grace }): Promise<void>` - Stop the parts in the sequence of the stages
 - `getEndpoints(): PeerEndpoint[]` - Get active endpoints
 - `getServer(): ProcedureServer` - Get underlying procedure server
+- `getHost(): ProcedureHost` - The procedures host: its parts, its faces and its info
+- `connections(): string[]` and `clientFor(id): Client` - The WebSocket connections, and a client of one
 
 #### Transport Configurations
 
@@ -339,9 +378,9 @@ Create a new peer instance.
 {
   type: "http",
   port?: number,        // Default: 3000
-  host?: string,        // Default: "0.0.0.0"
+  host?: string,        // Default: "127.0.0.1"
   basePath?: string,    // Default: "/api"
-  cors?: boolean,       // Default: true
+  cors?: boolean,       // Default: false
   corsOrigins?: string[] // Allowed origins
 }
 ```
@@ -352,7 +391,7 @@ Create a new peer instance.
 {
   type: "websocket",
   port?: number,        // Default: 3001
-  host?: string,        // Default: "0.0.0.0"
+  host?: string,        // Default: "127.0.0.1"
   path?: string         // Default: "/ws"
 }
 ```