asterism 0.7.0 → 0.8.0

data/lib/asterism/cli.rb

@@ -0,0 +1,424 @@
+# The command line of the gem (exe/asterism): look at an Asterism network
+# from CRuby, and call an object when asked to.
+#
+#   asterism nodes   --router tcp/192.0.2.2:7447
+#   asterism tree    --credentials admin.tar
+#   asterism objects 'games/games/*'
+#   asterism watch                         # joins, leaves, statuses as they come
+#   asterism ping    games/games/othello1  # the time of a round trip (meta)
+#   asterism call    games/games/othello1 view '"<token>"'
+#   asterism mcp     --allow 'games/othello1.*'   # an MCP server on stdio
+#
+# It is one more Asterism node: it connects with Asterism.connect (as the
+# certificate's name with --credentials, as cli-<6 hex digits> otherwise)
+# and reads what docs/protocol.md lets anyone read. It calls a method only
+# with `call` (and the MCP bridge only the methods --allow names). What it
+# can see is what the router lets it see: with a console's .tar, its role.
+require "asterism"
+require "optparse"
+require "json"
+require "securerandom"
+require_relative "cli/literal"
+require_relative "cli/survey"
+require_relative "cli/allow"
+
+module Asterism
+  class CLI
+    USAGE = <<~TEXT
+      Usage: asterism COMMAND [options]
+
+      Commands (they only read, except call):
+        nodes                the nodes, their applications and profiles
+        objects [PATTERN]    the objects and their methods (PATTERN: node/app/object, * and **)
+        tree                 nodes > applications (with their status) > objects (with their methods)
+        watch                nodes, applications and objects coming and going, and status changes
+        ping PATH            round trips: PATH node/app/object (its meta), or node (its profile);
+                             --call METHOD [ARG...] times a call instead (echo is the same command)
+        call PATH METHOD [ARG...]
+                             calls a method; each ARG is JSON, else a Ruby literal, else text
+        mcp                  an MCP server on stdio (needs the mcp gem): the listings as tools,
+                             and the methods --allow names
+        version              the gem's version
+
+      Where the network is (one of them):
+        --router LOCATOR     a router without TLS, e.g. tcp/192.0.2.2:7447
+        --credentials TAR    a console's .tar (mutual TLS; its router and name)
+    TEXT
+
+    def self.start(argv, out: $stdout, err: $stderr)
+      new(out: out, err: err).run(argv.dup)
+    end
+
+    def initialize(out: $stdout, err: $stderr)
+      @out = out
+      @err = err
+      @opts = { timeout: 2.0, settle: 1.5, json: false, count: 5, interval: 0.2, allow: [] }
+    end
+
+    def run(argv)
+      cmd = argv.shift
+      case cmd
+      when nil, "help", "-h", "--help"
+        @out.puts USAGE
+        return cmd.nil? ? 2 : 0
+      when "version", "--version", "-v"
+        @out.puts "asterism #{::Asterism::VERSION}"
+        return 0
+      end
+      unless %w[nodes objects tree watch ping echo call mcp].include?(cmd)
+        @err.puts "asterism: unknown command #{cmd.inspect}\n\n#{USAGE}"
+        return 2
+      end
+      rest = parser(cmd).parse(argv)
+      send("cmd_#{cmd == 'echo' ? 'ping' : cmd}", rest)
+    rescue OptionParser::ParseError, ArgumentError => e
+      @err.puts "asterism: #{e.message}"
+      2
+    rescue ::Asterism::Disconnected => e
+      @err.puts "asterism: cannot reach the network: #{e.message}"
+      1
+    rescue ::Asterism::Error => e
+      @err.puts "asterism: #{e.class}: #{e.message}"
+      1
+    rescue Interrupt
+      0
+    end
+
+    def parser(cmd)
+      OptionParser.new do |o|
+        o.banner = "Usage: asterism #{cmd} [options]"
+        o.on("--router LOCATOR", "a router (tcp/HOST:7447)") { @opts[:router] = _1 }
+        o.on("--credentials TAR", "a console's .tar") { @opts[:credentials] = _1 }
+        o.on("--peer LOCATOR", "a direct peer link to a node listening there (no router)") { @opts[:peer] = _1 }
+        o.on("--node NAME", "this node's ID (default: the certificate's name, or cli-<6 hex>)") { @opts[:node] = _1 }
+        o.on("--app NAME", "this application's name (default: cli-<4 hex>)") { @opts[:app] = _1 }
+        o.on("--json", "JSON instead of text (watch: one JSON object a line)") { @opts[:json] = true }
+        o.on("--timeout SECONDS", Float, "time limit of each get or call (2.0)") { @opts[:timeout] = _1 }
+        o.on("--settle SECONDS", Float, "how long to wait for the tokens at connect (1.5)") { @opts[:settle] = _1 }
+        case cmd
+        when "watch"
+          o.on("--duration SECONDS", Float, "stop after this long (default: until Ctrl-C)") { @opts[:duration] = _1 }
+        when "ping", "echo"
+          o.on("--count N", Integer, "round trips (5)") { @opts[:count] = _1 }
+          o.on("--interval SECONDS", Float, "pause between them (0.2)") { @opts[:interval] = _1 }
+          o.on("--call METHOD", "time a call of METHOD (with the ARGs after PATH) instead of the meta") { @opts[:call] = _1 }
+        when "call"
+          o.on("--kwargs VALUE", "keyword arguments: a JSON object or a Ruby Hash literal") { @opts[:kwargs] = _1 }
+        when "mcp"
+          o.on("--allow PATTERN", "methods the MCP client may call: [node/][app/]object.method, * as a wildcard " \
+                                  "(repeatable)") { @opts[:allow] << _1 }
+        end
+      end
+    end
+
+    # ------------------------------------------------------------ connecting
+
+    # Connects, starts the receiving thread, waits for the tokens and yields
+    # the Net and a Survey.
+    def connect(app_prefix: "cli")
+      router = @opts[:router]
+      creds = @opts[:credentials]
+      peer = @opts[:peer]
+      if router.nil? && creds.nil? && peer.nil?
+        raise ArgumentError, "where is the network? --router tcp/HOST:7447 or --credentials FILE.tar"
+      end
+      node = @opts[:node]
+      node ||= "#{app_prefix}-#{SecureRandom.hex(3)}" unless creds
+      app = @opts[:app] || "#{app_prefix}-#{SecureRandom.hex(2)}"
+      kw = { node: node, app: app }
+      kw[:credentials] = creds if creds
+      locator = router
+      if peer
+        locator = peer
+        kw[:mode] = :peer
+      end
+      ::Asterism.profile(name: app_prefix == "mcp" ? "asterism MCP" : "asterism CLI")
+      ::Asterism.connect(locator, **kw) do |net|
+        net.on_error { |e, where| @err.puts "asterism: #{where}: #{e.class}: #{e.message}" }
+        net.start
+        survey = Survey.new(timeout: @opts[:timeout])
+        survey.settle(@opts[:settle])
+        yield net, survey
+      end
+    end
+
+    def emit_json(v)
+      @out.puts JSON.pretty_generate(v)
+    end
+
+    # ------------------------------------------------------------ nodes
+
+    def cmd_nodes(_rest)
+      connect do |_net, sv|
+        tree = sv.tree(meta: false)
+        if @opts[:json]
+          emit_json(tree.map { |n| n.merge("apps" => n["apps"].map { |a| a.except("objects") }) })
+        elsif tree.empty?
+          @out.puts "(no other node is visible)"
+        else
+          tree.each do |n|
+            @out.puts "#{n['node']}#{profile_text(n['profile'])}"
+            n["apps"].each do |a|
+              @out.puts "  #{a['app']}#{"  #{a['objects'].size} objects" unless a['objects'].empty?}" \
+                        "#{"  status #{compact(a['status'])}" if a.key?('status')}"
+            end
+          end
+        end
+      end
+      0
+    end
+
+    # ------------------------------------------------------------ objects
+
+    def cmd_objects(rest)
+      pattern = rest.shift || "**"
+      connect do |_net, sv|
+        paths = sv.objects(pattern)
+        metas = sv.metas(paths)
+        if @opts[:json]
+          emit_json(paths.map do |p|
+            h = { "path" => p, "methods" => metas[p] }
+            h["doc"] = sv.object_doc(p) if sv.object_doc(p)
+            h
+          end)
+        elsif paths.empty?
+          @out.puts "(no object matches #{pattern})"
+        else
+          paths.each do |p|
+            @out.puts "#{p}  #{metas.key?(p) ? methods_text(metas[p]) : '(no meta: not answered in time, or not allowed)'}"
+            @out.puts "  #{sv.object_doc(p)}" if sv.object_doc(p)
+            # The methods that tell what they do, one a line (doc's first line).
+            (metas[p] || []).each do |m|
+              @out.puts "    #{signature(m)}  #{m['doc'].lines.first.strip}" if m["doc"]
+            end
+          end
+        end
+      end
+      0
+    end
+
+    # ------------------------------------------------------------ tree
+
+    def cmd_tree(_rest)
+      connect do |_net, sv|
+        tree = sv.tree
+        if @opts[:json]
+          emit_json(tree)
+        elsif tree.empty?
+          @out.puts "(no other node is visible)"
+        else
+          tree.each do |n|
+            @out.puts "#{n['node']}#{profile_text(n['profile'])}"
+            n["apps"].each do |a|
+              @out.puts "  #{a['app']}#{"  status #{compact(a['status'])}" if a.key?('status')}"
+              a["objects"].each do |o|
+                @out.puts "    #{o['name']}  #{o['methods'] ? methods_text(o['methods']) : '(no meta)'}"
+              end
+            end
+          end
+        end
+      end
+      0
+    end
+
+    # ------------------------------------------------------------ watch
+
+    # Prints the changes until Ctrl-C (or --duration): nodes (Asterism's
+    # on_join / on_leave), applications and objects (their liveliness
+    # tokens), statuses (their puts) and profiles (their puts). The
+    # statuses there at the start come first.
+    def cmd_watch(_rest)
+      connect do |net, sv|
+        own = "#{net.node_id}/#{net.app}"
+        sv.statuses.sort.each { |path, st| event("status", path, status: st, now: true) }
+        net.on_join { |n| event("join", n, what: "node") }
+        net.on_leave { |n| event("leave", n, what: "node") }
+        net.session.liveliness_watch("asterism/**") do |key, alive|
+          # The tokens alive at the start come first, in one burst: not news.
+          next unless @watch_started
+          path = key.delete_prefix("asterism/")
+          next if path == own || path.start_with?("#{own}/")
+          what = { 2 => "app", 3 => "object" }[path.count("/") + 1]
+          event(alive ? "join" : "leave", path, what: what) if what
+        end
+        net.session.subscribe(Survey::STATUS_ALL) do |sample|
+          got = ::Asterism::Status.parse(sample.key, sample.payload)
+          event("status", "#{got[0]}/#{got[1]}", status: got[2]) if got && "#{got[0]}/#{got[1]}" != own
+        end
+        net.session.subscribe(Survey::PROFILES_ALL) do |sample|
+          node = sample.key.split("/")[1]
+          pr = ::Asterism::Profile.check(::Asterism::Codec.unpack(sample.payload))
+          event("profile", node, profile: pr) if pr && node != net.node_id
+        end
+        sleep 0.3
+        @watch_started = true
+        @err.puts "asterism: watching (Ctrl-C to stop)" unless @opts[:json]
+        deadline = @opts[:duration] && (Process.clock_gettime(Process::CLOCK_MONOTONIC) + @opts[:duration])
+        loop do
+          break if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+          break unless net.connected?
+          sleep 0.05
+        end
+      end
+      0
+    end
+
+    def event(kind, path, what: nil, status: nil, profile: nil, now: false)
+      t = Time.now
+      if @opts[:json]
+        h = { "t" => t.utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ"), "event" => kind, "path" => path }
+        h["what"] = what if what
+        h["status"] = status if status
+        h["profile"] = profile if profile
+        h["now"] = true if now
+        @out.puts JSON.generate(h)
+      else
+        mark = { "join" => "+", "leave" => "-", "status" => "~", "profile" => "*" }[kind]
+        text = case kind
+               when "status" then "status #{path} #{compact(status)}#{' (now)' if now}"
+               when "profile" then "profile #{path}#{profile_text(profile)}"
+               else "#{what} #{path}"
+               end
+        @out.puts "#{t.strftime('%H:%M:%S.%L')} #{mark} #{text}"
+      end
+      @out.flush
+    end
+
+    # ------------------------------------------------------------ ping
+
+    # Round trips to PATH: the meta of an object (no method runs), the
+    # profile of a node, or with --call a method (with the ARGs given).
+    def cmd_ping(rest)
+      path = rest.shift or raise ArgumentError, "ping: which node or object? (asterism ping node/app/object)"
+      args = rest.map { Literal.parse(_1) }
+      chunks = path.split("/")
+      raise ArgumentError, "ping: PATH is node or node/app/object" unless [1, 3].include?(chunks.size)
+      raise ArgumentError, "ping: --call needs node/app/object" if @opts[:call] && chunks.size != 3
+      what = @opts[:call] ? "call #{@opts[:call]}" : (chunks.size == 3 ? "meta" : "profile")
+      times = []
+      connect do |_net, _sv|
+        ms = (@opts[:timeout] * 1000).round
+        @opts[:count].times do |i|
+          sleep @opts[:interval] if i.positive?
+          t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          ok = begin
+            ping_once(path, chunks, args, ms)
+            true
+          rescue ::Asterism::RemoteError => e
+            @err.puts "asterism: #{path}: #{e.remote_kind || 'error'}: #{e.message}" if i.zero?
+            true # it answered
+          rescue ::Asterism::TimeoutError => e
+            @err.puts "asterism: #{e.message}"
+            false
+          end
+          dt = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0) * 1000
+          times << dt if ok
+          @out.puts "#{path} #{what}: #{ok ? format('%.1f ms', dt) : 'no answer'}" unless @opts[:json]
+        end
+      end
+      if @opts[:json]
+        emit_json({ "path" => path, "what" => what, "count" => @opts[:count], "answered" => times.size,
+                    "ms" => times.map { _1.round(2) } })
+      elsif times.any?
+        @out.puts format("%d of %d answered: min %.1f / avg %.1f / max %.1f ms", times.size, @opts[:count],
+                         times.min, times.sum / times.size, times.max)
+      end
+      times.empty? ? 1 : 0
+    end
+
+    def ping_once(path, chunks, args, ms)
+      if @opts[:call]
+        ::Asterism[path, timeout_ms: ms].asterism_call(@opts[:call], *args)
+      elsif chunks.size == 3
+        raw = ::Asterism.meta(path, ms)
+        raise ::Asterism::Error, "malformed meta from #{path}" unless raw.is_a?(Hash)
+      else
+        ::Asterism.profile_async(path, false, nil, ms).raw_value
+      end
+    end
+
+    # ------------------------------------------------------------ call
+
+    def cmd_call(rest)
+      path = rest.shift
+      method = rest.shift
+      raise ArgumentError, "call: asterism call node/app/object METHOD [ARG...]" unless path && method
+      ::Asterism.split_path(path)
+      args = rest.map { Literal.parse(_1) }
+      kwargs = @opts[:kwargs] ? Literal.parse(@opts[:kwargs]) : {}
+      raise ArgumentError, "--kwargs: expected a JSON object or a Ruby Hash" unless kwargs.is_a?(Hash)
+      kwargs = kwargs.transform_keys(&:to_sym)
+      code = 0
+      connect do |_net, _sv|
+        px = ::Asterism[path, timeout: @opts[:timeout]]
+        begin
+          v = px.asterism_call(method, *args, **kwargs)
+          @opts[:json] ? @out.puts(JSON.generate({ "value" => json_safe(v) })) : @out.puts(v.inspect)
+        rescue ::Asterism::RemoteError => e
+          if @opts[:json]
+            @out.puts JSON.generate({ "error" => { "kind" => e.remote_kind, "class" => e.remote_class,
+                                                   "message" => e.remote_message } })
+          else
+            @err.puts "asterism: #{path}.#{method}: #{e.remote_kind || 'error'}: #{e.message}"
+          end
+          code = 1
+        rescue ::Asterism::TimeoutError => e
+          @err.puts "asterism: #{e.message}" \
+                    "#{"\n  (with a console's .tar, the router refuses a call its role does not allow; " \
+                       'it looks the same as no answer)' if @opts[:credentials]}"
+          code = 1
+        end
+      end
+      code
+    end
+
+    # ------------------------------------------------------------ mcp
+
+    def cmd_mcp(_rest)
+      begin
+        require_relative "cli/mcp"
+      rescue LoadError => e
+        raise unless e.message.include?("mcp")
+        @err.puts "asterism mcp needs the mcp gem: gem install mcp (#{e.message})"
+        return 1
+      end
+      connect(app_prefix: "mcp") do |net, sv|
+        MCPBridge.new(net, sv, allow: @opts[:allow], log: @err).run
+      end
+      0
+    end
+
+    # ------------------------------------------------------------ text
+
+    def profile_text(pr)
+      return "" unless pr
+      parts = [pr["kind"], pr["host"]].compact.join("/")
+      name = pr["name"] ? " \"#{pr['name']}\"" : ""
+      "  (#{parts})#{name}"
+    end
+
+    def methods_text(list)
+      list.map { |m| signature(m) }.join(" ")
+    end
+
+    # name(arg, arg) with the names the meta tells, else name(2) / name(*).
+    def signature(m)
+      return "#{m['name']}(#{m['args'].join(', ')}#{', *' if m['arity'].negative?})" if m["args"]
+      m["arity"].negative? ? "#{m['name']}(*)" : "#{m['name']}(#{m['arity']})"
+    end
+
+    def compact(v)
+      JSON.generate(json_safe(v))
+    end
+
+    # A value as JSON can hold it (bytes as a note).
+    def json_safe(v)
+      case v
+      when Hash then v.to_h { |k, x| [k.to_s, json_safe(x)] }
+      when Array then v.map { json_safe(_1) }
+      when String then v.encoding == Encoding::BINARY && !v.ascii_only? ? "(#{v.bytesize} bytes)" : v
+      else v
+      end
+    end
+  end
+end

data/lib/asterism/cruby/credentials.rb

@@ -0,0 +1,97 @@
+# 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:
+#
+#   <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
+  # 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
+    module CRuby
+      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
+    prepend CRuby
+  end
+end

data/lib/asterism/cruby/objects.rb

@@ -26,8 +26,8 @@ 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
-       profile profile_async session].each do |m|
+    %i[expose unexpose poll nodes [] call_async meta connected? reconnecting? exposed on_join on_leave off_join off_leave
+       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
@@ -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)
@@ -65,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 }
@@ -148,16 +157,18 @@ 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; 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.
@@ -178,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)
@@ -208,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/cruby/ros.rb

@@ -27,7 +27,7 @@ module Asterism
     # Opens a Zenoh session and makes a Connection for nodes on it. domain:
     # the ROS domain of the nodes made by ros.node. type_path: directories
     # with generated types to add to Asterism::ROS::TYPE_PATH. The other
-    # options go to Asterism::Zenoh::Session.open. With a block: yields the
+    # options (credentials: among them) go to Asterism::Zenoh.open. With a block: yields the
     # Connection, closes it when the block ends and returns its value.
     def self.connect(locator = nil, domain: 0, type_path: nil, interval: Runner::DEFAULT_INTERVAL, **opts)
       Array(type_path).each { |d| TYPE_PATH << File.expand_path(d) unless TYPE_PATH.include?(File.expand_path(d)) }