asterism 0.6.0 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba14899dd37f9c4c21e148a2256d71545785da6f61a1f8f6701e2d0d189e9061
-  data.tar.gz: 207e08ed177ffa93cd5c7173a84c31f519f59c8e076c6c641ccaa8db27712ea9
+  metadata.gz: d729d6c233d712c647e7fb1168f2587fa0e81eb1b176a11f12ac7c349f61a592
+  data.tar.gz: fce6e1102b0e4e2c404adf28a299c77efd548f6a07e92dc81a7b54a9efe1951e
 SHA512:
-  metadata.gz: de0f85b8c36d4b3c991603004f151ea68952bd7fcc7fdbc76b992af80505b45be3612c5975e509e4f1415f553db8d91ea94940817c00768705bdbf1a011d45e6
-  data.tar.gz: df7634a6c9453fb647c0f148199ff056c646451e3c839ac5cf02704db0ee7dfa7508d8aabdd9fde8005b8909dd6c7217f2d2b96a6e066ac6895d39d9a2af9481
+  metadata.gz: c2050d9890925ad4b0910f3e8063a7d2b6e9ef1e8f68ea3346bea26c02674cce7a6b0c2ee798d2940f2171d7c763c49dd8160a44b3d3204b13ccea813936430c
+  data.tar.gz: 862531b730d5bc6f00c673271fb4d1d8db6ecaaab11969a4be95234c09be4ba6eceed245b24102f490fda6608f946b5d30e8ce3b960255b197b95bcd5a4aa550

data/CHANGELOG.md

@@ -6,6 +6,100 @@ 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.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
+node of 0.7.0 and a node of 0.6.0 or earlier (protocol 0) do not see each
+other's objects, and a call between them fails: a protocol 0 call to a
+0.7.0 node is refused with the error kind `protocol`, a 0.7.0 call to an
+older node is not answered, and their replies are malformed answers to
+each other. Move every node of a network to 0.7.0 together (boards,
+browsers, consoles, CRuby programs). The Ruby API stays as it was, with
+the additions below. Needs asterism-zenoh / picoruby-asterism-zenoh 0.4.0
+(unchanged), and on mruby a MessagePack that reads and writes bin (README,
+"Using it").
+
+Protocol 1 (`docs/protocol.md`, normative; `docs/protocol_review.md` says
+what was decided and why):
+
+- A call is a get on `asterism/<node>/<app>/<object>/call/<caller>`, where
+  `<caller>` is the calling node's ID. Its payload is a map
+  `{"method" => name, "args" => [...], "kwargs" => {...}}` (args and
+  kwargs left out when empty) instead of the array `[method, args,
+  kwargs]`.
+- A reply is `{"value" => value}` or `{"error" => {"kind" => ..., "class"
+  => ..., "message" => ...}}` instead of `["ok", value]` /
+  `["error", class, message]`. The kinds: `raised`, `not_exposed`,
+  `no_object`, `arguments`, `malformed`, `unsendable`, `nesting`,
+  `protocol`.
+- The meta is `{"methods" => [{"name" => name, "arity" => n}, ...]}`.
+- Binary Strings go as MessagePack bin (CRuby: ASCII-8BIT Strings, no more
+  compatibility mode; mruby: `String#b`), and a bin arrives as a binary
+  String. The profile's icon is a bin.
+- The profile has `"protocol" => 1`.
+- Each application declares its own liveliness token
+  `asterism/<node>/<app>`; the node token `asterism/<node>`, which the
+  applications of a node shared, is gone. A node is present while any of
+  its applications or objects is.
+- A payload is exactly one value: bytes after it, ext types and integers
+  outside the signed 64-bit range make it malformed. CRuby raises
+  `EncodeError` before sending an Integer outside int64 (it raised
+  `RangeError` before).
+- A protocol 0 call (on the five-chunk `.../call` key) is answered with the
+  error kind `protocol`.
+
+Added
+
+- `Asterism.current_call` while an exposed method runs for a call (per
+  thread on CRuby, `net.current_call` too): `from` (the calling node),
+  `verified` (`:claimed`; `:local` for a call from the same application),
+  `object`, `method`. `Asterism::CurrentCall`.
+- `Asterism.expose(name, obj, methods:, caller: :from)` (and
+  `net.expose`): passes the calling node's ID as the keyword `from:` and
+  refuses a call that brings `from:` itself.
+- `RemoteError#remote_kind`: the error's kind, as above (nil when the
+  answer did not say).
+- `proxy.asterism_call(name, *args, **kw)` and `proxy.async.asterism_call`:
+  a call by the method's name, for names a proxy cannot forward (`display`,
+  `hash`, `class`, `fail`, ...) and names that are not Ruby identifiers.
+- `Asterism::PROTOCOL` (1).
+- The conformance tests (`test/protocol/`) are protocol 1's: 55 values, 54
+  incoming queries, 24 outgoing steps; CRuby and mruby pass them all.
+
+Changed
+
+- `proxy.asterism_meta` returns the new meta form.
+- `Asterism.connect`'s duplicate check also finds a copy of the
+  application that exposes nothing (it has its application token now).
+- `host_test/msgpack.rb` (the mruby test's MessagePack) writes a binary
+  String as bin and reads a bin as one; the mruby test build adds
+  mruby-encoding (to tell a binary String).
+- The documentation of the wire protocol (docs/protocol.md,
+  docs/protocol_review.md) and the conformance tests (X0, unreleased in
+  0.6.0) are rewritten for protocol 1.
+
 ## 0.6.0
 
 One connection for everything and a lighter `Asterism.poll`; every 0.5.x

data/README.md

@@ -14,6 +14,7 @@ repository holds the pure Ruby layers, written once for every Ruby:
 | `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`) |
+| `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) |
 
@@ -42,7 +43,15 @@ profiles ([Profiles](#profiles): what a node runs on, where, a name and an
 icon); 0.6.0 adds `Asterism.session`
 ([One connection](#one-connection-asterismsession): the object layer's
 session for plain Zenoh and ROS 2 too) and makes `Asterism.poll` cheap when
-nothing changed.
+nothing changed. **0.7.0 speaks wire protocol 1 only**
+([docs/protocol.md](docs/protocol.md)): it does not talk to the object
+layer of earlier versions, so every node of a network moves to 0.7.0
+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?
 
@@ -78,7 +87,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"'
 ```
 
@@ -91,7 +100,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.6.0.gem
+gem install --local ../asterism-zenoh/pkg/asterism-zenoh-0.4.1.gem pkg/asterism-0.7.1.gem
 ```
 
 From the working trees, without installing:
@@ -101,12 +110,14 @@ ruby -I lib -I ../asterism-zenoh/lib your_script.rb    # after `rake compile` in
 ```
 
 `Asterism::ROS::TYPE_PATH` is `data/msgs` there; add your own directories.
-MessagePack sends every String as str (compatibility mode), as the boards
-do: their MessagePack does not read the bin type.
+MessagePack sends a binary (ASCII-8BIT) String as bin and any other String
+as str (protocol 1; [Values](#values)).
 
 mruby / PicoRuby: add this repository and picoruby-asterism-zenoh as gems
 (`conf.gem "path/to/asterism"`; a `MessagePack` module with `pack` /
-`unpack` is needed too), and put `data/msgs` on the device's file system at
+`unpack` is needed too: for protocol 1 it must write a binary String
+(`String#b`) as bin and read a bin as one, and refuse ext types, integers
+outside int64 and bytes after the value), and put `data/msgs` on the device's file system at
 `/usr/share/asterism/msgs` (or add the place to
 `Asterism::ROS::TYPE_PATH`). Family mruby does this from pinned commits of
 these repositories.
@@ -120,6 +131,8 @@ rake test:objects     # objects and Asterism::ROS between CRuby sessions over a
 rake test:api         # the CRuby API (blocks, receiving threads, Enumerators)
 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)
+rake test:protocol_mruby   # the same driver against mruby (builds mruby; not part of `rake`)
 rake bench:poll       # the time and allocations of one Asterism.poll by nodes and objects (prints a table)
 ```
 
@@ -251,7 +264,8 @@ end
 |---|---|
 | `Asterism.connect(...) { \|net\| }` | yields an `Asterism::Net`, `Asterism.close` when the block ends; returns the block's value. Without a block, as before |
 | `Asterism.net` | the `Net` of the connection made without a block (nil when not connected) |
-| `net.expose` / `unexpose` / `exposed` | as `Asterism.expose`. The methods run on the receiving thread, in `run`, or in whatever polls |
+| `net.expose` / `unexpose` / `exposed` | as `Asterism.expose` (also `caller: :from`). The methods run on the receiving thread, in `run`, or in whatever polls |
+| `net.current_call` | `Asterism.current_call`: the call being answered on this thread (the receiving thread while it answers), or nil |
 | `net[path, timeout: 2.0]` | a proxy (`timeout` in seconds, or `timeout_ms:`) |
 | `net.each(pattern = "**")` | the proxies alive now; an Enumerator without a block. With a block it returns their number (1.0: `self`, as Ruby's `each` does; `net.count` is the number) |
 | `net.on_join { \|node\| }` / `net.on_leave { \|node\| }` | `Asterism.on_join` / `on_leave` of the portable API (the same blocks, told from `Asterism.poll`), here on the receiving thread; what they raise goes to `on_error`. `net.off_join(proc)` / `off_leave(proc)` remove one |
@@ -279,6 +293,28 @@ 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 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
@@ -416,21 +452,24 @@ 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:)` | `"<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. |
+| `Asterism.connect(locator, node:, app:, mode: nil, listen: nil, config: nil, connect_timeout: nil, check_timeout: 1.5)` (CRuby also `credentials:`, see [Over TLS](#over-tls-a-router-on-the-internet)) | `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.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_join { \|node\| }` / `Asterism.on_leave { \|node\| }` | `Asterism` | Another node appeared (its node token or one of its objects) / is gone (no token 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.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 (not exposed: `NoMethodError`; wrong number of arguments: `ArgumentError`; no such object: `NameError`), `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`). |
+| `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`). |
+| `proxy.asterism_call(name, *args, **kw)` | the remote return value | The same call by the method's name (a String or Symbol): for names a proxy cannot forward (those `Object` and `Kernel` have: `display`, `hash`, `class`, `fail`, ...) and names that are not Ruby identifiers. `proxy.async.asterism_call(...)` returns a `Future`. |
 | `proxy.async.<method>(...)` | `Future` | Sends and returns at once. `EncodeError` / `Disconnected` are raised here. |
 | `future.done?` | true / false | Never waits (`Asterism.poll` moves it on). True once the answer came, the time ran out or the connection closed. |
 | `future.value` | the return value | Waits (polling) if not done; raises like a waiting call. `future.took` (seconds) / `took_ms`: time to the answer. |
 | `proxy.respond_to?(name)` / `proxy.remote_methods` | true / false, `[Symbol]` | From the object's meta (fetched once, `proxy.asterism_refresh` forgets it). `respond_to?` is false when the object does not answer; `remote_methods` raises then. (`proxy.methods` returns the same with a deprecation warning; from 1.0 it is `Object#methods`.) |
-| `proxy.asterism_meta` / `proxy.asterism_path` | Hash, String | `{"methods" => [[name, arity], ...]}` |
+| `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.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). |
@@ -444,19 +483,20 @@ and an icon. A console draws it with that; anyone can ask.
 ```ruby
 Asterism.profile(name: "Rover", icon: File.binread("rover.png"))   # this node's (any time)
 Asterism.profile
-# => {"kind" => "cruby", "name" => "Rover", "icon" => "\x89PNG...", "icon_hash" => "2a8c0626"}
+# => {"protocol" => 1, "kind" => "cruby", "name" => "Rover", "icon" => "\x89PNG...", "icon_hash" => "2a8c0626"}
 Asterism.profile_of("fmruby-aaaaaa")
-# => {"kind" => "family_mruby", "host" => "atoms3r", "icon" => "\x89PNG...", "icon_hash" => "..."}
+# => {"protocol" => 1, "kind" => "family_mruby", "host" => "atoms3r", "icon" => "\x89PNG...", "icon_hash" => "..."}
 Asterism.profile_of("fmruby-aaaaaa", icon: false)   # the same without the icon bytes
 Asterism.profile_of("an-older-node")                 # => nil
 ```
 
 | Field | Value | Default |
 |---|---|---|
+| `protocol` | set by Asterism, never given: the wire protocol the node speaks (`Asterism::PROTOCOL`, 1). A node whose profile has none speaks protocol 0 (asterism before 0.7.0), which 0.7.0 does not talk to | |
 | `kind` | what Ruby runs the node: `family_mruby`, `picoruby`, `cruby`, `console` (a lower-case word: `a-z`, `0-9`, `_`, up to 32 bytes; other words are allowed) | `cruby` on CRuby, `picoruby` on mruby / PicoRuby; Family mruby's firmware sets `family_mruby` |
 | `host` | where it runs, e.g. `atoms3r`, `tab5`, `p4nano`, `browser`, `sim` (up to 32 bytes) | none; Family mruby's firmware sets it from the board |
 | `name` | a display name (up to 64 bytes) | none |
-| `icon` | the bytes of a PNG: at most 8 KB and 256x256 (32x32 is the size meant). PNG only: an SVG can carry scripts | the file at `Asterism.default_icon_path` when it is there: on CRuby the gem's `data/icon.png` (a ruby), on the boards `/usr/share/asterism/icon.png` |
+| `icon` | the bytes of a PNG (a binary String; sent as a MessagePack bin): at most 8 KB and 256x256 (32x32 is the size meant). PNG only: an SVG can carry scripts | the file at `Asterism.default_icon_path` when it is there: on CRuby the gem's `data/icon.png` (a ruby), on the boards `/usr/share/asterism/icon.png` |
 | `icon_hash` | set by Asterism, never given: the icon's summary (8 hex digits: the Adler-32 of the PNG's chunk CRCs, so a board computes it from a few bytes) | |
 
 - **Setting.** `Asterism.profile(**fields)` changes the fields given and keeps
@@ -536,7 +576,7 @@ end
   another. Your own `put` does not come back to your own subscriber on the
   same session.
 - **Keys.** Keep your keys out of the object layer's: `asterism/<node>/<app>/**`
-  is answered by its queryable (`get` there is a call), `asterism/<node>` and
+  is answered by its queryable (`get` there is a call), `asterism/<node>/<app>` and
   `asterism/<node>/<app>/<object>` are its liveliness tokens. Putting under
   `asterism/<node>/<app>/<object>/<anything>` (a state, a log) is fine:
   puts and subscriptions do not meet queryables or liveliness.
@@ -553,12 +593,18 @@ Asterism::Error                       (the Zenoh bindings define it)
 ├── Asterism::TimeoutError            (no answer in time; old name Asterism::Timeout)
 │   └── Asterism::ROS::TimeoutError   (old name Asterism::ROS::Timeout)
 ├── Asterism::EncodeError
-├── Asterism::RemoteError             (remote_class, remote_message)
+├── Asterism::RemoteError             (remote_kind, remote_class, remote_message)
 ├── Asterism::ROS::UnknownType
 ├── Asterism::CDR::DecodeError
 └── Asterism::DeprecationError        (only with Asterism.deprecations = :raise)
 ```
 
+`RemoteError#remote_kind` says what happened on the other side, as a word
+of the protocol (docs/protocol.md 4.4): `raised` (the method raised;
+`remote_class` is its class there), `not_exposed`, `no_object`,
+`arguments`, `malformed`, `unsendable`, `nesting`, `protocol` (the other
+side speaks a different protocol); nil when the answer did not say.
+
 The old names `Asterism::Timeout` and `Asterism::ROS::Timeout` still work
 (they warn once). Inside `module Asterism`, `Timeout` is Ruby's `Timeout`
 module again. The ROS layer raises `Zenoh::ClosedError` when its session
@@ -646,8 +692,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
@@ -658,22 +717,71 @@ session is closed, its entities raise `Zenoh::ClosedError`).
 
 ## Values
 
-Only what MessagePack carries: `nil`, `true`, `false`, `Integer` (64 bit),
-`Float`, `String`, `Array`, `Hash`. A `Symbol` is sent as a `String` (also
-as a Hash key: keyword arguments arrive as Symbols again). Anything else in
-the arguments raises `EncodeError` before sending; in a return value the
-caller gets `RemoteError` (`Asterism::EncodeError`). Nesting is limited to
-16 levels.
+Only what MessagePack carries: `nil`, `true`, `false`, `Integer` (signed
+64 bit), `Float`, `String`, `Array`, `Hash`. A `Symbol` is sent as a
+`String` and arrives as one (also as a Hash key; keyword names become
+Symbols again). A binary String (`String#b`: ASCII-8BIT on CRuby, the
+binary flag on mruby) goes as a MessagePack bin and arrives as a binary
+String; any other String goes as text (str). Anything else in the
+arguments, or an Integer outside the signed 64-bit range, raises
+`EncodeError` before sending; in a return value the caller gets
+`RemoteError` (`unsendable`). Nesting is limited to 16 levels.
+
+- Hash keys: use String (or Symbol) and Integer keys for anything another
+  language reads (Python and JavaScript refuse others by default).
+- Times: send an Integer of nanoseconds since the epoch (or name the unit:
+  `timeout_ms`); there is no time type.
+- A keyword given as `nil` and one left out differ: the callee's default
+  applies only to the one left out.
+- A JavaScript caller's `1.0` arrives as the Integer `1`.
+
+## Who called
+
+The caller's node ID travels in the call's key (`.../call/<caller>`). An
+exposed method can read it:
+
+```ruby
+class Rover
+  def stop
+    c = Asterism.current_call        # nil outside a call
+    log("stop from #{c.from}")       # c.verified: :claimed (:local from this app)
+  end
+
+  def drive(v, w, from:)             # caller: :from fills from: in
+    log("drive from #{from}")
+  end
+end
+Asterism.expose("rover", Rover.new, methods: { stop: 0 })
+Asterism.expose("wheels", Rover.new, methods: { drive: 2 }, caller: :from)
+```
+
+- `Asterism.current_call` is set only while a method runs for a call (per
+  thread on CRuby). Calls answered while that method waits for its own
+  call come on top of it and go when they end.
+- With `caller: :from`, a call that passes `from:` itself is refused
+  (`RemoteError`, `remote_kind` `arguments`): `from` is always the one
+  Asterism took from the call.
+- **It is a claim.** Any client can call with any name. A router's access
+  control makes it binding: with mutual TLS, zenohd's ACL can let each
+  certificate query only keys ending in its own name
+  (`asterism/*/*/*/call/<name>`; docs/protocol.md 4.7). Without such a
+  router, use `from` to avoid mistakes, not to decide who may do what.
 
 ## Keys and encoding
 
+Wire protocol 1. The full description, for implementations in other
+languages, is [docs/protocol.md](docs/protocol.md) (with the conformance
+tests); why it has this shape (the review of protocol 0's Ruby-shaped
+parts, and what was decided) is
+[docs/protocol_review.md](docs/protocol_review.md).
+
 | Key | Zenoh | Payload |
 |---|---|---|
-| `asterism/<node>/<app>/<object>/call` | get / queryable | query: `[method, [args...], {kwargs}]`; reply: `["ok", value]` or `["error", class name, message]` |
-| `asterism/<node>/<app>/<object>/meta` | get / queryable | reply: `{"methods" => [[name, arity], ...]}` (arity `-1` when not declared). The object may be `*` in the query: one reply per object |
-| `asterism/<node>` | liveliness | the node is connected |
+| `asterism/<node>/<app>/<object>/call/<caller>` | get / queryable | query: `{"method" => name, "args" => [...], "kwargs" => {...}}` (args and kwargs left out when empty); reply: `{"value" => value}` or `{"error" => {"kind" => ..., "class" => ..., "message" => ...}}`. `<caller>` is the calling node's ID |
+| `asterism/<node>/<app>/<object>/meta` | get / queryable | reply: `{"methods" => [{"name" => name, "arity" => n}, ...]}` (arity `-1` when not declared). The object may be `*` in the query: one reply per object |
+| `asterism/<node>/<app>` | liveliness | the application is connected (a node is there while any of its applications or objects is) |
 | `asterism/<node>/<app>/<object>` | liveliness | the object is exposed |
-| `asterism/<node>/@profile` | get / queryable, and put | query (parameter `icon=0` for no icon): reply the node's profile, a Hash (`kind`, `host`, `name`, `icon`, `icon_hash`; [Profiles](#profiles)). The node also puts the profile without the icon at connect and on each change. `@profile` is a verbatim chunk, so `asterism/**` does not match it: the object layer's wildcards never see it. An application's own profile would go at `asterism/<node>/<app>/@profile` (not in 0.6.0) |
+| `asterism/<node>/@profile` | get / queryable, and put | query (parameter `icon=0` for no icon): reply the node's profile, a Hash (`kind`, `host`, `name`, `icon`, `icon_hash`; [Profiles](#profiles)). The node also puts the profile without the icon at connect and on each change. `@profile` is a verbatim chunk, so `asterism/**` does not match it: the object layer's wildcards never see it. An application's own profile would go at `asterism/<node>/<app>/@profile` (not yet) |
 
 One queryable per application (`asterism/<node>/<app>/**`), and one for the
 profile (`asterism/<node>/@profile`). A call whose
@@ -728,9 +836,9 @@ nested type (`geometry_msgs/msg/Twist`) at start-up took 0.6 KB more.
 
 - Objects cannot be passed by reference (a return value is a copy), blocks
   cannot be sent, there are no events (later stages).
-- The node token `asterism/<node>` is shared by every application of that
-  node; when one of them closes, the others still list the node through
-  their objects, but a watcher may see the node token go away.
+- The wire protocol is protocol 1 only: nodes of asterism before 0.7.0
+  (protocol 0) do not see 0.7.0's objects and a call between the two
+  fails (a protocol 0 call is refused with `remote_kind` `protocol`).
 - No authentication by default (plain TCP): a trusted LAN is assumed, or
   TLS through a router (CRuby; [Over TLS](#over-tls-a-router-on-the-internet)).
 - One object-layer connection per process (per VM on the boards).

data/lib/asterism/cruby/credentials.rb

@@ -0,0 +1,152 @@
+# The credentials of one node or router as one file (CRuby only): the .tar
+# an Asterism console hands out when it issues a certificate ("Save all
+# (.tar)" on the certificate page; the archive is made in the browser that
+# made the key). It holds, at its top or in one directory:
+#
+#   <name>.key      the private key (PKCS#8 PEM)
+#   <name>.pem      the certificate (its common name is <name>)
+#   ca.pem          the CA that signed it (and the router's certificate)
+#   zenoh.json5     an example configuration (for zenohd or another client)
+#   asterism.json   {"name": ..., "router": "tls/host:port", "not_after": ..., ...}
+#
+#   Asterism.connect(credentials: "alice.tar", app: "game") { |net| ... }
+#   Asterism::Zenoh.open(credentials: "alice.tar") { |s| ... }
+#   Asterism::ROS.connect(credentials: "alice.tar") { |ros| ... }
+#
+# The file is read into memory (Gem::Package::TarReader, the standard
+# library): nothing is written anywhere. The certificates go to zenoh as
+# base64 (transport/link/tls/*_base64) with enable_mtls, the router's
+# locator and the node ID come from asterism.json unless given, and a file
+# that others may read is warned about, as ssh does with a key.
+require "rubygems/package"
+require "json"
+require "stringio"
+
+module Asterism
+  class Credentials
+    # What a credentials file is missing or holds wrong.
+    class Error < ::Asterism::Error; end
+
+    TLS = "transport/link/tls"
+    # The largest file read (the real ones are a few KB).
+    MAX_SIZE = 1024 * 1024
+
+    attr_reader :path, :name, :kind, :router, :not_after, :key_pem, :cert_pem, :ca_pem, :info
+
+    # Reads path (a String or Pathname of a .tar). warn: false skips the
+    # check of who may read the file.
+    def self.load(path, warn: true)
+      new(path, warn: warn)
+    end
+
+    # A credentials file (a path or a Credentials) and the arguments of a
+    # connection -> [locator, config Hash, credentials]. The locator given
+    # wins over asterism.json's router; config given (a Hash) is laid over
+    # the TLS keys. @api private
+    def self.merge(credentials, locator, config)
+      creds = credentials.is_a?(Credentials) ? credentials : load(credentials)
+      if config.is_a?(String)
+        raise ArgumentError, "credentials: and a config String cannot be combined; pass config: as a Hash"
+      end
+      merged = creds.zenoh_config.merge(config || {})
+      [locator || creds.router, merged, creds]
+    end
+
+    def initialize(path, warn: true)
+      @path = path.to_s
+      check_mode if warn
+      files = read_tar
+      @info = parse_info(files["asterism.json"])
+      keys = files.keys.select { _1.end_with?(".key") }
+      raise Error, "#{@path}: no private key (<name>.key) in it" if keys.empty?
+      raise Error, "#{@path}: more than one private key in it (#{keys.sort.join(', ')})" if keys.size > 1
+      @name = @info["name"].to_s
+      @name = File.basename(keys.first, ".key") if @name.empty?
+      @key_pem = files["#{@name}.key"] or raise Error, "#{@path}: the key is not named after #{@name} (#{keys.first})"
+      @cert_pem = files["#{@name}.pem"] or raise Error, "#{@path}: no certificate #{@name}.pem in it"
+      @ca_pem = files["ca.pem"] or raise Error, "#{@path}: no ca.pem in it"
+      @kind = @info["kind"]
+      @router = @info["router"].to_s.empty? ? nil : @info["router"].to_s
+      @not_after = @info["not_after"]
+      check_pair
+    end
+
+    # The zenoh configuration keys (a Hash for Session.open's config:):
+    # the CA, the certificate and the key as base64, and mutual TLS.
+    def zenoh_config
+      {
+        "#{TLS}/root_ca_certificate_base64" => b64(@ca_pem),
+        "#{TLS}/connect_certificate_base64" => b64(@cert_pem),
+        "#{TLS}/connect_private_key_base64" => b64(@key_pem),
+        "#{TLS}/enable_mtls" => true
+      }
+    end
+
+    def inspect
+      "#<Asterism::Credentials #{@name} #{@router || '(no router)'}#{@not_after ? " until #{@not_after}" : ''}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def b64(pem)
+      [pem].pack("m0")
+    end
+
+    # Like ssh with a private key: a file that the group or others may read
+    # is told about (it still works).
+    def check_mode
+      st = File.stat(@path)
+      return if Gem.win_platform? || (st.mode & 0o077).zero?
+      Kernel.warn("asterism: #{@path} holds a private key and can be read by others " \
+                  "(mode #{format('%04o', st.mode & 0o7777)}); chmod 600 #{@path}")
+    rescue SystemCallError => e
+      raise Error, "#{@path}: #{e.message}"
+    end
+
+    # {basename => content} of the regular files, at the top or in one
+    # directory.
+    def read_tar
+      data = File.binread(@path)
+      raise Error, "#{@path}: too large for a credentials file" if data.bytesize > MAX_SIZE
+      files = {}
+      Gem::Package::TarReader.new(StringIO.new(data)) do |tar|
+        tar.each do |entry|
+          next unless entry.file?
+          base = File.basename(entry.full_name)
+          raise Error, "#{@path}: #{base} is in it twice" if files.key?(base)
+          files[base] = entry.read.to_s
+        end
+      end
+      raise Error, "#{@path}: not a tar file with credentials in it" if files.empty?
+      files
+    rescue SystemCallError => e
+      raise Error, "#{@path}: #{e.message}"
+    rescue Gem::Package::TarInvalidError, ArgumentError => e
+      raise Error, "#{@path}: not a tar file (#{e.message})"
+    end
+
+    def parse_info(text)
+      return {} if text.nil?
+      h = JSON.parse(text)
+      raise Error, "#{@path}: asterism.json is not an object" unless h.is_a?(Hash)
+      h
+    rescue JSON::ParserError => e
+      raise Error, "#{@path}: asterism.json: #{e.message}"
+    end
+
+    # The key belongs to the certificate, and the certificate has not
+    # expired (a warning: zenoh refuses it anyway). Skipped without openssl.
+    def check_pair
+      require "openssl"
+      cert = OpenSSL::X509::Certificate.new(@cert_pem)
+      key = OpenSSL::PKey.read(@key_pem)
+      raise Error, "#{@path}: #{@name}.key is not the key of #{@name}.pem" unless cert.check_private_key(key)
+      Kernel.warn("asterism: #{@path}: the certificate expired at #{cert.not_after.utc}") if cert.not_after < Time.now
+    rescue LoadError
+      nil
+    rescue OpenSSL::OpenSSLError => e
+      raise Error, "#{@path}: #{e.message}"
+    end
+  end
+end

data/lib/asterism/cruby/objects.rb

@@ -26,7 +26,7 @@ module Asterism
   # The portable API, entered under LOCK. Prepended to the Asterism module's
   # singleton class, so the shared methods themselves are not changed.
   module Locked
-    %i[expose unexpose poll nodes [] call_async meta connected? exposed on_join on_leave off_join off_leave
+    %i[expose unexpose poll nodes [] call_async meta connected? reconnecting? exposed on_join on_leave off_join off_leave
        profile profile_async session].each do |m|
       define_method(m) do |*args, **kw, &blk|
         ::Asterism::LOCK.synchronize { super(*args, **kw, &blk) }
@@ -36,8 +36,16 @@ module Asterism
     # With a block: yields an Asterism::Net and closes when the block ends
     # (also on an exception); returns the block's value. Without a block,
     # as before (returns Asterism).
-    def connect(locator, node:, app:, mode: nil, listen: nil, config: nil, connect_timeout: nil, check_timeout: nil,
-                &blk)
+    #
+    # credentials: a .tar from an Asterism console (Asterism::Credentials):
+    # its certificates go to zenoh (mutual TLS), and the locator and node:
+    # default to its router and name (given ones win).
+    def connect(locator = nil, node: nil, app:, mode: nil, listen: nil, config: nil, connect_timeout: nil,
+                check_timeout: nil, credentials: nil, &blk)
+      if credentials
+        locator, config, creds = ::Asterism::Credentials.merge(credentials, locator, config)
+        node ||= creds.name
+      end
       ::Asterism::LOCK.synchronize do
         super(locator, node: node, app: app, mode: mode, listen: listen, config: config,
                        connect_timeout: connect_timeout, check_timeout: check_timeout)
@@ -148,17 +156,22 @@ module Asterism
     def node_id = ::Asterism.node_id
     def app = ::Asterism.app
     def connected? = ::Asterism.connected?
+    def reconnecting? = ::Asterism.reconnecting?
     def lost_reason = ::Asterism.lost_reason
     def nodes = ::Asterism.nodes
     def exposed = ::Asterism.exposed
 
     # Asterism.expose: methods: an Array of names or a Hash name => number
-    # of arguments. The object's methods run on the receiving thread (or in
+    # of arguments; caller: :from passes the calling node's ID as that
+    # keyword. The object's methods run on the receiving thread (or in
     # run, or in whatever polls).
-    def expose(name, obj, methods:)
-      ::Asterism.expose(name, obj, methods: methods)
+    def expose(name, obj, methods:, caller: nil)
+      ::Asterism.expose(name, obj, methods: methods, caller: caller)
     end
 
+    # Asterism.current_call: the call being answered on this thread, or nil.
+    def current_call = ::Asterism.current_call
+
     def unexpose(name)
       ::Asterism.unexpose(name)
     end