asterism 0.7.1 → 0.9.0

data/lib/asterism/cruby/credentials.rb

@@ -1,4 +1,5 @@
-# The credentials of one node or router as one file (CRuby only): the .tar
+# The credentials of one node or router as one file, CRuby's part (the
+# class itself is mrblib/credentials.rb, shared with the boards): 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:
@@ -23,130 +24,74 @@ require "json"
 require "stringio"
 
 module Asterism
+  # The portable class is mrblib/credentials.rb (the boards read the .tar
+  # with it); CRuby reads the file with the standard library and checks
+  # more: who may read the file, and the key pair (prepended, so the
+  # portable methods are not redefined).
   class Credentials
-    # What a credentials file is missing or holds wrong.
-    class Error < ::Asterism::Error; end
+    module CRuby
+      private
 
-    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"
+      def b64(pem)
+        [pem].pack("m0")
       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
+      # 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
+      # {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
-      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
+      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}"
+      # 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
+    prepend CRuby
   end
 end

data/lib/asterism/cruby/objects.rb

@@ -27,7 +27,7 @@ module Asterism
   # singleton class, so the shared methods themselves are not changed.
   module Locked
     %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|
+       on_app_join on_app_leave off_app_join off_app_leave profile profile_async status status_async apps session].each do |m|
       define_method(m) do |*args, **kw, &blk|
         ::Asterism::LOCK.synchronize { super(*args, **kw, &blk) }
       end
@@ -73,9 +73,10 @@ module Asterism
       ::Asterism::LOCK.synchronize { super }
     end
 
-    # The on_join / on_leave blocks (called from Asterism.poll): with a Net,
-    # what they raise goes to its on_error and the other blocks still run.
-    def tell(where, blk, node)
+    # The on_join / on_leave (and on_app_*) blocks (called from
+    # Asterism.poll): with a Net, what they raise goes to its on_error and
+    # the other blocks still run.
+    def tell(where, blk, node, app = nil)
       net = @net
       return super unless net
       net.runner.guard(where) { super }
@@ -162,11 +163,12 @@ module Asterism
     def exposed = ::Asterism.exposed
 
     # Asterism.expose: methods: an Array of names or a Hash name => number
-    # of arguments; caller: :from passes the calling node's ID as that
+    # of arguments (or => {args: [names], doc: "text"}); doc: the object's
+    # own text (both go to the meta); 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:, caller: nil)
-      ::Asterism.expose(name, obj, methods: methods, caller: caller)
+    def expose(name, obj, methods:, caller: nil, doc: nil)
+      ::Asterism.expose(name, obj, methods: methods, caller: caller, doc: doc)
     end
 
     # Asterism.current_call: the call being answered on this thread, or nil.
@@ -187,6 +189,34 @@ module Asterism
       ::Asterism.profile_of(node, icon: icon, timeout: timeout, timeout_ms: timeout_ms)
     end
 
+    # Asterism.status: this application's status (a Hash: the whole
+    # status; keywords: those fields). Without arguments, returns it.
+    def status(h = nil, **fields)
+      ::Asterism.status(h, **fields)
+    end
+
+    # Asterism.status_of: another application's status, or nil. Waits like
+    # a call (for the receiving thread's ticks while it runs).
+    def status_of(node, app, timeout: nil, timeout_ms: nil)
+      ::Asterism.status_of(node, app, timeout: timeout, timeout_ms: timeout_ms)
+    end
+
+    # on_status(pattern = "*/*") { |node, app, status| }: the statuses put
+    # by the applications whose "<node>/<app>" matches the pattern (Zenoh
+    # wildcards: * one chunk, ** several), as they change, on the receiving
+    # thread. Only changes come: ask status_of for the one there now.
+    # Returns the subscription (close it to stop).
+    def on_status(pattern = "*/*", &blk)
+      raise ArgumentError, "on_status needs a block" unless blk
+      session.subscribe("#{::Asterism::ROOT}/#{pattern}/#{::Asterism::Status::KEY}") do |sample|
+        got = ::Asterism::Status.parse(sample.key, sample.payload)
+        blk.call(*got) if got
+      end
+    end
+
+    # Asterism.apps: the applications alive now, "<node>/<app>".
+    def apps(pattern = "*/*") = ::Asterism.apps(pattern)
+
     # A proxy for <node>/<app>/<object>; timeout: in seconds (or
     # timeout_ms:).
     def [](path, timeout: nil, timeout_ms: nil)
@@ -217,6 +247,29 @@ module Asterism
       self
     end
 
+    # on_app_join { |node, app| } / on_app_leave { |node, app| }: an
+    # application appeared on the network / is gone (Asterism.on_app_join),
+    # on the receiving thread. What they raise goes to on_error.
+    def on_app_join(&blk)
+      ::Asterism.on_app_join(&blk)
+      self
+    end
+
+    def on_app_leave(&blk)
+      ::Asterism.on_app_leave(&blk)
+      self
+    end
+
+    def off_app_join(blk)
+      ::Asterism.off_app_join(blk)
+      self
+    end
+
+    def off_app_leave(blk)
+      ::Asterism.off_app_leave(blk)
+      self
+    end
+
     # Removes a block given to on_join / on_leave (keep the Proc).
     def off_join(blk)
       ::Asterism.off_join(blk)

data/lib/asterism/version.rb

@@ -3,5 +3,5 @@ module Asterism
   # 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.1"
+  VERSION = "0.9.0"
 end

data/lib/asterism.rb

@@ -12,7 +12,7 @@ require "asterism/zenoh"
 require_relative "asterism/version"
 
 # The same order as an mrbgem's mrblib (alphabetical).
-%w[asterism cdr future profile proxy ros].each do |f|
+%w[asterism cdr credentials future profile proxy ros status].each do |f|
   require_relative "../mrblib/#{f}"
 end
 require_relative "asterism/cruby"

data/mrblib/asterism.rb

@@ -13,10 +13,12 @@
 #                     reply {"value" => v} or
 #                     {"error" => {"kind" => k, "class" => c, "message" => m}}
 #   asterism/<node>/<app>/<object>/meta
-#                     get: reply {"methods" => [{"name" => n, "arity" => a}, ...]}
+#                     get: reply {"methods" => [{"name" => n, "arity" => a,
+#                     "args" => [...], "doc" => "..."}, ...], "doc" => "..."}
 #   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)
+#   asterism/<node>/<app>/@status     get: reply the application's status (status.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
@@ -240,16 +242,23 @@ module Asterism
   # Opens the connection. locator, mode: and listen: go to
   # Asterism::Zenoh::Session.open (client of a router by default; mode: :peer
   # with or without listen: for no router), and so do config: (a Hash of
-  # "key/path" => value or a JSON5 String, e.g. TLS certificates) and
-  # connect_timeout: (seconds) when they are given (CRuby's asterism-zenoh
-  # only; the boards raise ArgumentError). node: is this machine's ID and
-  # app: this application's name. check_timeout: how long to look for
-  # another copy of the same <node>/<app> (seconds, CHECK_TIMEOUT). Raises
-  # Disconnected when it cannot connect, and Error when the same
-  # <node>/<app> is already on the network.
-  def self.connect(locator, node:, app:, mode: nil, listen: nil, config: nil, connect_timeout: nil,
-                   check_timeout: nil)
+  # "key/path" => value or a JSON5 String, e.g. TLS certificates; the boards
+  # take the TLS keys only) and connect_timeout: (seconds; CRuby's
+  # asterism-zenoh only, the boards raise ArgumentError) when they are given.
+  # credentials: a .tar from an Asterism console (Asterism::Credentials, a
+  # path or a loaded one): its certificates go to zenoh (mutual TLS), and
+  # locator and node: default to its router and name. node: is this
+  # machine's ID and app: this application's name. check_timeout: how long
+  # to look for another copy of the same <node>/<app> (seconds,
+  # CHECK_TIMEOUT). Raises Disconnected when it cannot connect, and Error
+  # when the same <node>/<app> is already on the network.
+  def self.connect(locator = nil, node: nil, app:, mode: nil, listen: nil, config: nil, connect_timeout: nil,
+                   check_timeout: nil, credentials: nil)
     raise Error, "already connected (Asterism.close first)" if connected?
+    if credentials
+      locator, config, creds = Credentials.merge(credentials, locator, config)
+      node ||= creds.name
+    end
     release
     node = check_name("node", node)
     app = check_name("app", app)
@@ -279,7 +288,8 @@ module Asterism
     @session = s
     @node = node
     @app = app
-    @objects = {}  # name => [object, {method name => arity}, token, caller keyword or nil]
+    @objects = {}  # name => [object, {method name => arity}, token, caller keyword or nil,
+                   #          {method name => meta fields}, the object's doc or nil]
     @alive = {}    # "node/app/object" => node (from liveliness)
     @apps = {}     # "node/app" => node (from liveliness)
     @proxies = {}
@@ -287,10 +297,13 @@ module Asterism
     @lost = nil
     @known = []    # the other nodes told to on_join so far
     @known_set = {} # the same, as node => true
+    @known_apps = {} # "node/app" => true: the other applications told to on_app_join
     @node_list = [node] # what nodes returns (this node first), rebuilt on a change
     @nodes_changed = false # liveliness changed since tell_nodes last compared
     @was_reconnecting = false
+    @status_put = nil
     tell_profile   # for those who follow the profiles (the reply is the queryable's)
+    tell_status(true) # a status set before connecting (status.rb)
     self
   end
 
@@ -353,8 +366,11 @@ module Asterism
   def self.close
     release
     @known = nil
+    @known_apps = nil
     @on_join = nil
     @on_leave = nil
+    @on_app_join = nil
+    @on_app_leave = nil
     nil
   end
 
@@ -380,6 +396,8 @@ module Asterism
     @queryable = nil
     @watch = nil
     @profile_queryable = nil
+    @status_queryable = nil
+    @status_put = nil
   end
 
   # The Zenoh session of the connection (an Asterism::Zenoh::Session), for
@@ -438,21 +456,39 @@ 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).
+  # name => number of arguments (checked before calling; -1 for any), or
+  # name => {args: [names], doc: "text"} (docs/protocol.md 5): the
+  # arguments' names (their number is the number checked, unless arity:
+  # says otherwise) and what the method does, both told in the meta for
+  # the readers that show them (asterism mcp, the command line). doc: a
+  # text about the object itself, also in the meta.
   # 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)
+  def self.expose(name, obj, methods:, caller: nil, doc: nil)
     s = session!
     name = check_name("object", name)
     table = {}
+    info = {}
     if methods.is_a?(Hash)
-      methods.each { |m, n| table[m.to_s] = n.to_i }
+      methods.each do |m, n|
+        if n.is_a?(Hash)
+          d = method_doc(m, n)
+          table[m.to_s] = d[0]
+          info[m.to_s] = d[1]
+        else
+          table[m.to_s] = n.to_i
+        end
+      end
     else
       methods.each { |m| table[m.to_s] = -1 }
     end
     raise ArgumentError, "no method to expose" if table.empty?
+    unless doc.nil?
+      raise ArgumentError, "doc: expects a String, got #{doc.class}" unless doc.is_a?(String)
+      raise ArgumentError, "doc: at most #{DOC_MAX} bytes" if doc.bytesize > DOC_MAX
+    end
     table.each_key do |m|
       raise ArgumentError, "#{obj.class} has no public method #{m}" unless obj.respond_to?(m)
     end
@@ -466,12 +502,60 @@ module Asterism
     end
     unexpose(name)
     token = s.liveliness("#{ROOT}/#{@node}/#{@app}/#{name}")
-    @objects[name] = [obj, table, token, kw]
+    @objects[name] = [obj, table, token, kw, info, doc]
     "#{@node}/#{@app}/#{name}"
   rescue Asterism::Zenoh::Error => e
     raise Disconnected, e.message
   end
 
+  # The longest doc text (bytes) and the most argument names a method may
+  # tell in its meta (docs/protocol.md 5).
+  DOC_MAX = 2048
+  ARGS_MAX = 16
+
+  # A method's {args:, doc:, arity:} at expose: [the number of arguments
+  # checked, its meta fields {"args", "doc"}].
+  # @api private
+  def self.method_doc(m, h)
+    args = nil
+    doc = nil
+    arity = nil
+    h.each do |k, v|
+      ks = k.to_s
+      if ks == "args" then args = v
+      elsif ks == "doc" then doc = v
+      elsif ks == "arity" then arity = v
+      else raise ArgumentError, "#{m}: unknown key #{ks} (args:, doc:, arity:)"
+      end
+    end
+    out = {}
+    unless args.nil?
+      raise ArgumentError, "#{m}: args: expects an Array of names" unless args.is_a?(Array)
+      raise ArgumentError, "#{m}: args: at most #{ARGS_MAX} names" if args.size > ARGS_MAX
+      names = []
+      args.each do |a|
+        raise ArgumentError, "#{m}: args: expects names, got #{a.inspect}" unless a.is_a?(String) || a.is_a?(Symbol)
+        a = a.to_s
+        raise ArgumentError, "#{m}: args: an empty name" if a.empty? || a.bytesize > 64
+        names << a
+      end
+      out["args"] = names
+    end
+    unless doc.nil?
+      raise ArgumentError, "#{m}: doc: expects a String" unless doc.is_a?(String)
+      raise ArgumentError, "#{m}: doc: at most #{DOC_MAX} bytes" if doc.bytesize > DOC_MAX
+      out["doc"] = doc
+    end
+    n = if !arity.nil? then arity.to_i
+        elsif !args.nil? then args.size
+        else -1
+        end
+    if n >= 0 && !args.nil? && args.size != n
+      raise ArgumentError, "#{m}: #{args.size} names in args: for #{n} arguments"
+    end
+    [n, out]
+  end
+
   def self.unexpose(name)
     entry = @objects ? @objects.delete(name.to_s) : nil
     entry[2].close if entry
@@ -532,6 +616,88 @@ module Asterism
     self
   end
 
+  # on_app_join { |node, app| }: an application of another node appeared
+  # (its token asterism/<node>/<app>); on_app_leave { |node, app| }: it is
+  # gone. A node may run several applications: each comes and goes on its
+  # own, and the node stays (on_join / on_leave) while one of them or an
+  # object is there. The applications there already join on the first
+  # polls after connecting; when the connection is lost, every application
+  # known until then leaves. Called from Asterism.poll, as on_join;
+  # Asterism.close forgets them.
+  def self.on_app_join(&blk)
+    raise ArgumentError, "on_app_join needs a block" unless blk
+    (@on_app_join ||= []) << blk
+    self
+  end
+
+  def self.on_app_leave(&blk)
+    raise ArgumentError, "on_app_leave needs a block" unless blk
+    (@on_app_leave ||= []) << blk
+    self
+  end
+
+  def self.off_app_join(blk)
+    @on_app_join.delete(blk) if @on_app_join
+    self
+  end
+
+  def self.off_app_leave(blk)
+    @on_app_leave.delete(blk) if @on_app_leave
+    self
+  end
+
+  # Compares the applications alive now with those told before and calls
+  # the on_app_* blocks for the difference (this application left out).
+  # @api private
+  def self.tell_apps
+    known = @known_apps
+    return if known.nil?
+    now = {}
+    if @session
+      own = "#{@node}/#{@app}"
+      keys = @apps.keys
+      i = 0
+      while i < keys.size
+        now[keys[i]] = true unless keys[i] == own
+        i += 1
+      end
+    end
+    joined = []
+    left = []
+    keys = now.keys
+    i = 0
+    while i < keys.size
+      joined << keys[i] unless known[keys[i]]
+      i += 1
+    end
+    keys = known.keys
+    i = 0
+    while i < keys.size
+      left << keys[i] unless now[keys[i]]
+      i += 1
+    end
+    @known_apps = @session ? now : nil
+    tell_apps_each("on_app_join", @on_app_join, joined)
+    tell_apps_each("on_app_leave", @on_app_leave, left)
+  end
+
+  # @api private
+  def self.tell_apps_each(where, blocks, names)
+    return if blocks.nil? || names.empty?
+    i = 0
+    while i < names.size
+      cut = names[i].index("/")
+      node = names[i][0, cut]
+      app = names[i][cut + 1, names[i].size]
+      j = 0
+      while j < blocks.size
+        tell(where, blocks[j], node, app)
+        j += 1
+      end
+      i += 1
+    end
+  end
+
   # Compares the nodes alive now with those told before and calls the
   # blocks for the difference.
   # @api private
@@ -542,6 +708,7 @@ module Asterism
     # the connection is neither new nor lost): nothing can have changed.
     return unless @nodes_changed
     @nodes_changed = false
+    tell_apps
     now = []
     now_set = {}
     if @session
@@ -595,10 +762,15 @@ module Asterism
     end
   end
 
-  # One block for one node (CRuby routes what it raises to on_error).
+  # One block for one node, or one application (CRuby routes what it
+  # raises to on_error).
   # @api private
-  def self.tell(_where, blk, node)
-    blk.call(node)
+  def self.tell(_where, blk, node, app = nil)
+    if app.nil?
+      blk.call(node)
+    else
+      blk.call(node, app)
+    end
   end
 
   # @api private
@@ -612,6 +784,7 @@ module Asterism
     back_again(s)
     answer_calls
     answer_profile
+    answer_status
     follow_liveliness
     !@session.nil?
   rescue Asterism::Zenoh::Error => e
@@ -619,14 +792,16 @@ module Asterism
     !@session.nil?
   end
 
-  # After the binding opened a lost connection again: tell the profile
-  # again (a put made while the router was away reached nobody).
+  # After the binding opened a lost connection again: tell the profile and
+  # the status again (a put made while the router was away reached nobody).
   # @api private
   def self.back_again(s)
     now = s.respond_to?(:reconnecting?) && s.reconnecting?
     was = @was_reconnecting
     @was_reconnecting = now
-    tell_profile if was && !now
+    return unless was && !now
+    tell_profile
+    tell_status(true)
   end
 
   # A Zenoh error during a call or a poll: the connection is gone only when
@@ -924,8 +1099,16 @@ module Asterism
     entry = @objects[name]
     return nil unless entry
     list = []
-    entry[1].each { |m, n| list << { "name" => m, "arity" => n } }
-    { "methods" => list }
+    info = entry[4] || {}
+    entry[1].each do |m, n|
+      e = { "name" => m, "arity" => n }
+      extra = info[m]
+      extra.each { |k, v| e[k] = v } if extra
+      list << e
+    end
+    out = { "methods" => list }
+    out["doc"] = entry[5] if entry[5]
+    out
   end
 
   MALFORMED = "malformed call (expected a map {\"method\" => name, \"args\" => [...], \"kwargs\" => {...}})"