asterism 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54a2e8d7f4b96b04dc56b290714d60a4a8d10cdc87d789ccf01bbb2b474f0459
-  data.tar.gz: be9f2f6c820e67ea513ea19a3d6f88437589cb2020615bc558b553f83e882673
+  metadata.gz: 6ee81a1950e5fffa0f5d299999d7878834a79d897e3b4cbf879e293fc6b00531
+  data.tar.gz: 05a88c6ad24fafe262668cb11f4a48e7e5357678c1903207aae004ac0e518311
 SHA512:
-  metadata.gz: cb166817303dfd933dd1fd6a4444aecd966ce06b66347a4b058759c49dc0b0cd1397bbef60d05753c72ccf511a8f70ea5c49c8ffdfaa591eb2d2cf2255d8b1da
-  data.tar.gz: d0d0549e336a50af534813aa4ab74c068952bf3d43148cc7c2032c0f4447df0aae73c9d1d813f8aa99819310c13ae3e220d59376276195fed408506b34144399
+  metadata.gz: 4c6e015f5bd202a1cf44dc3d6ee59fe8af406cb899735df5ee828610cb82de5aa67035be2b5c9cbf1b4c603e0477eaba1e9e503f3ed901e81308ea1b98c91fbc
+  data.tar.gz: 717902fdcce318aad8a78776f0f72b4063241868dbc8b50def6a0386f2868f764dbf356403b0ef1cbd727c5dc8df6818ced7d465cfb23338452e892d3e0c6dc1

data/CHANGELOG.md

@@ -6,6 +6,84 @@ the earlier ones are only in this repository. From 0.4.0 the two Zenoh
 bindings (asterism-zenoh, picoruby-asterism-zenoh) carry the same minor
 version (a patch release of one may come without the other).
 
+## 0.8.0
+
+Needs asterism-zenoh 0.4.1 or later, as 0.7.1. Wire protocol 1 as before:
+the statuses and the methods' texts in the meta are additions that older
+nodes ignore. The command line comes with the gem (`exe/asterism`); its MCP
+server needs the mcp gem, which is not a dependency.
+
+- Application statuses (protocol 1, an addition: docs/protocol.md 8).
+  `Asterism.status(tables: 3)` / `Asterism.status({ ... })` sets this
+  application's status, a small Hash that changes while it runs (String
+  keys, nested 4 levels at most, 1024 bytes packed at most); it is put on
+  `asterism/<node>/<app>/@status` when it changes (the same status again
+  puts nothing), at connect and after a lost connection comes back, and a
+  get there answers it. `Asterism.status_of(node, app)` reads another
+  application's (nil when it has none). `Asterism::Status.check` /
+  `.parse` clean what comes in. CRuby: `net.status`, `net.status_of`,
+  `net.on_status(pattern) { |node, app, status| }`. Both on mruby too
+  (`rake test:mruby`). `@status` is a verbatim chunk like `@profile`:
+  `asterism/**` does not reach it. The conformance samples are version 3
+  (status queries, `status_of`, `status_puts`).
+- `Asterism.apps(pattern = "*/*")`: the applications alive now
+  (`"<node>/<app>"`, from their liveliness tokens).
+- The command line `asterism` (exe/asterism, CRuby): `nodes`, `objects`,
+  `tree`, `watch` (nodes, applications and objects coming and going, and
+  statuses), `ping` (alias `echo`: round trips of the meta, a profile or a
+  call), `call` (arguments as JSON or Ruby literals, read with Ripper), with
+  `--router` or `--credentials` (a console's `.tar`) and `--json`.
+  README "The command line". `rake test:cli`.
+- `asterism mcp`: an MCP server on stdio (the mcp gem, not a dependency).
+  Read-only tools (`asterism_nodes`, `asterism_objects`, `asterism_status`)
+  always; a tool per method that `--allow` names, its inputs made from the
+  meta's arity; the list follows the network (tools/list_changed).
+- The meta tells the arguments' names and what a method does (protocol 1,
+  an addition: docs/protocol.md 5). `expose` takes
+  `methods: { "move" => { args: %w[token n square], doc: "..." } }` next to
+  the numbers (`{ add: 2 }`), and `doc:` for the object itself; the names
+  give the number of arguments checked (`arity:` says otherwise, -1 for
+  any). Readers ignore the fields (old nodes and new ones mix). `asterism
+  mcp` makes the tools' inputs from the names and their descriptions from
+  the docs; `objects` and `tree` show them. The conformance samples are
+  version 4 (the object `other` of the node under test has them).
+- `on_app_join { |node, app| }` / `on_app_leave { |node, app| }`: an
+  application of another node came or went (its token
+  `asterism/<node>/<app>`), while the node may stay with others; on mruby
+  too. CRuby: `net.on_app_join` / `net.on_app_leave`, and `off_*`.
+
+- `credentials:` on the boards too: `Asterism::Credentials` moved to
+  `mrblib/credentials.rb` and reads the console's `.tar` in plain Ruby
+  (ustar taken apart with `byteslice` / `getbyte`, base64 without `pack`,
+  `asterism.json` with or without a JSON library). `Asterism.connect` takes
+  `credentials:` on mruby (with picoruby-asterism-zenoh's TLS, ESP-IDF
+  builds); `locator` and `node:` are optional when it is given. CRuby keeps
+  its reading (the standard library's tar reader, the file mode warning,
+  the key pair check) in a module prepended to the class. `rake test:mruby`
+  checks the board's reading against CRuby's.
+
+## 0.7.1
+
+Needs asterism-zenoh 0.4.1 or later (`Session#reconnecting?`).
+
+
+- `credentials:` on CRuby (`Asterism.connect`, `Asterism::Zenoh.open`,
+  `Asterism::ROS.connect`): the one `.tar` an Asterism console's
+  certificate page saves (key, certificate, CA, `asterism.json`). It is read
+  in memory (`Asterism::Credentials`, no temporary files) and handed to
+  zenoh as `transport/link/tls/*_base64` with `enable_mtls`; the locator and
+  `node:` default to the router and the name in `asterism.json` (given ones
+  win). A tar the group or others may read is warned about. `rake
+  test:credentials` (docker) connects two nodes to a mutual-TLS zenohd with
+  a tar each.
+
+- A client of a router keeps its connection across a router restart: the
+  bindings reopen it and declare everything again, and Asterism no longer
+  closes the connection on a Zenoh error while the session is reconnecting.
+  `Asterism.reconnecting?` (and `net.reconnecting?`) is true meanwhile; the
+  profile is told again once it is back. `rake test:reconnect` (docker)
+  restarts a zenohd under a CRuby and an mruby node.
+
 ## 0.7.0
 
 **This release breaks compatibility: it speaks wire protocol 1 only.** A

data/README.md

@@ -13,7 +13,8 @@ repository holds the pure Ruby layers, written once for every Ruby:
 | `data/icon.png` | CRuby's default profile icon (32x32 PNG; [Profiles](#profiles)) |
 | `data/msgs/` | ROS 2 message types generated from ROS 2 Jazzy's definitions (Apache-2.0; tf2_msgs BSD-3-Clause; see NOTICE) |
 | `tools/` | The type generator `asterism_msggen.rb`, the Jazzy definitions it reads, `ros2_types.rb` (refreshes them from a ROS 2 image) |
-| `test/` | `test/msgs` (types, CDR; CRuby only), `test_asterism.rb` (objects and ROS between CRuby sessions), `test_profile.rb` (node profiles), `test_session.rb` (`Asterism.session`, `on_join` / `on_leave`), `test_api_*.rb` (the CRuby API), `bench_poll.rb` (`rake bench:poll`) |
+| `exe/asterism`, `lib/asterism/cli*` | The command line: look at a network, call an object, an MCP server ([The command line](#the-command-line); CRuby only) |
+| `test/` | `test/msgs` (types, CDR; CRuby only), `test_asterism.rb` (objects and ROS between CRuby sessions), `test_profile.rb` (node profiles), `test_status.rb` (application statuses), `test_meta_apps.rb` (the meta's args / doc, on_app_join / on_app_leave), `test_cli.rb` (the command line), `test_session.rb` (`Asterism.session`, `on_join` / `on_leave`), `test_api_*.rb` (the CRuby API), `bench_poll.rb` (`rake bench:poll`) |
 | `test/protocol/` | the conformance samples of the wire protocol (`samples.json`), the driver that checks an implementation against them, and the Ruby node it checks (`rake test:protocol`, `rake test:protocol_mruby`; [docs/protocol.md](docs/protocol.md)) |
 | `host_test/` | `rake test:mruby`: the shared layer on mruby (profiles between two mruby processes; `Asterism.session`, `on_join` / `on_leave` and the time of a poll against `peer.rb`) |
 | `examples/` | CRuby: `node.rb` (objects with a board), `node_polled.rb` (the same with the portable API of the boards), `ros2_talker.rb` (topics, a timer, services with ROS 2), `ros2_rover.rb` (drive a ROS 2 robot: `/cmd_vel`, `/odom`, `/imu`), `zenoh.rb` (plain Zenoh), `mujoco/` (MuJoCo run from CRuby through Fiddle, its robot exposed as Asterism objects; see its README) |
@@ -50,6 +51,9 @@ together. It adds who called (`Asterism.current_call`, `expose(...,
 caller: :from)`; [Who called](#who-called)), the kind of a remote error
 (`RemoteError#remote_kind`) and `proxy.asterism_call`.
 
+A mechanism-by-mechanism comparison with dRuby and Rinda is in
+[docs/comparison.md](docs/comparison.md).
+
 ## Which API?
 
 Asterism has two APIs over the same layers. Both are in the CRuby gem;
@@ -84,7 +88,7 @@ time is taken, on both APIs and every Ruby; giving one twice raises
 CRuby (needs CRuby 3.2+ and a C compiler):
 
 ```
-gem install asterism          # also installs asterism-zenoh (~> 0.4.0) and msgpack
+gem install asterism          # also installs asterism-zenoh (>= 0.4.1, < 1.0) and msgpack
 ruby -e 'require "asterism"'
 ```
 
@@ -97,7 +101,7 @@ build but not yet tested. To install from the repositories instead:
 
 ```
 (cd ../asterism-zenoh && rake gem) && rake gem
-gem install --local ../asterism-zenoh/pkg/asterism-zenoh-0.4.0.gem pkg/asterism-0.7.0.gem
+gem install --local ../asterism-zenoh/pkg/asterism-zenoh-0.4.1.gem pkg/asterism-0.8.0.gem
 ```
 
 From the working trees, without installing:
@@ -126,6 +130,7 @@ rake                  # every suite
 rake test:msgs        # generator, type hashes, CDR, bundled types (CRuby only; no Zenoh, no docker)
 rake test:objects     # objects and Asterism::ROS between CRuby sessions over a local peer link
 rake test:api         # the CRuby API (blocks, receiving threads, Enumerators)
+rake test:cli         # the command line (exe/asterism) and its MCP bridge (the mcp gem's client; skipped without it)
 ASTERISM_TEST_ROUTER=tcp/127.0.0.1:7447 rake test:objects test:api   # the same through a zenohd router
 rake test:mruby       # the shared layer on mruby (builds mruby; not part of `rake`)
 rake test:protocol    # the wire protocol's conformance samples and driver against CRuby (docs/protocol.md)
@@ -160,7 +165,7 @@ ruby examples/node_polled.rb --router tcp/192.0.2.2:7447    # the same, polled
 ruby examples/ros2_talker.rb --router tcp/192.0.2.2:7447 [--service NAME]
 
 # ROS 2: drive a robot (made for family-mruby's MuJoCo rover,
-# docker-compose.mujoco.yml): 1 m forward and 90 degrees left by /odom,
+# docker/asterism/docker-compose.mujoco.yml): 1 m forward and 90 degrees left by /odom,
 # compared with /ground_truth/odom; or the keyboard
 ruby examples/ros2_rover.rb --router tcp/192.0.2.2:7447 [--keys]
 
@@ -290,6 +295,35 @@ Asterism.connect("tls/router.example.org:7448", node: "cruby", app: "demo", conf
 end
 ```
 
+With an Asterism console, the certificate page saves everything as one
+file ("Save all (.tar)": the key, the certificate, the CA, an example
+configuration and `asterism.json` with the name and the router). Connect
+with that one file:
+
+```ruby
+Asterism.connect(credentials: "alice.tar", app: "game") do |net|
+  net["fmruby-aaaaaa/game/board"].state
+end
+Asterism::Zenoh.open(credentials: "alice.tar") { |s| s.put("asterism/alice/game/hello", "hi") }
+Asterism::ROS.connect(credentials: "alice.tar") { |ros| ros.node("ruby_talker") }
+```
+
+The gem reads the tar in memory (nothing is written; `Asterism::Credentials`)
+and gives zenoh the CA, the certificate and the key as
+`transport/link/tls/root_ca_certificate_base64`,
+`connect_certificate_base64` and `connect_private_key_base64`, with
+`enable_mtls`. The locator defaults to the router in `asterism.json` and
+`node:` to the certificate's name; give either to use another. `config:`
+(a Hash) is laid over these keys. A tar that the group or others may read
+is warned about, as ssh does with a key: `chmod 600 alice.tar`.
+
+The boards (mruby / PicoRuby over picoruby-asterism-zenoh) take the same
+file with `Asterism.connect(credentials: "/home/asterism/alice.tar", app: "game")`
+when their Zenoh binding has TLS (`Asterism::Zenoh::TLS`; ESP-IDF builds).
+There `Asterism::Credentials` reads the tar in plain Ruby (no Regexp, no
+`pack`), the boards have no file modes to warn about, and the key pair is
+left for the router to check; `config:` takes the TLS keys only.
+
 The router checks the certificate against its CA, and its ACL can tell the
 nodes apart by the certificate's common name. The name in the locator must
 be one the router's certificate is valid for (zenoh checks it; it is
@@ -376,6 +410,95 @@ What may be shared between threads:
 | The boards | one thread (the application's update loop) |
 | Ractors | not supported |
 
+## The command line
+
+The gem has a command, `asterism`, that looks at a network from a terminal
+(CRuby). It is one more node: it connects, reads the liveliness tokens,
+the meta, the profiles and the statuses, and calls a method only when told
+to with `call`.
+
+```
+asterism nodes   --router tcp/192.0.2.2:7447        # nodes, their apps (with their status), profiles
+asterism objects --router tcp/192.0.2.2:7447 'games/games/*'   # objects and their methods
+asterism tree    --credentials admin.tar             # nodes > apps > objects, with methods and statuses
+asterism watch   --router tcp/192.0.2.2:7447        # nodes, apps and objects coming and going, statuses
+asterism ping    --router tcp/192.0.2.2:7447 games/games/othello1   # round trips (its meta; no method runs)
+asterism ping    ... games/games/othello1 --call view '"<token>"'   # round trips of a call
+asterism call    --router tcp/192.0.2.2:7447 games/games/othello1 join '"Alice"'
+asterism call    ... linux/demo/screen say hello --kwargs '{color: 3}'
+```
+
+```
+$ asterism tree --router tcp/192.0.2.2:7447
+games  (cruby) "asterism-games"
+  games  status {"mahjong1":{"st":"wait","members":0,"humans":0,"cpus":0,"away":0}, ...}
+    mahjong1  join(1) mine(0) leave(1) sit(2) stand(1) ...
+linux  (family_mruby/sim)
+  game
+$ asterism watch --router tcp/192.0.2.2:7447
+12:00:01.204 ~ status games/games {"othello1":{"st":"wait","members":0,...}} (now)
+12:00:04.881 + node wasm-1a2b3c
+12:00:04.881 + app wasm-1a2b3c/game
+12:00:05.120 ~ status games/games {"othello1":{"st":"wait","members":1,...}}
+```
+
+- **Where the network is.** `--router tcp/HOST:7447` (a router without TLS),
+  or `--credentials FILE.tar` (a console's `.tar`: mutual TLS, its router
+  and its name; `--router` overrides the router). `--peer LOCATOR` links
+  straight to a node listening there (no router). The node ID is the
+  certificate's name, otherwise `cli-` and 6 hex digits (`--node`); the
+  application `cli-` and 4 (`--app`).
+- **What it sees** is what the router lets it see. With a console's `.tar`
+  that is the row's roles: a role for looking only is in the console's
+  docs/g1_5.md ("Looking only: a viewer role"): it reads every node, object,
+  profile and status, and the router refuses its calls, so `asterism call`
+  says "nobody answers" and nothing runs. Something the router refuses is
+  left out of a listing; it is not reported as gone.
+- **Arguments** of `call` (and `ping --call`): each is JSON, else a Ruby
+  literal (nil, true, false, numbers, strings, symbols, arrays, hashes; read
+  with Ripper, nothing is evaluated), else the text as written. `--kwargs`
+  is a JSON object or a Ruby Hash.
+- **Output**: text, or `--json` (`watch --json`: one object a line, with
+  the time). `--timeout` (2.0 s) is each get's and call's limit, `--settle`
+  (1.5 s) how long it waits for the tokens after connecting.
+- **watch** shows the applications and objects themselves (their tokens),
+  not only the nodes: a node with two applications stays while one closes,
+  and `watch` shows that one leave.
+
+### MCP: Asterism as tools of an AI assistant
+
+`asterism mcp` is an MCP server on stdio (it needs the `mcp` gem, which
+the asterism gem does not depend on: `gem install mcp`). It reads by
+default, and calls only the methods `--allow` names:
+
+```
+asterism mcp --router tcp/192.0.2.2:7447 --allow 'games/othello1.*'
+claude mcp add asterism -- asterism mcp --credentials admin.tar --allow 'games/othello1.*'
+```
+
+| Tool | What |
+|---|---|
+| `asterism_nodes` | the nodes, their profiles, applications (with their statuses) and objects |
+| `asterism_objects` | the objects and their methods (meta); `callable_as` names the tool for an allowed method |
+| `asterism_status` | the applications' statuses (`node` / `app` narrow it) |
+| `<node>.<app>.<object>.<method>` | one per method an `--allow` pattern names, made from the meta: the arguments' names it tells are the inputs and its doc the description (with the object's doc after it); without names, arity n gives the inputs `arg1` .. `argN` (any JSON value), arity -1 an array `args`; `kwargs` is an object of keyword arguments. The answer is `{"value": ...}`, or an error with its kind |
+
+- `--allow PATTERN` (repeatable): `[node/][app/]object.method`, `*` within
+  a part as a wildcard. A pattern with fewer parts matches the last parts
+  of the path (`games/othello1.*` is `*/games/othello1.*`); without
+  `.method` every method of the object.
+- The call tools follow the network: when an allowed object appears or
+  goes, the list is made again and the client is told
+  (`notifications/tools/list_changed`).
+- The calls are made as this node (`--node`, or the certificate's name), so
+  an object exposed with `caller: :from` sees who called; a game table
+  gives the MCP client its own seat. `--app` names this application (a
+  game host that follows its players by the application `game` sees an
+  MCP client started with `--app game` come and go).
+- An object that describes its methods at `expose` (`args:` and `doc:`,
+  "Describing the methods" below) gives the AI assistant the names and the
+  texts; without them it sees only the number of arguments.
+
 ## License
 
 MIT (LICENSE) for Asterism's code. The ROS 2 definitions in
@@ -427,11 +550,12 @@ Asterism.nodes                            # => ["linux", "fmruby-bbbbbb"]
 
 | Call | Returns | Raises / notes |
 |---|---|---|
-| `Asterism.connect(locator, node:, app:, mode: nil, listen: nil, config: nil, connect_timeout: nil, check_timeout: 1.5)` | `Asterism` | `locator`, `mode:`, `listen:` (and `config:` / `connect_timeout:` when given, CRuby only: TLS and the rest of zenoh's configuration; the boards raise `ArgumentError`) go to `Asterism::Zenoh::Session.open` (client of a router by default; `mode: :peer` with or without `listen:` without one). `node:` is this machine's ID, `app:` the application's name (one key chunk each: no `/ * $ ? #`, not starting with `@`; else `ArgumentError`). `Disconnected` when it cannot connect; `Error` when objects of the same `<node>/<app>` are already alive (a second copy of the application), or when already connected. Waits up to `check_timeout:` seconds for that check (a router answers at once; give more over a slow relay). Returns the module itself: on a board the module is the connection (one per application). The default is plain text without authentication; see [Over TLS](#over-tls-a-router-on-the-internet). |
-| `Asterism.expose(name, obj, methods:, caller: nil)` | `"<node>/<app>/<name>"` | `methods:` is an Array of names, or a Hash `name => number of arguments` (checked before the call; `-1` or the Array form: any). `ArgumentError` when `obj` has no such public method. Exposing a name again replaces it. `caller: :from` passes the calling node's ID to every method as the keyword `from:` and refuses a call that brings `from:` itself ([Who called](#who-called)). |
+| `Asterism.connect(locator = nil, node: nil, app:, mode: nil, listen: nil, config: nil, connect_timeout: nil, check_timeout: 1.5, credentials: nil)` (`credentials:` see [Over TLS](#over-tls-a-router-on-the-internet)) | `Asterism` | `locator`, `mode:`, `listen:` (and `config:` / `connect_timeout:` when given: TLS and the rest of zenoh's configuration on CRuby; the boards take the TLS keys of `config:` only and raise `ArgumentError` for the rest) go to `Asterism::Zenoh::Session.open` (client of a router by default; `mode: :peer` with or without `listen:` without one). `node:` is this machine's ID, `app:` the application's name (one key chunk each: no `/ * $ ? #`, not starting with `@`; else `ArgumentError`). `Disconnected` when it cannot connect; `Error` when objects of the same `<node>/<app>` are already alive (a second copy of the application), or when already connected. Waits up to `check_timeout:` seconds for that check (a router answers at once; give more over a slow relay). Returns the module itself: on a board the module is the connection (one per application). The default is plain text without authentication; see [Over TLS](#over-tls-a-router-on-the-internet). |
+| `Asterism.expose(name, obj, methods:, caller: nil, doc: nil)` | `"<node>/<app>/<name>"` | `methods:` is an Array of names, or a Hash `name => number of arguments` (checked before the call; `-1` or the Array form: any) or `name => { args: [names], doc: "text" }` ([Describing the methods](#describing-the-methods)); `doc:` the object's own text. `ArgumentError` when `obj` has no such public method. Exposing a name again replaces it. `caller: :from` passes the calling node's ID to every method as the keyword `from:` and refuses a call that brings `from:` itself ([Who called](#who-called)). |
 | `Asterism.current_call` | `Asterism::CurrentCall` or nil | While an exposed method runs for a call: `from` (the calling node's ID), `verified` (`:claimed`, or `:local` for a call from this application), `object`, `method`. nil outside a call ([Who called](#who-called)). |
 | `Asterism.unexpose(name)` | true / false | |
 | `Asterism.poll` | true / false | Call from the update loop: polls Zenoh, answers the calls that came in, follows who is alive and calls the `on_join` / `on_leave` blocks. `false` once the connection is closed or lost. Cheap when nothing came (0.6.0): each queue is looked at by its count, and the list of nodes is made again only after a liveliness change. |
+| `Asterism.on_app_join { \|node, app\| }` / `Asterism.on_app_leave { \|node, app\| }` | `Asterism` | An application of another node appeared (its token `asterism/<node>/<app>`) / is gone. A node may run several: each comes and goes on its own while the node stays. Told like `on_join` (from `Asterism.poll`; at connect for those there; all leave when the connection is lost); `off_app_join(proc)` / `off_app_leave(proc)`; CRuby `net.on_app_join` / `net.on_app_leave` |
 | `Asterism.on_join { \|node\| }` / `Asterism.on_leave { \|node\| }` | `Asterism` | Another node appeared (one of its applications or objects) / is gone (no application and no object left). The nodes there already join on the first polls after connecting; when the connection is lost, every node known until then leaves (on the next `Asterism.poll`). The blocks run from `Asterism.poll` only, never from the polling inside a waiting call; what they raise comes out of `Asterism.poll`. Each call adds a block; `Asterism.off_join(proc)` / `off_leave(proc)` remove one; `Asterism.close` forgets them (a lost connection does not). |
 | `Asterism[path, timeout: 2.0]` | `Proxy` | `path` is `<node>/<app>/<object>` without wildcards (`ArgumentError`). `timeout:` (seconds) or `timeout_ms:` is the time limit of its calls. Nothing is sent until a method is called. |
 | `proxy.<method>(*args, **kw)` | the remote return value | Waits for the answer (the proxy's time limit). `RemoteError` when it raised there or could not be called (`remote_kind` says which: `raised`, or not exposed `not_exposed` (`NoMethodError`), wrong number of arguments `arguments` (`ArgumentError`), no such object `no_object` (`NameError`); [Errors](#errors)), `TimeoutError` when no answer came in time (also at once when nobody answers that key), `Disconnected`, `EncodeError` (before anything is sent) for a value MessagePack cannot carry. A block cannot be sent (`ArgumentError`). |
@@ -443,11 +567,39 @@ Asterism.nodes                            # => ["linux", "fmruby-bbbbbb"]
 | `proxy.asterism_meta` / `proxy.asterism_path` | Hash, String | `{"methods" => [{"name" => name, "arity" => n}, ...]}` |
 | `Asterism.each(pattern = "**") { \|proxy\| }` | count (Array without a block) | The exposed objects alive now (this application's own included) whose `<node>/<app>/<object>` matches; `*` is one chunk, `**` any number. 1.0 returns the proxies from the block form instead of their number (Ruby's `each` returns its receiver); write `Asterism.each(pattern).size` for the count. |
 | `Asterism.nodes` | `[String]` | Node IDs alive now, this one first. |
+| `Asterism.apps(pattern = "*/*")` | `[String]` | The applications alive now, `"<node>/<app>"` (from their liveliness tokens; this one first). |
 | `Asterism.connected?` / `node_id` / `app` / `exposed` / `lost_reason` | | |
+| `Asterism.reconnecting?` | true / false | True while the router is away and the binding opens the connection again ([When the connection is lost](#when-the-connection-is-lost)). |
 | `Asterism.session` | `Asterism::Zenoh::Session` | The connection's own session, for put / subscribe / a ROS 2 node on the same connection ([One connection](#one-connection-asterismsession)). The same object until the connection closes. `Disconnected` when not connected. Its `close` does nothing (warns once); `Asterism.close` closes it. |
 | `Asterism.close` | nil | Withdraws every exposed object. Idempotent. |
 | `Asterism.profile(kind:, name:, host:, icon:)` / `Asterism.profile` | Hash | This node's profile: sets the fields given and returns it; without arguments, returns it. See [Profiles](#profiles). |
 | `Asterism.profile_of(node, icon: true, timeout: 2.0)` | Hash or nil | Another node's profile, nil when it does not answer (an older version, a ROS 2 node). |
+| `Asterism.status(hash = nil, **fields)` / `Asterism.status` | Hash or nil | This application's status: a Hash is the whole status, keywords change those fields (nil removes one); put on the network when it changes. Without arguments, returns it. See [Status](#status). |
+| `Asterism.status_of(node, app, timeout: 2.0)` | Hash or nil | Another application's status, nil when it has none or does not answer. |
+
+## Describing the methods
+
+The meta (what `proxy.respond_to?` reads) can carry the arguments' names
+and what each method does, for the people and the tools that show them
+(`asterism mcp` turns them into an AI assistant's tool inputs and
+descriptions; `asterism objects` prints them). Give them at `expose`, next
+to the numbers:
+
+```ruby
+Asterism.expose("othello1", table, caller: :from, doc: "An othello table. Call view for the board.",
+                methods: { join: 1,                                   # a number, as before
+                           "move" => { args: %w[token n square],
+                                       doc: "Plays square (\"d3\") on the board version n of view." },
+                           view: { args: [:token], doc: "The board as this member sees it." } })
+```
+
+- The names give the number of arguments checked (`args: %w[a b]` is 2);
+  `arity: -1` keeps it unchecked (the names are then the leading ones).
+- The texts are at most 2048 bytes, the names at most 16 of 64 bytes; the
+  first line of a doc is its summary. They travel in every meta reply, so
+  keep them short on a board.
+- Old readers ignore them and old nodes do not send them
+  (docs/protocol.md 5); a proxy works the same either way.
 
 ## Profiles
 
@@ -502,6 +654,41 @@ Asterism.profile_of("an-older-node")                 # => nil
   an acceptable PNG (nil otherwise), for a tool that wants to check an icon
   first.
 
+## Status
+
+An application tells what changes while it runs: how many tables a game
+host has open and who sits at them, a battery level, a mode. The profile
+says once what a node is; the status is the application's and changes.
+
+```ruby
+Asterism.status(tables: 3, humans: 2)           # sets those fields, keeps the others
+Asterism.status(humans: nil)                    # nil removes a field
+Asterism.status({ "mahjong1" => { "st" => "play", "humans" => 1 } })   # a Hash: the whole status
+Asterism.status                                 # => {"mahjong1" => {...}} (nil when none was set)
+Asterism.status_of("games", "games")            # another application's, or nil
+```
+
+- **On the network.** `asterism/<node>/<app>/@status`
+  ([docs/protocol.md](docs/protocol.md) 8): the application answers a get
+  there with its status, and puts it there when it changes (setting the
+  same status again puts nothing), at connect and after a lost connection
+  comes back. An application that never set one answers nothing.
+- **The value.** A Hash with String (or Symbol) keys; the values are
+  anything a call can carry, nested at most 4 levels below the Hash, and
+  the whole packs into 1024 bytes at most. `ArgumentError` otherwise.
+  Whoever may read `asterism/*/*/@status` reads it: counts and states, not
+  secrets.
+- **Following.** Subscribe to `asterism/*/*/@status` and read each put with
+  `Asterism::Status.parse(key, payload)` (`[node, app, status]` or nil); on
+  CRuby, `net.on_status("*/*") { |node, app, status| }`. Only changes are
+  put: ask `status_of` once for an application that appeared.
+- **Behind access control.** `@status` is a verbatim chunk: `asterism/**`
+  does not match it. A router's rules need `asterism/*/*/@status` for a
+  reader (query, subscription) and `asterism/<node>/*/@status` for the
+  application (put, queryable, reply).
+- Kept across `connect` and `close`, like the profile (it belongs to the
+  process, or the VM on a board).
+
 ## One connection: `Asterism.session`
 
 An application that also puts, subscribes or runs a ROS 2 node uses the
@@ -666,8 +853,21 @@ a field, as before.
 
 ### When the connection is lost
 
-Asterism follows `Asterism::Zenoh`: the connection is closed when the router
-(or the only peer) goes away, and is not reopened by itself. From then on
+A client of a router keeps its connection when the router goes away for a
+while (it restarts, the line drops): the Zenoh binding opens the connection
+again by itself (zenoh-c on CRuby; zenoh-pico built with reconnection on
+the boards) and declares again everything that was declared, so the
+application token, the exposed objects, the liveliness watch and what the
+application declared on `Asterism.session` are all back without the
+application doing anything. Meanwhile `Asterism.reconnecting?` is true,
+`connected?` stays true, the other nodes leave (`on_leave`) and join again
+after it (`on_join`), calls raise `Asterism::Disconnected` or time out, and
+puts reach nobody. The profile is told again once it is back. Measured
+with zenohd 1.10.1 restarted by `docker restart` (`rake test:reconnect`,
+CRuby and mruby): back about 1 s after the router.
+
+A peer connection (or a build without reconnection) is closed when the
+peer (or the router) goes away, and is not reopened by itself. From then on
 `Asterism.poll` returns `false`, `connected?` is false, `lost_reason` says
 why, and calls raise `Asterism::Disconnected`. **`Asterism::Zenoh::Error`
 never comes out of Asterism; it is always wrapped in `Disconnected`** (the

data/exe/asterism

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# The command line of the asterism gem: look at an Asterism network, call
+# an object, or serve it to an MCP client (lib/asterism/cli.rb; `asterism
+# help`).
+require "asterism/cli"
+exit Asterism::CLI.start(ARGV)

data/lib/asterism/cli/allow.rb

@@ -0,0 +1,53 @@
+# The --allow patterns of `asterism mcp` (lib/asterism/cli/mcp.rb): which
+# methods an MCP client may call.
+module Asterism
+  class CLI
+    # The --allow patterns: [node/][app/]object.method, each part a glob
+    # (* any text within the part). A pattern with fewer parts matches the
+    # last parts of the path ("games/othello1.*" is "*/games/othello1.*";
+    # "othello1" alone is "*/*/othello1.*": a pattern without .method
+    # allows every method).
+    class Allow
+      def initialize(patterns)
+        @list = patterns.map { parse(_1) }
+      end
+
+      def empty? = @list.empty?
+
+      # Whether some pattern names this object (any of its methods).
+      def object?(path)
+        parts = path.split("/")
+        @list.any? { |chunks, _| chunks_match?(chunks, parts) }
+      end
+
+      def method?(path, method)
+        parts = path.split("/")
+        @list.any? { |chunks, m| chunks_match?(chunks, parts) && glob?(m, method.to_s) }
+      end
+
+      private
+
+      def parse(pat)
+        slash = pat.rindex("/") || -1
+        dot = pat.index(".", slash + 1)
+        path = dot ? pat[0...dot] : pat
+        meth = dot ? pat[(dot + 1)..] : "*"
+        chunks = path.split("/", -1)
+        if chunks.empty? || chunks.size > 3 || chunks.any?(&:empty?) || meth.empty?
+          raise ArgumentError, "--allow #{pat.inspect}: expected [node/][app/]object.method (globs allowed)"
+        end
+        [Array.new(3 - chunks.size, "*") + chunks, meth]
+      end
+
+      def chunks_match?(chunks, parts)
+        parts.size == 3 && chunks.each_with_index.all? { |c, i| glob?(c, parts[i]) }
+      end
+
+      # Only * is a wildcard (any text); ? and the rest are themselves (a
+      # method may be called ok?).
+      def glob?(pat, text)
+        Regexp.new("\\A#{pat.split('*', -1).map { Regexp.escape(_1) }.join('.*')}\\z").match?(text)
+      end
+    end
+  end
+end

data/lib/asterism/cli/literal.rb

@@ -0,0 +1,132 @@
+# The arguments of `asterism call` (and of the MCP bridge's tests): each is
+# read as JSON, else as a Ruby literal, else taken as the text it is.
+#
+#   Literal.parse('{"seat": 1}')   # => {"seat" => 1}          (JSON)
+#   Literal.parse("[1, :a, nil]")  # => [1, :a, nil]           (Ruby)
+#   Literal.parse("{seat: 1}")     # => {seat: 1}              (Ruby)
+#   Literal.parse("hello")         # => "hello"                (text)
+#
+# The Ruby form is read with Ripper and only literals are taken: nil,
+# true, false, integers, floats, strings without interpolation, symbols,
+# arrays (also %w / %i) and hashes. Nothing is evaluated: anything else (a
+# method call, a constant, a variable) makes it not a literal, and the
+# argument is then the text as written.
+require "json"
+require "ripper"
+
+module Asterism
+  class CLI
+    module Literal
+      class NotLiteral < StandardError; end
+
+      module_function
+
+      # The value of one argument (see above).
+      def parse(text)
+        json(text)
+      rescue JSON::ParserError
+        begin
+          ruby(text)
+        rescue NotLiteral
+          text
+        end
+      end
+
+      # JSON: a value of any kind at the top ("1", "\"x\"", "null" too).
+      def json(text)
+        JSON.parse(text)
+      end
+
+      # A Ruby literal, or NotLiteral.
+      def ruby(text)
+        tree = Ripper.sexp(text)
+        raise NotLiteral, "not Ruby" unless tree && tree[0] == :program
+        body = tree[1]
+        raise NotLiteral, "one value expected" unless body.is_a?(Array) && body.size == 1
+        node(body[0])
+      end
+
+      def node(n)
+        raise NotLiteral, "unexpected #{n.inspect}" unless n.is_a?(Array)
+        case n[0]
+        when :@int then Integer(n[1].delete("_"), 0)
+        when :@float then Float(n[1].delete("_"))
+        when :unary
+          raise NotLiteral, "only - before a number" unless n[1] == :-@ && %i[@int @float].include?(n[2][0])
+          -node(n[2])
+        when :var_ref, :@kw then keyword(n[0] == :var_ref ? n[1] : n)
+        when :string_literal then string(n[1])
+        when :symbol_literal then symbol(n[1])
+        when :dyna_symbol then string(n[1]).to_sym
+        when :array then array(n[1])
+        when :hash then hash(n[1])
+        when :bare_assoc_hash then pairs(n[1])
+        else raise NotLiteral, "not a literal: #{n[0]}"
+        end
+      end
+
+      def keyword(kw)
+        raise NotLiteral, "not a keyword" unless kw[0] == :@kw
+        case kw[1]
+        when "nil" then nil
+        when "true" then true
+        when "false" then false
+        else raise NotLiteral, "keyword #{kw[1]}"
+        end
+      end
+
+      # string_content: plain parts only (no #{...}).
+      def string(content)
+        return "" if content.nil?
+        parts = content[0] == :string_content ? content[1..] : content
+        parts.map do |p|
+          raise NotLiteral, "interpolation" unless p.is_a?(Array) && p[0] == :@tstring_content
+          unescape(p[1])
+        end.join
+      end
+
+      # The escapes of a double-quoted string (\n, \t, \", \\, \u...).
+      def unescape(s)
+        return s unless s.include?("\\")
+        "\"#{s}\"".undump
+      rescue RuntimeError
+        s
+      end
+
+      def symbol(sym)
+        raise NotLiteral, "symbol" unless sym[0] == :symbol
+        sym[1][1].to_sym
+      end
+
+      def array(items)
+        return [] if items.nil?
+        items.map do |e|
+          if e.is_a?(Array) && e[0] == :@tstring_content # %w[...]
+            e[1]
+          elsif e.is_a?(Array) && %i[qwords_add words_add qsymbols_add symbols_add].include?(e[0])
+            raise NotLiteral, "old Ripper form"
+          elsif e.is_a?(Array) && e[0] == :@ident # %i[...]
+            e[1].to_sym
+          else
+            node(e)
+          end
+        end
+      end
+
+      def hash(list)
+        return {} if list.nil?
+        raise NotLiteral, "hash" unless list[0] == :assoclist_from_args
+        pairs(list[1])
+      end
+
+      def pairs(assocs)
+        assocs.to_h do |a|
+          raise NotLiteral, "not a key => value" unless a[0] == :assoc_new
+          k = a[1]
+          key = k[0] == :@label ? k[1].chomp(":").to_sym : node(k)
+          [key, node(a[2])]
+        end
+      end
+    end
+  end
+end