rsmp 0.48.4 → 0.51.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a7aa9df937cb7b5576fb663f49805e407ad171eb15e8984def184f417591092
-  data.tar.gz: 3e7331da7fa601171f970850fa10a2e923a6aaa4aabf860d1e18a5aad7d25ff0
+  metadata.gz: 363ee5c8eb68f060a0f464939cc6a4444265568821fab38186992b189de29dd0
+  data.tar.gz: f53b952f5877fd3c17b8d90ee82b7e1412432ad34a68cdcac3736320674cce8f
 SHA512:
-  metadata.gz: 4b42f68a891ca93dfe38f7d643551c2a09a82b577f95b6dfe8b46bb7dd75f240b52b8373ab93f6d33e1c86719be3da9778b8e4e225da0e05e998e394c0c025ec
-  data.tar.gz: 303b2c7eca70376a291f04a145e7aa54c4b9666a2db73223e4d42b9cd41d2f6673a8c7ef5ac2af52b1ef9d1701a8f262d88b5b718bdc816707e0db7e894519d9
+  metadata.gz: ed82fd73d09b5bcbd83c5c675a9e8ff9ed8d925e23f7cd059dd8efd9ca413e672f53ca0f3f76717114686d541c88b2a84f6dcd204a57338688b4c5db11dec1c9
+  data.tar.gz: 2598d67cfd2d5a66bf466b6c8901d2013689160b18cf4fead369111c41dd0cc2ee760874551fc0b86d70f284b21a38b68aa5810c534a0a3563b79ef028f972a9

data/CHANGELOG.md

@@ -705,3 +705,9 @@ Initial release.
 
 ## 0.48.2
 - fix legacy TLC M0001 schemas to use scalar command arguments
+
+## 0.50.0
+- return immutable results for finite sends, waits, validation, and collection
+- publish typed events for expected peer and connection failures
+- preserve unexpected exceptions and backtraces through structured Async task trees
+- add explicit bang variants for callers that prefer exception-based handling

data/Gemfile.lock

@@ -1,8 +1,8 @@
 PATH
   remote: .
   specs:
-    rsmp (0.48.4)
-      async (~> 2.39)
+    rsmp (0.51.0)
+      async (~> 2.45)
       colorize (~> 1.1)
       io-endpoint (~> 0.17)
       io-stream (~> 0.13)
@@ -15,15 +15,13 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
-    async (2.41.0)
+    async (2.45.1)
       console (~> 1.29)
       fiber-annotation
-      io-event (~> 1.11)
-      metrics (~> 0.12)
-      traces (~> 0.18)
+      io-event (~> 1.21)
     bigdecimal (4.1.2)
     colorize (1.1.0)
-    console (1.36.0)
+    console (1.37.0)
       fiber-annotation
       fiber-local (~> 1.1)
       json
@@ -32,22 +30,24 @@ GEM
       fiber-storage
     fiber-storage (1.0.1)
     hana (1.3.7)
-    io-endpoint (0.17.2)
-    io-event (1.19.1)
-    io-stream (0.13.1)
-    json (2.20.0)
+    io-endpoint (0.18.0)
+      openssl (>= 3.3.0)
+    io-event (1.21.1)
+    io-stream (0.14.0)
+      openssl (>= 3.3)
+    json (2.21.2)
     json_schemer (2.5.0)
       bigdecimal
       hana (~> 1.3)
       regexp_parser (~> 2.0)
       simpleidn (~> 0.2)
-    language_server-protocol (3.17.0.5)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
-    metrics (0.15.0)
+    openssl (4.0.2)
     ostruct (0.6.3)
     parallel (2.1.0)
-    parser (3.3.11.1)
+    parser (3.3.12.0)
       ast (~> 2.4.1)
       racc
     prism (1.9.0)
@@ -55,8 +55,8 @@ GEM
     rainbow (3.1.1)
     rake (13.4.2)
     regexp_parser (2.12.0)
-    rubocop (1.87.0)
-      json (~> 2.3)
+    rubocop (1.90.0)
+      json (>= 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
       parallel (>= 1.10)
@@ -66,21 +66,20 @@ GEM
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.1)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     rubocop-rake (0.7.1)
       lint_roller (~> 1.1)
       rubocop (>= 1.72.1)
     ruby-progressbar (1.13.0)
-    simpleidn (0.2.3)
-    sus (0.37.0)
+    simpleidn (0.3.0)
+    sus (0.37.2)
     sus-fixtures-async (0.2.0)
       async
       sus (~> 0.10)
     thor (1.5.0)
     timecop (0.9.11)
-    traces (0.18.2)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)

data/README.md

@@ -20,12 +20,20 @@ The RSMP::Site and RSMP::Supervisor classes can be used to run a RSMP site.
 
 ```ruby
 require 'rsmp'
-RSMP::Site.new.start 		# run site until Ctlr-C is pressed
+Async do |task|
+  site = RSMP::Site.new
+  site.start(parent: task)
+  site.wait
+end
 ```
 
 ```ruby
 require 'rsmp'
-RSMP::Supervisor.new.start  		# run supervisor until Ctlr-C is pressed
+Async do |task|
+  supervisor = RSMP::Supervisor.new
+  supervisor.start(parent: task)
+  supervisor.wait
+end
 ```
 
 By default, a site will try to connect to a single supervisor on localhost 127.0.0.1, port 12111. By default, a supervisor will listen for sites on port 12111 and accept any site.
@@ -131,12 +139,19 @@ the RSMP Core and SXL source repositories.
 Core and SXL schemas are selected with a flat map:
 
 ```ruby
-RSMP::Schema.validate(message, {
+validation = RSMP::Schema.validate(message, {
   core: '3.3.0',
   tlc: '1.3.0'
 })
+warn validation.message if validation.invalid?
 ```
 
+Finite operations such as waits, sends, and response collection return
+`RSMP::Result`. Expected peer, transport, and timeout failures are values;
+unexpected implementation errors still propagate with their original
+backtraces. See [finite operations and collection](documentation/collecting_message.md)
+and [Async task ownership](documentation/tasks.md).
+
 Sites and supervisors configure one or more SXLs with `sxls`:
 
 ```yaml
@@ -149,6 +164,15 @@ See [configuration](documentation/configuration.md) for connection-role examples
 ## Command-line tool
 Tools for easily running RSMP supervisors and sites. The binary is called ```rsmp```.
 
+It also provides SXL dependency and manifest tooling:
+
+```console
+$ rsmp sxl resolve path/to/sxl.yaml --source path/to/sxl-catalog
+$ rsmp sxl verify manifest.yaml --source path/to/sxl-catalog
+```
+
+See [the CLI reference](documentation/cli.md#rsmp-sxl-resolve) for source layout, requirement syntax, and options.
+
 The ```supervisor``` command will start an RSMP supervisor, which sites can connect to:
 
 ```console

data/Rakefile

@@ -23,7 +23,9 @@ end
 def require_minimum_core_version!(source_path)
   yaml = YAML.load_file(source_path)
   minimum_core_version = yaml.dig('meta', 'minimum_core_version')
-  raise "Missing meta.minimum_core_version in #{source_path}" if minimum_core_version.nil? || minimum_core_version.to_s.empty?
+  return unless minimum_core_version.nil? || minimum_core_version.to_s.empty?
+
+  raise "Missing meta.minimum_core_version in #{source_path}"
 end
 
 # Update vendored schemas from source repos.

data/documentation/cli.md

@@ -1,6 +1,7 @@
 # RSMP CLI
 
-The `rsmp` command can run a site, run a supervisor, validate config files, generate JSON Schemas from an SXL, and print the gem version.
+The `rsmp` command can run a site, run a supervisor, validate config files, resolve SXL dependencies,
+verify SXL manifests, generate JSON Schemas from an SXL, and print the gem version.
 
 Use help at any level:
 
@@ -8,8 +9,10 @@ Use help at any level:
 $ rsmp help
 $ rsmp help site
 $ rsmp help supervisor
-$ rsmp help config check
-$ rsmp help schema generate
+$ rsmp config help check
+$ rsmp schema help generate
+$ rsmp sxl help resolve
+$ rsmp sxl help verify
 ```
 
 ## Quick Examples
@@ -66,6 +69,18 @@ Generate JSON Schema files from an SXL YAML file:
 $ rsmp schema generate --in schemas/tlc/1.3.0/sxl.yaml --out /tmp/tlc-schema
 ```
 
+Resolve an SXL and its dependencies from local sources:
+
+```console
+$ rsmp sxl resolve schema/sxl.yaml --source ../sxl-catalog
+```
+
+Verify the resulting manifest against the same sources:
+
+```console
+$ rsmp sxl verify manifest.yaml --source ../sxl-catalog
+```
+
 ## Configuration Files
 
 Most real runs should use YAML config files. The CLI accepts `--config`, `-c`, and `--options` as aliases:
@@ -206,10 +221,70 @@ Options:
 - `--in PATH`, `-i PATH`: path to the input `sxl.yaml`. Defaults to `sxl.yaml`.
 - `--out PATH`, `-o PATH`: output directory. Defaults to the current directory.
 
-The command writes the generated status, command, alarm, root schema, definitions, and `sxl_index.json` files to the output directory.
+The input can use either the top-level `components` or `objects` mapping. Both forms are normalized to
+`components` before processing. The command
+writes the generated status, command, alarm, root schema, definitions, and `sxl_index.json` files to the output directory.
 
 If the input file is missing, the command prints an error and exits with status `1`.
 
+### `rsmp sxl resolve`
+
+Resolves direct and transitive SXL dependencies, checks for conflicting component types and message codes,
+and writes a manifest:
+
+```console
+$ rsmp sxl resolve schema/sxl.yaml --source ../sxl-catalog
+```
+
+Roots can be SXL YAML paths or `name:requirement` specifications. Several roots can be supplied
+for a site SXL list:
+
+```console
+$ rsmp sxl resolve traffic_light_controller:~1.3 public_priority:2.1.0 \
+    --source ../sxl-catalog --out site-manifest.yaml
+```
+
+Quote a requirement when it contains spaces:
+
+```console
+$ rsmp sxl resolve 'traffic_light_controller:>=1.3.0 and <2.0.0' --source ../sxl-catalog
+```
+
+Source arguments can be individual YAML files or directories. Directories are searched recursively for files
+named `sxl.yaml` or `sxl.yml`. Every source must use top-level `meta`, optional `prefix`, optional
+`dependencies`, and either `components` or `objects`. Both input forms are normalized to `components`.
+Sources are indexed by exact `meta.name` and `meta.version`.
+
+Options:
+
+- `--source PATH...`, `-s PATH...`: one or more local source files or directories.
+- `--out PATH`, `-o PATH`: manifest output path. Defaults to `manifest.yaml`.
+- `--format VERSION`: RSMP Core version written as `meta.format`. Defaults to the latest Core version bundled with the gem.
+- `--force`, `-f`: replace an existing output file. Without this option, existing files are preserved and the command fails.
+
+The resolver supports exact versions, `>`, `>=`, `<`, `<=`, `~`, and two comparisons joined by `and`. It tries
+available versions newest first, rejects unsatisfied requirements and dependency cycles, applies each SXL prefix,
+and rejects component types or message codes defined by more than one resolved SXL. For non-zero major versions,
+`~1.3` means `>=1.3.0 and <2.0.0`. A major-zero compatibility requirement must include all three parts and is exact,
+for example `~0.3.1` matches only `0.3.1`.
+
+### `rsmp sxl verify`
+
+Verifies a manifest against locally supplied SXL sources:
+
+```console
+$ rsmp sxl verify manifest.yaml --source ../sxl-catalog
+```
+
+The manifest defaults to `manifest.yaml`. `--source PATH...` has the same meaning as for `sxl resolve`.
+Verification checks the manifest shape and metadata, natural name order, availability of every exact SXL version,
+the complete dependency closure and version requirements, dependency cycles, Core-format compatibility, and component
+or message-code conflicts. A valid manifest prints `OK`; a failure prints an error and exits with status `1`.
+
+Because the manifest format records only exact resolved versions and does not distinguish roots from dependencies,
+verification checks validity but cannot determine whether the manifest still selects the newest versions in a changed
+source catalogue. Run `sxl resolve` again to refresh version selection.
+
 ### `rsmp version`
 
 Prints the installed `rsmp` gem version:

data/documentation/collecting_message.md

@@ -1,226 +1,146 @@
-# Collection
-You often need to collect messages or responses. The collector classes are used to collect message asyncronously. Other tasks continue until the collection completes, time outs or is cancelled.
+# Finite operations and message collection
 
-A collector can collect ingoing and/or outgoing messages.
-
-An object that includes the Distributor module (or implements the same functionality) must be provided when you construct a Collected. The collector will attach itself to this distributor when it starts collecting, to receive messages. The SiteProxy and SupervisorProxy classes both include the Distributor module, and can therefore be used as message sources.
-
-Messages that match the relevant criteria are stored by the collector.
-
-When the collection is done, the collector detaches from the distributor, and returns the status.
-
-
-## Collector
-Class used for collecting messages filtered by message type, direction and/or component id. A block can be used for custom filtering.
-
-You can choose to collect a specific number of message and/or for a specific duration.
-
-A collector has a status, which is `:ready` initialialy. When you start collecting, it changes to `:collecting`. It will be `:ok` once collection completes successfully, or `:cancel` if it was cancelled to to some error or by a filter block.
-
-### Initialization
-When you create a collector, you provide a Filter to specify the messages types you want to collect. You can also specify ingoing and/or outgoing direction and the RSMP component.
+RSMP distinguishes expected operational failures from implementation defects.
+Operations that can normally time out, be rejected, or lose their connection
+return an `RSMP::Result`. They do not use exceptions for ordinary control flow.
 
 ```ruby
-collector = MessageCollector.new(distributor,
-	num: 10,
-	filter: Filter.new(ingoing: true, outgoing: true)
-```
-
-num: The number of messages to collect. If not provided, a timeout must be set instead.
-filter: filter to identify the types of messages to look for.
+result = proxy.wait_for_state(:ready, timeout: 5)
 
-### Filter
-The Filter class is used to filter messages according to message type, direction and component.
-
-```ruby
-filter = Filter.new(
-	type: 'Alarm',
-	ingoing: true,
-	outgoing: false,
-	component: 'DL1'
-	)
+if result.success?
+  puts "Reached #{result.value}"
+else
+  warn "#{result.failure.code}: #{result.failure.message}"
+end
 ```
 
-type: a string, or an array of string, specifiying one or more RSMP message types.
-ingoing: Whether to collect ingoing messages. Defaults to true
-outgoing: Whether to collect outgoing messages. Defaults to true
-component: An RSMP component id.
+`RSMP::Result::Success` contains `value`. `RSMP::Result::Failure` contains an
+immutable `RSMP::Failure` with:
 
-### Collecting
-Use collect() to start collecting and wait for completion or timeout. The status will be returned.
+- `code`: a stable symbol such as `:timeout`, `:not_ready`,
+  `:message_rejected`, or `:disconnected`.
+- `message`: a human-readable explanation.
+- `source`: where the failure originated, such as `:peer`, `:transport`,
+  `:connection`, `:timeout`, or `:local`.
+- `context`: structured details such as the message and connection session.
+- `cause`: the underlying exception, when an expected low-level exception was
+  translated at a boundary.
+
+Use the corresponding bang method when exception-based handling is more
+convenient. A failed result is then raised as `RSMP::OperationError`; its
+`failure` attribute retains the structured failure.
 
 ```ruby
-result = collector.collect # => :ok, :timeout or :cancelled
-collector.messages # => collected messages
+proxy.wait_for_state!(:ready, timeout: 5)
 ```
 
-If you want start collection, but not wait for the result, use `start()`. You can then later use `wait()` if you want:
+Unexpected exceptions are never converted into a `Result`. They propagate with
+their original class and backtrace because they indicate a bug in the library or
+calling application.
 
-```ruby
-result = collector.start # => nil
-# do other stuff
-result = collector.wait
-```
+Message handlers can reject schema-valid but semantically invalid peer input by
+raising `RSMP::PeerMessageError` or one of its domain subclasses, normally
+`RSMP::MessageRejected`. The receive boundary converts only this explicit error
+family to a peer failure. It does not rescue arbitrary `StandardError` values.
 
-### Custom filtering
-You can use a block to do extra filtering. The block will be callled for each messages that passes the Filter provided when initializing the collector.
+## Validation
 
-The block must return nil or a list of symbols to indicate whether the message should be kept, and whether collection should be cancelled.
+Schema mismatches are expected when communicating with an external peer.
+`RSMP::Schema.validate` and `message.validate` return an `RSMP::Validation`:
 
 ```ruby
-result = collector.collect do |message|
-	:keep, :cancel 		# example of how to keep the message and cancel collection
+validation = message.validate(core: '3.3.0', tlc: '1.3.0')
+
+unless validation.valid?
+  warn validation.message
+  validation.violations.each { |violation| warn violation.inspect }
 end
 ```
 
-`:keep` keeps (collect) this message
-`:cancel` cancel collection
+`message.validate!` is the explicit raising variant. Invalid API arguments,
+missing schema configuration, and unknown schema versions still raise directly
+because they are programming or configuration errors rather than invalid peer
+messages.
 
-Note that you cannot use `return` in a block. You can either simply provide the values as the last expresssion in the block, or use next().
+## Collectors
 
-Exceptions in the block will cause the collector to abort. If the collect! or wait! variants are used, the exception is propagated to the caller.
-
-### Bang version
-The method collect!() will raise exceptions in case of errors, and will return the collect message directly.
+A collector attaches to a message distributor, such as `SiteProxy` or
+`SupervisorProxy`, and waits for matching messages. Give it a count, a timeout,
+or a block that completes or cancels the collection.
 
 ```ruby
-message = collector.collect! # => collected message.
+filter = RSMP::Filter.new(type: 'Alarm', ingoing: true, component: 'DL1')
+collector = RSMP::Collector.new(proxy, filter: filter, num: 2, timeout: 5)
+result = collector.collect
 ```
 
-Similar, `wait!()` will raise an exception in case of timeouts or errors:
+A successful collector returns `Result<RSMP::Collection>`. A collection is an
+immutable snapshot containing `messages` and, for state collectors, `reached`
+and `matcher_status`.
 
 ```ruby
-message = collector.wait! # => collected message.
+if result.success?
+  result.value.messages.each { |message| puts message }
+end
 ```
 
+`collect!` and `wait!` return the message array directly and raise
+`RSMP::OperationError` for an expected failure.
 
-### Schema Errors and Disconnects
-The collector can optionally cancel collection in special cases, controlled by the `:cancel` option provided when contructing the collector.
+To start without waiting:
 
 ```ruby
-options = {
-	cancel: {
-		disconnect: true,
-		schema_error: true
-	}
-}
-result = collector.collect options
+collector.start
+# Perform another operation.
+result = collector.wait
 ```
 
-disconnect: If the proxy which provides messages experience a disconnect, the collector will cancel collection.
-
-schema_error: If the proxy receives a message with a schema error, the collector will cancel collection, if the the invalid message has the correct message type.
-
-### NotAck
-A typical scenaria is that you send a command or status request, and want to collect the response. But if the original message is rejected by the site, you will received a NotAck instead of a reply. The collector classes can handle this, as long as you provide the message id of the original request in the `m_id` key of teh options when you construct the collector.
-
-If a NotAck is received with a matching `oMId` (original message id), the collection is cancelled.
+Collectors start in an inactive state, become active after `start`, and detach
+from the distributor exactly once when they succeed or fail. A matching
+`MessageNotAck`, timeout, invalid peer message, connection end, or explicit
+`cancel` resolves the collector with a failure. An exception raised by a custom
+collector callback rejects its completion and propagates unchanged.
 
-## StatusCollector
-Waits for a set of status criteria to be met.
-
-Note that a single RSMP status message can contain multiple status items. Unlike MessageCollector, a StatusCollector therefore operates on items, rather than messages, and you can't specify a number of messages to collect.
-
-
-### Criteria
-You construct a StatusCollector with set of criteria, specifying the status codes, names, and optionally values that must be met.
-
-### Collecting
-When you start collection, it will complete once all criteria are all fulfilled, the timeout is reached or a custom filtering block aborts the collection.
+Custom blocks return `:keep` to retain a matching message. They can also call
+`collector.cancel(reason)` explicitly.
 
 ```ruby
-collector = StatusCollector.new(options)
-result = matcher.collect(timeout: 5)
-```
-
-### Custom filtering
-You can use a block to do extra filtering. The block will be called for each individual status item that fulfils all criteria, like status code and name, component, etc.
-
-Like with MessageCollector, the block must return a hash specifing whether to keep the message and whether to continue collection.
+result = collector.collect do |message|
+  next :keep if useful?(message)
 
-```ruby
-matcher = StatusCollector.new(options)
-result = matcher.collect(options) do |message,item|
-	next(:keep) if good_item?(item) 		# keep item
+  collector.cancel('No longer needed') if finished?
 end
 ```
 
-## Sending commands
-The method `send_command` sends a CommandRequest to the site and returns the sent message. `component:` defaults to `main.c_id`.
-
-```ruby
-message = send_command(
-  [{'cCI' => 'M0001', 'n' => 'status', 'v' => 'NormalControl'}],
-  component: 'AA+BBCCC=DDDEE001'
-)
-```
+## Sending and collecting atomically
 
-To send and wait for the CommandResponse, use `send_command_and_collect`. It returns a collector; call `.ok!` to raise on NotAck or timeout.
+High-level send methods follow the same non-bang/bang convention:
 
 ```ruby
-collector = send_command_and_collect(
-  [{'cCI' => 'M0001', 'n' => 'status', 'v' => 'NormalControl'}],
-  within: 5,
-  component: 'AA+BBCCC=DDDEE001'
-)
-collector.ok!
+result = proxy.send_command(command_list, component: 'C1')
+message = proxy.send_command!(command_list, component: 'C1')
 ```
 
-## Requesting status
-The method `request_status` sends a StatusRequest to the site and returns `{ sent: message }`. `component:` defaults to `main.c_id`.
+Methods ending in `_and_collect` start their collector before sending, so an
+immediate peer response cannot be missed. They return `Result<RSMP::Exchange>`.
+The exchange contains the request and the immutable completed collection.
 
 ```ruby
-result = request_status(
-  [{'sCI' => 'S0001', 'n' => 'signalgroupstatus'}],
-  component: 'AA+BBCCC=DDDEE001'
-)
-result[:sent]  # => the StatusRequest message
-```
+result = proxy.send_command_and_collect(command_list, component: 'C1', within: 5)
 
-To send and wait for the StatusResponse, use `request_status_and_collect`. It returns a collector; call `.ok!` to raise on NotAck or timeout.
-
-```ruby
-collector = request_status_and_collect(
-  [{'sCI' => 'S0001', 'n' => 'signalgroupstatus'}],
-  within: 5,
-  component: 'AA+BBCCC=DDDEE001'
-)
-collector.ok!
-```
-
-## Subscribing to status updates
-The method `subscribe_to_status` sends a StatusSubscribe message to the site and returns `{ sent: message }`. `component:` defaults to `main.c_id`.
-
-### Without collection
-
-```ruby
-result = subscribe_to_status(
-  [{'sCI' => 'S0001', 'n' => 'signalgroupstatus', 'uRt' => '1'}],
-  component: 'AA+BBCCC=DDDEE001'
-)
-result[:sent]  # => the StatusSubscribe message
-```
-
-If you want to manually collect incoming status updates after subscribing, start a collector before subscribing so you don't miss early responses:
-
-```ruby
-task = async do
-  MessageCollector.new(options).collect(num: 5, timeout: 10)
+if result.success?
+  exchange = result.value
+  puts exchange.request
+  puts exchange.collection.messages
 end
-subscribe_to_status(status_list)
-task.wait
 ```
 
-### With collection
-
-Use `subscribe_to_status_and_collect` to subscribe and collect status updates matching the criteria. It returns a collector; call `.ok!` to raise on NotAck or timeout.
+Status requests and subscriptions use the same shape:
 
 ```ruby
-collector = subscribe_to_status_and_collect(
-  [{'sCI' => 'S0001', 'n' => 'signalgroupstatus', 'uRt' => '1'}],
-  within: 5,
-  component: 'AA+BBCCC=DDDEE001'
-)
-collector.ok!
+result = proxy.request_status_and_collect(status_list, component: 'C1', within: 5)
+result = proxy.subscribe_to_status_and_collect(subscription_list, component: 'C1', within: 5)
 ```
 
+The raising variants are `send_command_and_collect!`,
+`request_status_and_collect!`, and `subscribe_to_status_and_collect!`.

data/documentation/message_distribution.md

@@ -1,12 +1,18 @@
 # Message distribution
 
-Proxy - - Distributor --> Receivers
+```text
+Proxy -- Distributor --> message receivers
+  |
+  +-- EventSource ----> explicit node event subscribers
+```
 
-A proxy distributes messages to receivers, when they are installed.
+A proxy distributes messages to receivers when they are installed. Distribution
+uses a receiver snapshot, so a receiver may safely detach during delivery.
 
 Collectors are special receivers that wait for specific messages, and are used to implement methods for waiting for RSMP responses, statuses, alarms, etc.
 
-Note that Archive is not a receiver, and does not receive messages via the Distributor. Instead the Archive gets and stores messages via the log() interface in the Logging module. The reason is that the items that the Archive and the Logger contain other data as well as the message, like error messages, warnings, text descriptions, colors codes, etc. The Distributor and Receiver handles only Message objects.
+Archive is not a receiver. It stores messages and other log entries through the
+logging interface.
 
 ## Distributor
 A module that handles distributing messages to receivers.
@@ -14,9 +20,17 @@ A module that handles distributing messages to receivers.
 ## Receiver
 Receives messages as long as it's installed into a distributor.
 
+Collectors also receive relevant `RSMP::Event` values, such as
+`:invalid_message` and `:connection_ended`. This lets expected peer and
+transport failures resolve a pending collection without raising.
+
 ## Collector
 Includes the Receiver module to wait for specific messages. Once received
 the client receives the collection.
 
 ## Proxy
 A proxy includes the Distributor module and distributes each message to receivers after processing it.
+
+Long-running occurrences are additionally published to the owning node's
+explicit event subscribers. Event delivery is synchronous and ordered; there is
+no implicit global error queue.