asterism 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba14899dd37f9c4c21e148a2256d71545785da6f61a1f8f6701e2d0d189e9061
-  data.tar.gz: 207e08ed177ffa93cd5c7173a84c31f519f59c8e076c6c641ccaa8db27712ea9
+  metadata.gz: 54a2e8d7f4b96b04dc56b290714d60a4a8d10cdc87d789ccf01bbb2b474f0459
+  data.tar.gz: be9f2f6c820e67ea513ea19a3d6f88437589cb2020615bc558b553f83e882673
 SHA512:
-  metadata.gz: de0f85b8c36d4b3c991603004f151ea68952bd7fcc7fdbc76b992af80505b45be3612c5975e509e4f1415f553db8d91ea94940817c00768705bdbf1a011d45e6
-  data.tar.gz: df7634a6c9453fb647c0f148199ff056c646451e3c839ac5cf02704db0ee7dfa7508d8aabdd9fde8005b8909dd6c7217f2d2b96a6e066ac6895d39d9a2af9481
+  metadata.gz: cb166817303dfd933dd1fd6a4444aecd966ce06b66347a4b058759c49dc0b0cd1397bbef60d05753c72ccf511a8f70ea5c49c8ffdfaa591eb2d2cf2255d8b1da
+  data.tar.gz: d0d0549e336a50af534813aa4ab74c068952bf3d43148cc7c2032c0f4447df0aae73c9d1d813f8aa99819310c13ae3e220d59376276195fed408506b34144399

data/CHANGELOG.md

@@ -6,6 +6,78 @@ 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.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,12 @@ 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`.
 
 ## Which API?
 
@@ -91,7 +97,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.0.gem pkg/asterism-0.7.0.gem
 ```
 
 From the working trees, without installing:
@@ -101,12 +107,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 +128,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 +261,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 |
@@ -417,17 +428,19 @@ 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.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` | | |
@@ -444,19 +457,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 +550,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 +567,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
@@ -658,22 +678,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 +797,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/objects.rb

@@ -153,12 +153,16 @@ module Asterism
     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

data/lib/asterism/cruby.rb

@@ -9,12 +9,53 @@ module Asterism
   ROS::TYPE_PATH.replace([MSGS_DIR])
 
   module Codec
-    # CRuby's msgpack packs binary (ASCII-8BIT) Strings, such as payloads
-    # that came from Zenoh, as the bin type. The mruby MessagePack of the
-    # boards reads only the str type, so every String goes as str
-    # (compatibility mode), which is what the boards send too.
+    INT_MIN = -(2**63)
+    INT_MAX = 2**63 - 1
+
+    # msgpack-ruby packs a binary (ASCII-8BIT) String, such as a payload
+    # that came from Zenoh or File.binread, as a bin and any other String
+    # as a str (docs/protocol.md 3.1): no compatibility mode.
     def self.pack(v)
-      ::MessagePack.pack(check(v), compatibility_mode: true)
+      ::MessagePack.pack(check(v))
+    end
+
+    class << self
+      alias_method :check_portable, :check
+
+      # An Integer outside the signed 64-bit range cannot be sent (the
+      # other implementations cannot hold it): EncodeError, before sending.
+      def check(v, depth = 0)
+        if v.is_a?(Integer) && (v < INT_MIN || v > INT_MAX)
+          raise ::Asterism::EncodeError, "Integer #{v} is outside the signed 64-bit range"
+        end
+        return v if v.is_a?(Integer)
+        check_portable(v, depth)
+      end
+
+      alias_method :unpack_portable, :unpack
+
+      # Also nil for an integer above 2^63-1 (msgpack-ruby reads a uint64;
+      # the protocol carries signed 64-bit integers only).
+      def unpack(bytes)
+        v = unpack_portable(bytes)
+        return v unless bytes&.b&.include?("\xcf".b)
+        int64_only?(v) ? v : nil
+      end
+
+      def int64_only?(v)
+        case v
+        when Integer then v <= INT_MAX
+        when Array then v.all? { int64_only?(_1) }
+        when Hash then v.all? { |k, x| int64_only?(k) && int64_only?(x) }
+        else true
+        end
+      end
+
+      # A text field of the protocol is a str, whatever the String's
+      # encoding was.
+      def text(s)
+        s.to_s.dup.force_encoding(Encoding::UTF_8)
+      end
     end
   end
 
@@ -62,7 +103,10 @@ module Asterism
     end
   end
 
-  def self.error_reply(klass, message)
-    ::MessagePack.pack(["error", klass.to_s, message.to_s], compatibility_mode: true)
+  # The calls being answered, per thread: an exposed method runs on the
+  # thread that answers (the receiving thread, or whatever polls), and
+  # Asterism.current_call on another thread is not inside that call.
+  def self.call_stack
+    Thread.current[:asterism_call_stack] ||= []
   end
 end

data/lib/asterism/version.rb

@@ -1,6 +1,7 @@
 module Asterism
   # The gem's version (the CRuby gem asterism). The Zenoh binding it needs
-  # is in asterism.gemspec (asterism-zenoh ~> 0.4.0 for 0.5.0 and 0.6.0:
-  # the bindings did not change; see CHANGELOG.md).
-  VERSION = "0.6.0"
+  # is in asterism.gemspec (asterism-zenoh ~> 0.4.0 for 0.5.0 to 0.7.0:
+  # the bindings did not change; see CHANGELOG.md). 0.7.0 speaks wire
+  # protocol 1 only (Asterism::PROTOCOL, docs/protocol.md).
+  VERSION = "0.7.0"
 end

data/mrblib/asterism.rb

@@ -7,20 +7,25 @@
 #                                      # Asterism["...", timeout: 5.0])
 #   Asterism.poll                      # call regularly (answers incoming calls)
 #
-# Keys (doc/ruby_asterism/design.md ch. 4):
-#   asterism/<node>/<app>/<object>/call   get: payload [method, args, kwargs]
-#                                         reply ["ok", value] or
-#                                         ["error", class name, message]
-#   asterism/<node>/<app>/<object>/meta   get: reply {"methods" => [[name, arity], ...]}
-#   asterism/<node>                       liveliness: the node is up
-#   asterism/<node>/<app>/<object>        liveliness: the object is exposed
-#   asterism/<node>/@profile              get: reply the node's profile (profile.rb)
+# Keys and payloads: protocol 1 (docs/protocol.md):
+#   asterism/<node>/<app>/<object>/call/<caller>
+#                     get: {"method" => name, "args" => [...], "kwargs" => {...}}
+#                     reply {"value" => v} or
+#                     {"error" => {"kind" => k, "class" => c, "message" => m}}
+#   asterism/<node>/<app>/<object>/meta
+#                     get: reply {"methods" => [{"name" => n, "arity" => a}, ...]}
+#   asterism/<node>/<app>             liveliness: the application is up
+#   asterism/<node>/<app>/<object>    liveliness: the object is exposed
+#   asterism/<node>/@profile          get: reply the node's profile (profile.rb)
 #
 # Everything is polled: nothing runs behind the application's back. A call
 # that waits for its answer keeps polling meanwhile and answers the calls
 # that come in, so two machines calling each other do not lock up.
 module Asterism
   ROOT = "asterism"
+  # The version of the wire protocol this implementation speaks (and the
+  # only one: protocol 0, the 0.x releases before 0.7.0, is not spoken).
+  PROTOCOL = 1
   # The time limit of a call (Asterism[path] without timeout:), in seconds
   # and in milliseconds.
   DEFAULT_TIMEOUT = 2.0
@@ -51,17 +56,49 @@ module Asterism
   class Disconnected < Error; end
 
   # The remote method raised, or could not be called (not exposed, wrong
-  # number of arguments). remote_class is the class name on the other side.
+  # number of arguments). remote_class is the class name on the other side,
+  # remote_kind what happened, as a protocol word (a String): "raised" (the
+  # method raised; remote_class is then the callee language's own name),
+  # "not_exposed", "no_object", "arguments", "malformed", "unsendable",
+  # "nesting", "protocol" (docs/protocol.md 4.4); nil when the answer did
+  # not say.
   class RemoteError < Error
-    attr_reader :remote_class, :remote_message
+    attr_reader :remote_class, :remote_message, :remote_kind
 
-    def initialize(remote_class, remote_message)
+    def initialize(remote_class, remote_message, remote_kind = nil)
       @remote_class = remote_class.to_s
       @remote_message = remote_message.to_s
+      @remote_kind = remote_kind.nil? ? nil : remote_kind.to_s
       super("#{@remote_class}: #{@remote_message}")
     end
   end
 
+  # What Asterism.current_call returns while an exposed method runs for a
+  # call: who called and what. from is the calling node's ID (a String),
+  # verified how far that is checked: :claimed (the caller named itself in
+  # the call's key; a router's access control is what makes the name
+  # binding, docs/protocol.md 4.7) or :local (a call from this same
+  # application, which does not go on the network). object is the exposed
+  # object's name, method the method's name (Strings).
+  class CurrentCall
+    attr_reader :from, :verified, :object, :method
+
+    def initialize(from, verified, object, method)
+      @from = from
+      @verified = verified
+      @object = object
+      @method = method
+    end
+
+    def inspect
+      "#<Asterism::CurrentCall #{@object}.#{@method} from #{@from} (#{@verified})>"
+    end
+
+    def to_s
+      inspect
+    end
+  end
+
   # The old names of renamed constants: Asterism::Timeout (deprecated) is
   # TimeoutError. A constant alias would shadow Ruby's Timeout module inside
   # `module Asterism`, and cannot warn.
@@ -79,6 +116,9 @@ module Asterism
     MAX_DEPTH = 16
 
     # The value as it will be sent (Symbols become Strings), or EncodeError.
+    # A String goes as a MessagePack str, a binary String (String#b) as a
+    # bin: the MessagePack module decides by the String's encoding
+    # (ASCII-8BIT on CRuby, the binary flag on mruby).
     def self.check(v, depth = 0)
       raise ::Asterism::EncodeError, "value nested too deep (max #{MAX_DEPTH})" if depth > MAX_DEPTH
       if v.nil? || v == true || v == false || v.is_a?(Integer) || v.is_a?(Float) || v.is_a?(String)
@@ -101,7 +141,15 @@ module Asterism
       ::MessagePack.pack(check(v))
     end
 
-    # nil when the bytes are not MessagePack.
+    # A String for a text field of the protocol (an error's class and
+    # message): always a str, also when it came as a binary String.
+    def self.text(s)
+      "#{s}"
+    end
+
+    # nil when the bytes are not exactly one MessagePack value of the types
+    # above (the MessagePack module refuses trailing bytes, ext types and
+    # integers outside int64).
     def self.unpack(bytes)
       return nil if bytes.nil? || bytes.empty?
       ::MessagePack.unpack(bytes)
@@ -219,7 +267,7 @@ module Asterism
         s.close
         raise Error, "#{node}/#{app} is already on the network"
       end
-      @node_token = s.liveliness("#{ROOT}/#{node}")
+      @app_token = s.liveliness("#{ROOT}/#{node}/#{app}")
       @queryable = s.queryable("#{ROOT}/#{node}/#{app}/**", depth: 32)
       @watch = s.liveliness_watch("#{ROOT}/**", depth: watch_depth)
       @profile_queryable = s.queryable("#{ROOT}/#{node}/#{Profile::KEY}", depth: 4)
@@ -231,9 +279,9 @@ module Asterism
     @session = s
     @node = node
     @app = app
-    @objects = {}  # name => [object, {method name => arity}, token]
+    @objects = {}  # name => [object, {method name => arity}, token, caller keyword or nil]
     @alive = {}    # "node/app/object" => node (from liveliness)
-    @nodes = {}    # node => true (from liveliness)
+    @apps = {}     # "node/app" => node (from liveliness)
     @proxies = {}
     @depth = 0
     @lost = nil
@@ -245,8 +293,8 @@ module Asterism
     self
   end
 
-  # Whether objects of node/app are alive already (a second copy of the
-  # same application). Waits for the answer (a router answers at once), at
+  # Whether node/app is alive already (its application token or an object:
+  # a second copy of the same application). Waits for the answer (a router answers at once), at
   # most check_ms. @api private
   def self.already_there?(s, node, app, check_ms = 1500)
     get_ms = check_ms > 1000 ? check_ms - 500 : check_ms
@@ -301,7 +349,7 @@ module Asterism
     @session = nil
     @objects = {}
     @alive = {}
-    @nodes = {}
+    @apps = {}
     @node_list = nil
     @nodes_changed = true
     @proxies = {}
@@ -313,7 +361,7 @@ module Asterism
         @releasing = nil
       end
     end
-    @node_token = nil
+    @app_token = nil
     @queryable = nil
     @watch = nil
     @profile_queryable = nil
@@ -376,7 +424,11 @@ module Asterism
   # Makes obj callable from other machines as <node>/<app>/<name>. Only the
   # listed methods can be called. methods: is an Array of names, or a Hash
   # name => number of arguments (checked before calling; -1 for any).
-  def self.expose(name, obj, methods:)
+  # caller: a keyword name (caller: :from): each call passes the calling
+  # node's ID (Asterism.current_call.from) to the method as that keyword,
+  # and a call that brings the keyword itself is refused (an "arguments"
+  # error), so the value is always the one Asterism took from the call.
+  def self.expose(name, obj, methods:, caller: nil)
     s = session!
     name = check_name("object", name)
     table = {}
@@ -389,9 +441,17 @@ module Asterism
     table.each_key do |m|
       raise ArgumentError, "#{obj.class} has no public method #{m}" unless obj.respond_to?(m)
     end
+    kw = nil
+    unless caller.nil?
+      unless caller.is_a?(Symbol) || caller.is_a?(String)
+        raise ArgumentError, "caller: expects a keyword name (caller: :from), got #{caller.inspect}"
+      end
+      kw = caller.to_s
+      raise ArgumentError, "caller: expects a keyword name (caller: :from), got #{caller.inspect}" if kw.empty?
+    end
     unexpose(name)
     token = s.liveliness("#{ROOT}/#{@node}/#{@app}/#{name}")
-    @objects[name] = [obj, table, token]
+    @objects[name] = [obj, table, token, kw]
     "#{@node}/#{@app}/#{name}"
   rescue Asterism::Zenoh::Error => e
     raise Disconnected, e.message
@@ -424,7 +484,7 @@ module Asterism
 
   # ------------------------------------------------------------ nodes coming and going
 
-  # on_join { |node| }: another node appeared (its node token or one of its
+  # on_join { |node| }: another node appeared (one of its applications or
   # objects). The nodes there already join on the first polls after
   # connecting. on_leave { |node| }: a node is gone (no token and no object
   # left); when the connection is lost, every node known until then leaves.
@@ -546,7 +606,11 @@ module Asterism
   # Polls until the block is true. Answers incoming calls meanwhile.
   # @api private
   def self.wait_until
-    raise Error, "calls nested too deep (max #{MAX_NESTING})" if (@depth || 0) >= MAX_NESTING
+    if (@depth || 0) >= MAX_NESTING
+      # Kept, so that a method that lets it out is answered as "nesting".
+      @nesting_error = Error.new("calls nested too deep (max #{MAX_NESTING})")
+      raise @nesting_error
+    end
     @depth = (@depth || 0) + 1
     begin
       until yield
@@ -592,13 +656,13 @@ module Asterism
       i += 1
       rest = key[ROOT.length + 1, key.length].to_s
       parts = rest.split("/")
-      if parts.size == 1
+      if parts.size == 2 # an application: asterism/<node>/<app>
         if alive
-          @nodes[rest] = true
+          @apps[rest] = parts[0]
         else
-          @nodes.delete(rest)
+          @apps.delete(rest)
         end
-      elsif parts.size == 3
+      elsif parts.size == 3 # an object: asterism/<node>/<app>/<object>
         if alive
           @alive[rest] = parts[0]
         else
@@ -622,7 +686,7 @@ module Asterism
     return list if list
     list = [@node]
     seen = { @node => true }
-    names = @nodes.keys
+    names = @apps.values
     i = 0
     while i < names.size
       n = names[i]
@@ -689,14 +753,16 @@ module Asterism
   # @api private
   def self.call_async(path, method, args, kwargs, timeout_ms)
     parts = split_path(path)
-    payload = Codec.pack([method.to_s, args, kwargs])
+    payload = Codec.pack(request(method, args, kwargs))
     if parts[0] == @node && parts[1] == @app && @session
       # This application's own object: no network (a session does not see
       # its own queryable), same encoding and checks as a remote call.
-      return Future.answered(path, method, dispatch(parts[2], payload))
+      return Future.answered(path, method, dispatch(parts[2], payload, @node, :local))
     end
     begin
-      g = session!.get("#{ROOT}/#{path}/call", timeout_ms: timeout_ms, payload: payload)
+      s = session!
+      # The caller's node ID is the key's last chunk (docs/protocol.md 4.1).
+      g = s.get("#{ROOT}/#{path}/call/#{@node}", timeout_ms: timeout_ms, payload: payload)
     rescue Asterism::Zenoh::Error => e
       lost(e.message)
       raise Disconnected, e.message
@@ -704,18 +770,28 @@ module Asterism
     Future.new(path, method, g, now_ms + timeout_ms, timeout_ms)
   end
 
+  # The request of a call: a map with the method's name, and the arguments
+  # and keyword arguments when there are any (absent means none).
+  # @api private
+  def self.request(method, args, kwargs)
+    req = { "method" => method.to_s }
+    req["args"] = args unless args.nil? || args.empty?
+    req["kwargs"] = kwargs unless kwargs.nil? || kwargs.empty?
+    req
+  end
+
   # @api private
   def self.call(path, method, args, kwargs, timeout_ms)
     call_async(path, method, args, kwargs, timeout_ms).value
   end
 
-  # The meta reply of path: {"methods" => [[name, arity], ...]}.
+  # The meta reply of path: {"methods" => [{"name" => n, "arity" => a}, ...]}.
   # @api private
   def self.meta(path, timeout_ms = DEFAULT_TIMEOUT_MS)
     parts = split_path(path)
     if parts[0] == @node && parts[1] == @app && @session
       m = meta_of(parts[2])
-      raise RemoteError.new("NameError", "no object #{parts[2]} exposed by #{@node}/#{@app}") unless m
+      raise RemoteError.new("NameError", "no object #{parts[2]} exposed by #{@node}/#{@app}", "no_object") unless m
       return m
     end
     begin
@@ -730,6 +806,21 @@ module Asterism
 
   # ------------------------------------------------------------ answering
 
+  # The call being answered now (an Asterism::CurrentCall: who called,
+  # which object and method), while an exposed method runs for a call; nil
+  # outside one. Calls answered while that method waits for its own call
+  # are on top of it until they end.
+  def self.current_call
+    stack = call_stack
+    stack.empty? ? nil : stack[stack.size - 1]
+  end
+
+  # The calls being answered, innermost last (CRuby: per thread).
+  # @api private
+  def self.call_stack
+    @call_stack ||= []
+  end
+
   # @api private
   def self.answer_calls
     qa = @queryable
@@ -753,62 +844,121 @@ module Asterism
     end
   end
 
-  # asterism/<node>/<app>/<object>/<call|meta>; the node and app may come
-  # as wildcards (the query matched this application's queryable).
+  # asterism/<node>/<app>/<object>/call/<caller> and
+  # asterism/<node>/<app>/<object>/meta; the node and app may come as
+  # wildcards (the query matched this application's queryable).
   # @api private
   def self.answer(q)
     parts = q.key.split("/")
-    return unless parts.size == 5
+    n = parts.size
+    return unless n == 5 || n == 6
     obj = parts[3]
     kind = parts[4]
     prefix = "#{ROOT}/#{@node}/#{@app}/"
     if kind == "meta"
+      return unless n == 5
       names = obj == "*" ? @objects.keys : [obj]
-      names.each do |n|
-        m = meta_of(n)
-        q.reply("#{prefix}#{n}/meta", Codec.pack(m)) if m
+      names.each do |nm|
+        m = meta_of(nm)
+        q.reply("#{prefix}#{nm}/meta", Codec.pack(m)) if m
+      end
+    elsif kind == "call" && valid_name?(obj)
+      if n == 5
+        # A protocol 0 call (no caller chunk): refused, so that its sender
+        # learns why at once instead of waiting.
+        q.reply("#{prefix}#{obj}/call",
+                error_reply("protocol", "Asterism::Error",
+                            "#{@node}/#{@app} speaks Asterism protocol #{PROTOCOL}: call " \
+                            "asterism/<node>/<app>/<object>/call/<caller> with a map " \
+                            "{\"method\", \"args\", \"kwargs\"} (asterism 0.7.0 and later)"))
+      elsif valid_name?(parts[5])
+        q.reply("#{prefix}#{obj}/call/#{parts[5]}", dispatch(obj, q.payload, parts[5], :claimed))
       end
-    elsif kind == "call" && obj != "*"
-      q.reply("#{prefix}#{obj}/call", dispatch(obj, q.payload))
     end
   end
 
+  # Whether s can be a node, app or object name (check_name without raising).
+  # @api private
+  def self.valid_name?(s)
+    return false if s.nil? || s.empty? || s.start_with?("@")
+    !(s.include?("/") || s.include?("*") || s.include?("$") || s.include?("?") || s.include?("#"))
+  end
+
   # @api private
   def self.meta_of(name)
     entry = @objects[name]
     return nil unless entry
     list = []
-    entry[1].each { |m, n| list << [m, n] }
+    entry[1].each { |m, n| list << { "name" => m, "arity" => n } }
     { "methods" => list }
   end
 
-  # Runs a call on an exposed object; returns the packed reply.
+  MALFORMED = "malformed call (expected a map {\"method\" => name, \"args\" => [...], \"kwargs\" => {...}})"
+
+  # Runs a call on an exposed object; returns the packed reply. from is
+  # the caller's node ID, verified how it is known (CurrentCall).
   # @api private
-  def self.dispatch(obj_name, payload)
-    req = Codec.unpack(payload)
-    unless req.is_a?(Array) && req.size == 3 && req[0].is_a?(String) && req[1].is_a?(Array) && req[2].is_a?(Hash)
-      return error_reply("ArgumentError", "malformed call (expected [method, args, kwargs])")
-    end
+  def self.dispatch(obj_name, payload, from, verified)
+    req = parse_request(Codec.unpack(payload))
+    return error_reply("malformed", "ArgumentError", MALFORMED) unless req
     entry = @objects[obj_name]
-    return error_reply("NameError", "no object #{obj_name} exposed by #{@node}/#{@app}") unless entry
+    return error_reply("no_object", "NameError", "no object #{obj_name} exposed by #{@node}/#{@app}") unless entry
     name = req[0]
     args = req[1]
     kw = req[2]
     arity = entry[1][name]
     if arity.nil?
-      return error_reply("NoMethodError", "undefined method '#{name}' for #{@node}/#{@app}/#{obj_name} (not exposed)")
+      return error_reply("not_exposed", "NoMethodError",
+                         "undefined method '#{name}' for #{@node}/#{@app}/#{obj_name} (not exposed)")
     end
     if arity >= 0 && args.size != arity
-      return error_reply("ArgumentError", "wrong number of arguments (given #{args.size}, expected #{arity})")
+      return error_reply("arguments", "ArgumentError", "wrong number of arguments (given #{args.size}, expected #{arity})")
+    end
+    ckw = entry[3]
+    if ckw
+      if kw.key?(ckw)
+        return error_reply("arguments", "ArgumentError",
+                           "#{ckw}: is given by Asterism, not by the caller " \
+                           "(#{@node}/#{@app}/#{obj_name} is exposed with caller: :#{ckw})")
+      end
+      kw[ckw] = from
     end
+    stack = call_stack
+    stack << CurrentCall.new(from, verified, obj_name, name)
     begin
       value = invoke(entry[0], name, args, kw)
-      Codec.pack(["ok", value])
-    rescue EncodeError => e
-      error_reply("Asterism::EncodeError", "the return value: #{e.message}")
     rescue => e
-      error_reply(e.class.to_s, e.message)
+      return error_reply(e.equal?(@nesting_error) ? "nesting" : "raised", e.class.to_s, e.message)
+    ensure
+      stack.pop
+    end
+    begin
+      Codec.pack({ "value" => value })
+    rescue EncodeError => e
+      error_reply("unsendable", "Asterism::EncodeError", "the return value: #{e.message}")
+    end
+  end
+
+  # [method, args, kwargs] of a decoded request, or nil when it is not one:
+  # a map with "method" (a non-empty str), "args" (an array, absent: none)
+  # and "kwargs" (a map with str keys, absent: none). Other keys are
+  # ignored (room for later additions).
+  # @api private
+  def self.parse_request(req)
+    return nil unless req.is_a?(Hash)
+    m = req["method"]
+    return nil unless m.is_a?(String) && !m.empty?
+    args = req.key?("args") ? req["args"] : []
+    return nil unless args.is_a?(Array)
+    kw = req.key?("kwargs") ? req["kwargs"] : {}
+    return nil unless kw.is_a?(Hash)
+    keys = kw.keys
+    i = 0
+    while i < keys.size
+      return nil unless keys[i].is_a?(String)
+      i += 1
     end
+    [m, args, kw]
   end
 
   # @api private
@@ -817,13 +967,14 @@ module Asterism
       obj.public_send(name, *args)
     else
       opts = {}
-      kw.each { |k, v| opts[k.to_s.to_sym] = v }
+      kw.each { |k, v| opts[k.to_sym] = v }
       obj.public_send(name, *args, **opts)
     end
   end
 
+  # {"error" => {"kind", "class", "message"}}, packed.
   # @api private
-  def self.error_reply(klass, message)
-    ::MessagePack.pack(["error", klass.to_s, message.to_s])
+  def self.error_reply(kind, klass, message)
+    ::MessagePack.pack({ "error" => { "kind" => kind, "class" => Codec.text(klass), "message" => Codec.text(message) } })
   end
 end

data/mrblib/future.rb

@@ -48,16 +48,22 @@ module Asterism
       @finished
     end
 
+    # The answer: {"value" => v} gives v, {"error" => {"kind", "class",
+    # "message"}} raises RemoteError; anything else is a malformed answer.
     def value
       raw = raw_value
-      unless raw.is_a?(Array) && (raw[0] == "ok" || raw[0] == "error")
-        raise ::Asterism::Error, "malformed answer from #{@path}"
+      raise ::Asterism::Error, "malformed answer from #{@path}" unless raw.is_a?(Hash)
+      if raw.key?("error")
+        e = raw["error"]
+        raise ::Asterism::Error, "malformed answer from #{@path}" unless e.is_a?(Hash)
+        kind = e["kind"]
+        raise ::Asterism::RemoteError.new(e["class"], e["message"], kind.is_a?(String) ? kind : nil)
       end
-      raise ::Asterism::RemoteError.new(raw[1], raw[2]) if raw[0] == "error"
-      raw[1]
+      raise ::Asterism::Error, "malformed answer from #{@path}" unless raw.key?("value")
+      raw["value"]
     end
 
-    # The decoded answer (meta replies are not ["ok", value] pairs).
+    # The decoded answer (meta and profile replies are not value maps).
     def raw_value
       ::Asterism.wait_until { done? } unless done?
       if @reply.nil?

data/mrblib/profile.rb

@@ -7,11 +7,14 @@
 #
 # Key: asterism/<node>/@profile (a queryable of every application connected
 # as that node). The reply is a MessagePack Hash:
+#   "protocol"   the wire protocol the node speaks (Asterism::PROTOCOL, 1);
+#                a node without it speaks protocol 0
 #   "kind"       what Ruby runs the node: "family_mruby", "picoruby",
 #                "cruby", "console" (others are allowed)
 #   "host"       where it runs, optional ("atoms3r", "tab5", "sim", ...)
 #   "name"       a display name, optional
-#   "icon"       PNG bytes, optional (8 KB and 256x256 at most)
+#   "icon"       PNG bytes as a MessagePack bin, optional (8 KB and
+#                256x256 at most)
 #   "icon_hash"  the icon's summary (Profile.png_info): a reader that has
 #                that icon already asks again with the parameter icon=0 and
 #                gets the rest without it
@@ -87,6 +90,13 @@ module Asterism
       nil
     end
 
+    # The bytes as a binary String (String#b), so that they are sent as a
+    # MessagePack bin; as they are where String#b is missing.
+    # @api private
+    def self.binary(s)
+      s.respond_to?(:b) ? s.b : s
+    end
+
     # @api private
     def self.type?(b, pos, c0, c1, c2, c3)
       b.getbyte(pos + 4) == c0 && b.getbyte(pos + 5) == c1 && b.getbyte(pos + 6) == c2 && b.getbyte(pos + 7) == c3
@@ -107,6 +117,8 @@ module Asterism
       kind = h["kind"]
       return nil unless kind.is_a?(String) && kind?(kind)
       out = { "kind" => kind }
+      pr = h["protocol"]
+      out["protocol"] = pr if pr.is_a?(Integer) && pr >= 0
       host = h["host"]
       out["host"] = host if host.is_a?(String) && !host.empty? && host.bytesize <= HOST_MAX
       name = h["name"]
@@ -301,7 +313,7 @@ module Asterism
   # @api private
   def self.profile_hash(with_icon)
     set = @profile_set || {}
-    h = { "kind" => set["kind"] || default_profile_kind }
+    h = { "protocol" => PROTOCOL, "kind" => set["kind"] || default_profile_kind }
     h["host"] = set["host"] if set["host"]
     h["name"] = set["name"] if set["name"]
     icon = profile_icon
@@ -324,7 +336,8 @@ module Asterism
         bytes = path ? read_icon_file(path) : nil
       end
       info = bytes ? Profile.png_info(bytes) : nil
-      @profile_icon = info ? [bytes, info[2]] : false
+      # A binary String: it goes as a MessagePack bin.
+      @profile_icon = info ? [Profile.binary(bytes), info[2]] : false
     end
     @profile_icon ? @profile_icon : nil
   end

data/mrblib/proxy.rb

@@ -3,9 +3,9 @@ module Asterism
   # Any method it does not have itself becomes a call that waits for the
   # answer. respond_to? and remote_methods come from the object's meta.
   #
-  # Its own methods (not forwarded): async, asterism_path, asterism_meta,
-  # asterism_refresh, remote_methods, respond_to?, methods, inspect, to_s
-  # and those of Object.
+  # Its own methods (not forwarded): async, asterism_call, asterism_path,
+  # asterism_meta, asterism_refresh, remote_methods, respond_to?, methods,
+  # inspect, to_s and those of Object.
   class Proxy
     # Conversions Ruby asks for implicitly (puts, Array#flatten, ...): never
     # forwarded.
@@ -27,6 +27,15 @@ module Asterism
       ::Asterism.call(@path, name, args, kw, @timeout_ms)
     end
 
+    # Calls the remote method by its name (a String or Symbol): for the
+    # names the proxy cannot forward (those Object and Kernel define:
+    # display, hash, class, fail, ...) and for names that are not Ruby
+    # identifiers (from objects written in other languages).
+    def asterism_call(name, *args, **kw, &blk)
+      raise ::ArgumentError, "a block cannot be sent to #{@path}" if blk
+      ::Asterism.call(@path, name.to_s, args, kw, @timeout_ms)
+    end
+
     # In Ruby rather than through respond_to_missing?: Object#respond_to? is
     # C, and calling back into Ruby from it (which then waits for the meta)
     # costs another interpreter entry on the C stack.
@@ -52,7 +61,8 @@ module Asterism
       remote_methods
     end
 
-    # The meta reply, fetched once: {"methods" => [[name, arity], ...]}.
+    # The meta reply, fetched once:
+    # {"methods" => [{"name" => name, "arity" => n}, ...]}.
     def asterism_meta
       @meta ||= ::Asterism.meta(@path, @timeout_ms)
     end
@@ -67,7 +77,9 @@ module Asterism
     def remote_names
       list = asterism_meta["methods"]
       return [] unless list.is_a?(Array)
-      list.map { |pair| pair.is_a?(Array) ? pair[0].to_s : pair.to_s }
+      names = []
+      list.each { |m| names << m["name"].to_s if m.is_a?(Hash) && m["name"].is_a?(String) }
+      names
     end
 
     # The same object, calls that do not wait: each returns a Future.
@@ -100,6 +112,12 @@ module Asterism
       !::Asterism::Proxy::LOCAL_ONLY.include?(name.to_sym)
     end
 
+    # Proxy#asterism_call that does not wait: returns a Future.
+    def asterism_call(name, *args, **kw, &blk)
+      raise ::ArgumentError, "a block cannot be sent to #{@path}" if blk
+      ::Asterism.call_async(@path, name.to_s, args, kw, @timeout_ms)
+    end
+
     def inspect
       "#<Asterism::AsyncProxy #{@path}>"
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: asterism
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Katsuhiko Kageyama