derelict_m 0.6.2a

data/lib/derelict/box/not_found.rb

@@ -0,0 +1,16 @@
+module Derelict
+  class Box
+    # A box that isn't currently installed has been retrieved
+    class NotFound < Derelict::Exception
+      # Initializes a new instance, for a particular box name/provider
+      #
+      #   * box_name: The name of the box that this exception relates
+      #               to
+      #   * provider: The provider of the box that this exception
+      #               relates to
+      def initialize(box_name, provider)
+        super "Box '#{box_name}' for provider '#{provider}' missing"
+      end
+    end
+  end
+end

data/lib/derelict/connection.rb

@@ -0,0 +1,84 @@
+module Derelict
+  # Connects a Derelict::Instance to its use in a particular directory
+  class Connection
+    autoload :Invalid,  "derelict/connection/invalid"
+    autoload :NotFound, "derelict/connection/not_found"
+
+    # Include "logger" method to get a logger for this class
+    include Utils::Logger
+
+    attr_reader :instance
+    attr_reader :path
+
+    # Initializes a Connection for use in a particular directory
+    #
+    #   * instance: The Derelict::Instance to use to control Vagrant
+    #   * path:     The project path, which contains the Vagrantfile
+    def initialize(instance, path)
+      @instance = instance
+      @path = path
+      logger.debug "Successfully initialized #{description}"
+    end
+
+    # Validates the data used for this connection
+    #
+    # Raises exceptions on failure:
+    #
+    #   * +Derelict::Connection::NotFound+ if the path is not found
+    def validate!
+      logger.debug "Starting validation for #{description}"
+      raise NotFound.new path unless File.exists? path
+      logger.info "Successfully validated #{description}"
+      self
+    end
+
+    # Executes a Vagrant subcommand using this connection
+    #
+    #   * subcommand: Vagrant subcommand to run (:up, :status, etc.)
+    #   * arguments:  Arguments to pass to the subcommand (optional)
+    #   * block:      Passed through to @instance#execute
+    def execute(subcommand, *arguments, &block)
+      log_execute subcommand, *arguments
+      Dir.chdir path do
+        instance.execute subcommand.to_sym, *arguments, &block
+      end
+    end
+
+    # Executes a Vagrant subcommand, raising an exception on failure
+    #
+    #   * subcommand: Vagrant subcommand to run (:up, :status, etc.)
+    #   * arguments:  Arguments to pass to the subcommand (optional)
+    #   * block:      Passed through to Derelict::Executer.execute
+    #
+    # Raises +Derelict::Instance::CommandFailed+ if the command fails.
+    def execute!(subcommand, *arguments, &block)
+      log_execute subcommand, *arguments
+      Dir.chdir path do
+        instance.execute! subcommand.to_sym, *arguments, &block
+      end
+    end
+
+    # Retrieves a Derelict::VirtualMachine for a particular VM
+    #
+    #   * name: The name of the virtual machine to retrieve
+    def vm(name)
+      logger.debug "Retrieving VM '#{name}' from #{description}"
+      Derelict::VirtualMachine.new(self, name).validate!
+    end
+
+    # Provides a description of this Connection
+    #
+    # Mainly used for log messages.
+    def description
+      "Derelict::Connection at '#{path}' using #{instance.description}"
+    end
+
+    private
+      # Handles the logging that should occur for a call to #execute(!)
+      def log_execute(subcommand, *arguments)
+        logger.debug do
+          "Executing #{subcommand} #{arguments.inspect} on #{description}"
+        end
+      end
+  end
+end

data/lib/derelict/connection/invalid.rb

@@ -0,0 +1,14 @@
+module Derelict
+  class Connection
+    # Represents an invalid connection, which Derelict can't use
+    class Invalid < Derelict::Exception
+      include Derelict::Exception::OptionalReason
+
+      private
+        # Retrieves the default error message
+        def default_message
+          "Invalid Derelict connection"
+        end
+    end
+  end
+end

data/lib/derelict/connection/not_found.rb

@@ -0,0 +1,13 @@
+module Derelict
+  class Connection
+    # The Vagrantfile for the connection was not found
+    class NotFound < Invalid
+      # Initializes a new instance of this exception for a given path
+      #
+      #   * path: The requested path of the instance
+      def initialize(path)
+        super "Vagrantfile not found for #{path}"
+      end
+    end
+  end
+end

data/lib/derelict/exception.rb

@@ -0,0 +1,6 @@
+module Derelict
+  # Base class for any exceptions thrown by Derelict
+  class Exception < ::Exception
+    autoload :OptionalReason, "derelict/exception/optional_reason"
+  end
+end

data/lib/derelict/exception/optional_reason.rb

@@ -0,0 +1,32 @@
+module Derelict
+  class Exception
+    # An exception that has a message and optional additional reason
+    #
+    # The reason can be passed to the constructor (if desired). When a
+    # reason is passed, it's appended to the default message. If no
+    # reason is passed, the default message is used.
+    module OptionalReason
+      # Initializes a new instance of this exception, with a reason
+      #
+      #   * reason: Optional reason to add to the default error message
+      #             (optional, the default message will be used if no
+      #             reason is provided)
+      def initialize(reason = nil)
+        if reason.nil?
+          super default_message
+        else
+          super "#{default_message}: #{reason}"
+        end
+      end
+
+      private
+        # Retrieves the default error message
+        #
+        # This needs to be overridden in child classes in order to
+        # customize the default error message.
+        def default_message
+          raise NotImplementedError.new "#default_message not defined"
+        end
+    end
+  end
+end

data/lib/derelict/executer.rb

@@ -0,0 +1,237 @@
+module Derelict
+  # Executes an external (shell) command "safely"
+  #
+  # The safety involved is mainly ensuring that the command is
+  # gracefully terminated if this process is about to terminate.
+  class Executer
+    # Include "logger" method to get a logger for this class
+    include Utils::Logger
+
+    attr_reader :stdout, :stderr, :pid
+
+    # Executes <tt>command</tt> and returns after execution
+    #
+    #   * command: A string containing the command to run
+    #   * options: A hash of options, with the following (symbol) keys:
+    #      * :mode:      Controls how the process' output is given to
+    #                    the block, one of :chars (pass each character
+    #                    one by one, retrieved with getc), or :lines
+    #                    (pass only whole lines, retrieved with gets).
+    #                    (optional, defaults to :lines)
+    #      * :no_buffer: If true, the process' stdout and stderr won't
+    #                    be collected in the stdout and stderr
+    #                    properties, and will only be passed to the
+    #                    block (optional, defaults to false)
+    #   * block:   Gets passed stdout and stderr every time the process
+    #              outputs to each stream (first parameter is stdout,
+    #              second parameter is stderr; only one will contain
+    #              data, the other will be nil)
+    def self.execute(command, options = {}, &block)
+      self.new(options).execute(command, &block)
+    end
+
+
+    # Initializes an Executer instance with particular options
+    #
+    #   * options: A hash of options, with the following (symbol) keys:
+    #      * :mode:      Controls how the process' output is given to
+    #                    the block, one of :chars (pass each character
+    #                    one by one, retrieved with getc), or :lines
+    #                    (pass only whole lines, retrieved with gets).
+    #                    (optional, defaults to :lines)
+    #      * :no_buffer: If true, the process' stdout and stderr won't
+    #                    be collected in the stdout and stderr
+    #                    properties, and will only be passed to the
+    #                    block (optional, defaults to false)
+    def initialize(options = {})
+      @options = {:mode => :lines, :no_buffer => false}.merge(options)
+
+      logger.info "Initializing with options: #{@options.inspect}"
+
+      if @options[:mode] == :chars
+        @reader = proc {|s| s.getc }
+      else
+        @reader = proc {|s| s.gets }
+      end
+
+      @mutex = Mutex.new
+      reset
+    end
+
+    # Executes <tt>command</tt> and returns after execution
+    #
+    #   * command: A string containing the command to run
+    #   * block:   Gets passed stdout and stderr every time the process
+    #              outputs to each stream (first parameter is stdout,
+    #              second parameter is stderr; only one will contain
+    #              data, the other will be nil)
+    def execute(command, &block)
+      logger.info "Executing command '#{command}'"
+      reset
+      pid, stdin, stdout_stream, stderr_stream = Open4::popen4(command)
+      @pid = pid
+      stdin.close rescue nil
+
+      save_exit_status(pid)
+      forward_signals_to(pid) do
+        handle_streams stdout_stream, stderr_stream, &block
+      end
+
+      self
+    ensure
+      logger.debug "Closing stdout and stderr streams for process"
+      stdout.close rescue nil
+      stderr.close rescue nil
+    end
+
+    # Determines whether the last command was successful or not
+    #
+    # If the command's exit status was zero, this will return true.
+    # If the command's exit status is anything else, this will return
+    # false. If a command is currently running, this will return nil.
+    def success?
+      @success
+    end
+
+    # Return the real exit status of the last command as it was returned to
+    # the system.  This is useful if your doing things like running commands
+    # inside a vm over ssh and want to obtain the exit status from the command
+    # itself.  If a command is currently running, this will return nil.
+    def status
+      @status
+    end
+
+    private
+      # Clears the variables relating to a particular command execution
+      #
+      # This is done when first initialising, and just before a command
+      # is run, to get rid of the previous command's data.
+      def reset
+        logger.debug "Resetting executer state"
+        @stdout = ''
+        @stderr = ''
+        @success = nil
+        @status = nil
+        @pid = nil
+      end
+
+      # Waits for the exit status of a process (in a thread) saving it
+      #
+      # This will set the @status instance variable to true if the exit
+      # status was 0, or false if the exit status was anything else.
+      def save_exit_status(pid)
+        logger.debug "Spawning thread to monitor process ID #{pid}"
+        @success = nil
+        Thread.start do
+          logger.debug "Thread started, waiting for PID #{pid}"
+          @status = Process.waitpid2(pid).last.exitstatus
+          logger.debug "Process exited with status #{@status}"
+          @success = (@status == 0)
+        end
+      end
+
+      # Forward signals to a process while running the given block
+      #
+      #   * pid:     The process ID to forward signals to
+      #   * signals: The names of the signals to handle (optional,
+      #              defaults to SIGINT only)
+      def forward_signals_to(pid, signals = %w[INT])
+        # Set up signal handlers
+        logger.debug "Setting up signal handlers for #{signals.inspect}"
+        signal_count = 0
+        signals.each do |signal|
+          Signal.trap(signal) do
+            Process.kill signal, pid rescue nil
+
+            # If this is the second time we've received and forwarded
+            # on the signal, make sure next time we just give up.
+            reset_handlers_for signals if ++signal_count >= 2
+          end
+        end
+
+        # Run the block now that the signals are being forwarded
+        yield
+      ensure
+        # Always good to make sure we clean up after ourselves
+        reset_handlers_for signals
+      end
+
+      # Resets the handlers for particular signals to the default
+      #
+      #   * signals: An array of signal names to reset the handlers for
+      def reset_handlers_for(signals)
+        logger.debug "Resetting signal handlers for #{signals.inspect}"
+        signals.each {|signal| Signal.trap signal, "DEFAULT" }
+      end
+
+      # Manages reading from the stdout and stderr streams
+      #
+      #   * stdout_stream: The process' stdout stream
+      #   * stderr_stream: The process' stderr stream
+      #   * block:         The block to pass output to (optional)
+      def handle_streams(stdout_stream, stderr_stream, &block)
+        logger.debug "Monitoring stdout/stderr streams for output"
+        streams = [stdout_stream, stderr_stream]
+        until streams.empty?
+          # Find which streams are ready for reading, timeout 0.1s
+          selected, = select(streams, nil, nil, 0.1)
+
+          # Try again if none were ready
+          next if selected.nil? or selected.empty?
+
+          selected.each do |stream|
+            if stream.eof?
+              logger.debug "Stream reached end-of-file"
+              if @success.nil?
+                logger.debug "Process hasn't finished, keeping stream"
+              else
+                logger.debug "Removing stream"
+                streams.delete(stream)
+              end
+              next
+            end
+
+            while data = @reader.call(stream)
+              data = ((@options[:mode] == :chars) ? data.chr : data)
+              stream_name = (stream == stdout_stream) ? :stdout : :stderr
+              output data, stream_name, &block unless block.nil?
+              buffer data, stream_name unless @options[:no_buffer]
+            end
+          end
+        end
+      end
+
+      # Outputs data to the block
+      #
+      #   * data:        The data that needs to be passed to the block
+      #   * stream_name: The stream data came from (:stdout or :stderr)
+      #   * block:       The block to pass the data to
+      def output(data, stream_name = :stdout, &block)
+        # Pass the output to the block
+        if block.arity == 2
+          args = [nil, nil]
+          if stream_name == :stdout
+            args[0] = data
+          else
+            args[1] = data
+          end
+          block.call(*args)
+        else
+          yield data if stream_name == :stdout
+        end
+      end
+
+      # Buffers data for a stream into this object to retrieve it later
+      #
+      #   * data:        The data that should be added to the buffer
+      #   * stream_name: Which stream the data came from (:stdout or
+      #                  :stderr)
+      def buffer(data, stream_name)
+        if stream_name == :stdout
+          @stdout += data
+        else
+          @stderr += data
+        end
+      end
+  end
+end

data/lib/derelict/instance.rb

@@ -0,0 +1,147 @@
+module Derelict
+  # Represents a Vagrant instance installed via the Installer package
+  class Instance
+    autoload :CommandFailed, "derelict/instance/command_failed"
+    autoload :Invalid,       "derelict/instance/invalid"
+    autoload :MissingBinary, "derelict/instance/missing_binary"
+    autoload :NonDirectory,  "derelict/instance/non_directory"
+    autoload :NotFound,      "derelict/instance/not_found"
+
+    # Include "memoize" class method to memoize methods
+    extend Memoist
+
+    # Include "logger" method to get a logger for this class
+    include Utils::Logger
+
+    # The default path to the Vagrant installation folder
+    DEFAULT_PATH = "/Applications/Vagrant"
+
+    attr_reader :path
+
+    # Initialize an instance for a particular directory
+    #
+    #   * path: The path to the Vagrant installation folder (optional,
+    #           defaults to DEFAULT_PATH)
+    def initialize(path = DEFAULT_PATH)
+      @path = path
+      logger.debug "Successfully initialized #{description}"
+    end
+
+    # Validates the data used for this instance
+    #
+    # Raises exceptions on failure:
+    #
+    #   * +Derelict::Instance::NotFound+ if the instance is not found
+    #   * +Derelict::Instance::NonDirectory+ if the path is a file,
+    #     instead of a directory as expected
+    #   * +Derelict::Instance::MissingBinary+ if the "vagrant" binary
+    #     isn't in the expected location or is not executable
+    def validate!
+      logger.debug "Starting validation for #{description}"
+      raise NotFound.new path unless File.exists? path
+      raise NonDirectory.new path unless File.directory? path
+      raise MissingBinary.new vagrant unless File.exists? vagrant
+      raise MissingBinary.new vagrant unless File.executable? vagrant
+      logger.info "Successfully validated #{description}"
+      self
+    end
+
+    # Determines the version of this Vagrant instance
+    def version
+      logger.info "Determining Vagrant version for #{description}"
+      output = execute!("--version").stdout
+      Derelict::Parser::Version.new(output).version
+    end
+    memoize :version
+
+    # Executes a Vagrant subcommand using this instance
+    #
+    #   * subcommand: Vagrant subcommand to run (:up, :status, etc.)
+    #   * arguments:  Arguments to pass to the subcommand (optional)
+    #   * options:    If the last argument is a Hash, it will be used
+    #                 as a hash of options. A list of valid options is
+    #                 below. Any options provided that aren't in the
+    #                 list of valid options will get passed through to
+    #                 Derelict::Executer.execute.
+    #                 Valid option keys:
+    #      * sudo:    Whether to run the command as root, or not
+    #                 (defaults to false)
+    #   * block:      Passed through to Derelict::Executer.execute
+    def execute(subcommand, *arguments, &block)
+      options = arguments.last.is_a?(Hash) ? arguments.pop : Hash.new
+      command = command(subcommand, *arguments)
+      command = "sudo -- #{command}" if options.delete(:sudo)
+      logger.debug "Executing #{command} using #{description}"
+      Executer.execute command, options, &block
+    end
+
+    # Executes a Vagrant subcommand, raising an exception on failure
+    #
+    #   * subcommand: Vagrant subcommand to run (:up, :status, etc.)
+    #   * arguments:  Arguments to pass to the subcommand (optional)
+    #   * block:      Passed through to Derelict::Executer.execute
+    #
+    # Raises +Derelict::Instance::CommandFailed+ if the command fails.
+    def execute!(subcommand, *arguments, &block)
+      execute(subcommand, *arguments, &block).tap do |result|
+        unless result.success?
+          command = command(subcommand, *arguments)
+          exception = CommandFailed.new command, result
+          logger.warn "Command #{command} failed: #{exception.message}"
+          raise exception
+        end
+      end
+    end
+
+    # Initializes a Connection for use in a particular directory
+    #
+    #   * instance: The Derelict::Instance to use to control Vagrant
+    #   * path:     The project path, which contains the Vagrantfile
+    def connect(path)
+      logger.info "Creating connection for '#{path}' by #{description}"
+      Derelict::Connection.new(self, path).validate!
+    end
+
+    # Initializes a plugin manager for use with this instance
+    def plugins
+      logger.info "Creating plugin manager for #{description}"
+      Derelict::Plugin::Manager.new(self)
+    end
+
+    # Initializes a box manager for use with this instance
+    def boxes
+      logger.info "Creating box manager for #{description}"
+      Derelict::Box::Manager.new(self)
+    end
+
+    # Provides a description of this Instance
+    #
+    # Mainly used for log messages.
+    def description
+      "Derelict::Instance at '#{path}'"
+    end
+
+    private
+      # Retrieves the path to the vagrant binary for this instance
+      def vagrant
+        File.join(@path, "bin", "vagrant").tap do |vagrant|
+          logger.debug "Vagrant binary for #{description} is '#{vagrant}'"
+        end
+      end
+      memoize :vagrant
+
+
+      # Constructs the command to execute a Vagrant subcommand
+      #
+      #   * subcommand: Vagrant subcommand to run (:up, :status, etc.)
+      #   * arguments:  Arguments to pass to the subcommand (optional)
+      def command(subcommand, *arguments)
+        args = [vagrant, subcommand.to_s, arguments].flatten
+        args.map {|a| Shellwords.escape a }.join(' ').tap do |command|
+          logger.debug "Generated command '#{command}' from " +
+            "subcommand '#{subcommand.to_s}' with arguments " +
+            arguments.inspect
+        end
+      end
+  end
+end