rfacter 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 57a9d18faa5cfba3610ad4e136cc0f6b67674f7e
-  data.tar.gz: ddc6e4a94f5cb61e2ff6133c46d1eb1bda340eed
+  metadata.gz: e7bc8b832480542b3e326f4f99389ea4d2b9968d
+  data.tar.gz: 37bad144b7ffbef453ad397ea39ed7ca89c1e43a
 SHA512:
-  metadata.gz: e2633c5de708b220c5d8cb5bb39aadb635cce530fe9d7a5d1c228860c82f3f698c54ca4d45f33850fd796914e6a53b69f96f3efaa2908583eb6b3cd2a585c20f
-  data.tar.gz: b6ebc55e51bfb161ef8363e3f1381e9b4ce5d37ef21bfc27eee45b101c055c2a279a747bd36049f2b0c59c5752de9fa8426d4af7931c1e7f9646576a6f198244
+  metadata.gz: afef987a44e33cc8c83134de30694a0a3591f64984aac19906cbe35e27f090635c67af8202271af9b1f3ccfeafce07630690de3678eeafda008ec20e5336347e
+  data.tar.gz: fea2ba928eb78d00e736e35b53bd2f1106223aa612a4371bfe36bcb9e9d1b5731bfe05c5bc27aafc3d38769e9a2da79c27c01cb59d38091edb850219630f3127

data/lib/rfacter.rb

@@ -1,3 +1,4 @@
+# Reduced, Remote-enabled, Ruby fork of Facter
 module RFacter;end
 module RFacter::Config;end
 module RFacter::Core;end

data/lib/rfacter/cli.rb

@@ -5,8 +5,13 @@ require 'rfacter'
 
 require_relative 'config'
 require_relative 'node'
+require_relative 'factset'
 require_relative 'util/collection'
 
+# RFacter Command Line Interface module
+#
+# @api public
+# @since 0.1.0
 module RFacter::CLI
   extend SingleForwardable
 
@@ -20,31 +25,17 @@ module RFacter::CLI
       @config.nodes['localhost'] = RFacter::Node.new('localhost')
     end
 
-    logger.info('cli::run') { "Configured nodes: #{@config.nodes.values.map(&:hostname)}" }
+    logger.info('cli::run') { "Configured nodes: #{@config.nodes.values.map(&:id)}" }
 
-    collection = RFacter::Util::Collection.new
-    collection.load_all
+    factset = RFacter::Factset.new(@config.nodes.values)
 
-    facts = @config.nodes.values.inject(Hash.new) do |h, node|
-      node_facts = if names.empty?
-        collection.to_hash(node)
-      else
-        names.inject(Hash.new) do |n, name|
-          n[name] = collection.value(name, node)
-          n
-        end
-      end
+    node_facts = if names.empty?
+                   factset.to_hash
+                 else
+                   factset.value(names)
+                 end
 
-      # TODO: Implement proper per-node Fact caching so that we don't just
-      # reset the colleciton on each loop.
-      collection.flush
-
-      h[node.hostname] = node_facts
-      h
-    end
-
-
-    puts JSON.pretty_generate(facts)
+    puts JSON.pretty_generate(node_facts)
 
     exit 0
   end

data/lib/rfacter/config.rb

@@ -13,6 +13,7 @@ require_relative 'node'
 # and contains methods for initializing the settings instance from
 # various sources.
 #
+# @api public
 # @since 0.1.0
 module RFacter::Config
   # Return global configuration
@@ -75,6 +76,10 @@ module RFacter::Config
       settings.logger.level = Logger::DEBUG
     end
 
+    parser.on('--profile', 'Profile fact resolution times.') do
+      settings.profile = true
+    end
+
     parser.on('-n', '--node', '=MANDATORY', URI, 'Add a node by URI.') do |uri|
       node = RFacter::Node.new(uri)
       settings.nodes[node.hostname] = node

data/lib/rfacter/config/settings.rb

@@ -6,6 +6,7 @@ require_relative '../util/logger'
 # Instances of this class hold top-level configuration values and shared
 # service objects such as loggers.
 #
+# @api public
 # @since 0.1.0
 class RFacter::Config::Settings
   # Access the logger instance
@@ -22,10 +23,16 @@ class RFacter::Config::Settings
   #   schemes to use when contacting them.
   attr_reader :nodes
 
+  # A boolean switch for enabling execution profiling
+  #
+  # @return [Boolean] Defaults to false.
+  attr_accessor :profile
+
   def initialize(**options)
     @logger = RFacter::Util::Logger.new($stderr)
     @logger.level = Logger::WARN
 
+    @profile = false
     @nodes = Hash.new
   end
 end

data/lib/rfacter/core/aggregate.rb

@@ -8,12 +8,12 @@ require_relative '../config'
 # Aggregates are evaluated in two parts: generating individual chunks and then
 # aggregating all chunks together. Each chunk is a block of code that generates
 # a value, and may depend on other chunks when it runs. After all chunks have
-# been evaluated they are passed to the aggregate block as Hash<name, result>.
+# been evaluated they are passed to the aggregate block as `Hash<name, result>`.
 # The aggregate block converts the individual chunks into a single value that is
 # returned as the final value of the aggregate.
 #
-# @api public
-# @since 2.0.0
+# @api private
+# @since 0.1.0
 class RFacter::Core::Aggregate
   require_relative 'directed_graph'
   require_relative 'resolvable'
@@ -32,19 +32,17 @@ class RFacter::Core::Aggregate
   attr_reader :name
 
   # @!attribute [r] deps
-  #   @api private
-  #   @return [Facter::Core::DirectedGraph]
+  #   @return [RFacter::Core::DirectedGraph]
   attr_reader :deps
 
   # @!attribute [r] confines
-  #   @return [Array<Facter::Core::Confine>] An array of confines restricting
+  #   @return [Array<RFacter::Core::Confine>] An array of confines restricting
   #     this to a specific platform
-  #   @see Facter::Core::Suitable
+  #   @see RFacter::Core::Suitable
   attr_reader :confines
 
   # @!attribute [r] fact
-  # @return [Facter::Util::Fact]
-  # @api private
+  # @return [RFacter::Util::Fact]
   attr_reader :fact
 
   def initialize(name, fact, config: RFacter::Config.config, **options)
@@ -83,8 +81,6 @@ class RFacter::Core::Aggregate
 
   # Define a new chunk for the given aggregate
   #
-  # @api public
-  #
   # @example Defining a chunk with no dependencies
   #   aggregate.chunk(:mountpoints) do
   #     # generate mountpoint information
@@ -120,8 +116,6 @@ class RFacter::Core::Aggregate
 
   # Define how all chunks should be combined
   #
-  # @api public
-  #
   # @example Merge all chunks
   #   aggregate.aggregate do |chunks|
   #     final_result = {}
@@ -160,7 +154,7 @@ class RFacter::Core::Aggregate
 
   # Evaluate the results of this aggregate.
   #
-  # @see Facter::Core::Resolvable#value
+  # @see RFacter::Core::Resolvable#value
   # @return [Object]
   def resolve_value
     chunk_results = run_chunks()

data/lib/rfacter/core/directed_graph.rb

@@ -5,6 +5,12 @@ require 'rfacter'
 
 module RFacter
   module Core
+    # Directed graph for sorting aggregate chunk dependencies
+    #
+    # @see RFacter::Core::Aggregate
+    #
+    # @api private
+    # @since 0.1.0
     class DirectedGraph < Hash
       include TSort
 

data/lib/rfacter/core/resolvable.rb

@@ -9,6 +9,9 @@ require_relative '../util/normalization'
 # Classes including this mixin should implement at #name method describing
 # the value being resolved and a #resolve_value that actually executes the code
 # to resolve the value.
+#
+# @api private
+# @since 0.1.0
 module RFacter::Core::Resolvable
 
   # The timeout, in seconds, for evaluating this resolution.
@@ -19,11 +22,11 @@ module RFacter::Core::Resolvable
   # Return the timeout period for resolving a value.
   # (see #timeout)
   # @return [Numeric]
-  # @comment requiring 'timeout' stdlib class causes Object#timeout to be
-  #   defined which delegates to Timeout.timeout. This method may potentially
-  #   overwrite the #timeout attr_reader on this class, so we define #limit to
-  #   avoid conflicts.
   def limit
+    # requiring 'timeout' stdlib class causes Object#timeout to be defined
+    # which delegates to Timeout.timeout. This method may potentially overwrite
+    # the #timeout attr_reader on this class, so we define #limit to avoid
+    # conflicts.
     @timeout || 0
   end
 
@@ -39,8 +42,7 @@ module RFacter::Core::Resolvable
   # Please see the Solaris zones fact for an example of how this feature may be
   # used.
   #
-  # @see Facter::Util::Fact#flush
-  # @see Facter::Util::Resolution#flush
+  # @see RFacter::Util::Fact#flush
   #
   # @api public
   def on_flush(&block)
@@ -48,10 +50,9 @@ module RFacter::Core::Resolvable
   end
 
   ##
-  # flush executes the block, if any, stored by the {on_flush} method
+  # flush executes the block, if any, stored by the {#on_flush} method
   #
-  # @see Facter::Util::Fact#flush
-  # @see Facter::Util::Resolution#on_flush
+  # @see RFacter::Util::Fact#flush
   #
   # @api private
   def flush
@@ -82,13 +83,16 @@ module RFacter::Core::Resolvable
   private
 
   def with_timing
-    starttime = Time.now.to_f
-
-    yield
+    unless @config.profile
+      yield
+    else
+      starttime = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+      yield
+      finishtime = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
 
-    finishtime = Time.now.to_f
-    ms = (finishtime - starttime) * 1000
-    #::Facter.show_time "#{qualified_name}: #{"%.2f" % ms}ms"
+      elapsed = (finishtime - starttime)
+      logger.info { "#{qualified_name}: #{"%.2f" % elapsed}ms" }
+    end
   end
 
   def qualified_name

data/lib/rfacter/core/suitable.rb

@@ -4,7 +4,10 @@ require 'rfacter'
 # certain platforms and determining the run precedence of these objects.
 #
 # Classes that include the Suitable mixin should define a `#confines` method
-# that returns an Array of zero or more Facter::Util::Confine objects.
+# that returns an Array of zero or more {RFacter::Util::Confine} objects.
+#
+# @api private
+# @since 0.1.0
 module RFacter::Core::Suitable
   require_relative '../util/confine'
 
@@ -18,8 +21,6 @@ module RFacter::Core::Suitable
   # @param weight [Integer] the weight of this resolution
   #
   # @return [void]
-  #
-  # @api public
   def has_weight(weight)
     @weight = weight
   end
@@ -29,8 +30,6 @@ module RFacter::Core::Suitable
   #
   # @return [void]
   #
-  # @api public
-  #
   # @overload confine(confines)
   #   Confine a fact to a specific fact value or values.  This form takes a
   #   hash of fact names and values. Every fact must match the values given for
@@ -40,7 +39,7 @@ module RFacter::Core::Suitable
   #   @param [Hash{String,Symbol=>String,Array<String>}] confines set of facts identified by the hash keys whose
   #     fact value must match the argument value.
   #   @example Confining to Linux
-  #       Facter.add(:powerstates) do
+  #       RFacter.add(:powerstates) do
   #         # This resolution only makes sense on linux systems
   #         confine :kernel => "Linux"
   #         setcode do
@@ -56,7 +55,7 @@ module RFacter::Core::Suitable
   #   @param [Proc] block determines the suitability of the fact.  If the block
   #     evaluates to `false` or `nil` then the confined fact will not be
   #     evaluated.
-  #   @yield [value] the value of the fact identified by {confines}
+  #   @yield [value] the value of the fact identified by `confines`
   #   @example Confine the fact to a host with an ipaddress in a specific
   #     subnet
   #       confine :ipaddress do |addr|
@@ -95,8 +94,6 @@ module RFacter::Core::Suitable
   # specific resolution wins over a less specific one).
   #
   # @return [Integer] the weight of this resolution
-  #
-  # @api private
   def weight
     if @weight
       @weight
@@ -106,8 +103,6 @@ module RFacter::Core::Suitable
   end
 
   # Is this resolution mechanism suitable on the system in question?
-  #
-  # @api private
   def suitable?
     @confines.all? { |confine| confine.true? }
   end

data/lib/rfacter/dsl.rb

@@ -7,9 +7,10 @@ require_relative 'util/non_nullable'
 # Facter compatibility layer
 #
 # This module exists to provide compatibility shims for Facter DSL methods as
-# exposed by the Facter 3.0 Ruby API. Any fact source code that is executed
-# within the {RFacter::Util} namespace via `instance_eval` should pick up on
-# these shims. The methods in this module should never be called directly.
+# exposed by the Facter 3 Ruby Extension API. Any fact source code that is
+# loaded into a {RFacter::Util::Collection} instance via `instance_eval`
+# should pick up on these shims. The methods in this module should never be
+# called outside of files that define custom facts.
 #
 # However, lexical scope is a tricky thing, so "should" is the operative word
 # here.
@@ -60,7 +61,7 @@ EOS
     #   of {RFacter::Util::Fact} and {Facter::Util::Resolution} can be
     #   supplied here
     # @option options [Integer] :timeout set the
-    #   {RFacter::Util::Resolution#timeout timeout} for this resolution
+    #   {RFacter::Core::Resolvable#timeout timeout} for this resolution
     # @param block [Proc] a block defining a fact resolution
     #
     # @return [RFacter::Util::Fact] the fact object, which includes any previously
@@ -104,7 +105,7 @@ EOS
     #
     # @return [RFacter::Util::Fact] The fact that was defined
     #
-    # @see {RFacter::Util::Collection#define_fact}
+    # @see RFacter::Util::Collection#define_fact
     def self.define_fact(name, options = {}, &block)
       COLLECTION.value.define_fact(name, options, &block)
     end
@@ -116,7 +117,7 @@ EOS
     #
     # @return [void]
     def self.each
-      COLLECTION.value.each(NODE.value) do |*args|
+      COLLECTION.value.each do |*args|
         yield(*args)
       end
     end
@@ -185,7 +186,7 @@ EOS
     #
     # @return [Hash{String => Object}] the hash of fact names and values
     def self.to_hash
-      COLLECTION.value.to_hash(NODE.value)
+      COLLECTION.value.to_hash
     end
 
     # Gets the value for a fact.
@@ -195,7 +196,7 @@ EOS
     # @return [Object, nil] the value of the fact, or nil if no fact is
     #   found
     def self.value(name)
-      COLLECTION.value.value(name, NODE.value)
+      COLLECTION.value.value(name)
     end
 
     # Returns the current RFacter version
@@ -304,11 +305,11 @@ EOS
     # Facter::Util DSL methods
     module Util
       require_relative 'util/fact'
-      # (see RFacter::Util::Fact)
+      # @see RFacter::Util::Fact
       Fact = ::RFacter::Util::Fact
 
       require_relative 'util/resolution'
-      # (see RFacter::Util::Resolution)
+      # @see RFacter::Util::Resolution
       Resolution = ::RFacter::Util::Resolution
 
       # Methods for interacting with remote files.

data/lib/rfacter/facts/os.rb

@@ -40,21 +40,56 @@ Facter.add(:os, :type => :aggregate) do
     # stats and reads, so multiple file ops only incur a cost once. However,
     # these ops are all going over the network, so we should probably
     # prioritize RedHat and SuSE detection over less common Linuxen in order to
-    # cut down on network chatter that will be useless in most cases. Also,
-    # might be worth adding /etc/os-release detection at the front of the list
-    # since that's the new hotness from systemd standardization.
+    # cut down on network chatter that will be useless in most cases.
     operatingsystem = nil
 
-    operatingsystem = if Facter.value(:kernel) == "GNU/kFreeBSD"
-      "GNU/kFreeBSD"
-    elsif Facter::Util::FileRead.exists?('/etc/debian_version')
-      case Facter::Core::Execution.exec('lsb_release -i')
-      when /Ubuntu/i
-        'Ubuntu'
-      when /LinuxMint/i
-        'LinuxMint'
-      else
-        'Debian'
+    # Determine OS name from /etc/os-release if it exists.
+    #
+    # see: https://www.freedesktop.org/software/systemd/man/os-release.html
+    if Facter::Util::FileRead.exists?('/etc/os-release')
+      os_release = Facter::Util::FileRead.read('/etc/os-release')
+      # NOTE: The ID field is used instead of NAME as ID was explicitly
+      # designed to be parsed by scripts whereas NAME is for human consumption.
+      os_id = os_release.lines.find {|l| l.start_with?('ID=')}
+
+      unless os_id.nil?
+        operatingsystem = case os_id
+                          when /debian/i
+                            'Debian'
+                          when /ubuntu/i
+                            'Ubuntu'
+                          when /opensuse/i
+                            'OpenSuSE'
+                          when /sles/i
+                            'SLES'
+                          when /fedora/i
+                            'Fedora'
+                          when /centos/i
+                            'CentOS'
+                          when /ol/i
+                            'OracleLinux'
+                          when /rhel/i
+                            'RedHat'
+                          when /amzn/i
+                            'Amazon'
+                          else
+                            os_id.scan(/^(?:\w+)=[\"']?(.+?)[\"']?$/).flatten.first
+                          end
+      end
+    end
+
+    if operatingsystem.nil?
+      operatingsystem = if Facter.value(:kernel) == "GNU/kFreeBSD"
+        "GNU/kFreeBSD"
+      elsif Facter::Util::FileRead.exists?('/etc/debian_version')
+        case Facter::Core::Execution.exec('lsb_release -i')
+        when /Ubuntu/i
+          'Ubuntu'
+        when /LinuxMint/i
+          'LinuxMint'
+        else
+          'Debian'
+        end
       end
     end
 

data/lib/rfacter/factset.rb

@@ -0,0 +1,116 @@
+require 'forwardable'
+
+require 'rfacter'
+
+require_relative 'config'
+require_relative 'node'
+require_relative 'util/collection'
+
+# A class that can retrieve facts from several nodes
+#
+# A factset joins instances of {RFacter::Node} to {RFacter::Util::Collection}
+# and enables parallel and asynchronous resolution of fact values across
+# several nodes. Supports retrieving single facts asynchronously via {#fetch}
+# and in a blocking fashion via {#value}. All facts can be retrieved
+# asynchronously via {#fetch_all} and in a blocking fashion via {#to_hash}.
+#
+# @api public
+# @since 0.1.0
+class RFacter::Factset
+  extend Forwardable
+
+  instance_delegate([:logger] => :@config)
+
+  # Returns a new instance of Factset
+  #
+  # @param nodes [Array<RFacter::Node>] An array of node objects to collect
+  #   facts from.
+  def initialize(nodes, config: RFacter::Config.config, **opts)
+    @config = config
+
+    @collections = nodes.each_with_object({}) do |node, hash|
+      hash[node.id] = RFacter::Util::Collection.new(node)
+    end
+  end
+
+  # Asynchronously fetch the value of a fact from each node
+  #
+  # This method spawns a background thread per node which resolves the value
+  # of a fact specified by `query`.
+  #
+  # @param queries [Array<String>] The names of the facts to fetch.
+  #
+  # @return [Concurrent::Future{String => Hash}]
+  #   A future that will return a hash mapping the node id to a hash containing
+  #   the resolved facts when `value` is called.
+  def fetch(queries)
+    queries = Array(queries)
+    # Spawn async lookups in the background for each node.
+    futures = @collections.each_with_object({}) do |(name, collection), hash|
+      hash[name] = {}
+      queries.each do |query|
+        hash[name][query] = collection.async.value(query)
+      end
+    end
+
+    # Return a future with the resolved values.
+    Concurrent::Future.execute do
+      futures.each_with_object({}) do |(name, ivars), hash|
+        hash[name] = ivars.each_with_object({}) do |(query, ivar), results|
+          # TODO: Add exception handling for failed futures.
+          results[query] = ivar.value
+        end
+      end
+    end
+  end
+
+  # Fetch the value of a fact from each node
+  #
+  # This method calls {#fetch} and then blocks until the result is available.
+  #
+  # @return [Hash{String => Hash}]
+  #   A hash mapping the node id to a hash containing the resolved facts.
+  def value(queries)
+    fetch(queries).value
+  end
+
+  # Asynchronously fetch all facts from each node
+  #
+  # This method spawns a background thread per node which resolves all
+  # fact values for each node.
+  #
+  # @return [Concurrent::Future{String => Hash}]
+  #   A future that will return a hash mapping the node id to a hash containing
+  #   the resolved facts when `value` is called.
+  def fetch_all
+    futures = @collections.each_with_object({}) do |(name, collection), hash|
+      collection.async.load_all
+      hash[name] = collection.async.to_hash
+    end
+
+    Concurrent::Future.execute do
+      futures.each_with_object({}) do |(name, future), hash|
+        # TODO: Add exception handling for failed futures.
+        hash[name] = future.value
+      end
+    end
+  end
+
+  # Fetch all facts from each node
+  #
+  # This method calls {#fetch_all} and then blocks until the result
+  # is available.
+  #
+  # @return [Hash{String => Hash}]
+  #   A hash mapping the node id to a hash containing the resolved facts.
+  def to_hash
+    fetch_all.value
+  end
+
+  # Flush cached fact values
+  #
+  # @return [void]
+  def flush
+    @collections.values.each {|c| c.flush}
+  end
+end

data/lib/rfacter/node.rb

@@ -13,6 +13,7 @@ require 'concurrent'
 # @note This class should be refacter to provide an abstracted interface to
 #   different transport backends like Train, Vagrant, Chloride, etc.
 #
+# @api public
 # @since 0.1.0
 class RFacter::Node
   extend Forwardable
@@ -34,10 +35,17 @@ class RFacter::Node
   attr_reader :password
   # @return [Hash]
   attr_reader :options
+  # @return [String]
+  attr_reader :id
 
   attr_reader :transport
 
-  def initialize(uri, config: RFacter::Config.config, **opts)
+  # Returns a new instance of Node
+  #
+  # @param uri [URI] The URI of the node.
+  # @param id [String, nil] An optional string to use when identifying
+  #   this node.
+  def initialize(uri, id: nil, config: RFacter::Config.config, **opts)
     @config = config
 
     @uri = unless uri.is_a?(URI)
@@ -67,6 +75,20 @@ class RFacter::Node
     @options = @uri.query.nil? ? Hash.new : CGI.parse(@uri.query)
     @options.update(opts)
 
+    @id = unless id.nil?
+            id
+          else
+            # Create a default from the URI, minus the password and options
+            # components.
+            id_string = "#{@scheme}://"
+            id_string += "#{@user}@" unless @user.nil?
+            id_string += @hostname
+            id_string += ":#{@port}" unless @port.nil?
+            id_string
+          end
+
+    @id.freeze
+
     # TODO: This should be abstracted.
     @transport = Train.create(@scheme,
       host: @hostname,
@@ -135,3 +157,39 @@ class RFacter::Node
     connection.file(path)
   end
 end
+
+
+# Hello dear reader. Hiding at the bottom of this file is a consequence of bad
+# design decisions in Ruby --- specifically the Kernel.autoload feature. Train
+# uses autload to lazily require its subcomponents. However, autoload plays
+# filthy tricks with the resolution of Constants that are not thread-safe. So,
+# this chunk of code is sitting down here out of sight to force these autoloads
+# to be resolved up front so that we can get on with the business of actually
+# saving significant time by using parallelism.
+#
+# See:
+#   http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-core/41149
+#   http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-core/20238
+#
+# TODO: Remove if this PR lands:
+#   https://github.com/chef/train/pull/178
+require 'train/plugins/transport'
+require 'train/plugins/base_connection'
+
+require 'train/transports/ssh'
+require 'train/transports/ssh_connection'
+require 'train/transports/winrm'
+require 'train/transports/winrm_connection'
+require 'train/transports/local'
+require 'train/transports/local_file'
+require 'train/transports/local_os'
+
+require 'train/extras'
+require 'train/extras/command_wrapper'
+require 'train/extras/file_common'
+require 'train/extras/file_unix'
+require 'train/extras/file_aix'
+require 'train/extras/file_linux'
+require 'train/extras/file_windows'
+require 'train/extras/os_common'
+require 'train/extras/stat'

data/lib/rfacter/util/collection.rb

@@ -1,16 +1,22 @@
 require 'forwardable'
 
+require 'concurrent'
+
 require 'rfacter'
 require_relative '../config'
 require_relative '../dsl'
 require_relative 'loader'
 require_relative 'fact'
 
-# Manage which facts exist and how we access them.  Largely just a wrapper
-# around a hash of facts.
+# Manage which facts exist on a Node and how we access them.
+#
+# Largely just a wrapper around a hash of facts that have been retrieved from a
+# particular node.
 #
 # @api private
+# @since 0.1.0
 class RFacter::Util::Collection
+  include Concurrent::Async
   # Ensures unqualified namespaces like `Facter` and `Facter::Util` get
   # re-directed to RFacter shims when the loader calls `instance_eval`
   include RFacter::DSL
@@ -18,15 +24,21 @@ class RFacter::Util::Collection
 
   instance_delegate([:logger] => :@config)
 
-  def initialize(config: RFacter::Config.config, **opts)
+  # Initialize a new Collection object
+  #
+  # @param node [RFacter::Node] The node from which this collection
+  #   should retrieve facts.
+  def initialize(node, config: RFacter::Config.config, **opts)
+    @node = node
     @config = config
+
     @facts = Hash.new
     @internal_loader = RFacter::Util::Loader.new
   end
 
   # Return a fact object by name.
-  def [](name, node)
-    value(name, node)
+  def [](name)
+    value(name)
   end
 
   # Define a new fact or extend an existing fact.
@@ -34,7 +46,7 @@ class RFacter::Util::Collection
   # @param name [Symbol] The name of the fact to define
   # @param options [Hash] A hash of options to set on the fact
   #
-  # @return [Facter::Util::Fact] The fact that was defined
+  # @return [RFacter::Util::Fact] The fact that was defined
   def define_fact(name, options = {}, &block)
     fact = create_or_return_fact(name, options)
 
@@ -53,7 +65,7 @@ class RFacter::Util::Collection
   # @param name [Symbol] The name of the fact to define
   # @param options [Hash] A hash of options to set on the fact and resolution
   #
-  # @return [Facter::Util::Fact] The fact that was defined
+  # @return [RFacter::Util::Fact] The fact that was defined
   def add(name, options = {}, &block)
     fact = create_or_return_fact(name, options)
 
@@ -65,11 +77,11 @@ class RFacter::Util::Collection
   include Enumerable
 
   # Iterate across all of the facts.
-  def each(node)
+  def each
     load_all
 
-    RFacter::DSL::COLLECTION.bind(self) do
-      RFacter::DSL::NODE.bind(node) do
+    COLLECTION.bind(self) do
+      NODE.bind(@node) do
         @facts.each do |name, fact|
           value = fact.value
           unless value.nil?
@@ -118,24 +130,22 @@ class RFacter::Util::Collection
   end
 
   # Return a hash of all of our facts.
-  def to_hash(node)
-    @facts.inject({}) do |h, ary|
-      resolved_value = RFacter::DSL::COLLECTION.bind(self) do
-        RFacter::DSL::NODE.bind(node) do
-          ary[1].value
+  def to_hash
+    COLLECTION.bind(self) do
+      NODE.bind(@node) do
+        @facts.each_with_object({}) do |(name, fact), hash|
+          resolved_value = fact.value
+
+          # For backwards compatibility, convert the fact name to a string.
+          hash[name.to_s] = resolved_value unless resolved_value.nil?
         end
       end
-
-      # For backwards compatibility, convert the fact name to a string.
-      h[ary[0].to_s] = resolved_value unless resolved_value.nil?
-
-      h
     end
   end
 
-  def value(name, node)
-    RFacter::DSL::COLLECTION.bind(self) do
-      RFacter::DSL::NODE.bind(node) do
+  def value(name)
+    COLLECTION.bind(self) do
+      NODE.bind(@node) do
         if fact = fact(name)
           fact.value
         end
@@ -153,8 +163,6 @@ class RFacter::Util::Collection
     if fact.nil?
       fact = RFacter::Util::Fact.new(name, options)
       @facts[name] = fact
-    else
-      fact.extract_ldapname_option!(options)
     end
 
     fact

data/lib/rfacter/util/confine.rb

@@ -7,6 +7,9 @@ require_relative 'values'
 
 # A restricting tag for fact resolution mechanisms.  The tag must be true
 # for the resolution mechanism to be suitable.
+#
+# @api private
+# @since 0.1.0
 class RFacter::Util::Confine
   extend Forwardable
 

data/lib/rfacter/util/fact.rb

@@ -4,11 +4,12 @@ require 'rfacter'
 require_relative '../config'
 
 # This class represents a fact. Each fact has a name and multiple
-# {Facter::Util::Resolution resolutions}.
+# {RFacter::Util::Resolution resolutions}.
 #
-# Create facts using {Facter.add}
+# Create facts using {RFacter::DSL::Facter.add Facter.add}
 #
-# @api public
+# @api private
+# @since 0.1.0
 class RFacter::Util::Fact
   require_relative '../core/aggregate'
   require_relative 'resolution'
@@ -21,40 +22,27 @@ class RFacter::Util::Fact
   # @return [String]
   attr_accessor :name
 
-  # @return [String]
-  # @deprecated
-  attr_accessor :ldapname
-
-  # Creates a new fact, with no resolution mechanisms. See {Facter.add}
+  # Creates a new fact, with no resolution mechanisms. See {RFacter::DSL::Facter.add}
   # for the public API for creating facts.
   # @param name [String] the fact name
   # @param options [Hash] optional parameters
-  # @option options [String] :ldapname set the ldapname property on the fact
-  #
-  # @api private
   def initialize(name, config: RFacter::Config.config, **options)
     @name = name.to_s.downcase.intern
     @config = config
 
-    extract_ldapname_option!(options)
-
-    @ldapname ||= @name.to_s
-
     @resolves = []
     @searching = false
 
     @value = nil
   end
 
-  # Adds a new {Facter::Util::Resolution resolution}.  This requires a
+  # Adds a new {RFacter::Util::Resolution resolution}.  This requires a
   # block, which will then be evaluated in the context of the new
   # resolution.
   #
   # @param options [Hash] A hash of options to set on the resolution
   #
-  # @return [Facter::Util::Resolution]
-  #
-  # @api private
+  # @return [RFacter::Util::Resolution]
   def add(options = {}, &block)
     define_resolution(nil, options, &block)
   end
@@ -64,9 +52,7 @@ class RFacter::Util::Fact
   #
   # @param resolution_name [String] The name of the resolve to define or look up
   # @param options [Hash] A hash of options to set on the resolution
-  # @return [Facter::Util::Resolution]
-  #
-  # @api public
+  # @return [RFacter::Util::Resolution]
   def define_resolution(resolution_name, options = {}, &block)
 
     resolution_type = options.delete(:type) || :simple
@@ -85,7 +71,7 @@ class RFacter::Util::Fact
   #
   # @param name [String]
   #
-  # @return [Facter::Util::Resolution, nil] The resolution if exists, nil if
+  # @return [RFacter::Util::Resolution, nil] The resolution if exists, nil if
   #   it doesn't exist or name is nil
   def resolution(name)
     return nil if name.nil?
@@ -96,18 +82,14 @@ class RFacter::Util::Fact
   # Flushes any cached values.
   #
   # @return [void]
-  #
-  # @api private
   def flush
     @resolves.each { |r| r.flush }
     @value = nil
   end
 
   # Returns the value for this fact. This searches all resolutions by
-  # suitability and weight (see {Facter::Util::Resolution}). If no
+  # suitability and weight (see {RFacter::Util::Resolution}). If no
   # suitable resolution is found, it returns nil.
-  #
-  # @api public
   def value
     return @value if @value
 
@@ -128,15 +110,6 @@ class RFacter::Util::Fact
     end
   end
 
-  # @api private
-  # @deprecated
-  def extract_ldapname_option!(options)
-    if options[:ldapname]
-      logger.warnonce("ldapname is deprecated and will be removed in a future version")
-      self.ldapname = options.delete(:ldapname)
-    end
-  end
-
   private
 
   # Are we in the midst of a search?

data/lib/rfacter/util/loader.rb

@@ -8,6 +8,7 @@ require_relative '../dsl'
 # Load facts on demand.
 #
 # @api private
+# @since 0.1.0
 class RFacter::Util::Loader
   extend Forwardable
 
@@ -20,7 +21,6 @@ class RFacter::Util::Loader
 
   # Load all resolutions for a single fact.
   #
-  # @api public
   # @param fact [Symbol]
   def load(fact, collection)
     # Now load from the search path
@@ -40,8 +40,6 @@ class RFacter::Util::Loader
   end
 
   # Load all facts from all directories.
-  #
-  # @api public
   def load_all(collection)
     return if defined?(@loaded_all)
 
@@ -69,7 +67,6 @@ class RFacter::Util::Loader
   # A warning will be generated for paths that are not
   # absolute directories.
   #
-  # @api public
   # @return [Array<String>]
   def search_path
     search_paths = [File.expand_path('../../facts', __FILE__)]

data/lib/rfacter/util/logger.rb

@@ -11,6 +11,7 @@ require 'rfacter'
 #   - `debugonce`
 #   - `log_exception`
 #
+# @api private
 # @since 0.1.0
 class RFacter::Util::Logger < ::Logger
   @@warn_messages = Hash.new

data/lib/rfacter/util/non_nullable.rb

@@ -8,6 +8,7 @@ require 'rfacter'
 # if de-referenced to `nil`. This allows the creation of variables
 # that must always be bound to a specific value before use.
 #
+# @api private
 # @since 0.1.0
 class RFacter::Util::NonNullable < Concurrent::ThreadLocalVar
   # @param err_message [String] The error message to raise if

data/lib/rfacter/util/normalization.rb

@@ -1,5 +1,9 @@
 require 'rfacter'
 
+# Routines for normalizing fact return values
+#
+# @api private
+# @since 0.1.0
 module RFacter
   module Util
     module Normalization
@@ -11,7 +15,6 @@ module RFacter
 
       # Recursively normalize the given data structure
       #
-      # @api public
       # @raise [NormalizationError] If the data structure contained an invalid element.
       # @return [void]
       def normalize(value)
@@ -33,46 +36,27 @@ module RFacter
       #
       # Attempt to normalize and validate the given string.
       #
-      # On Ruby 1.8 the string is checked by stripping out all non UTF-8
-      # characters and comparing the converted string to the original. If they
-      # do not match then the string is considered invalid.
+      # The string is validate by checking that the string encoding is UTF-8
+      # and that the string content matches the encoding. If the string is not
+      # an expected encoding then it is converted to UTF-8.
       #
-      # On Ruby 1.9+, the string is validate by checking that the string encoding
-      # is UTF-8 and that the string content matches the encoding. If the string
-      # is not an expected encoding then it is converted to UTF-8.
-      #
-      # @api public
       # @raise [NormalizationError] If the string used an unsupported encoding or did not match its encoding
       # @param value [String]
       # @return [void]
+      def normalize_string(value)
+        value = value.encode(Encoding::UTF_8)
 
-      if RUBY_VERSION =~ /^1\.8/
-        require 'iconv'
-
-        def normalize_string(value)
-          converted = Iconv.conv('UTF-8//IGNORE', 'UTF-8', value)
-          if converted != value
-            raise NormalizationError, "String #{value.inspect} is not valid UTF-8"
-          end
-          value
+        unless value.valid_encoding?
+          raise NormalizationError, "String #{value.inspect} doesn't match the reported encoding #{value.encoding}"
         end
-      else
-        def normalize_string(value)
-          value = value.encode(Encoding::UTF_8)
 
-          unless value.valid_encoding?
-            raise NormalizationError, "String #{value.inspect} doesn't match the reported encoding #{value.encoding}"
-          end
-
-          value
-        rescue EncodingError
-          raise NormalizationError, "String encoding #{value.encoding} is not UTF-8 and could not be converted to UTF-8"
-        end
+        value
+      rescue EncodingError
+        raise NormalizationError, "String encoding #{value.encoding} is not UTF-8 and could not be converted to UTF-8"
       end
 
       # Validate all elements of the array.
       #
-      # @api public
       # @raise [NormalizationError] If one of the elements failed validation
       # @param value [Array]
       # @return [void]
@@ -84,7 +68,6 @@ module RFacter
 
       # Validate all keys and values of the hash.
       #
-      # @api public
       # @raise [NormalizationError] If one of the keys or values failed normalization
       # @param value [Hash]
       # @return [void]

data/lib/rfacter/util/resolution.rb

@@ -6,14 +6,15 @@ require_relative '../config'
 # This represents a fact resolution. A resolution is a concrete
 # implementation of a fact. A single fact can have many resolutions and
 # the correct resolution will be chosen at runtime. Each time
-# {Facter.add} is called, a new resolution is created and added to the
-# set of resolutions for the fact named in the call.  Each resolution
-# has a {#has_weight weight}, which defines its priority over other
+# {RFacter::DSL::Facter.add Facter.add} is called, a new resolution is created
+# and added to the set of resolutions for the fact named in the call.  Each
+# resolution has a {#has_weight weight}, which defines its priority over other
 # resolutions, and a set of {#confine _confinements_}, which defines the
-# conditions under which it will be chosen. All confinements must be
-# satisfied for a fact to be considered _suitable_.
+# conditions under which it will be chosen. All confinements must be satisfied
+# for a fact to be considered _suitable_.
 #
-# @api public
+# @api private
+# @since 0.1.0
 class RFacter::Util::Resolution
   require_relative '../dsl'
   require_relative '../core/resolvable'
@@ -22,7 +23,6 @@ class RFacter::Util::Resolution
 
   instance_delegate([:logger] => :@config)
 
-  # @api private
   attr_accessor :code
   attr_writer :value
 
@@ -33,12 +33,10 @@ class RFacter::Util::Resolution
   # The name of this resolution. The resolution name should be unique with
   # respect to the given fact.
   # @return [String]
-  # @api public
   attr_accessor :name
 
   # @!attribute [r] fact
-  # @return [Facter::Util::Fact]
-  # @api private
+  # @return [RFacter::Util::Fact]
   attr_reader :fact
 
   def which(command)
@@ -53,8 +51,6 @@ class RFacter::Util::Resolution
   #
   # @param name [String] The name of the resolution.
   # @return [void]
-  #
-  # @api private
   def initialize(name, fact, config: RFacter::Config.config, **options)
     @name = name
     @fact = fact
@@ -83,14 +79,7 @@ class RFacter::Util::Resolution
 
     instance_eval(&block)
 
-    # Ruby 1.9+ provides the source location of procs which can provide useful
-    # debugging information if a resolution is being evaluated twice. Since 1.8
-    # doesn't support this we opportunistically provide this information.
-    if block.respond_to? :source_location
-      @last_evaluated = block.source_location.join(':')
-    else
-      @last_evaluated = true
-    end
+    @last_evaluated = block.source_location.join(':')
   end
 
   def set_options(options)
@@ -130,8 +119,6 @@ class RFacter::Util::Resolution
   #   @param [Proc] block The block to determine the resolution's value.
   #     This block is run when the fact is evaluated. Errors raised from
   #     inside the block are rescued and printed to stderr.
-  #
-  # @api public
   def setcode(string = nil, &block)
     if string
       @code = Proc.new do

data/lib/rfacter/util/values.rb

@@ -1,5 +1,9 @@
 require 'rfacter'
 
+# Helper methods for coercing items to JSON datatypes
+#
+# @api private
+# @since 0.1.0
 module RFacter
   module Util
     # A util module for facter containing helper methods

data/lib/rfacter/version.rb

@@ -1,3 +1,3 @@
 module RFacter
-  VERSION = '0.0.1'.freeze
+  VERSION = '0.1.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rfacter
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Charlie Sharpsteen
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-05-10 00:00:00.000000000 Z
+date: 2017-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: train
@@ -40,19 +40,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: inch
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '12.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '12.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -67,6 +67,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: |
   RFacter is a library for collecting facts from remote system(s) by executing
   commands over transports such as SSH and WinRM.
@@ -92,6 +106,7 @@ files:
 - lib/rfacter/facts/kernelversion.rb
 - lib/rfacter/facts/networking.rb
 - lib/rfacter/facts/os.rb
+- lib/rfacter/factset.rb
 - lib/rfacter/node.rb
 - lib/rfacter/util/collection.rb
 - lib/rfacter/util/confine.rb