excadg 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5bccdde832f42e296103812d1a60fa0adf8534d102c697d08b97697d5524dd37
-  data.tar.gz: a1da774573729eac556f4dfa3ff2c46bb21f1029db30cebeb172e00c9f3f9460
+  metadata.gz: 1b39410e76cbbe770fa2baa0f94eb10f25dd73bb644bb304c19fe4bc7b7fa39b
+  data.tar.gz: 0df53fa109fbfdb56809b87d8dd8314c5f884bb6a8060ce8eff2913627ca63c1
 SHA512:
-  metadata.gz: 29923112c768f2bb6a3ca99109c5d2a7bd48b6b0b45b9df7c9715ab29f557414fce338da3dd7ff6cbda5922d10bfd04d57316204c2279b8f402dba08687306f3
-  data.tar.gz: 496d09bc1390c268800976e6aa238f153671c9548d40be92e82e6d12b5a949537070317b65973ddbbfe62e6783b9643cf19280ea72a333ff577e0e6dc89cd67f
+  metadata.gz: 897dab58f102d0baf617b8d592f46a649e9c4213186cad003f79a36711c104d7d393a6f6e1454119465fbb423c0c4be6f980f89334d4ac5c77818b5b7ed718a5
+  data.tar.gz: 1cf7919dd79fed3d3e21499b7a246a9a96ebec26b06cb1462abdb66db67ab971de5f639ffc9ca00c025be1b313bec5fcd0ecb9e26147f95e437e1a36e8ff56ce

data/README.md

@@ -185,12 +185,17 @@ Logging is disabled by default, but it could be useful to debug tests. Add `ExcA
     - problem: can't find what to suspend
 - make a loop payload template
   - provide a mechanism to control # of children
-
-## Graph checks
-
-  - check for loops in the config
+- allow to dump shell payload stdout/err in realtime
+
+## Graph stability and tracking
+
+- add a tracker that collects execution graph from broker
+  - is hooked by broker
+  - can be enabled / disabled
+- visualize current execution on TUI
+  - allow to focus on a certain vertex to see what's it waiting for
+  - allow to dump currect vertice's state
+- implement checks using tracker:
+  - check for loops by deducting vertices to some signatures
   - check for unreachable islands - graph connectivity
   - check that there are nodes to start from
-
-
-- check MAX_CPU ...

data/lib/excadg/assertions.rb

@@ -5,6 +5,9 @@ module ExcADG
   module Assertions
     class << self
       # asserts that all vars are instances of one of the clss
+      # @param vars array or a single variable to check
+      # @param clss array or a single class to check against
+      # @raise StandardError if any of vars are not of clss
       def is_a? vars, clss
         return if vars.is_a?(Array) && clss == Array
 

data/lib/excadg/broker.rb

@@ -11,7 +11,7 @@ module ExcADG
   # handle requests sending/receiving though Ractor's interface
   module Broker
     class << self
-      attr_reader :data_store
+      attr_reader :data_store, :vtracker
 
       # is used from vertices to send reaqests to the broker
       # @return data received in response from the main ractor
@@ -36,9 +36,11 @@ module ExcADG
       end
 
       # start requests broker for vertices in a separated thread
+      # @param track {Boolean} whether to track execution graph
       # @return the thread started
-      def run
+      def run track: false
         @data_store ||= DataStore.new
+        @vtracker ||= track ? VTracker.new : nil
         @broker = Thread.new { loop { process_request } } unless @broker&.alive?
 
         at_exit {
@@ -79,6 +81,7 @@ module ExcADG
           Log.info "received request: #{request}"
           request.self.send case request
                             when Request::GetStateData
+                              @vtracker&.track request.self, deps
                               request.filter? ? request.deps.collect { |d| @data_store[d] } : @data_store.to_a
                             when Request::Update
                               @data_store << request.data

data/lib/excadg/data_store.rb

@@ -35,8 +35,8 @@ module ExcADG
       @by_vertex[new.vertex] = new if new.vertex
     end
 
-    # retrieves VStateData by key
-    # @param key either Vertex or VStateData::Key to retrieve Full state data
+    # retrieves {VStateData} by key
+    # @param key {Vertex} or {VStateData::Key} or vertex name (String || Symbol) to retrieve Full state data
     # @return VStateData::Full for the respective key
     # @raise StandardError if key is not of a supported type
     def [] key

data/lib/excadg/tui/assets.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# static assets to select from
+module ExcADG::Tui
+  module Assets
+    CORNERS = {
+      sharp: '┏┓┗┛',
+      round: '╭╮╰╯'
+    }.freeze
+  end
+end

data/lib/excadg/tui/block.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require_relative 'format'
+
+module ExcADG::Tui
+  # basic TUI building block;
+  # in a nutshell, it's a column, as {String}s in it are printed vertically one by one (see {#to_s});
+  # it could be a row only semantically if it's a part of a vertically composed array (see {.column})
+  class Block
+    attr_reader :width, :array
+
+    include Format
+
+    # transform array or "rows" to a single column;
+    # @example
+    #   Block.column "some", "other"               # some and other will be centered in column by default
+    #   Block.column "some", "other", align: :left # some and other will be shifted to the left
+    #   Block.column
+    #     Block.row("one", "two"),
+    #     "three"
+    #   ]} # one and two will be printed in the first row, three will be below them centered
+    #   Block.column("some", "other") { |el| el.box! } # enclose both string to boxes before making a row
+    # @param *rows array of rows ({Block}s / {String}s)
+    # @param align how to align blocks between each other: :center (default), :right, :left
+    # @param &block idividual row processor, the block is supplied with {Block}s
+    def self.column *rows, align: nil, &block
+      # row could be a String, make an array of horizontal lines from it
+      rows.collect! { |col| col.is_a?(Block) ? col : Block.new(col) }
+      rows.collect!(&block) if block_given? # allow to pre-process "rows"
+      max_row_width = rows.collect(&:width).max
+      Block.new rows.collect! { |blk|
+        extra_columns = max_row_width - blk.width
+        case align
+        when :left then blk.collect! { |line| line + ' ' * extra_columns }
+        when :right then blk.collect! { |line| ' ' * extra_columns + line }
+        else
+          blk.h_pad!(extra_columns / 2)
+          extra_columns.odd? ? blk.collect! { |line| line + ' ' } : blk
+        end
+        blk.array # get the array to join using builtin flatten
+      }.flatten!
+    end
+
+    # squash a row of columns (blocks) to a single block
+    # @example
+    #   Block.row "some", "other" # => "someother"
+    #   Block.row "some", ["other", "foo"], aligh: bottom # some will be shifted down by 1 line
+    #   Block.row("some", "other") { |blk| blk.box! } # both columns will be enclosed in a box
+    # @param *cols array of columns ({Block}s / {String}s)
+    # @param align how to align blocks between each other: :center (default), :top, :bottom
+    # @param &block idividual column processor, the block is supplied with {Block}s
+    def self.row *cols, align: nil, &block
+      cols.collect! { |col| col.is_a?(Block) ? col : Block.new(col) }
+      cols.collect!(&block) if block_given? # allow to pre-process columns
+      max_col_height = cols.collect(&:height).max
+      Block.new cols.collect! { |col|
+        extra_lines = max_col_height - col.height
+        case align
+        when :top then col << Array.new(extra_lines, '')
+        when :bottom then col >> Array.new(extra_lines, '')
+        else
+          col.v_pad!(extra_lines / 2)
+          col << '' if extra_lines.odd?
+        end
+        col.v_align! # is needed due to transpose call below
+        col.array # get the array to process using builtin methods
+      }.transpose.collect(&:join)
+    end
+
+    # make printable
+    def to_s
+      @array.join "\n"
+    end
+
+    # add extra lines from the supplied array to the block;
+    # no auto-alignment is performed, see {#v_align} to make width even
+    # @param other either {Array} or {String} to push back
+    def << other
+      other.is_a?(Array) ? @array += other : @array << other
+      @width = @array.collect(&:size).max
+      self
+    end
+
+    # add extra lines to the start of the block
+    # @param other either {Array} or {String} to push forward
+    # @example
+    #   Block.column '1'
+    #   block << %w[2 3] # now block has %w[2 3 1]
+    def >> other
+      case other
+      when Array
+        other.reverse_each { |i|
+          @array.unshift i
+        }
+      when String
+        @array.unshift other
+      end
+      @width = @array.collect(&:size).max
+      self
+    end
+
+    # column's height is its size
+    def height
+      @array.size
+    end
+
+    # main inline modification method
+    def collect! &block
+      @array.collect!(&block)
+      @width = @array.collect(&:size).max
+    end
+
+    private
+
+    # constructor is private;
+    # {#column} and {#row} are enough to make blocks;
+    # in case you need to align a single block, use e.g. `Block.column("one", "two") { |blk| blk.box!.pad! 2 }`
+    def initialize arg
+      case arg
+      when Array then @array = arg
+      when String then @array = [arg]
+      else raise "can't make block from #{arg.class}"
+      end
+      @width = @array.collect(&:size).max
+    end
+  end
+end

data/lib/excadg/tui/format.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module ExcADG::Tui
+  # collection of low-level {Block} formatting methods;
+  # most methods mutate an object they called for to avoid re-copying data each time;
+  # the module isn't expected to be used directly and exists just to de-couple
+  # formatting methods and basic blocks positioning (see {Block});
+  # all methods could be chained: `block.v_pad!(10).h_pad!(2).box!`
+  module Format
+    # add horizontal padding to the block
+    # @param size number of spaces to add
+    def h_pad! size
+      @array.collect! { |row|
+        "#{' ' * size}#{row}#{' ' * size}"
+      }
+      @width += size * 2
+      self
+    end
+
+    # add vertical padding to the block
+    # @param size number of spaces to add
+    def v_pad! size
+      filler = ' ' * @width
+      size.times {
+        self >> filler
+        self << filler
+      }
+      self
+    end
+
+    # adds spaces around the block
+    # @param size number of spaces to add
+    def pad! size
+      v_pad! size
+      h_pad! size
+    end
+
+    # aligns block elements vertically by adding spaces;
+    # all lines in block gets changed to have the same # of chars
+    # @param type {Symbol} :left (default), :center, :right
+    # @param width {Integer} target block width, defaults to the current width
+    def v_align! type = nil, width: nil
+      line_transformer = case type
+                         when :center
+                           ->(line, num_spaces) { ' ' * (num_spaces / 2) + line.to_s + (' ' * (num_spaces / 2)) + (num_spaces.odd? ? ' ' : '') }
+                         when :right
+                           ->(line, num_spaces) { (' ' * num_spaces) + line.to_s }
+                         else # :left
+                           ->(line, num_spaces) { line.to_s + (' ' * num_spaces) }
+                         end
+
+      @width = width unless width.nil? || @width > width
+      @array.collect! { |line| line_transformer.call line, @width - line.size }
+      self
+    end
+
+    # adds a square box around the block;
+    # auto-aligns the block, so use {#v_align!}
+    # if you want custom alignment for the block
+    def box! corners: :round
+      corners = Assets::CORNERS[corners]
+      v_align!
+      @array.collect! { |line| "│#{line}│" }
+      @array.unshift "#{corners[0]}#{'─' * width}#{corners[1]}"
+      @array << "#{corners[2]}#{'─' * width}#{corners[3]}"
+      @width += 2
+      self
+    end
+
+    # fit the current block to a rectangle by
+    # cropping the block and adding a special markers to content;
+    # actual content width and height will be 1 char less to store cropping symbols;
+    # filling does not align content, {v_align!} does
+    # @param width width to fit, nil means don't touch width
+    # @param height height to fit, nil means don't touch height
+    # @param fill whether to fill column for the sizes provided
+    def fit! width: nil, height: nil, fill: false
+      # pre-calc width to use below
+      @width = width unless width.nil? || (@width < width && !fill)
+
+      unless height.nil?
+        if @array.size > height
+          @array.slice!((height - 1)..)
+          @array << ('░' * @width)
+        elsif fill && @array.size < height
+          @array += Array.new(height - @array.size, ' ' * @width)
+        end
+      end
+      unless width.nil?
+        @array.collect! { |line|
+          if line.size > width
+            "#{line[...(width - 1)]}░"
+          elsif fill && line.size < width
+            line << ' ' * (width - line.size)
+          else
+            line
+          end
+        }
+      end
+      self
+    end
+  end
+end

data/lib/excadg/tui.rb

@@ -1,11 +1,13 @@
-# frozen_string_literal: true
-
 require 'date'
 require 'io/console'
 
 require_relative 'broker'
 require_relative 'state_machine'
 
+require_relative 'tui/assets'
+require_relative 'tui/block'
+require_relative 'tui/format'
+
 module ExcADG
   # render status on the screen
   module Tui
@@ -21,7 +23,10 @@ module ExcADG
         Log.info 'spawning tui'
         @thread = Thread.new {
           loop {
-            print_in_box stats
+            # print_in_box stats
+            clear
+            refresh_sizes
+            print stats
             sleep DELAY
           }
         }
@@ -29,43 +34,32 @@ module ExcADG
 
       def summarize has_failed, timed_out
         @thread.kill
-        print_in_box stats + (print_summary has_failed, timed_out)
-      end
-
-      private
-
-      # @param content is a list of lines to print
-      def print_in_box content
         clear
-        refresh_sizes
-        print "+-#{'-' * @content_size[:width]}-+\n"
-        content[..@content_size[:height]].each { |line|
-          if line.size > @content_size[:width]
-            printf @line_template, "#{line[...(@content_size[:width] - 3)]}..."
-          else
-            printf @line_template, line
-          end
-        }
-        if content.size < @content_size[:height]
-          (@content_size[:height] - content.size).times { printf @line_template, ' ' }
-        else
-          printf @line_template, '<some content did not fit and was cropped>'[..@content_size[:width]]
-        end
-        print "+-#{'-' * @content_size[:width]}-+\n"
+        print stats summary: get_summary(has_failed, timed_out)
       end
 
-      def print_summary has_failed, timed_out
+      # private
+
+      def get_summary has_failed, timed_out
         [timed_out ? 'execution timed out' : 'execution completed',
          "#{has_failed ? 'some' : 'no'} vertices failed"]
       end
 
       # make summary paragraph on veritces
-      def stats
-        [
-          "time spent (ms): #{DateTime.now.strftime('%Q').to_i - @started_at}",
-          "vertices seen: #{Broker.data_store.size}",
-          'progress:'
-        ] + state_stats.collect { |line| "  #{line}" }
+      def stats summary: nil
+        Block.column(
+          Block.column(summary || 'running').h_pad!(1).box!.v_align!(:center, width: @content_size[:width]),
+          Block.column(
+            *[
+              "time spent (ms): #{DateTime.now.strftime('%Q').to_i - @started_at}",
+              "vertices seen: #{Broker.data_store.size}",
+              'progress:'
+            ] + state_stats,
+            align: :left
+          ).h_pad!(2),
+          align: :left
+        ).fit!(width: @content_size[:width], height: @content_size[:height], fill: true)
+             .box!(corners: :sharp)
       end
 
       def clear
@@ -81,7 +75,7 @@ module ExcADG
           height: box_size[:height] - 4, # 2 for borders, 1 for \n, 1 for remark
           width: box_size[:width] - 5 # 2 for borders, 2 to indent
         }.freeze
-        @line_template = "| %-#{@content_size[:width]}s |\n"
+        @line_template = "│ %-#{@content_size[:width]}s │\n"
       end
 
       # make states summary, one for a line with consistent placing
@@ -93,13 +87,34 @@ module ExcADG
                                       .collect { |state, vertices| [state, vertices_stats(vertices)] }
                                       .to_h
         # rubocop:enable Style/HashTransformValues
-        filled.collect { |k, v| format '%-10s: %s', k, "#{v.empty? ? '<none>' : v}" }
+        filled.collect { |k, v| format '  %-10s: %s', k, "#{v.empty? ? '<none>' : v}" }
       end
 
       def vertices_stats vertice_pairs
-        full_list = vertice_pairs.collect(&:name)
-        addition = full_list.size > MAX_VERTEX_TO_SHOW ? "... and #{full_list.size - MAX_VERTEX_TO_SHOW} more" : ''
-        full_list[0...MAX_VERTEX_TO_SHOW].join(', ') + addition
+        vertice_pairs.collect(&:name).join(', ')
+      end
+
+      # make ASCII drawing of a graph
+      def tracked_graph g, r
+        reversed_graph = g # Broker.vtracker.graph.reverse
+        # Broker.vtracker.by_state[:ready].collect { |ready_vertex|
+        items = r.collect { |ready_vertex|
+          # deps = g.adjacent_vertices ready_vertex
+          # parents = reversed_graph.adjacent_vertices ready_vertex
+          [ready_vertex.name.to_s, ready_vertex.state.to_s]
+        }
+        items[1] << 'asd'
+        items[1] << 'dsa'
+        Block.row(
+          Block.column(
+            Block.row(*items) { |blk| blk.v_align!(:right).box!.h_pad!(3) },
+            ['x' * 70],
+            align: :centre
+          ),
+          Block.column(*Array.new(20, 'Y')),
+          align: :bottom
+        ).array
+        # TODO: add a row below the current row
       end
     end
   end

data/lib/excadg/vtracker.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'rgl/adjacency'
+
+module ExcADG
+  # tracker for {Vertex}-es graph:
+  # it's hooked by {Broker} to register dependencies polling events
+  # and make an actual graph of vertices with states in runtime
+  #
+  # it's not possible to do this in other way, because vertices can be spawned:
+  # - in any order => code is not guaranteed to know the full graph (even static one)
+  # - dynamically => there is no central place but {Broker} that's aware of all vertices
+  class VTracker
+    attr_reader :graph, :by_state
+
+    def initialize
+      @graph = RGL::DirectedAdjacencyGraph.new
+      @by_state = {}
+    end
+
+    # register the vertex and its new known deps in the @graph and by_state cache
+    # @param vertice vertice that requested info about deps
+    # @param deps list of dependencies as supplied by {Request::GetStateData}
+    def track vertex, deps
+      Assertions.is_a? vertex, Vertex
+      Assertions.is_a? deps, Array
+
+      add_to_states_cache vertex, vertex.state
+
+      deps.each { |raw_dep|
+        # it could be not Vertex, so do a lookup through data store
+        next unless Broker.data_store[raw_dep]
+
+        dep_data = Broker.data_store[raw_dep]
+        add_to_states_cache dep_data.vertex, dep_data.state
+        @graph.add_edge vertex, dep_data.vertex
+      }
+    end
+
+    private
+
+    # adds a given {Vertex} in state to @by_state cache;
+    # makes sure to remove it from the rest of the lists;
+    # lazily initializes the cache
+    def add_to_states_cache vertex, state
+      # TODO: shouldn't we add these vertices to the graph as "unresolved" up until they appear as {Vertex}
+      return unless state
+
+      @by_state.each_value { |v| v.delete vertex }
+      @by_state[state] ||= []
+      @by_state[state] << vertex
+    end
+  end
+end

data/lib/excadg.rb

@@ -15,3 +15,4 @@ require_relative 'excadg/state_machine'
 require_relative 'excadg/tui'
 require_relative 'excadg/vertex'
 require_relative 'excadg/vstate_data'
+require_relative 'excadg/vtracker'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: excadg
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - skorobogatydmitry
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-13 00:00:00.000000000 Z
+date: 2024-07-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rgl
@@ -51,9 +51,13 @@ files:
 - lib/excadg/rtimeout.rb
 - lib/excadg/state_machine.rb
 - lib/excadg/tui.rb
+- lib/excadg/tui/assets.rb
+- lib/excadg/tui/block.rb
+- lib/excadg/tui/format.rb
 - lib/excadg/vertex.rb
 - lib/excadg/vstate_data.rb
 - lib/excadg/vtimeout.rb
+- lib/excadg/vtracker.rb
 homepage: https://github.com/skorobogatydmitry/excadg
 licenses:
 - LGPL-3.0-only