@procedures/server 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @procedures/server
 
+## 0.5.0
+
+### Minor Changes
+
+- a47bee6: The hosts can confine the file procedures to a root (roadmap R33).
+  
+  - `confineFsProcedures(registry, root)` of `@procedures/fs` replaces the handler of each `fs.*` procedure of a registry with the handler of `createFsModule({ root })`. It adds no procedure. A nested `fs.*` call of another procedure is confined too. The root must be a folder that exists.
+  - `mark --fs-root <folder>` confines the `fs.*` procedures of each mode and host of `mark`: a command, the REPL, `--server`, `serve` and `mcp`. Give the flag before the command.
+  - A `mark` command uses a CLI server only when the server has the same root. The lockfile of `@procedures/peer` has the new field `fsRoot`, and `findServer()` compares it.
+  - `procedure-server --fs-root <folder>` and `mark serve --fs-root <folder>` confine the procedures of the server.
+  - The MCP server reads `MCP_FS_ROOT`, and `mark mcp` has the flag `--fs-root`. `fs` is not a tool namespace, so the tools do not change.
+  - A path outside the root gives `FORBIDDEN` with the reason `outside-root`. A procedure that reads files with `node:fs`, or that starts a program, is not confined.
+  - `@procedures/lib/cli-flags` has the global flags `--fs-root` and `--events`, and the field `repeatable`.
+- a47bee6: The hosts serve the remote events (`documentation/EVENTS.md`).
+  
+  - `hostPolicy()` takes the option `events`: the topic rule, with an optional bus, `allow` function and buffer. `procedureServerOptions()` gives it to the `ProcedureServer`, which pins `events.subscribe`. `HostPolicy` has the new field `events`.
+  - `procedure-server` and `mark serve` have the option `--events <patterns>`. The option is repeatable, and it takes comma-separated patterns: exact names, prefixes (`orders.*`) or `*`. `parseTopicPatterns()` checks them.
+  - `mark --server` has the same option `--events`.
+  - These hosts always serve `events.subscribe`. Without `--events`, they serve no topic, and each subscription gets `TOPIC_NOT_FOUND`. The bus is the global bus, which is also the `ctx.bus` of their procedures.
+  - The MCP server serves no events, because its transport carries only MCP.
+  - `mark --port`, `--host`, `--transport` and `--events` without `--server` are an error now, also before `serve` and `mcp`. Before, `mark --port 4000 serve` ignored `--port`.
+
+### Patch Changes
+
+- Updated dependencies [0f75644]
+- Updated dependencies [09e5566]
+- Updated dependencies [ab77f75]
+- Updated dependencies [a47bee6]
+- Updated dependencies [a47bee6]
+- Updated dependencies [bc74091]
+  - @procedures/client@0.5.0
+  - @procedures/peer@0.5.0
+
+## 0.4.0
+
+### Minor Changes
+
+- d42d716: `server.start`, `server.stop` and `server.status` moved from `@procedures/peer` to `@procedures/server`, the package of the host. Their names, schemas and effects stay the same. They manage the background server of the `mark` CLI.
+  
+  In this version, `@procedures/server` has a `./module` entry, a `./register` entry and the `client.procedures` field, so `mark server start`, `mark server stop` and `mark server status` keep working. The registry of `procedure-server` and `mark serve` has the module of the peer package and the module of the server package, as before.
+  
+  The module of `@procedures/peer` does not register the three procedures any more, and `@procedures/peer/procedures` does not export them. The lockfiles stay in `@procedures/peer/lockfile`.
+  
+  `connect()` of `@procedures/peer` takes `WebSocketTransport` from `@procedures/client/node`, not from the root of `@procedures/client`. Thus a peer connection in Node uses the `WebSocket` class of `ws`, and a drop ends the socket at once with `terminate()`.
+
+### 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 [d42d716]
+- Updated dependencies [4e751da]
+  - @procedures/client@0.4.0
+  - @procedures/peer@0.4.0
+
 ## 0.3.0
 
 ### Patch Changes

package/README.md

@@ -15,6 +15,7 @@
 - [Architecture](#architecture)
 - [Quick Start](#quick-start)
 - [CLI Reference](#cli-reference)
+- [Procedures](#procedures)
 - [Examples](#examples)
 - [Integration](#integration)
 - [Requirements](#requirements)
@@ -162,12 +163,37 @@ procedure-server -p @procedures/mongo/register -t http,websocket
 | `--token` | - | `SERVER_TOKEN`, or a random token that the server prints | The token that every request sends: `Authorization: Bearer <token>`, or `?token=` for WebSocket |
 | `--no-token` | - | - | Serve without a token (only on a trusted host) |
 | `--expose` | `-e` | every loaded procedure | Comma-separated procedures to serve: exact keys (`git.status`) or prefixes (`git.*`) |
+| `--events` | - | no topics | The topics of the event bus that a peer can subscribe to. Exact names (`orders.created`), prefixes (`orders.*`) or `*`. Repeat the option, or separate the patterns with commas. |
+| `--fs-root` | - | no root | The folder that confines each path of the `fs.*` procedures, also in their nested calls |
 | `--verbose` | `-v` | - | Verbose output |
 | `--help` | `-h` | - | Show help |
 
-`mark serve` takes the same options and starts the same server.
+`mark serve` takes the same options and starts the same server. `mark --fs-root <folder> serve` gives the root to the server too.
 
-The server has a registry of its own (roadmap 3.1): the `server.*` procedures and the `./module` entry of each `--procedures` package. Two servers in one process serve only their own packages. `pkg/register`, the form of the old examples, gives the module of `pkg`. A package without a `./module` entry still works: the server takes the procedures that its import registers. The token, the `--expose` list and the browser checks come from `hostPolicy()` of `@procedures/client`.
+### Remote events
+
+The server always serves the procedure `events.subscribe` ([EVENTS.md](../documentation/EVENTS.md)). The `--events` patterns are its topic rule:
+
+- Without `--events`, the rule is empty. Each subscription gets `TOPIC_NOT_FOUND`.
+- The `--expose` list does not apply to `events.subscribe`. The topic rule is its expose rule.
+- The bus is the global bus of the process. The procedures of the server get it as `ctx.bus`, so a procedure publishes with `ctx.bus.emit()`.
+- The token applies to a subscription as to each call. The server has no capability, so it permits each subscription to a topic of the rule.
+- A subscriber uses WebSocket (`transport.subscribe()`) or HTTP with NDJSON (`subscribeRemote()`).
+
+```bash
+procedure-server -p ./my-procedures.js -t http,websocket --events "orders.*" --events audit.created
+```
+
+### The root of the file procedures
+
+With `--fs-root <folder>`, the server starts `confineFsProcedures()` of `@procedures/fs` after it builds its registry (roadmap R33):
+
+- Each `fs.*` procedure refuses a path outside the folder with `FORBIDDEN` and the reason `outside-root`. A relative path starts at the folder.
+- A nested `fs.*` call of another procedure is confined too.
+- The server does not start when the folder does not exist, or when it cannot load `@procedures/fs`.
+- A procedure that reads files with `node:fs`, or that starts a program, is not confined. The [README of the MCP server](../impl-mcp-dev/README.md) lists them.
+
+The server has a registry of its own (roadmap 3.1): the `server.*` procedures and the `./module` entry of each `--procedures` package. The `server.*` procedures come from two modules: the module of `@procedures/peer` (`server.create`, `server.call` and the others) and the module of this package. Two servers in one process serve only their own packages. `pkg/register`, the form of the old examples, gives the module of `pkg`. A package without a `./module` entry still works: the server takes the procedures that its import registers. The token, the `--expose` list and the browser checks come from `hostPolicy()` of `@procedures/client`.
 
 ### Transport Configuration
 
@@ -192,6 +218,22 @@ graph TB
 
 ---
 
+## Procedures
+
+The package has three procedures. They manage the background server of the `mark` CLI (`mark --server`). In version 0.3.0 and before, they were in `@procedures/peer`. Their names did not change.
+
+| Procedure | Function |
+|---|---|
+| `server.start` | Start the CLI server as a background process. It writes `~/.mark/server.log`. |
+| `server.stop` | Stop the CLI servers of the lockfiles, or the server of one port. A process that does not answer as the peer of its lockfile gets no signal. |
+| `server.status` | Give the state of the CLI servers. It deletes the lockfile of a server that does not answer. |
+
+- `import "@procedures/server/register"` registers them in the global registry. The package root and the `./module` entry register nothing.
+- `mark` finds the package from its `client.procedures` field: `mark server start`, `mark server stop` and `mark server status` run them.
+- The lockfiles stay in `@procedures/peer` (`@procedures/peer/lockfile`), because the peer of `mark --server` writes them.
+
+---
+
 ## Examples
 
 ### MongoDB Server