@procedures/server 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @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

package/README.md

@@ -163,10 +163,35 @@ 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.
+
+### 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`.