appear 1.0.0

data/lib/appear/config.rb

@@ -0,0 +1,24 @@
+module Appear
+  # all the adjustable options for a Appear::Instance
+  class Config
+    # if set, the Appear::Instance will log debug information to this file.
+    # @return [String, nil] default nil
+    attr_accessor :log_file
+
+    # if false, the Appear::Instance will log debug information to STDERR.
+    # @return [Boolean] default true
+    attr_accessor :silent
+
+    # Record everything executed by Runner service to spec/command_output.
+    # Intended for generating test cases.
+    #
+    # @return [Boolean] default false
+    attr_accessor :record_runs
+
+    # sets defaults
+    def initialize
+      self.silent = true
+      self.record_runs = false
+    end
+  end
+end

data/lib/appear/constants.rb

@@ -0,0 +1,17 @@
+require 'pathname'
+
+module Appear
+  VERSION = '1.0.0'
+
+  # root error for our library; all other errors inherit from this one.
+  class Error < StandardError; end
+
+  # we also put common constants in here because it's a good spot.
+  # Should we rename this file to 'appear/constants' ?
+
+  # the root of the Appear project directory
+  MODULE_DIR = Pathname.new(__FILE__).realpath.join('../../..')
+
+  # where we look for os-specific helper files
+  TOOLS_DIR = MODULE_DIR.join('tools')
+end

data/lib/appear/instance.rb

@@ -0,0 +1,54 @@
+require 'logger'
+require 'appear/constants'
+require 'appear/service'
+
+require 'appear/output'
+require 'appear/processes'
+require 'appear/runner'
+require 'appear/lsof'
+require 'appear/mac_os'
+require 'appear/tmux'
+require 'appear/revealers'
+
+module Appear
+  class CannotRevealError < Error; end
+  class NoGuiError < CannotRevealError; end
+
+  # Instance is the main class in Appear. It constructs all the other services
+  # and co-ordinates the actual revealing process.
+  class Instance < Service
+    delegate :process_tree, :processes
+
+    def initialize(config)
+      @config = config
+
+      # provide a reference to this revealer instance so that sub-revealers can
+      # appear other process trees, if needed. Our Tmux revealer uses this
+      # service to appear the tmux client.
+      @all_services = { :revealer => self }
+
+      # instantiate all our various services
+      @all_services[:output] = Appear::Output.new(@config.log_file, @config.silent)
+      @all_services[:runner] = Appear::Runner.new(@all_services)
+      @all_services[:runner] = Appear::RunnerRecorder.new(@all_services) if @config.record_runs
+      @all_services[:processes] = Appear::Processes.new(@all_services)
+      @all_services[:lsof] = Appear::Lsof.new(@all_services)
+      @all_services[:mac_os] = Appear::MacOs.new(@all_services)
+      @all_services[:tmux] = Appear::Tmux.new(@all_services)
+
+      # make sure we can use our processes service, and log stuff.
+      super(@all_services)
+    end
+
+    def call(pid)
+      tree = process_tree(pid)
+
+      statuses = ::Appear::REVEALERS.map do |klass|
+        revealer = klass.new(@all_services)
+        revealer.call(tree)
+      end
+
+      statuses.any? { |status| !status.nil? }
+    end
+  end
+end

data/lib/appear/join.rb

@@ -0,0 +1,100 @@
+module Appear
+  # join objects based on hash value or method value.
+  #
+  # example:
+  #
+  # ```
+  # foos = many_foos
+  # bars = many_bars
+  # foo_bars = Join.join(:common_attribute, foos, bars)
+  #
+  # # can still access all the properties on either a foo or a bar
+  # foo_bars.first.common_attribute
+  #
+  # # can access attributes by symbol, too
+  # foo_bars.first[:something_else]
+  # ```
+  #
+  # foo_bars is an array of Join instances. Reads from a foo_bar will read
+  # first from the foo, and then from the bar - this is based on the order of
+  # "tables" passed to Join.join().
+  class Join
+    # @param field [Symbol] the method or hash field name to join on.
+    # @param tables [Array<Any>] arrays of any sort of object, so long as it is
+    # either a hash, or implements the given field.
+    # @return [Array<Join>]
+    def self.join(field, *tables)
+      by_field = Hash.new { |h, k| h[k] = self.new }
+
+      tables.each do |table|
+        table.each do |row|
+          field_value = access(row, field)
+          joined = by_field[field_value]
+          joined.push!(row)
+        end
+      end
+
+      by_field.values.select do |joined|
+        joined.joined_count >= tables.length
+      end
+    end
+
+    def self.can_access?(obj, field)
+      if obj.respond_to?(field)
+        return true
+      elsif obj.respond_to?(:[])
+        return true
+      end
+      return false
+    end
+
+    def self.access(obj, field)
+      if obj.respond_to?(field)
+        obj.send(field)
+      elsif obj.respond_to?(:[])
+        obj[field]
+      else
+        raise "cannot access #{field.inspect} on #{object.inspect}"
+      end
+    end
+
+    # an instance of Join is a joined object containing all the data in all its
+    # parts. Joins are read from left to right, returning the first non-nil
+    # value encountered.
+    def initialize(*objs)
+      @objs = objs
+    end
+
+    def push!(obj, note = nil)
+      @objs << obj
+    end
+
+    def joined_count
+      @objs.length
+    end
+
+    def [](sym)
+      result = nil
+
+      @objs.each do |obj|
+        if self.class.can_access?(obj, sym)
+          result = self.class.access(obj, sym)
+        end
+        break unless result.nil?
+      end
+
+      result
+    end
+
+    def method_missing(method, *args, &block)
+      raise NoMethodError.new("Cannot access #{method.inspect}") unless respond_to?(method)
+      raise ArgumentError.new("Passed args to accessor") if args.length > 0
+      raise ArgumentError.new("Passed block to accessor") if block
+      self[method]
+    end
+
+    def respond_to?(sym, priv = false)
+      super(sym, priv) || (@objs.any? { |o| self.class.can_access?(o, sym) })
+    end
+  end
+end

data/lib/appear/lsof.rb

@@ -0,0 +1,153 @@
+require 'appear/service'
+require 'pry'
+
+module Appear
+  # 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
+  # a file.
+  class Lsof < Service
+    attr_reader :cache
+
+    delegate :run, :runner
+
+    # 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
+    end
+
+    # Represents a pane's connection to a TTY.
+    class PaneConnection
+      attr_reader :pane, :connection, :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.
+      # @param process [Appear::Processes::ProcessInfo] a process
+      def initialize(pane, connection, process)
+        @pane = pane
+        @connection = connection
+        @process = process
+      end
+
+      def tty
+        connection.file_name
+      end
+
+      def pid
+        connection.pid
+      end
+    end
+
+    def initialize(*args)
+      super(*args)
+      @cache = {}
+    end
+
+    # find any intersections where a process in the given tree is present in
+    # one of the terminal emulator panes. Performs an LSOF lookup on the TTY of
+    # each pane. Returns cases where one of the panes' ttys also have a
+    # connection from a process in the process tree.
+    #
+    # This is much faster if each pane includes a .pids method that returns an
+    # array of PIDs that could be the PID of the terminal emulator with that pane
+    #
+    # @param tree [Array<Process>]
+    # @param panes [Array<Pane>]
+    # @return [Array<PaneConnection>]
+    def join_via_tty(tree, panes)
+      hitlist = {}
+      tree.each do |process|
+        hitlist[process.pid] = process
+      end
+
+      ttys = panes.map(&:tty)
+      if panes.all? {|p| p.respond_to?(:pids) }
+        puts "using pids in join_via_tty"
+        pids = hitlist.keys + panes.map(&:pids).flatten
+        # binding.pry
+        lsofs = lsofs(ttys, :pids => pids)
+      else
+        lsofs = lsofs(ttys)
+      end
+
+      hits = {}
+      panes.each do |pane|
+        connections = lsofs[pane.tty]
+        connections.each do |conn|
+          process = hitlist[conn.pid]
+          if process
+            hits[conn.pid] = PaneConnection.new(pane, conn, process)
+          end
+        end
+      end
+
+      hits.values
+    end
+
+    # 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 = {})
+      results = {}
+      threads = files.map do |file|
+        Thread.new do
+          results[file] = lsof(file, opts)
+        end
+      end
+      threads.each { |t| t.join }
+      results
+    end
+
+    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
+        })
+      end
+      rows[1..-1]
+    rescue Appear::ExecutionFailure
+      []
+    end
+  end
+end

data/lib/appear/mac_os.rb

@@ -0,0 +1,42 @@
+require 'json'
+
+require 'appear/constants'
+require 'appear/service'
+
+module Appear
+  class MacToolError < Error
+    def initialize(message, stack)
+      super("Mac error #{message.inspect}\n#{stack}")
+    end
+  end
+
+  # The MacOs service handles macOS-specific concerns; mostly running our
+  # companion macOS helper tool.
+  class MacOs < Service
+    delegate :run, :runner
+
+    # the "realpath" part is basically an assertion that this file exists.
+    SCRIPT = Appear::TOOLS_DIR.join('macOS-helper.js').realpath.to_s
+
+    # call a method in our helper script. Communicates with JSON!
+    def call_method(method_name, data = nil)
+      command = [SCRIPT, method_name.to_s]
+      command << data.to_json unless data.nil?
+      output = run(command)
+      result = JSON.load(output.lines.last.strip)
+
+      if result["status"] == "error"
+        raise MacToolError.new(result["error"]["message"], result["error"]["stack"])
+      else
+        result["value"]
+      end
+    end
+
+    # TODO: ask Applescript if this a GUI application instead of just looking
+    # at the path
+    def has_gui?(process)
+      executable = process.command.first
+      executable =~ /\.app\/Contents\//
+    end
+  end
+end

data/lib/appear/output.rb

@@ -0,0 +1,30 @@
+require 'appear/service'
+require 'logger'
+
+module Appear
+  # The Output service encapsulates writing logging information to log files
+  # and STDERR, and writing output to STDOUT.
+  class Output
+    def initialize(log_file_name, silent)
+      @file_logger = Logger.new(log_file_name.to_s) if log_file_name
+      @stderr_logger = Logger.new(STDERR) unless silent
+    end
+
+    def log(*any)
+      @stderr_logger.debug(*any) if @stderr_logger
+      @file_logger.debug(*any) if @file_logger
+    end
+
+    def log_error(err)
+      log("Error #{err.inspect}: #{err.to_s.inspect}")
+      if err.backtrace
+        err.backtrace.each { |line| log("  " + line) }
+      end
+    end
+
+    def output(*any)
+      STDOUT.puts(*any)
+      @file_logger.debug(*any) if @file_logger
+    end
+  end
+end

data/lib/appear/processes.rb

@@ -0,0 +1,88 @@
+require 'appear/constants'
+require 'appear/service'
+
+module Appear
+  # Raised if Processes tries to get info for a dead process, or a PID that is
+  # otherwise not found.
+  class DeadProcess < Error; end
+
+  # The Processes service handles looking up information about a system
+  # process. It mostly interacts with the `ps` system utility.
+  class Processes < Service
+    delegate :run, :runner
+
+    # contains information about a process. Returned by Processes#get_info and
+    # its derivatives.
+    class ProcessInfo
+      attr_accessor :pid, :command, :name, :parent_pid
+      def initialize(hash)
+        hash.each do |key, value|
+          send("#{key}=", value)
+        end
+      end
+    end
+
+    def initialize(*args)
+      super(*args)
+      @cache = {}
+    end
+
+    # Get info about a process by PID, including its command and parent_pid.
+    #
+    # @param pid [Integer]
+    # @return [ProcessInfo]
+    def get_info(pid)
+      result = @cache[pid]
+      unless result
+        result = fetch_info(pid)
+        @cache[pid] = result
+      end
+      result
+    end
+
+    # Is the given process alive?
+    #
+    # @param pid [Integer]
+    # @return [Boolean]
+    def alive?(pid)
+      begin
+        ::Process.getpgid(pid)
+        true
+      rescue Errno::ESRCH
+        false
+      end
+    end
+
+    # look up all the processes between the given pid and PID 1
+    # @param pid [Number]
+    # @return [Array<ProcessInfo>]
+    def process_tree(pid)
+      tree = [ get_info(pid) ]
+      while tree.last.pid > 1 && tree.last.parent_pid != 0
+        tree << get_info(tree.last.parent_pid)
+      end
+      tree
+    end
+
+    # @param pattern [String]
+    # @return [Array<Integer>] pids found
+    def pgrep(pattern)
+      output = run(['pgrep', '-lf', pattern])
+      output.lines.map do |line|
+        line.strip.split(/\s+/).first.to_i
+      end
+    rescue Appear::ExecutionFailure
+      []
+    end
+
+    private
+
+    def fetch_info(pid)
+      raise DeadProcess.new("cannot fetch info for dead PID #{pid}") unless alive?(pid)
+      output = run(['ps', '-p', pid.to_s, '-o', 'ppid=', '-o', 'command='])
+      ppid, *command = output.strip.split(/\s+/).reject(&:empty?)
+      name = File.basename(command.first)
+      ProcessInfo.new({:pid => pid.to_i, :parent_pid => ppid.to_i, :command => command, :name => name})
+    end
+  end
+end