asterism 0.7.1 → 0.9.0

data/lib/asterism/cli/survey.rb

@@ -0,0 +1,206 @@
+# What `asterism nodes / objects / tree` and the MCP bridge read from the
+# network, on a connection that is already open (Asterism.connect): the
+# applications and objects from the liveliness tokens, then the meta of
+# the objects, the nodes' profiles and the applications' statuses
+# (docs/protocol.md 5, 7, 8) with one get for each node or application.
+#
+# Not one wildcard get for all (asterism/*/*/@status): behind a router's
+# access control a query must fit the rules of every node it would reach
+# (a game host may answer asterism/games/*/@status, not asterism/*/*/@status),
+# so a wildcard over the nodes is refused where the plain keys pass. The
+# gets go out at once and are read as their replies come (zenoh-c fills
+# them on its own threads), so a listing costs one time limit at most,
+# whatever the number of nodes. What a router refuses is simply not there,
+# and the listing says so instead of calling a node gone.
+module Asterism
+  class CLI
+    class Survey
+      # What watch subscribes to (puts are routed per subscriber, so the
+      # wildcards pass where the rules let them through).
+      PROFILES_ALL = "asterism/*/@profile"
+      STATUS_ALL = "asterism/*/*/@status"
+      STEP = 0.005
+
+      attr_reader :timeout
+
+      # own: this connection's "<node>/<app>", left out of the listings.
+      def initialize(timeout: 2.0, own: nil)
+        @timeout = timeout
+        @own = own || "#{::Asterism.node_id}/#{::Asterism.app}"
+        @object_docs = {}
+      end
+
+      # Waits for the tokens alive at connect to come in (they come in one
+      # burst from the router): until the applications stop changing for
+      # quiet seconds, at most max seconds.
+      def settle(max = 1.5, quiet: 0.3)
+        t0 = now
+        last = nil
+        since = now
+        loop do
+          cur = [::Asterism.apps, ::Asterism.each("**").size]
+          if cur != last
+            last = cur
+            since = now
+          end
+          break if now - since >= quiet || now - t0 >= max
+          sleep 0.02
+        end
+      end
+
+      # The applications alive, "<node>/<app>", sorted (this one left out).
+      def apps(pattern = "*/*")
+        (::Asterism.apps(pattern) - [@own]).sort
+      end
+
+      # The nodes that have an application or an object alive (sorted).
+      def nodes
+        (apps.map { _1.split("/")[0] } + objects.map { _1.split("/")[0] }).uniq.sort
+      end
+
+      # The objects alive, "<node>/<app>/<object>", sorted (this
+      # application's own left out).
+      def objects(pattern = "**")
+        ::Asterism.each(pattern).map(&:asterism_path).reject { _1.start_with?("#{@own}/") }.sort
+      end
+
+      # {path => [{"name", "arity"}, ...]} for the paths given (an object
+      # that does not answer its meta in time is left out). One get per
+      # application (asterism/<node>/<app>/*/meta), then one for each object
+      # it did not bring.
+      def metas(paths)
+        return {} if paths.empty?
+        out = {}
+        apps = paths.map { _1.split("/")[0, 2].join("/") }.uniq
+        gets(apps.map { "asterism/#{_1}/*/meta" }).each_value do |replies|
+          replies.each do |key, payload|
+            path = key.delete_prefix("asterism/").delete_suffix("/meta")
+            m = meta_list(payload, path)
+            out[path] = m if m && paths.include?(path)
+          end
+        end
+        missing = paths - out.keys
+        unless missing.empty?
+          gets(missing.map { "asterism/#{_1}/meta" }).each do |key, replies|
+            path = key.delete_prefix("asterism/").delete_suffix("/meta")
+            m = replies.first && meta_list(replies.first[1], path)
+            out[path] = m if m
+          end
+        end
+        out
+      end
+
+      # {node => profile without the icon} of the nodes that answered (one
+      # get per node, all at once).
+      def profiles(list = nodes)
+        out = {}
+        gets(list.map { "asterism/#{_1}/@profile" }, params: "icon=0").each do |key, replies|
+          pr = replies.first && ::Asterism::Profile.check(::Asterism::Codec.unpack(replies.first[1]))
+          out[key.split("/")[1]] = pr if pr
+        end
+        out
+      end
+
+      # {"<node>/<app>" => status} of the applications that answered (one
+      # get per application, all at once).
+      def statuses(list = apps)
+        out = {}
+        gets(list.map { "asterism/#{_1}/@status" }).each do |key, replies|
+          st = replies.first && ::Asterism::Status.check(::Asterism::Codec.unpack(replies.first[1]))
+          parts = key.split("/")
+          out["#{parts[1]}/#{parts[2]}"] = st if st
+        end
+        out
+      end
+
+      # The tree: [{"node", "profile", "apps" => [{"app", "status",
+      # "objects" => [{"name", "methods"}]}]}]. meta: false leaves the
+      # methods out (no meta gets); node: (and app:) narrow it to one node
+      # (one application).
+      def tree(meta: true, node: nil, app: nil)
+        scope = node && "#{node}/#{app || '*'}"
+        objs = scope ? objects("#{scope}/*") : objects
+        app_list = scope ? apps(scope) : apps
+        threads = []
+        node_list = (app_list.map { _1.split("/")[0] } + objs.map { _1.split("/")[0] }).uniq
+        threads << Thread.new { profiles(node_list) }
+        threads << Thread.new { statuses(app_list) }
+        threads << Thread.new { meta ? metas(objs) : {} }
+        prof, stat, met = threads.map(&:value)
+        by_node = Hash.new { |h, k| h[k] = {} }
+        app_list.each { |a| n, ap = a.split("/"); by_node[n][ap] ||= [] }
+        objs.each do |o|
+          n, ap, name = o.split("/")
+          (by_node[n][ap] ||= []) << name
+        end
+        by_node.keys.sort.map do |n|
+          apps = by_node[n].keys.sort.map do |ap|
+            h = { "app" => ap }
+            h["status"] = stat["#{n}/#{ap}"] if stat.key?("#{n}/#{ap}")
+            h["objects"] = by_node[n][ap].sort.map do |name|
+              e = { "name" => name }
+              e["methods"] = met["#{n}/#{ap}/#{name}"] if met.key?("#{n}/#{ap}/#{name}")
+              d = object_doc("#{n}/#{ap}/#{name}")
+              e["doc"] = d if d
+              e
+            end
+            h
+          end
+          h = { "node" => n }
+          h["profile"] = prof[n] if prof[n]
+          h["apps"] = apps
+          h
+        end
+      end
+
+      # Sends a get on each key at once and waits for all of them (at most
+      # the time limit): {key => [[reply key, payload], ...]}.
+      def gets(keys, params: nil)
+        s = ::Asterism.session
+        ms = (@timeout * 1000).round
+        pending = keys.to_h { |k| [k, s.get(k, timeout_ms: ms, params: params)] }
+        out = keys.to_h { [_1, []] }
+        until pending.empty?
+          pending.delete_if do |k, g|
+            ended = g.done?
+            out[k].concat(g.each_reply.map { |r| [r[0], r[1]] })
+            ended
+          end
+          sleep STEP unless pending.empty?
+        end
+        out
+      rescue ::Asterism::Zenoh::Error => e
+        raise ::Asterism::Disconnected, e.message
+      end
+
+      # A meta reply's methods: [{"name", "arity"} and, when the object
+      # tells them (docs/protocol.md 5), "args" (names) and "doc"]. Fields
+      # of another shape are left out, unknown ones ignored.
+      def meta_list(payload, path = nil)
+        m = ::Asterism::Codec.unpack(payload)
+        list = m.is_a?(Hash) ? m["methods"] : nil
+        return nil unless list.is_a?(Array)
+        @object_docs[path] = m["doc"] if path && m["doc"].is_a?(String)
+        list.filter_map do |e|
+          next unless e.is_a?(Hash) && e["name"]
+          h = { "name" => e["name"].to_s, "arity" => e["arity"].to_i }
+          args = e["args"]
+          h["args"] = args if args.is_a?(Array) && args.all? { _1.is_a?(String) } &&
+                              (h["arity"].negative? || args.size == h["arity"])
+          h["doc"] = e["doc"] if e["doc"].is_a?(String)
+          h
+        end
+      end
+
+      # The text an object tells about itself in its meta (read by metas),
+      # or nil.
+      def object_doc(path)
+        @object_docs[path]
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/asterism/cli/text.rb

@@ -0,0 +1,256 @@
+# How the command line's text looks (not --json, which stays as it is):
+# colours and the terminal's width when the output is a terminal, plain
+# text 80 columns wide (or COLUMNS) otherwise; NO_COLOR turns the colours
+# off. Statuses are laid out as indented key=value lines, the methods and
+# the descriptions are wrapped to the width, and watch tells what changed
+# in a status. The standard library only (io/console for the width).
+require "json"
+
+module Asterism
+  class CLI
+    # Colours and width for one output.
+    class Style
+      CODES = { bold: 1, dim: 2, red: 31, green: 32, yellow: 33, blue: 34, magenta: 35, cyan: 36 }.freeze
+      # What each kind of thing is painted with.
+      ROLES = {
+        node: %i[bold blue], app: [:cyan], object: [:green], method: [:bold], note: [:dim], time: [:dim],
+        join: [:green], leave: [:red], status: [:yellow], profile: [:magenta]
+      }.freeze
+      MIN_WIDTH = 20
+
+      attr_reader :width
+
+      def initialize(io, env = ENV)
+        tty = io.respond_to?(:tty?) && io.tty?
+        @color = tty && env["NO_COLOR"].to_s.empty?
+        w = (tty && terminal_width(io)) || env["COLUMNS"].to_i
+        @width = w.positive? ? [w, MIN_WIDTH].max : 80
+      end
+
+      def color?
+        @color
+      end
+
+      # text painted as role (a ROLES key) or with the CODES given.
+      def paint(text, *styles)
+        text = text.to_s
+        return text unless @color
+        codes = styles.flat_map { ROLES.fetch(_1, [_1]) }.map { CODES.fetch(_1) }
+        codes.empty? ? text : "\e[#{codes.join(';')}m#{text}\e[0m"
+      end
+
+      private
+
+      def terminal_width(io)
+        require "io/console"
+        w = io.winsize[1]
+        w.positive? ? w : nil
+      rescue StandardError, LoadError
+        nil
+      end
+    end
+
+    # Laying text out: display widths (East Asian wide characters take two
+    # columns), word wrapping, statuses and their differences.
+    module Text
+      module_function
+
+      ANSI = /\e\[[0-9;]*m/
+      # Code points that take two columns on a terminal (East Asian Wide and
+      # Fullwidth, roughly).
+      WIDE = /[ᄀ-ᅟ⺀-〾ぁ-㏿㐀-䶿一-鿿ꀀ-꓏가-힣豈-﫿︰-﹏＀-｠￠-￦\u{1F300}-\u{1F64F}\u{1F900}-\u{1F9FF}\u{20000}-\u{3FFFD}]/
+      # A string value longer than this (columns) is cut, and so is an
+      # array written on one line; --json has them whole.
+      LONG = 60
+      ARROW = "→"
+      ELLIPSIS = "…"
+
+      # The columns text takes on a terminal (colour codes take none).
+      def width(text)
+        s = text.to_s.gsub(ANSI, "")
+        s = s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) unless s.encoding == Encoding::UTF_8
+        s.scrub.each_char.sum { _1.match?(WIDE) ? 2 : 1 }
+      end
+
+      # The tokens joined with sep in lines at most cols columns wide: the
+      # first starts with first, the others with rest (spaces as wide as
+      # first by default). A plain token wider than a line is broken between
+      # characters (break_long: false keeps it whole, on a line of its own);
+      # a painted one (a method's signature) is kept whole. Returns the
+      # lines (at least one).
+      def wrap(tokens, cols, first: "", rest: nil, sep: " ", break_long: true)
+        rest ||= " " * width(first)
+        lines = []
+        line = first
+        lw = width(first)
+        empty = true
+        tokens.each do |tok|
+          tok = tok.to_s
+          tw = width(tok)
+          if !empty && lw + sep.size + tw > cols
+            lines << line
+            line = rest
+            lw = width(rest)
+            empty = true
+          end
+          while break_long && lw + tw > cols && !tok.match?(ANSI) && tok.size > 1
+            head, tail = split_width(tok, [cols - lw, 1].max)
+            break if tail.empty?
+            lines << (empty ? line : line + sep) + head
+            line = rest
+            lw = width(rest)
+            empty = true
+            tok = tail
+            tw = width(tok)
+          end
+          line += (empty ? "" : sep) + tok
+          lw += (empty ? 0 : sep.size) + tw
+          empty = false
+        end
+        lines << line
+        lines
+      end
+
+      # text's words wrapped (wrap), each paragraph (blank lines between)
+      # starting a new line with rest.
+      def wrap_text(text, cols, first: "", rest: nil)
+        rest ||= " " * width(first)
+        paras = text.to_s.strip.split(/\n\s*\n/).map(&:split).reject(&:empty?)
+        return [first.rstrip] if paras.empty?
+        paras.each_with_index.flat_map { |words, i| wrap(words, cols, first: i.zero? ? first : rest, rest: rest) }
+      end
+
+      # [the start of text no wider than cols (one character at least), the rest]
+      def split_width(text, cols)
+        w = 0
+        n = 0
+        text.each_char do |c|
+          cw = width(c)
+          break if n.positive? && w + cw > cols
+          w += cw
+          n += 1
+        end
+        [text[0, n], text[n..]]
+      end
+
+      # ------------------------------------------------------------ statuses
+
+      # A status (a Hash) as lines indented by indent spaces: the plain
+      # values of a level as key=value on one line (wrapped), a Hash of
+      # plain values as "key: k=v k=v", deeper ones as "key:" and their
+      # lines two spaces further in, an array with a Hash in it as "key:"
+      # and its elements as "- " lines. A key=value is never broken: one
+      # wider than the line has a line of its own (the terminal folds it).
+      def status_lines(h, cols, indent = 0)
+        pad = " " * indent
+        lines = []
+        flat = []
+        flush = lambda do
+          lines.concat(wrap(flat, cols, first: pad, break_long: false)) unless flat.empty?
+          flat = []
+        end
+        h.each do |k, v|
+          if plain?(v)
+            flat << pair(k, v)
+            next
+          end
+          flush.call
+          if v.is_a?(Hash) && v.empty?
+            lines << "#{pad}#{k}: {}"
+          elsif v.is_a?(Hash) && v.values.all? { plain?(_1) }
+            # The lines after the first under the first value (two spaces in
+            # when the key is long).
+            hang = width(k) + 2 > cols / 3 ? 2 : width(k) + 2
+            lines.concat(wrap(v.map { |kk, vv| pair(kk, vv) }, cols, first: "#{pad}#{k}: ", rest: pad + (" " * hang),
+                                                                    break_long: false))
+          elsif v.is_a?(Hash)
+            lines << "#{pad}#{k}:"
+            lines.concat(status_lines(v, cols, indent + 2))
+          else
+            lines << "#{pad}#{k}:"
+            v.each { |e| lines.concat(element_lines(e, cols, indent + 2)) }
+          end
+        end
+        flush.call
+        lines.empty? ? ["#{pad}{}"] : lines
+      end
+
+      # One element of an array that holds a Hash: "- " and the element.
+      def element_lines(e, cols, indent)
+        pad = " " * indent
+        if e.is_a?(Hash) && !e.empty? && e.values.all? { plain?(_1) }
+          wrap(e.map { |k, v| pair(k, v) }, cols, first: "#{pad}- ", rest: "#{pad}  ", break_long: false)
+        elsif e.is_a?(Hash) && !e.empty?
+          sub = status_lines(e, cols, indent + 2)
+          sub[0] = "#{pad}- #{sub[0].lstrip}"
+          sub
+        else
+          ["#{pad}- #{inline(e)}"]
+        end
+      end
+
+      # No Hash anywhere in v (it goes on one line).
+      def plain?(v)
+        case v
+        when Hash then false
+        when Array then v.all? { plain?(_1) }
+        else true
+        end
+      end
+
+      def pair(k, v)
+        "#{k}=#{inline(v)}"
+      end
+
+      # A value on one line: a word as it is, other text quoted (JSON), a
+      # long one cut; [a, b] (a long array cut, with the count left out);
+      # {k=v k=v}; nil as nil.
+      def inline(v)
+        case v
+        when Hash then "{#{v.map { |k, x| pair(k, x) }.join(' ')}}"
+        when Array then inline_array(v)
+        when String then inline_string(v)
+        when nil then "nil"
+        else v.to_s
+        end
+      end
+
+      def inline_string(s)
+        s = s.encode(Encoding::UTF_8, invalid: :replace, undef: :replace) unless s.encoding == Encoding::UTF_8
+        s = "#{split_width(s, LONG - 1)[0]}#{ELLIPSIS}" if width(s) > LONG
+        s.match?(/\A[^\s="'{}\[\],]+\z/) ? s : JSON.generate(s)
+      end
+
+      def inline_array(a)
+        parts = a.map { inline(_1) }
+        text = "[#{parts.join(', ')}]"
+        return text if width(text) <= LONG || parts.size < 2
+        kept = []
+        parts.each do |p|
+          break if width("[#{(kept + [p]).join(', ')}, #{ELLIPSIS}+#{parts.size}]") > LONG && kept.any?
+          kept << p
+        end
+        "[#{kept.join(', ')}, #{ELLIPSIS}+#{parts.size - kept.size}]"
+      end
+
+      # What changed from the status old to new, one String a change:
+      # "a.b 0→1" (a value changed), "+a.b=1" (a key came; a Hash on one
+      # line), "-a.b" (a key went). Hashes in both are compared key by key.
+      def status_diff(old, new, prefix = nil)
+        out = []
+        at = ->(k) { prefix ? "#{prefix}.#{k}" : k.to_s }
+        new.each do |k, v|
+          if !old.key?(k)
+            out << "+#{pair(at.(k), v)}"
+          elsif old[k].is_a?(Hash) && v.is_a?(Hash)
+            out.concat(status_diff(old[k], v, at.(k)))
+          elsif old[k] != v
+            out << "#{at.(k)} #{inline(old[k])}#{ARROW}#{inline(v)}"
+          end
+        end
+        old.each_key { |k| out << "-#{at.(k)}" unless new.key?(k) }
+        out
+      end
+    end
+  end
+end