vagrant-ansible_auto 0.1.5 → 0.2.1

data/lib/vagrant/ansible_auto/cap/guest/posix/ssh_server_address.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require 'set'
 
 module VagrantPlugins
@@ -6,22 +7,32 @@ module VagrantPlugins
     module Cap
       module Guest
         module POSIX
+          # Attempt to find the IP address and port of an active SSH server
+          # @todo test not merely that a host and port combo is open, but that
+          #   there's an SSH server listening there
           class SSHServerAddress
             class << self
+              # @param [Vagrant::Machine] machine a guest machine
+              # @param [Vagrant::Machine,nil] target_machine a guest machine
+              # @return [Array<(String, Integer)>] the host and port on which
+              #   an SSH server may be listening
               def ssh_server_address(machine, target_machine = nil)
                 with_open_ports(machine, target_machine).first
               end
 
-            private
-
+              # @param (see #ssh_server_address)
+              # @return [Array<Array<(String, Integer)>>] a list of host and
+              #   port pairs on which an SSH server may be listening
               def ssh_server_addresses(machine, target_machine = nil)
                 with_open_ports(machine, target_machine).to_a
               end
 
+            private
+
               def with_open_ports(machine, target_machine = nil)
                 return enum_for(__method__, machine, target_machine) unless block_given?
 
-                return unless machine.guest.capability?(:check_open_port)
+                return unless machine.guest.capability?(:port_open?)
 
                 target_machine ||= machine
                 ssh_info = target_machine.ssh_info
@@ -30,13 +41,13 @@ module VagrantPlugins
                 with_candidate_addresses(target_machine) do |host, port|
                   port ||= default_port
 
-                  if machine.guest.capability(:check_open_port, host, port)
+                  if machine.guest.capability(:port_open?, host, port)
                     yield host, port
                   end
                 end
               end
 
-              network_type_precedence_map = Hash[[:forwarded_port, :public_network, :private_network].each_with_index.map { |type, i| [type, i] }]
+              network_type_precedence_map = Hash[%i[forwarded_port public_network private_network].each_with_index.map { |type, i| [type, i] }]
               define_method(:network_type_precedence) do |type|
                 network_type_precedence_map[type]
               end
@@ -62,18 +73,17 @@ module VagrantPlugins
                 machine.config.vm.networks.sort_by { |(type, _)| network_type_precedence(type) }.each do |type, info|
                   case type
                   when :private_network, :public_network
-                      has_routable_ip = true
+                    has_routable_ip = true
 
-                      yield_unseen_candidate.call([info[:ip]]) if info.key?(:ip)
+                    yield_unseen_candidate.call([info[:ip]]) if info.key?(:ip)
                   when :forwarded_port
-                      # TODO: the `:id' restriction might not be right.
-                      if info[:protocol] == 'tcp' and info[:id] == 'ssh'
-                        yield_unseen_candidate.call([info[:host_ip], info[:host]])
-                      end
+                    if info[:protocol] == 'tcp' && info[:id] == 'ssh'
+                      yield_unseen_candidate.call([info[:host_ip], info[:host]])
+                    end
                   end
                 end
 
-                return if has_routable_ip or !machine.guest.capability?(:gateway_addresses)
+                return if has_routable_ip || !machine.guest.capability?(:gateway_addresses)
 
                 machine.guest.capability(:gateway_addresses).each do |gateway_address|
                   yield_unseen_candidate.call(gateway_address)

data/lib/vagrant/ansible_auto/cap/guest/posix.rb

@@ -0,0 +1,16 @@
+
+# Here for documentation purposes only
+
+module VagrantPlugins
+  module AnsibleAuto
+    # Capabilities on guests and hosts
+    module Cap
+      # Capabilities on guests
+      module Guest
+        # Capabilities on POSIX hosts
+        module POSIX
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/ansible_auto/command/inventory.rb

@@ -1,44 +1,70 @@
 # frozen_string_literal: true
+
 require 'optparse'
 
 module VagrantPlugins
   module AnsibleAuto
     module Command
+      # Vagrant +ansible inventory+ subcommand
       class Inventory < Vagrant.plugin(2, :command)
+        # @return [String] summary of the +ansible inventory+ command
         def self.synopsis
           'dynamic ansible inventory'
         end
 
+        # Print the Ansible inventory for the current Vagrantfile.
+        #
+        # By default, the inventory is printed in Ansible's static INI
+        # inventory style.  When the +-l/--list+ flag is present, the inventory
+        # is printed in Ansible's dynamic JSON inventory style.
+        #
+        # @return [Integer] the exit status of the command
         def execute
+          operation = :as_ini
+
           opts = OptionParser.new do |op|
             op.banner = 'Usage: vagrant ansible inventory [<options>]'
             op.separator ''
             op.separator 'Available options:'
 
-            op.on('-l', '--list', 'List all hosts as json') do |_target|
-              @env.ui.info inventory.to_json, prefix: false
-              return 0
+            op.on('--ini', 'List hosts as INI (default)') do
+              operation = :as_ini
             end
 
-            op.on('-h', '--help', 'Show this message') do
-              @env.ui.info opts.help, prefix: false
-              return 0
+            op.on('--json', 'List all hosts as JSON') do
+              operation = :as_json
+            end
+
+            op.on('--pretty', 'List all hosts as pretty JSON') do
+              operation = :as_pretty_json
             end
           end
 
-          @argv = parse_options(opts)
+          machines = parse_options(opts)
 
-          @env.ui.info inventory.to_ini, prefix: false
+          @env.ui.info send(operation, machines), prefix: false
 
           0
         end
 
       private
 
-        def inventory
-          @inventory = with_target_vms(@argv) {}.each_with_object(AnsibleAuto::Inventory.new) do |machine, inventory|
+        def as_ini(machines)
+          build_inventory(machines).to_ini
+        end
+
+        def as_json(machines)
+          build_inventory(machines).to_json
+        end
+
+        def as_pretty_json(machines)
+          JSON.pretty_generate(build_inventory(machines))
+        end
+
+        def build_inventory(machines)
+          with_target_vms(machines) {}.each_with_object(AnsibleAuto::Inventory.new) do |machine, inventory|
             unless machine.state.id == :running
-              @env.ui.warn "machine #{machine.name} is not running; falling back to default hostvar values"
+              @env.ui.warn "machine #{machine.name} is not running; falling back to default hostvar values", channel: :error
             end
             inventory.merge!(machine.config.ansible.inventory)
             inventory.add_host(machine)

data/lib/vagrant/ansible_auto/command/root.rb

@@ -1,57 +1,60 @@
 # frozen_string_literal: true
+
 require 'optparse'
 
+require 'vagrant/ansible_auto/errors'
+
 module VagrantPlugins
   module AnsibleAuto
+    # Vagrant +ansible+ subcommand
     module Command
+      # Command for creating a static Ansible inventory from the machines
+      # defined in a Vagrantfile
       class Root < Vagrant.plugin(2, :command)
+        # @return [String] summary of the +ansible+ command
         def self.synopsis
           'build ansible inventory'
         end
 
-        def initialize(argv, env)
-          super
-
-          @main_args, @sub_command, @sub_args = split_main_and_subcommand(argv)
-
-          @subcommands = Vagrant::Registry.new
-
-          @subcommands.register(:inventory) do
-            require_relative 'inventory'
-            Inventory
-          end
-        end
-
+        # Execute the +ansible+ command
+        # @return [Integer] the exit status of the command
         def execute
-          if @main_args.include?('-h') || @main_args.include?('--help')
-            return help
+          @argv, subcommand_name, subcommand_argv = split_main_and_subcommand(@argv)
+
+          if subcommand_name.nil?
+            @argv = ['-h'] if @argv.empty?
+            return parse_options(prepare_options)
+          elsif subcommands.key? subcommand_name.to_sym
+            return subcommands.get(subcommand_name.to_sym).new(subcommand_argv, @env.dup).execute
+          else
+            raise Errors::UnrecognizedCommandError, command: subcommand_name
           end
-
-          command_class = @subcommands.get(@sub_command.to_sym) if @sub_command
-          return help if !command_class || !@sub_command
-          @logger.debug("Invoking command class: #{command_class} #{@sub_args.inspect}")
-
-          command_class.new(@sub_args, @env).execute
         end
 
-        def help
-          opts = OptionParser.new do |o|
+      private
+
+        def prepare_options
+          OptionParser.new do |o|
             o.banner = 'Usage: vagrant ansible <subcommand> [<options>]'
             o.separator ''
             o.separator 'Available subcommands:'
 
-            keys = []
-            @subcommands.each { |key, _value| keys << key.to_s }
-
-            keys.sort.each do |key|
-              o.separator "     #{key}"
+            subcommands.keys.sort.each do |k|
+              o.separator "    #{k}"
             end
 
-            o.separator ""
-            o.separator "For help on any individual subcommand run `vagrant ansible <subcommand> -h`"
+            o.separator ''
+            o.separator 'For help on any individual subcommand run `vagrant ansible <subcommand> -h`'
           end
+        end
 
-          @env.ui.info(opts.help, prefix: false)
+        def subcommands
+          @subcommands ||= Vagrant::Registry.new.tap do |r|
+            r.register(:inventory) do
+              require_relative 'inventory'
+              Inventory
+            end
+          end
         end
       end
     end

data/lib/vagrant/ansible_auto/config.rb

@@ -1,56 +1,109 @@
 # frozen_string_literal: true
-require 'vagrant/ansible_auto/inventory'
-require 'vagrant/ansible_auto/errors'
-require 'vagrant/util/deep_merge'
 
 require 'vagrant'
 require Vagrant.source_root + 'plugins/provisioners/ansible/config/guest'
 
+require 'vagrant/ansible_auto/inventory'
+require 'vagrant/ansible_auto/errors'
+require 'vagrant/ansible_auto/util/config'
+
 module VagrantPlugins
   module AnsibleAuto
+    # Configuration for the +ansible_auto+ provisioner and +ansible+ command
     class Config < VagrantPlugins::Ansible::Config::Guest
+      include Util::Config
+
       attr_accessor :inventory, :groups, :vars, :children,
-                    :strict_host_key_checking, :host_connect_tries, :host_connect_sleep
+                    :strict_host_key_checking, :host_connect_tries,
+                    :host_connect_sleep, :insert_control_machine_public_key,
+                    :upload_inventory_host_private_keys
 
       protected(:inventory=)
 
+      BOOLEAN = %I[
+        strict_host_key_checking
+        insert_control_machine_public_key
+        upload_inventory_host_private_keys
+      ].freeze
+
+      INTEGER = %I[
+        host_connect_tries
+      ].freeze
+
+      NUMBER = %I[
+        host_connect_sleep
+      ].freeze
+
       def initialize
         super
-        @inventory                = Inventory.new
-        @groups                   = UNSET_VALUE
-        @vars                     = UNSET_VALUE
-        @children                 = UNSET_VALUE
-        @strict_host_key_checking = UNSET_VALUE
-        @host_connect_tries       = UNSET_VALUE
-        @host_connect_sleep       = UNSET_VALUE
-        @__errors                 = []
+        @inventory                          = Inventory.new
+        @groups                             = UNSET_VALUE
+        @vars                               = UNSET_VALUE
+        @children                           = UNSET_VALUE
+        @strict_host_key_checking           = UNSET_VALUE
+        @host_connect_tries                 = UNSET_VALUE
+        @host_connect_sleep                 = UNSET_VALUE
+        @insert_control_machine_public_key  = UNSET_VALUE
+        @upload_inventory_host_private_keys = UNSET_VALUE
+        @__errors = []
       end
 
+      # Set default configuration values at the end of constructing the Vagrant
+      # environment
+      # @api private
+      # @return [void]
       def finalize!
         super
-        @inventory.groups         = @groups   unless @groups                == UNSET_VALUE
-        @inventory.vars           = @vars     unless @vars                  == UNSET_VALUE
-        @inventory.children       = @children unless @children              == UNSET_VALUE
-        @strict_host_key_checking = false     if @strict_host_key_checking  == UNSET_VALUE
-        @host_connect_tries       = 10        if @host_connect_tries        == UNSET_VALUE
-        @host_connect_sleep       = 2         if @host_connect_sleep        == UNSET_VALUE
+        @inventory.groups                   = @groups                             unless @groups                          == UNSET_VALUE
+        @inventory.vars                     = @vars                               unless @vars                            == UNSET_VALUE
+        @inventory.children                 = @children                           unless @children                        == UNSET_VALUE
+        @strict_host_key_checking           = false                               if @strict_host_key_checking            == UNSET_VALUE
+        @host_connect_tries                 = 10                                  if @host_connect_tries                  == UNSET_VALUE
+        @host_connect_sleep                 = 2                                   if @host_connect_sleep                  == UNSET_VALUE
+        @insert_control_machine_public_key  = true                                if @insert_control_machine_public_key   == UNSET_VALUE
+        @upload_inventory_host_private_keys = !@insert_control_machine_public_key if @upload_inventory_host_private_keys  == UNSET_VALUE
+
+        # NOTE @limit is defined in core Vagrant's Ansible config.
+        @limit = '*' if @limit == UNSET_VALUE
       rescue Errors::InventoryError => e
         @__errors << e.message
       end
 
+      # Ensure that the configuration is in a valid state
+      # @api private
+      # @return [Hash{String=>Array}] a structure containing a list of errors
+      #   under the +ansible_auto+ key
       def validate(machine)
         super
 
         errors = _detected_errors + @__errors
 
-        # TODO: -- test that `host_wait...' values are integers
-        unless @strict_host_key_checking == true or @strict_host_key_checking == false
-          errors << "strict_host_key_checking must be either true or false"
+        BOOLEAN.each do |o|
+          unless bool? instance_variable_get(:"@#{o}")
+            errors << "#{o} must be either true or false"
+          end
+        end
+
+        INTEGER.each do |o|
+          unless int? instance_variable_get(:"@#{o}")
+            errors << "#{o} must be an integer"
+          end
+        end
+
+        NUMBER.each do |o|
+          unless num? instance_variable_get(:"@#{o}")
+            errors << "#{o} must be a number"
+          end
         end
 
         { 'ansible_auto' => errors }
       end
 
+      # Merge two configurations
+      # @api private
+      # @param [Config] other the configuration to merge into this
+      #   configuration
+      # @return [Config] the merged configuration
       def merge(other)
         return super if other.nil?
 
@@ -61,18 +114,6 @@ module VagrantPlugins
           result.inventory  = inventory.merge(other.inventory)
         end
       end
-
-    private
-
-      def conditional_merge(a, b)
-        if b.nil? or b == UNSET_VALUE
-          a
-        elsif a.nil? or a == UNSET_VALUE
-          b
-        else
-          Vagrant::Util::DeepMerge.deep_merge(a, b)
-        end
-      end
     end
   end
 end

data/lib/vagrant/ansible_auto/errors.rb

@@ -1,14 +1,43 @@
 # frozen_string_literal: true
+
 module VagrantPlugins
   module AnsibleAuto
+    # Error classes for the +ansible_auto+ provisioner and +ansible+ command
     module Errors
+      # An error representing an {Inventory} misconfiguration
       class InventoryError < Vagrant::Errors::VagrantError
-        error_namespace('vagrant.provisioners.ansible_auto')
+        error_namespace('vagrant.ansible_auto.errors.inventory')
       end
 
+      # Raised when an Ansible inventory group is expected to exist but doesn't
       class MissingGroupError < InventoryError
         error_key(:missing_group)
       end
+
+      # Raised when a group specifies child groups that do not exist
+      class GroupMissingChildError < MissingGroupError
+        error_key(:group_missing_child)
+      end
+
+      # Raised when provided data can't be converted to a {Host} object
+      class InvalidHostTypeError < InventoryError
+        error_key(:invalid_host_type)
+      end
+
+      # Raised when a group name is disallowed
+      class InvalidGroupNameError < InventoryError
+        error_key(:invalid_group_name)
+      end
+
+      # Class representing {Command} errors
+      class CommandError < Vagrant::Errors::VagrantError
+        error_namespace('vagrant.ansible_auto.errors.command')
+      end
+
+      # Raised on receipt of an unrecognized +vagrant ansible+ subcommand
+      class UnrecognizedCommandError < CommandError
+        error_key('unrecognized_command')
+      end
     end
   end
 end

data/lib/vagrant/ansible_auto/host.rb

@@ -1,85 +1,174 @@
 # frozen_string_literal: true
+
 require 'vagrant'
-require 'vagrant/ansible_auto/util'
+
+require 'vagrant/ansible_auto/util/hash_with_indifferent_access'
+require 'vagrant/ansible_auto/util/keys'
 
 module VagrantPlugins
   module AnsibleAuto
+    # Class representing a single host in an Ansible inventory
     class Host
-      include VagrantPlugins::AnsibleAuto::Util
-
-      ANSIBLE_HOSTVARS = [:ssh_user, :ssh_host, :ssh_port, :ssh_private_key_file, :connection].freeze
-
-      attr_writer(*ANSIBLE_HOSTVARS)
+      include Util::Keys
 
+      # @param [#to_s] name the name of the {Host} as it should appear in an
+      #   {Inventory}
+      # @param [Hash] hostvars variables to associate with the host
       def initialize(name, hostvars = {})
         @name = name
 
-        # Convert keys to symbols
-        @hostvars = hostvars.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+        # # Convert keys to symbols
+        # @hostvars = hostvars.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+        self.hostvars = hostvars
       end
 
+      # @return [String] the name of the {Host}, default +"default"+
       def name
         @name ||= 'default'
       end
 
-      def ssh_user
-        @ssh_user ||= @hostvars[:ssh_user] || 'vagrant'
+      # @return [String] the name of the machine as a string
+      def inventory_hostname
+        @inventory_hostname ||= name.to_s
+      end
+
+      # @param new_name [#to_s] the name to associate with this host in the
+      #   generated inventory
+      # @return (see #inventory_hostname)
+      def inventory_hostname=(new_name)
+        @inventory_hostname = new_name.to_s
+      end
+
+      # @return [String] the SSH user for the {Host}, default +"vagrant"+
+      def ansible_ssh_user
+        hostvars[:ansible_ssh_user] ||= 'vagrant'
       end
 
-      def ssh_host
-        @ssh_host ||= @hostvars[:ssh_host] || '127.0.0.1'
+      # @return [String] the hostname of the {Host}, default +"127.0.0.1"+
+      def ansible_ssh_host
+        hostvars[:ansible_ssh_host] ||= '127.0.0.1'
       end
 
-      def ssh_port
-        @ssh_port ||= @hostvars[:ssh_port] || 22
+      # @return [Integer] the SSH port of the {Host}, default +22+
+      def ansible_ssh_port
+        hostvars[:ansible_ssh_port] ||= 22
       end
 
-      def ssh_private_key_file
-        @ssh_private_key_file ||= @hostvars[:ssh_private_key_file]
+      # The SSH private key file
+      # @return [String] if the SSH private key file is defined
+      # @return [nil] if no SSH private key file is defined
+      def ansible_ssh_private_key_file
+        hostvars[:ansible_ssh_private_key_file]
       end
 
-      def connection
-        @connection ||= @hostvars[:connection]
+      # The connection type
+      # @return [String] if the connection type is defined
+      # @return [nil] if no connection type is defined
+      def ansible_connection
+        hostvars[:ansible_connection]
       end
 
+      # @return [Hash] the {Host}'s attributes keyed to its attribute names
+      # @example
+      #   host = Host.new("myhost", {ansible_ssh_user: 'me', ansible_ssh_port: 2200})
+      #   host.hostvars #=> {
+      #                 #     'ansible_ssh_user'  => 'me',
+      #                 #     'ansible_ssh_host'  => '127.0.0.1',
+      #                 #     'ansible_ssh_port'  => 2200,
+      #                 #   }
       def hostvars
-        ANSIBLE_HOSTVARS.each_with_object({}) do |m, acc|
-          value = send(m)
-          acc["ansible_#{m}"] = value unless value.nil?
-        end
+        @hostvars ||= Util::HashWithIndifferentAccess.new
+      end
+
+      # @param [Hash] hostvars the variables to set on the host
+      # @return [Hash] the new hostvars
+      def hostvars=(hostvars)
+        raise ArgumentError, 'hostvars must be a hash' unless hostvars.is_a? Hash
+        @hostvars = Util::HashWithIndifferentAccess.new(hostvars)
       end
 
+      # @return [Hash{String=>Hash}] the {Host}'s {hostvars} keyed to its
+      #   {name}
       def to_h
-        { name => hostvars }
+        finalize!
+        { inventory_hostname => hostvars }
       end
 
+      # @return [String] the {Host} represented as an entry in an Ansible
+      #   INI-style static inventory
+      # @example
+      #   host = Host.new("myhost", {ssh_user: 'me', ssh_port: 2200})
+      #   host.to_ini #=> "myhost ansible_ssh_user=me ansible_ssh_host=127.0.0.1 ansible_ssh_port=2200"
       def to_ini
-        [name, *hostvars.reject { |_, value| value.nil? }.map { |key, value| "#{key}=#{value}" }].join(' ')
+        [inventory_hostname, *hostvars.sort.reject { |_, value| value.nil? }.map { |key, value| "#{key}=#{value}" }].join(' ')
+      end
+
+      # @return [Fixnum] hash key
+      def hash
+        to_h.hash
+      end
+
+      # @return [Boolean] whether two hosts are identical
+      def eql?(other)
+        to_h.eql?(other.to_h)
+      end
+
+    private
+
+      def finalize!
+        %i[ansible_connection ansible_ssh_user ansible_ssh_host ansible_ssh_port ansible_ssh_private_key_file].each do |m|
+          send(m)
+        end
+      end
+
+      def respond_to_missing?(method, _include_all = false)
+        method.to_s.start_with? 'ansible_'
+      end
+
+      def method_missing(method, *args, &block)
+        super unless respond_to_missing?(method)
+
+        if method[-1] == '='
+          hostvars[method[0..-2]] = args[0]
+        else
+          hostvars[method]
+        end
       end
     end
 
+    # An Ansible host initialized from a {Vagrant::Machine}
     class HostMachine < Host
+      # @param [Vagrant::Machine] machine a {Vagrant::Machine} objectj
+      # @param [Hash] hostvars  the hostvars associated with the machine
       def initialize(machine, hostvars = {})
         super(machine.name, hostvars)
         @machine = machine
-        @ssh_info = machine.ssh_info || {}
       end
 
-      def ssh_user
-        @ssh_user ||= @hostvars[:ssh_user] || @ssh_info[:username] || super
+      # @see Host#ssh_user
+      def ansible_ssh_user
+        hostvars[:ansible_ssh_user] ||= ssh_info[:username] || super
       end
 
-      def ssh_host
-        @ssh_host ||= @hostvars[:ssh_host] || @ssh_info[:host] || super
+      # @see Host#ssh_host
+      def ansible_ssh_host
+        hostvars[:ansible_ssh_host] ||= ssh_info[:host] || super
       end
 
-      def ssh_port
-        @ssh_port ||= @hostvars[:ssh_port] || @ssh_info[:port] || super
+      # @see Host#ssh_port
+      def ansible_ssh_port
+        hostvars[:ansible_ssh_port] ||= ssh_info[:port] || super
       end
 
-      # TODO: better inference of which private key to use
-      def ssh_private_key_file
-        @ssh_private_key_file ||= @hostvars[:ssh_private_key_file] || fetch_private_key(@machine)
+      # @see Host#ssh_private_key_file
+      def ansible_ssh_private_key_file
+        hostvars[:ansible_ssh_private_key_file] ||= fetch_private_key(@machine)
+      end
+
+    private
+
+      def ssh_info
+        @machine.ssh_info || {}
       end
     end
   end