@procedures/client 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @procedures/client
 
+## 0.5.0
+
+### Minor Changes
+
+- 09e5566: Remote events (`documentation/EVENTS.md`): a peer subscribes to the topics of the event bus of another peer. A subscription is a streaming call of the procedure `events.subscribe`, so it uses the frames of each call: credit is the backpressure, and a cancel is the unsubscribe. It works over WebSocket in the two directions, HTTP with NDJSON, a message port and the local transport. The protocol stays v1.
+  
+  - `WebSocketTransport.subscribe(topics, handler)` gives the unsubscribe function, with the `ready` promise of the first confirmation. `WebSocketTransport.events(topics)` gives an async iterator. After a drop, the transport resubscribes on the new connection.
+  - `subscribeRemote()` and `remoteEvents()` do the same over each transport. After a failure that a retry can repair, they resubscribe with a backoff.
+  - `ProcedureServer` has the option `events`: a bus, a topic rule (`topics`), an `allow` function and a `buffer`. The server pins `events.subscribe` outside its registry, so it is not an MCP tool. `ProcedureServer.publish()` emits on the bus. `stop()` ends each subscription with `UNAVAILABLE`.
+  - `WebSocketServerTransport.subscribe(connectionId, topics, handler)` and `events(connectionId, topics)` subscribe to the bus of a client. `LocalTransport` takes an `EventPublisher` with its option `events`.
+  - The delivery is at most once, in the order of `emit()`. When the queue of a slow subscriber is full, the publisher drops the oldest event, and the next event tells the loss (`dropped`).
+  - The new error code `TOPIC_NOT_FOUND` (404) is for a topic outside the topic rule. A topic that `allow` refuses gives `FORBIDDEN` with the reason `topic-not-allowed`.
+  - The `onEvent` option of `WebSocketTransport` is now a wrapper: it gets each event of each subscription of the transport. A raw `event` frame still goes to it.
+  - The WebSocket client does not warn about a `stream` frame of a call that it cancelled. The WebSocket server ignores a late `stream`, `response` or `error` frame of a call that it stopped. Before, it answered such a frame with an `error` frame.
+- ab77f75: Sequence numbers of the stream frames (`documentation/WIRE-PROTOCOL.md`). Before, a duplicate `stream` frame gave a duplicate item. The change is additive, and the protocol stays v1.
+  
+  - Each `stream` frame has the field `seq`: 1 in the first frame of a call, and one more in each next frame. The end frame has a number too. Each NDJSON line `item` or `done` has the same field.
+  - The receiver drops a frame whose `seq` is not above the last one. Thus a duplicate frame or a late frame gives no item.
+  - A gap does not end the stream, because the delivery is at most once. The next item has the number of lost frames in the metadata key `stream-gap` (`STREAM_GAP_METADATA_KEY`), and the console gets a warning. The receiver gives back the credit of the lost frames.
+  - A frame without `seq` comes from an older peer. The receiver takes it as before.
+  - The rules apply to WebSocket in the two directions, the message port and HTTP with NDJSON. The local transport has no frames.
+  - `WebSocketMessage` has the optional field `seq`.
+- 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`.
+- bc74091: Two changes for the contract of `CollectionStorage`:
+  
+  - The collection procedure `collections.<name>.get` takes the input `found: true`. Then its output is `{ found, value }`, so a stored `null` and a missing id give different outputs in one call. Without `found`, the output is the item, as before.
+  - `ProcedureServer.stop()` and `closeStorages()` close each storage one time, also a storage of two collections, and remove the storages from the server. Before, a server that started again used the closed storages.
+
+### Patch Changes
+
+- 0f75644: The dependencies go to `@mark1russell7/algebra` `^0.7.0` and `@mark1russell7/service` `^0.4.1`. A host that uses algebra 0.7.0 gets one copy of it. Algebra 0.7.0 only adds to 0.6.0.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -27,7 +27,7 @@ The core depends on no other package of the repository. The procedure components
 - **Type-Safe Procedures**: Schema-validated procedures with auto-discovery and registry management
 - **Middleware System**: Composable middleware for retry, cache, timeout, circuit breaker, rate limiting, auth, tracing, and validation
 - **Procedure-as-Data**: JSON programs of calls, references and control flow ([PROGRAM-FORMAT.md](../documentation/PROGRAM-FORMAT.md))
-- **Event Bus**: Pub/sub messaging with async iteration support
+- **Event Bus**: Pub/sub messaging with async iteration support. A peer subscribes to the bus of another peer over each transport ([EVENTS.md](../documentation/EVENTS.md))
 - **Error System**: 70+ error codes with rich metadata and recovery suggestions
 
 ## Installation
@@ -284,6 +284,17 @@ new WebSocketServerTransport(server, { server: http, heartbeat: { interval: seco
 const transport = new WebSocketTransport({ url, serve: new ProcedureServer({ registry: uiRegistry, autoRegister: true }) });
 const toClient = new Client({ transport: wsServer.transportFor(connectionId) });   // or peer.clientFor(id)
 await toClient.call({ service: "ui", operation: "notify" }, { text: "Build done" });
+
+// Remote events (documentation/EVENTS.md): subscribe to topics of the bus of the server. The
+// function gives the unsubscribe. After a drop, the transport resubscribes on the new connection.
+const unsubscribe = transport.subscribe("orders.created", (order, event) => console.log(event.seq, order), {
+  onSubscribed: (topics) => console.log("subscribed", topics),
+  onError: (error) => console.error(error.code),   // TOPIC_NOT_FOUND, FORBIDDEN, NOT_FOUND
+});
+await unsubscribe.ready;
+unsubscribe();
+// The same events as an async iterator: a break or the signal unsubscribes
+for await (const event of transport.events(["orders.created", "orders.paid"], { signal })) console.log(event.topic, event.data);
 ```
 
 #### `LocalTransport`
@@ -500,6 +511,39 @@ const unsubscribe = bus.on("event", handler)
 unsubscribe()
 ```
 
+#### Remote events
+
+A peer subscribes to the topics of the bus of another peer ([EVENTS.md](../documentation/EVENTS.md)). A subscription is a streaming call of the procedure `events.subscribe`, so it works over WebSocket (in the two directions), HTTP with NDJSON, a message port and the local transport.
+
+```typescript
+// The publisher: a ProcedureServer with the option events
+const bus = createEventBus()
+const server = new ProcedureServer({
+  registry,
+  autoRegister: true,
+  events: {
+    bus,                                  // the procedures of the server get it as ctx.bus
+    topics: ["orders.*", "system:*"],     // the topic rule: an exact name, a prefix with *, or *
+    allow: (topic, call) => !topic.startsWith("system:") || call.capability.clearance === "admin",
+    buffer: 1024,                         // the events that one subscription holds for a slow subscriber
+  },
+})
+server.publish("orders.created", { order: 1 })   // the same as bus.emit()
+
+// The subscriber, over each transport
+const unsubscribe = subscribeRemote(transport, "orders.created", (order, event) => console.log(order, event.seq))
+for await (const event of remoteEvents(transport, ["orders.created"], { signal })) console.log(event.data)
+
+// The server subscribes to the bus of a client: the client serves it with `serve`
+new WebSocketTransport({ url, serve: new ProcedureServer({ events: { bus: clientBus, topics: ["ui.*"] } }) })
+wsServer.subscribe(connectionId, "ui.clicked", (click) => console.log(click))
+```
+
+- The delivery is at most once, in the order of `emit()`. `seq` numbers the events of a subscription, and `dropped` tells the events that the publisher dropped for a slow subscriber.
+- A topic outside the topic rule gives `TOPIC_NOT_FOUND`. A topic that `allow` refuses gives `FORBIDDEN` with the reason `topic-not-allowed`. The procedure reads the resource `events`, so the capability of the host applies to it.
+- `ProcedureServer.stop()` ends each subscription with `UNAVAILABLE`, and the subscriber resubscribes later.
+- `events.subscribe` is not in a registry: it is not an MCP tool.
+
 ### Server
 
 ```typescript
@@ -550,6 +594,7 @@ interface ProcedureServerOptions {
   registry?: ProcedureRegistry;
   storage?: StorageConfig;
   transports?: ServerTransport[];
+  events?: EventPublisherOptions | EventPublisher;   // the remote events: refer to "Remote events"
 }
 ```