asterism 0.8.0 → 0.10.0

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

data/lib/asterism/cli/values.rb

@@ -0,0 +1,216 @@
+# The values the applications put on their own keys
+# (asterism/<node>/<app>/<object>/<more>, docs/protocol.md 2.2: a game
+# table's state, a log), for `asterism object get / echo` and the MCP
+# bridge's asterism_values. A put is not kept anywhere and a get has no
+# answer for it (an application's queryable answers only the key shapes of
+# 4.3), so the latest value is only what a subscriber received and kept:
+# Values::Store keeps it, a key at a time, within limits.
+require "json"
+
+module Asterism
+  class CLI
+    module Values
+      PREFIX = "asterism/"
+      # Characters a part of a key cannot have (2.1); * and ** are whole
+      # parts.
+      BAD = /[*$?#]/
+
+      module_function
+
+      # The pattern (node/app/object/more, * and ** as whole parts) checked;
+      # ArgumentError otherwise.
+      def check_pattern!(pattern)
+        parts = pattern.to_s.split("/", -1)
+        bad = parts.empty? || parts.any? do |p|
+          p.empty? || p.start_with?("@") || (p.match?(BAD) && !%w[* **].include?(p))
+        end
+        raise ArgumentError, "#{pattern.inspect}: a key's parts are names, * (one part) or ** (any parts)" if bad
+        pattern
+      end
+
+      # The Zenoh key expression of a pattern.
+      def key_expr(pattern)
+        "#{PREFIX}#{pattern}"
+      end
+
+      def match?(pattern, key)
+        ::Asterism.glob?(pattern, key)
+      end
+
+      # [value, format] of a payload: MessagePack (Asterism's own, 3.1);
+      # else JSON text; else UTF-8 text; else "(n bytes)". The value is
+      # what JSON can hold (bytes inside as "(n bytes)").
+      def decode(payload)
+        bytes = payload.to_s.b
+        return [nil, "empty"] if bytes.empty?
+        begin
+          return [json_safe(::MessagePack.unpack(bytes)), "msgpack"]
+        rescue StandardError
+          nil
+        end
+        text = bytes.dup.force_encoding(Encoding::UTF_8)
+        return ["(#{bytes.bytesize} bytes)", "bytes"] unless text.valid_encoding?
+        begin
+          [json_safe(JSON.parse(text)), "json"]
+        rescue JSON::ParserError
+          [text, "text"]
+        end
+      end
+
+      def json_safe(v)
+        case v
+        when Hash then v.to_h { |k, x| [k.is_a?(String) ? k : 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
+        when Float then v.finite? ? v : v.to_s
+        when Integer, true, false, nil then v
+        when Symbol then v.to_s
+        else v.inspect
+        end
+      end
+
+      def time(t)
+        t.getutc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+      end
+
+      # One put as the command line and the MCP tool show it: {"key"
+      # (without asterism/), "t", "bytes", "format", "value"}.
+      def entry(key, payload, t = Time.now)
+        value, format = decode(payload)
+        { "key" => key.delete_prefix(PREFIX), "t" => time(t), "bytes" => payload.to_s.bytesize,
+          "format" => format, "value" => value }
+      end
+
+      # The latest put of each key, as received since it was made: at most
+      # max_keys keys and max_total payload bytes (the key received
+      # longest ago is forgotten first); a payload over max_bytes is kept
+      # as its size only. Thread safe; wait blocks until a key matches.
+      class Store
+        MAX_KEYS = 1000
+        MAX_BYTES = 256 * 1024
+        MAX_TOTAL = 16 * 1024 * 1024
+        # The JSON text of a value longer than this is cut in an answer.
+        VALUE_CUT = 8192
+        # The most keys an answer lists (the rest counted as "more").
+        MAX_ANSWER = 100
+        # The longest wait an answer may ask for (seconds).
+        MAX_WAIT = 30
+
+        attr_reader :since, :forgotten
+
+        # alive: given "<node>/<app>", true when the application is on the
+        # network now. clock: the monotonic seconds (for the tests).
+        def initialize(max_keys: MAX_KEYS, max_bytes: MAX_BYTES, max_total: MAX_TOTAL, alive: nil,
+                       clock: nil, now: nil)
+          @max_keys = max_keys
+          @max_bytes = max_bytes
+          @max_total = max_total
+          @alive = alive || ->(_app) { true }
+          @clock = clock || -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+          @now = now || -> { Time.now }
+          @since = @now.call
+          @keys = {} # key => record, the oldest received first
+          @total = 0
+          @forgotten = 0
+          @lock = Mutex.new
+          @cond = ConditionVariable.new
+        end
+
+        # A put received (key with or without asterism/).
+        def put(key, payload)
+          key = key.delete_prefix(PREFIX)
+          payload = payload.to_s
+          size = payload.bytesize
+          rec = if size > @max_bytes
+                  { "value" => "(#{size} bytes: too large to keep)", "format" => "dropped", "kept" => false }
+                else
+                  v, f = Values.decode(payload)
+                  { "value" => v, "format" => f }
+                end
+          rec.merge!("key" => key, "bytes" => size, "t" => @now.call, "mono" => @clock.call, "left" => false)
+          @lock.synchronize do
+            old = @keys.delete(key)
+            @total -= old["kept"] == false ? 0 : old["bytes"] if old
+            @keys[key] = rec
+            @total += size unless rec["kept"] == false
+            while @keys.size > @max_keys || (@total > @max_total && @keys.size > 1)
+              _, gone = @keys.shift
+              @total -= gone["bytes"] unless gone["kept"] == false
+              @forgotten += 1
+            end
+            @cond.broadcast
+          end
+          self
+        end
+
+        # The application "<node>/<app>" left the network: its values are
+        # from before (kept, marked).
+        def left(app)
+          prefix = "#{app}/"
+          @lock.synchronize { @keys.each_value { |r| r["left"] = true if r["key"].start_with?(prefix) } }
+          self
+        end
+
+        def size
+          @lock.synchronize { @keys.size }
+        end
+
+        def keys
+          @lock.synchronize { @keys.keys }
+        end
+
+        # The records whose keys match (sorted by key); with wait (seconds),
+        # until one matches or the time is up.
+        def match(pattern, wait: 0)
+          deadline = @clock.call + wait.to_f
+          @lock.synchronize do
+            loop do
+              got = @keys.values.select { Values.match?(pattern, _1["key"]) }
+              return got.sort_by { _1["key"] } unless got.empty?
+              left = deadline - @clock.call
+              return [] if left <= 0
+              @cond.wait(@lock, left)
+            end
+          end
+        end
+
+        # What asterism_values answers: {"since", "values" => [{"key", "t",
+        # "age_s", "app", "bytes", "format", "value"(, "truncated")}]}, with
+        # "more" when more keys matched than an answer lists, "forgotten"
+        # when the limits made it forget keys, and "note" when nothing came.
+        def answer(pattern = "**", wait: 0)
+          Values.check_pattern!(pattern)
+          wait = wait.to_f.clamp(0, MAX_WAIT)
+          recs = match(pattern, wait: wait)
+          now = @clock.call
+          alive = {}
+          out = { "since" => Values.time(@since) }
+          out["values"] = recs.first(MAX_ANSWER).map do |r|
+            app = r["key"].split("/")[0, 2].join("/")
+            here = alive.key?(app) ? alive[app] : (alive[app] = @alive.call(app) ? true : false)
+            h = { "key" => r["key"], "t" => Values.time(r["t"]), "age_s" => (now - r["mono"]).round(1),
+                  "app" => here ? (r["left"] ? "restarted" : "alive") : "gone", "bytes" => r["bytes"],
+                  "format" => r["format"] }
+            text = JSON.generate(r["value"])
+            if text.bytesize > VALUE_CUT
+              h["value"] = "#{text.byteslice(0, VALUE_CUT).scrub('')}…"
+              h["truncated"] = true
+            else
+              h["value"] = r["value"]
+            end
+            h["truncated"] = true if r["kept"] == false
+            h
+          end
+          out["more"] = recs.size - MAX_ANSWER if recs.size > MAX_ANSWER
+          out["forgotten"] = @forgotten if @forgotten.positive?
+          if recs.empty?
+            out["note"] = "nothing came for #{pattern}#{wait.positive? ? " in #{format('%g', wait)} s" : ''}: " \
+                          "it has not been put since this server started (puts come only when a value " \
+                          "changes), or the router does not let this server read it"
+          end
+          out
+        end
+      end
+    end
+  end
+end