appear 1.1.1 → 1.2.0

data/lib/appear/lsof.rb

@@ -1,6 +1,12 @@
 require 'appear/service'
+require 'appear/util/memoizer'
+require 'appear/util/value_class'
 
 module Appear
+  # raised if we can't parse a connection from an output line of the `lsof`
+  # command.
+  class LsofParseError < Appear::Error; end
+
   # The LSOF service co-ordinates access to the `lsof` system utility.  LSOF
   # stands for "list open files". It can read the "connections" various
   # programs have to a given file, eg, what programs have a file descriptor for
@@ -12,18 +18,46 @@ module Appear
 
     # A connection of a process to a file.
     # Created from one output row of `lsof`.
-    class Connection
-      attr_accessor :command_name, :pid, :user, :fd, :type, :device, :size, :node, :name, :file_name
-      def initialize(hash)
-        hash.each do |key, value|
-          send("#{key}=", value)
-        end
-      end
+    class Connection < ::Appear::Util::ValueClass
+      # @return [String]
+      property :command_name
+
+      # @return [Fixnum]
+      property :pid
+
+      # @return [String]
+      property :fd
+
+      # @return [String]
+      property :fd
+
+      # @return [String]
+      property :type
+
+      # @return [String]
+      property :device
+
+      # @return [String]
+      property :size
+
+      # @return [String]
+      property :node
+
+      # @return [String]
+      property :file_name
     end
 
     # Represents a pane's connection to a TTY.
     class PaneConnection
-      attr_reader :pane, :connection, :process
+      # @return [#tty] a Terminal emulator pane.
+      attr_reader :pane
+
+      # @return [Connection] an LSOF connection
+      attr_reader :connection
+
+      # @return [Appear::Processes::ProcessInfo] the process
+      attr_reader :process
+
       # @param pane [#tty] a pane in a terminal emulator
       # @param connection [Appear::Lsof::Connection] a connection of a process
       #   to a file -- usually a TTY device.
@@ -34,10 +68,12 @@ module Appear
         @process = process
       end
 
+      # @return [String] the TTY this connection is to
       def tty
         connection.file_name
       end
 
+      # @return [Fixnum] pid of the process making the connection
       def pid
         connection.pid
       end
@@ -45,7 +81,7 @@ module Appear
 
     def initialize(*args)
       super(*args)
-      @cache = {}
+      @lsof_memo = Util::Memoizer.new
     end
 
     # find any intersections where a process in the given tree is present in
@@ -87,63 +123,60 @@ module Appear
       hits.values
     end
 
-    # list connections to files
+    # list connections to files.
     #
     # @param files [Array<String>] files to query
     # @return [Hash<String, Array<Connection>>] map of filename to connections
     def lsofs(files, opts = {})
-      cached = files.select { |f| @cache[f] }
-      uncached = files.reject { |f| @cache[f] }
-
-      result = parallel_lsof(uncached, opts)
-      result.each do |file, data|
-        @cache[file] = data
-      end
-
-      cached.each do |f|
-        result[f] = @cache[f]
-      end
-
-      result
-    end
-
-    private
-
-    # lsof takes a really long time, so parallelize lookups when you can.
-    def parallel_lsof(files, opts = {})
+      mutex = Mutex.new
       results = {}
       threads = files.map do |file|
         Thread.new do
-          results[file] = lsof(file, opts)
+          single_result = lsof(file, opts)
+          mutex.synchronize do
+            results[file] = single_result
+          end
         end
       end
       threads.each { |t| t.join }
       results
     end
 
+    private
+
     def lsof(file, opts = {})
-      pids = opts[:pids]
-      if pids
-        output = run(['lsof', '-ap', pids.join(','), file])
-      else
-        output = run("lsof #{file.shellescape}")
-      end
-      rows = output.lines.map do |line|
-        command, pid, user, fd, type, device, size, node, name = line.strip.split(/\s+/)
-        Connection.new({
-          command_name: command,
-          pid: pid.to_i,
-          user: user,
-          fd: fd,
-          type: type,
-          device: device,
-          size: size,
-          node: node,
-          file_name: name
-        })
+      @lsof_memo.call(file, opts) do
+        pids = opts[:pids]
+        if pids
+          output = run(['lsof', '-ap', pids.join(','), file], :allow_failure => true)
+        else
+          output = run(['lsof', file], :allow_failure => true)
+        end
+        next [] if output.empty?
+        rows = output.lines.map do |line|
+          line = line.strip
+          fields = line.split(/\s+/)
+          if fields.length < 9
+            raise LsofParseError.new("Not enough fields in line #{line.inspect}")
+          end
+          command, pid, user, fd, type, device, size, node, name = fields
+          Connection.new({
+            command_name: command,
+            pid: pid.to_i,
+            user: user,
+            fd: fd,
+            type: type,
+            device: device,
+            size: size,
+            node: node.to_i,
+            file_name: name
+          })
+        end
+        # drop header row
+        rows[1..-1]
       end
-      rows[1..-1]
-    rescue Appear::ExecutionFailure
+    rescue LsofParseError => err
+      log("lsof: parse error: #{err}")
       []
     end
   end

data/lib/appear/mac_os.rb

@@ -4,6 +4,7 @@ require 'appear/constants'
 require 'appear/service'
 
 module Appear
+  # Raised if our helper program returns an error.
   class MacToolError < Error
     def initialize(message, stack)
       super("Mac error #{message.inspect}\n#{stack}")
@@ -19,6 +20,10 @@ module Appear
     SCRIPT = Appear::TOOLS_DIR.join('macOS-helper.js').realpath.to_s
 
     # call a method in our helper script. Communicates with JSON!
+    # @param method_name [String, Symbol] check the source of macOS-helper.js for method names.
+    # @param data [Any, nil] json-able data to pass to the named method.
+    # @return [Any] json data returned from the helper
+    # @raise [MacToolError] if an error occured
     def call_method(method_name, data = nil)
       command = [SCRIPT, method_name.to_s]
       command << data.to_json unless data.nil?
@@ -32,8 +37,13 @@ module Appear
       end
     end
 
-    # TODO: ask Applescript if this a GUI application instead of just looking
-    # at the path
+    # Return true if the given process is a macOS GUI process, false otherwise.
+    #
+    # @todo: ask Applescript if this a GUI application instead of just looking
+    #   at the path
+    #
+    # @param process [Appear::Processes::ProcessInfo]
+    # @return [Boolean]
     def has_gui?(process)
       executable = process.command.first
       executable =~ /\.app\/Contents\//

data/lib/appear/output.rb

@@ -5,16 +5,29 @@ module Appear
   # The Output service encapsulates writing logging information to log files
   # and STDERR, and writing output to STDOUT.
   class Output
+    # Create a new Output service.
+    #
+    # @param log_file_name [String, nil] if a string, log to the file at this path
+    # @param silent [Boolean] if true, output to STDERR
     def initialize(log_file_name, silent)
+      @file_logger = nil
+      @stderr_logger = nil
+
       @file_logger = Logger.new(log_file_name.to_s) if log_file_name
       @stderr_logger = Logger.new(STDERR) unless silent
     end
 
+    # Log a message.
+    #
+    # @param any [Array<Any>]
     def log(*any)
       @stderr_logger.debug(*any) if @stderr_logger
       @file_logger.debug(*any) if @file_logger
     end
 
+    # Log an error
+    #
+    # @param err [Error]
     def log_error(err)
       log("Error #{err.inspect}: #{err.to_s.inspect}")
       if err.backtrace
@@ -22,6 +35,9 @@ module Appear
       end
     end
 
+    # Output a message to STDOUT, and also to the log file.
+    #
+    # @param any [Array<Any>]
     def output(*any)
       STDOUT.puts(*any)
       @file_logger.debug(*any) if @file_logger

data/lib/appear/processes.rb

@@ -1,5 +1,6 @@
 require 'appear/constants'
 require 'appear/service'
+require 'appear/util/memoizer'
 
 module Appear
   # Raised if Processes tries to get info for a dead process, or a PID that is
@@ -24,7 +25,7 @@ module Appear
 
     def initialize(*args)
       super(*args)
-      @cache = {}
+      @get_info_memo = Util::Memoizer.new
     end
 
     # Get info about a process by PID, including its command and parent_pid.
@@ -32,12 +33,9 @@ module Appear
     # @param pid [Integer]
     # @return [ProcessInfo]
     def get_info(pid)
-      result = @cache[pid]
-      unless result
-        result = fetch_info(pid)
-        @cache[pid] = result
+      @get_info_memo.call(pid) do
+        fetch_info(pid)
       end
-      result
     end
 
     # Is the given process alive?

data/lib/appear/revealers.rb

@@ -1,5 +1,7 @@
 require 'appear/service'
-require 'appear/join'
+require 'appear/util/join'
+require 'appear/terminal'
+require 'ostruct'
 
 module Appear
   # stores all the ways we can appear something
@@ -11,6 +13,11 @@ module Appear
   module Revealers
     # extend to implement more revealers
     class BaseRevealer < Service
+      # Reveal `tree` if supported by this revealer. You can get a tree from
+      # {Processes#process_tree}.
+      #
+      # @param tree [Array<Processes::ProcessInfo>]
+      # @return [true, nil] return true if we revealed something, otherwise nil
       def call(tree)
         target, *rest = tree
         if supports_tree?(target, rest)
@@ -18,98 +25,82 @@ module Appear
         end
       end
 
-      # TODO
+      # Reveal `tree`. Should be implemented by subclasses.
+      #
+      # @abstract subclasses must implement this method.
+      # @param tree [Array<Processes::ProcessInfo>]
+      # @return [true, nil] return true if we revealed something, otherwise nil
       def reveal_tree(tree)
         raise "not implemented"
       end
 
-      # appear the first process in this process tree.
-      # should return nil if no action was performed.
-      # otherwise, return true.
+      # Returns true if this revealer may be able to reveal something in the
+      # tree. For this method, the caller splits the tree into the target and
+      # the rest of the tree, which sometimes simplifies the implementation of
+      # this method.
+      #
+      # @abstract subclasses must implement this method.
+      # @param target [Processes::ProcessInfo] bottom (child-most) item in the process
+      #   tree
+      # @param rest [Array<Processes::ProcessInfo>] the rest of the tree
+      # @return [Boolean]
       def supports_tree?(target, rest)
         raise "not implemented"
       end
 
+      # Register this class as a revealer so it will be called by
+      # {Instance#call}
       def self.register!
         Appear::REVEALERS.push(self)
       end
     end
 
+    # Base class for Mac-terminal revealers.
     class MacRevealer < BaseRevealer
-      delegate :join_via_tty, :lsof
       require_service :mac_os
+      require_service :mac_term
+      require_service :lsof
 
-      def panes
-        raise "not implemented"
-      end
-
-      def reveal_hit(hit)
-        raise "not implemented"
-      end
-
+      # Implementation.
+      # @see BaseRevealer#reveal_tree
       def reveal_tree(tree)
-        hits = join_via_tty(tree, panes)
+        hits = services.lsof.join_via_tty(tree, services.mac_term.panes)
         actual_hits = hits.uniq {|hit| hit.tty }.
           reject {|hit| services.mac_os.has_gui?(hit.process) }.
-          each { |hit| reveal_hit(hit) }
+          each { |hit| services.mac_term.reveal_pane(hit) }
 
         return actual_hits.length > 0
       end
 
-      # TODO: read the bundle identifier somehow, but this is close enough.
-      # or get the bundle identifier and enhance the process lists with it?
-      def has_gui_app_named?(tree, name)
-        tree.any? do |process|
-          process.name == name && services.mac_os.has_gui?(process)
+      # Implementation
+      # @see BaseRevealer#supports_tree?
+      def supports_tree?(target, rest)
+        rest.any? do |process|
+          process.name == services.mac_term.app_name && services.mac_os.has_gui?(process)
         end
       end
     end
 
+    # Iterm2 revealer support
     class Iterm2 < MacRevealer
-      require_service :processes
-
-      def supports_tree?(target, rest)
-        has_gui_app_named?(rest, 'iTerm2')
-      end
-
-      def panes
-        pids = services.processes.pgrep('iTerm2')
-        services.mac_os.call_method('iterm2_panes').map do |hash|
-          hash[:pids] = pids
-          OpenStruct.new(hash)
-        end
-      end
-
-      def reveal_hit(hit)
-        services.mac_os.call_method('iterm2_reveal_tty', hit.tty)
+      def initialize(services)
+        super(services.merge(
+          :mac_term => Appear::Terminal::Iterm2.new(services)
+        ))
       end
     end
 
+    # TerminalApp revealer support
     class TerminalApp < MacRevealer
-      require_service :processes
-
-      def supports_tree?(target, rest)
-        has_gui_app_named?(rest, 'Terminal')
-      end
-
-      def panes
-        pids = services.processes.pgrep('Terminal.app')
-        services.mac_os.call_method('terminal_panes').map do |hash|
-          hash[:pids] = pids
-          OpenStruct.new(hash)
-        end
-      end
-
-      def reveal_hit(hit)
-        # iterm2 runs a non-gui server process. Because of implementation
-        # details of MacOs#has_gui?, we don't *techinically* have to worry
-        # about this, but we should in case I ever implement real mac
-        # gui-or-not lookup.
-        return if hit.process.name == 'iTerm2'
-        services.mac_os.call_method('terminal_reveal_tty', hit.tty)
+      def initialize(services)
+        super(services.merge(
+          :mac_term => Appear::Terminal::TerminalApp.new(services)
+        ))
       end
     end
 
+    # support for the cross-platform Tmux multiplexer. Also reveals a connected
+    # tmux client, if possible.
     class Tmux < BaseRevealer
       # TODO: cache services.tmux.panes, services.tmux.clients for this revealer?
       require_service :tmux
@@ -117,12 +108,16 @@ module Appear
       require_service :revealer
       require_service :processes
 
+      # Implementation
+      # @see BaseRevealer#supports_tree?
       def supports_tree?(target, rest)
         rest.any? { |p| p.name == 'tmux' }
       end
 
+      # Implementation.
+      # @see BaseRevealer#reveal_tree
       def reveal_tree(tree)
-        relevent_panes = Join.join(:pid, tree, services.tmux.panes)
+        relevent_panes = Util::Join.join(:pid, tree, services.tmux.panes)
         relevent_panes.each do |pane|
           log("#{self.class.name}: revealing pane #{pane}")
           services.tmux.reveal_pane(pane)
@@ -141,17 +136,21 @@ module Appear
       # to find the PID of a tmux client is to lsof() the TTY that the client
       # is connected to, and then deduce the client PID, which will be a tmux
       # process PID that is not the server PID.
+      #
+      # @param tree [Array<Processes::ProcessInfo>]
+      # @return [Number, nil] pid of a tmux client, if one was found. Otherwise
+      #   nil.
       def tmux_client_for_tree(tree)
         tmux_server = tree.find {|p| p.name == 'tmux'}
 
         # join processes on tmux panes by PID.
-        proc_and_panes = Join.join(:pid, services.tmux.panes, tree)
+        proc_and_panes = Util::Join.join(:pid, services.tmux.panes, tree)
 
         # Join the list of tmux clients with process_and_pid on :session.
         # In tmux, every pane is addressed by session_name:window_index:pane_index.
         # This gives us back a list of all the clients that have a pane that
         # contains a process in our given process tree.
-        proc_and_clients = Join.join(:session, services.tmux.clients, proc_and_panes)
+        proc_and_clients = Util::Join.join(:session, services.tmux.clients, proc_and_panes)
 
         # there *should* be only one of these, unless there are two clients
         # connected to the same tmux session. In that case we just choose one
@@ -167,11 +166,15 @@ module Appear
           [tty_of_client],
           :pids => services.processes.pgrep('tmux')
         )[tty_of_client]
+
         client_connection = connections_to_tty.find do |conn|
           (conn.command_name =~ /^tmux/) && (conn.pid != tmux_server.pid)
         end
 
-        client_connection.pid if client_connection
+        if client_connection
+          log("tmux_client_for_tree: found client pid=#{client_connection.pid} for tree pid=#{tree.first.pid}")
+          return client_connection.pid
+        end
       end
     end
 

data/lib/appear/runner.rb

@@ -21,8 +21,17 @@ module Appear
     # either be a string, or an array of command name and parameters.
     # Returns the combinded STDERR and STDOUT of the command.
     #
-    # @return String
-    def run(command)
+    # @param command [String, Array] command to run, as an argv array, or as a
+    #   sh command string.
+    # @param opts [Hash] options
+    # @option opts [Boolean] :allow_failure (false) permit running the command
+    #   to fail. Do not raise an ExecutionFailure error.
+    #
+    # @raise [ExecutionFailure] if the command exists non-zero
+    #
+    # @return [String]
+    def run(command, opts = {})
+      allow_failure = opts[:allow_failure] || false
       start = Time.new
       if command.is_a? Array
         output, status = Open3.capture2e(*command)
@@ -31,14 +40,20 @@ module Appear
       end
       finish = Time.new
       log("Runner: ran #{command.inspect} in #{finish - start}s")
-      raise ExecutionFailure.new(command, output) unless status.success?
+      if !status.success? && !allow_failure
+        raise ExecutionFailure.new(command, output)
+      end
       output
     end
   end
 
   # Records every command run to a directory; intended to be useful for later integration tests.
   class RunnerRecorder < Runner
+    # The location to write recorded runs to. Currently hard-coded to a
+    # location inside the gem's spec folder.
     OUTPUT_DIR = MODULE_DIR.join('spec/command_output')
+
+    # the time that this class file was loaded at
     INIT_AT = Time.new
 
     def initialize(*args)
@@ -46,14 +61,19 @@ module Appear
       @command_runs = Hash.new { |h, k| h[k] = [] }
     end
 
-    def run(command)
+    # @see Runner#run
+    def run(command, opts = {})
       begin
         result = super(command)
         record_success(command, result)
         return result
       rescue ExecutionFailure => err
         record_error(command, err)
-        raise err
+        if opts[:allow_failure]
+          return err.output
+        else
+          raise err
+        end
       end
     end