neo4j_bolt 0.4.1 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c587989e6936680692675035dada5d220122cc81655f2607b97e72b4725b23b
-  data.tar.gz: 6bedef9539b66644474e2d657b1e4454918a7bfe4a7db73cdfc626fb9b150426
+  metadata.gz: 38ed2e6727f1bc4baccc838b195d72a2392bbb82788598d704a1e81bd0f20de0
+  data.tar.gz: d781a67c3eee09dd9e32a9af60fe1fb65a61bb8afddb96307dd897cbcd99ddf1
 SHA512:
-  metadata.gz: 9640636068e101464e9a92e0ca38e465bc3c847863b457d90ae3e5361c37960359e7fd9c24ec8915f1ad27f90311b0867b95973801e28a17939f2bf70b3bad75
-  data.tar.gz: ed3142cd503626d3ba4d04ea86a708426178a070513c14325e46bac405bfa384250f8978d12cf6eb72920bb35ec7170cbb3ecd90500de121f6c650279387313e
+  metadata.gz: e1d4c318c5adb68878da6368dc8d694a63c79cc953ab0e87ffe5aceaf77ce9d47d06b35a80cef8ea835ac90e6753974a59c2bb2bd9088f144fdf8761976b9b8a
+  data.tar.gz: d28fd8341cbbfe89391c7685331ed8fc666864edb7222f8ccb3530ddd3e93b2bad68d9fa6ebdf75049cad99c8d68926b356e3b55fadcb795e017dfc0be9d0f22

data/README.md

@@ -157,7 +157,14 @@ File.open("database.dump", "r") do |io|
 end
 ```
 
-Passing `progress_io:` is optional for the Ruby API. The CLI always reports dump/load progress on stderr, so dump data written to stdout remains safe to redirect or pipe. Terminal progress is updated in place; redirected stderr receives periodic progress lines.
+Passing `progress_io:` is optional for the Ruby API. The CLI always reports dump/load progress on stderr, so dump data written to stdout remains safe to redirect or pipe. In `auto` mode a terminal gets a colored, in-place progress bar while redirected stderr receives periodic plain-text progress lines. Set `NEO4J_BOLT_PROGRESS=pretty` to force the terminal display through a container or other wrapper that hides the TTY, or `NEO4J_BOLT_PROGRESS=plain` to force log-friendly output. `NO_COLOR` disables colors without disabling the in-place display.
+
+Both `dump` and `load` accept `--color COLOR` to choose the spinner and filled progress-bar accent. The default is `cyan`. The Ruby API exposes the same setting as `progress_color:`. Available colors are `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, `white`, `bright-red`, `bright-green`, `bright-yellow`, `bright-blue`, `bright-magenta`, `bright-cyan`, and `bright-white`.
+
+```bash
+neo4j_bolt dump --color magenta -o database.dump
+neo4j_bolt load --color bright-blue database.dump
+```
 
 The `0, 1, 2, ...` IDs are synthetic dump-local IDs. Database-internal IDs and element IDs are never written to the persistent format. Dumping keeps the count, node, and relationship reads in one transaction, so the driver-provided entity identity used to connect the two streamed result sets stays within Neo4j's transaction-scoped identity guarantee. To keep dump numbering deterministic, ordering uses `elementId()` on modern Neo4j and an internal `id()` fallback only on Neo4j 4.4, where `elementId()` does not exist. Old Neo4jBolt dumps remain loadable.
 
@@ -175,8 +182,8 @@ The `neo4j_bolt` executable retains these commands:
 | --- | --- |
 | `neo4j_bolt console` | Open an IRB console with Neo4jBolt loaded |
 | `neo4j_bolt clear --srsly` | Delete all nodes and relationships |
-| `neo4j_bolt dump` | Write the textual database dump |
-| `neo4j_bolt load [--force] [--batch-size N] PATH` | Load a textual dump |
+| `neo4j_bolt dump [--color COLOR]` | Write the textual database dump |
+| `neo4j_bolt load [--force] [--batch-size N] [--color COLOR] PATH` | Load a textual dump |
 | `neo4j_bolt index ls` | List constraints and indexes |
 | `neo4j_bolt index rm --force` | Remove all constraints and indexes |
 | `neo4j_bolt visualize` | Generate a GraphViz document |

data/bin/neo4j_bolt

@@ -47,9 +47,10 @@ class App
     long_desc 'Dump all nodes and relationships.'
     command :dump do |c|
         c.flag [:o, 'out-file'.to_sym], :default_value => '/dev/stdout'
+        c.flag [:color], :default_value => 'cyan', :desc => 'progress accent color'
         c.action do |global_options, options|
             File.open(options['out-file'.to_sym], 'w') do |f|
-                dump_database(f, progress_io: $stderr)
+                dump_database(f, progress_io: $stderr, progress_color: options[:color])
             end
         end
     end
@@ -63,6 +64,7 @@ class App
         c.switch [:f, :force], :default_value => false, :desc => 'force appending nodes even if the database is not empty'
         c.flag [:b, 'batch-size'.to_sym], :default_value => Neo4jBolt::LOAD_INITIAL_BATCH_SIZE,
                :desc => 'initial batch size; automatically reduced on transaction-memory errors'
+        c.flag [:color], :default_value => 'cyan', :desc => 'progress accent color'
         c.action do |global_options, options, args|
             help_now!('input path is required') if args.empty?
             path = args.shift
@@ -71,6 +73,7 @@ class App
                     f,
                     force_append: options[:force],
                     progress_io: $stderr,
+                    progress_color: options[:color],
                     initial_batch_size: options['batch-size'.to_sym]
                 )
             end

data/lib/neo4j_bolt/version.rb

@@ -1,3 +1,3 @@
 module Neo4jBolt
-    VERSION = "0.4.1"
+    VERSION = "0.4.3"
 end

data/lib/neo4j_bolt.rb

@@ -23,70 +23,207 @@ module Neo4jBolt
 
   class ProgressReporter
     UPDATE_INTERVAL = 0.5
-
-    def initialize(io)
+    BAR_WIDTH = 24
+    SPINNER = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+    ANSI = {
+      reset: "\e[0m",
+      bold: "\e[1m",
+      dim: "\e[2m",
+      red: "\e[31m",
+      green: "\e[32m",
+      yellow: "\e[33m",
+      blue: "\e[34m",
+      magenta: "\e[35m",
+      cyan: "\e[36m",
+      white: "\e[37m",
+      bright_red: "\e[91m",
+      bright_green: "\e[92m",
+      bright_yellow: "\e[93m",
+      bright_blue: "\e[94m",
+      bright_magenta: "\e[95m",
+      bright_cyan: "\e[96m",
+      bright_white: "\e[97m"
+    }.freeze
+    ACCENT_STYLES = {
+      "red" => :red, "green" => :green, "yellow" => :yellow, "blue" => :blue,
+      "magenta" => :magenta, "cyan" => :cyan, "white" => :white,
+      "bright-red" => :bright_red, "bright-green" => :bright_green,
+      "bright-yellow" => :bright_yellow, "bright-blue" => :bright_blue,
+      "bright-magenta" => :bright_magenta, "bright-cyan" => :bright_cyan,
+      "bright-white" => :bright_white
+    }.freeze
+
+    def initialize(io, color: "cyan")
       @io = io
-      @tty = io && io.respond_to?(:tty?) && io.tty? && Neo4jBolt.bolt_verbosity.to_i.zero?
+      @accent_style = ACCENT_STYLES.fetch(color.to_s) do
+        raise ArgumentError, "progress color must be one of: #{ACCENT_STYLES.keys.join(', ')}"
+      end
+      mode = ENV.fetch("NEO4J_BOLT_PROGRESS", "auto")
+      unless %w[auto pretty plain].include?(mode)
+        raise ArgumentError, "NEO4J_BOLT_PROGRESS must be auto, pretty, or plain"
+      end
+
+      detected_tty = io && io.respond_to?(:tty?) && io.tty? && Neo4jBolt.bolt_verbosity.to_i.zero?
+      @pretty = io && (mode == "pretty" || (mode == "auto" && detected_tty))
+      @color = @pretty && !ENV.key?("NO_COLOR") && (mode == "pretty" || ENV["TERM"] != "dumb")
       @last_update_at = nil
-      @line_width = 0
       @line_open = false
+      @spinner_index = 0
     end
 
-    def update(message, force: false)
+    def update(message, force: false, percent: nil)
       return unless @io
 
       now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       return if !force && @last_update_at && now - @last_update_at < UPDATE_INTERVAL
 
-      if @tty
-        padding = [@line_width - message.length, 0].max
-        @io.print "\r#{message}#{' ' * padding}"
-        @io.flush
-        @line_width = [@line_width, message.length].max
-        @line_open = true
+      if @pretty
+        percent ||= extract_percent(message)
+        render_line(activity_line(message, percent))
       else
         @io.puts message
       end
       @last_update_at = now
     end
 
-    def note(message)
+    def note(message, level: :info)
       return unless @io
 
-      clear_tty_line
-      @io.puts message
-      @last_update_at = nil
+      if @pretty && level == :info
+        update(message, force: true)
+      else
+        clear_line
+        if @pretty
+          icon = level == :warning ? color(:yellow, "!") : color(:cyan, "•")
+          @io.puts "#{icon} #{terminal_text(message)}"
+        else
+          @io.puts message
+        end
+        @last_update_at = nil
+      end
     end
 
     def finish(message)
       return unless @io
 
-      update(message, force: true)
-      if @tty
-        @io.puts
-        @line_width = 0
+      if @pretty
+        clear_line
+        label, detail = terminal_parts(message)
+        line = "#{color(:green, '✓')} #{color(:bold, label)}"
+        line += "  #{detail}" unless detail.empty?
+        @io.puts line
         @line_open = false
+      else
+        @io.puts message
       end
+      @last_update_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
     def close
-      return unless @io && @tty && @line_open
+      return unless @io && @pretty && @line_open
 
-      @io.puts
-      @line_width = 0
-      @line_open = false
+      clear_line
     end
 
     private
 
-    def clear_tty_line
-      return unless @tty && @line_open
+    def activity_line(message, percent)
+      label, detail = terminal_parts(message, strip_percent: !percent.nil?)
+      spinner = SPINNER[@spinner_index % SPINNER.length]
+      @spinner_index += 1
+
+      parts = [color(@accent_style, spinner), color(:bold, label)]
+      if percent
+        percent = [[percent.to_i, 0].max, 100].min
+        parts << progress_bar(percent)
+        parts << color(:bold, format("%3d%%", percent))
+      end
+      parts << detail unless detail.empty?
+      parts.join("  ")
+    end
+
+    def progress_bar(percent)
+      filled = (percent * BAR_WIDTH / 100.0).round
+      empty = BAR_WIDTH - filled
+      "#{color(@accent_style, '━' * filled)}#{color(:dim, '─' * empty)}"
+    end
+
+    def terminal_parts(message, strip_percent: false)
+      text = message.sub(/\.\.\.\z/, "")
+      label, detail = text.split(": ", 2)
+      label = pretty_label(label)
+      detail ||= ""
+      if strip_percent
+        detail = detail.sub(/\s+\(\d+%\)/, "")
+        detail = "" if detail.match?(/\A\d+%\z/)
+      end
+      detail = detail.gsub(/ \[batch (\d+)\]/) do
+        " #{color(:dim, '·')} batch #{format_count(Regexp.last_match(1))}"
+      end
+      detail = format_counts(detail)
+      detail = detail.gsub(", ", " #{color(:dim, '·')} ")
+      [label, detail]
+    end
+
+    def terminal_text(message)
+      label, detail = terminal_parts(message)
+      detail.empty? ? format_counts(label) : "#{label}: #{detail}"
+    end
+
+    def pretty_label(label)
+      case label
+      when "Building temporary relationship lookup index"
+        "Building lookup index"
+      when "Temporary relationship lookup index ready."
+        "Lookup index ready"
+      when "Cleaning temporary load metadata"
+        "Cleaning load metadata"
+      when "Temporary load metadata removed."
+        "Load metadata removed"
+      else
+        label
+      end
+    end
+
+    def extract_percent(message)
+      if (match = message.match(/\((\d+)%\)/)) || (match = message.match(/:\s*(\d+)%\z/))
+        return match[1].to_i
+      end
+
+      match = message.match(/:\s*(\d+)\/(\d+) nodes\z/)
+      return nil unless match
+
+      total = match[2].to_i
+      total.zero? ? 100 : match[1].to_i * 100 / total
+    end
+
+    def format_counts(text)
+      text.gsub(/\b\d{4,}\b/) { |number| format_count(number) }
+    end
 
-      @io.print "\r#{' ' * @line_width}\r"
+    def format_count(number)
+      number.to_s.reverse.scan(/.{1,3}/).join(",").reverse
+    end
+
+    def render_line(line)
+      @io.print "\r\e[2K#{line}"
+      @io.flush
+      @line_open = true
+    end
+
+    def clear_line
+      return unless @pretty && @line_open
+
+      @io.print "\r\e[2K"
       @io.flush
-      @line_width = 0
       @line_open = false
     end
+
+    def color(style, text)
+      return text unless @color
+
+      "#{ANSI.fetch(style)}#{text}#{ANSI[:reset]}"
+    end
   end
   private_constant :ProgressReporter
   MIN_INTEGER = -(2**63)
@@ -399,8 +536,8 @@ module Neo4jBolt
     nil
   end
 
-  def dump_database(io, progress_io: nil)
-    progress = ProgressReporter.new(progress_io)
+  def dump_database(io, progress_io: nil, progress_color: "cyan")
+    progress = ProgressReporter.new(progress_io, color: progress_color)
     dumped_nodes = 0
     dumped_relationships = 0
 
@@ -459,7 +596,7 @@ module Neo4jBolt
     progress&.close
   end
 
-  def load_database_dump(io, force_append: false, progress_io: nil,
+  def load_database_dump(io, force_append: false, progress_io: nil, progress_color: "cyan",
                          initial_batch_size: LOAD_INITIAL_BATCH_SIZE)
     raise Error, "load_database_dump cannot run inside a transaction" if transaction_context
 
@@ -471,7 +608,7 @@ module Neo4jBolt
       raise Error, "There are nodes in this database, exiting now." unless count.zero?
     end
 
-    progress = ProgressReporter.new(progress_io)
+    progress = ProgressReporter.new(progress_io, color: progress_color)
     node_batches = Hash.new { |hash, key| hash[key] = [] }
     relationship_batches = Hash.new { |hash, key| hash[key] = [] }
     total_nodes, total_relationships = parse_dump(io, node_batches, relationship_batches, progress)
@@ -767,7 +904,8 @@ module Neo4jBolt
         batch_size = [batch_size, reduced_batch_size].min
         progress&.note(
           "Neo4j rejected a #{kind} batch of #{slice.size} for transaction memory; " \
-          "retrying with batches of #{batch_size}."
+          "retrying with batches of #{batch_size}.",
+          level: :warning
         )
       end
     end
@@ -822,7 +960,8 @@ module Neo4jBolt
 
         batch_size = [batch_size / 2, 1].max
         progress&.note(
-          "Neo4j rejected a cleanup batch for transaction memory; retrying with batches of #{batch_size}."
+          "Neo4j rejected a cleanup batch for transaction memory; retrying with batches of #{batch_size}.",
+          level: :warning
         )
       end
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: neo4j_bolt
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.3
 platform: ruby
 authors:
 - Michael Specht