octofacts 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 61e9a30a1976cdb0fb35f94e0d7a9c6447923719
+  data.tar.gz: 7db84b41abcd552aedc84346159cd3f67be8d68f
+SHA512:
+  metadata.gz: 559197f0fd9d352eb28bd862e3f87f1fb4acf95d25aed162f4f8f7815c87592a99997a5a595829ac95d76f24d2fabddbef8f551f7eff14a75ff453547e00a5a6
+  data.tar.gz: 4fc2845a2297be4ebc7225ad0145f186fffb69545f3e98c64d741ade9a807e514d4e881c3556e0d16a612f76c876a878a74ab58d116a79588d0c7864399a0d39

data/.version

@@ -0,0 +1 @@
+0.5.0

data/lib/octofacts.rb

@@ -0,0 +1,15 @@
+require "octofacts/constructors/from_file"
+require "octofacts/constructors/from_index"
+require "octofacts/manipulators"
+require "octofacts/errors"
+require "octofacts/facts"
+require "octofacts/backends/base"
+require "octofacts/backends/index"
+require "octofacts/backends/yaml_file"
+require "octofacts/util/config"
+require "octofacts/util/keys"
+require "octofacts/version"
+
+module Octofacts
+  #
+end

data/lib/octofacts/backends/base.rb

@@ -0,0 +1,35 @@
+module Octofacts
+  module Backends
+    # This is a template class to define the minimum API to be implemented
+    class Base
+      # Returns a hash of the facts selected based on current criteria. Once this is done,
+      # it is no longer possible to select, reject, or prefer.
+      def facts
+        # :nocov:
+        raise NotImplementedError, "This method needs to be implemented in the subclass"
+        # :nocov:
+      end
+
+      # Filters the possible fact sets based on the criteria.
+      def select(*)
+        # :nocov:
+        raise NotImplementedError, "This method needs to be implemented in the subclass"
+        # :nocov:
+      end
+
+      # Removes possible fact sets based on the criteria.
+      def reject(*)
+        # :nocov:
+        raise NotImplementedError, "This method needs to be implemented in the subclass"
+        # :nocov:
+      end
+
+      # Reorders possible fact sets based on the criteria.
+      def prefer(*)
+        # :nocov:
+        raise NotImplementedError, "This method needs to be implemented in the subclass"
+        # :nocov:
+      end
+    end
+  end
+end

data/lib/octofacts/backends/index.rb

@@ -0,0 +1,127 @@
+require "yaml"
+require "set"
+
+module Octofacts
+  module Backends
+    class Index < Base
+      attr_reader :index_path, :fixture_path, :options
+      attr_writer :facts
+      attr_accessor :nodes
+
+      def initialize(args = {})
+        index_path = Octofacts::Util::Config.fetch(:octofacts_index_path, args)
+        fixture_path = Octofacts::Util::Config.fetch(:octofacts_fixture_path, args)
+        strict_index = Octofacts::Util::Config.fetch(:octofacts_strict_index, args, false)
+
+        raise(ArgumentError, "No index passed and ENV['OCTOFACTS_INDEX_PATH'] is not defined") if index_path.nil?
+        raise(ArgumentError, "No fixture path passed and ENV['OCTOFACTS_FIXTURE_PATH'] is not defined") if fixture_path.nil?
+        raise(Errno::ENOENT, "The index file #{index_path} does not exist") unless File.file?(index_path)
+        raise(Errno::ENOENT, "The fixture path #{fixture_path} does not exist") unless File.directory?(fixture_path)
+
+        @index_path = index_path
+        @fixture_path = fixture_path
+        @strict_index = strict_index == true || strict_index == "true"
+        @facts = nil
+        @options = args
+
+        @node_facts = {}
+
+        # If there are any other arguments treat them as `select` conditions.
+        remaining_args = args.dup
+        remaining_args.delete(:octofacts_index_path)
+        remaining_args.delete(:octofacts_fixture_path)
+        remaining_args.delete(:octofacts_strict_index)
+        select(remaining_args) if remaining_args
+      end
+
+      def facts
+        @facts ||= node_facts(nodes.first)
+      end
+
+      def select(conditions)
+        Octofacts::Util::Keys.desymbolize_keys!(conditions)
+        conditions.each do |key, value|
+          add_fact_to_index(key) unless indexed_fact?(key)
+          matching_nodes = index[key][value.to_s]
+          raise Octofacts::Errors::NoFactsError if matching_nodes.nil?
+          self.nodes = nodes & matching_nodes
+        end
+
+        self
+      end
+
+      def reject(conditions)
+        matching_nodes = nodes
+        Octofacts::Util::Keys.desymbolize_keys!(conditions)
+        conditions.each do |key, value|
+          add_fact_to_index(key) unless indexed_fact?(key)
+          unless index[key][value.to_s].nil?
+            matching_nodes -= index[key][value.to_s]
+            raise Octofacts::Errors::NoFactsError if matching_nodes.empty?
+          end
+        end
+
+        self.nodes = matching_nodes
+        self
+      end
+
+      def prefer(conditions)
+        Octofacts::Util::Keys.desymbolize_keys!(conditions)
+        conditions.each do |key, value|
+          add_fact_to_index(key) unless indexed_fact?(key)
+          matching_nodes = index[key][value.to_s]
+          unless matching_nodes.nil?
+            self.nodes = (matching_nodes.to_set + nodes.to_set).to_a
+          end
+        end
+
+        self
+      end
+
+      private
+
+      # If a select/reject/prefer is called and the fact is not in the index, this will
+      # load the fact files for all currently eligible nodes and then add the fact to the
+      # in-memory index. This can be memory-intensive and time-intensive depending on the
+      # number of fact fixtures, so it is possible to disable this by passing
+      # `:strict_index => true` to the backend constructor, or by setting
+      # ENV["OCTOFACTS_STRICT_INDEX"] = "true" in the environment.
+      def add_fact_to_index(fact)
+        if @strict_index || ENV["OCTOFACTS_STRICT_INDEX"] == "true"
+          raise Octofacts::Errors::FactNotIndexed, "Fact #{fact} is not indexed and strict indexing is enabled."
+        end
+
+        index[fact] ||= {}
+        nodes.each do |node|
+          v = node_facts(node)[fact]
+          if v.nil?
+            # TODO: Index this somehow
+          else
+            index[fact][v.to_s] ||= []
+            index[fact][v.to_s] << node
+          end
+        end
+      end
+
+      def nodes
+        @nodes ||= index["_nodes"]
+      end
+
+      def index
+        @index ||= YAML.safe_load(File.read(index_path))
+      end
+
+      def indexed_fact?(fact)
+        index.key?(fact)
+      end
+
+      def node_facts(node)
+        @node_facts[node] ||= begin
+          f = YAML.safe_load(File.read("#{fixture_path}/#{node}.yaml"))
+          Octofacts::Util::Keys.desymbolize_keys!(f)
+          f
+        end
+      end
+    end
+  end
+end

data/lib/octofacts/backends/yaml_file.rb

@@ -0,0 +1,39 @@
+require "yaml"
+
+module Octofacts
+  module Backends
+    class YamlFile < Base
+      attr_reader :filename, :options
+
+      def initialize(filename, options = {})
+        raise(Errno::ENOENT, "The file #{filename} does not exist") unless File.file?(filename)
+
+        @filename = filename
+        @options  = options
+        @facts    = nil
+      end
+
+      def facts
+        @facts ||= begin
+          f = YAML.safe_load(File.read(filename))
+          Octofacts::Util::Keys.symbolize_keys!(f)
+          f
+        end
+      end
+
+      def select(conditions)
+        Octofacts::Util::Keys.symbolize_keys!(conditions)
+        raise Octofacts::Errors::NoFactsError unless (conditions.to_a - facts.to_a).empty?
+      end
+
+      def reject(conditions)
+        Octofacts::Util::Keys.symbolize_keys!(conditions)
+        raise Octofacts::Errors::NoFactsError if (conditions.to_a - facts.to_a).empty?
+      end
+
+      def prefer(conditions)
+        # noop
+      end
+    end
+  end
+end

data/lib/octofacts/constructors/from_file.rb

@@ -0,0 +1,18 @@
+module Octofacts
+  # Octofacts.from_file(filename, options) - Construct Octofacts::Facts from a filename.
+  #
+  # filename - Relative or absolute path to the file containing the facts.
+  # opts[:octofacts_fixture_path] - Directory where fact fixture files are found (default: ENV["OCTOFACTS_FIXTURE_PATH"])
+  #
+  # Returns an Octofacts::Facts object.
+  def self.from_file(filename, opts = {})
+    unless filename.start_with? "/"
+      dir = Octofacts::Util::Config.fetch(:octofacts_fixture_path, opts)
+      raise ArgumentError, ".from_file needs to know :octofacts_fixture_path or environment OCTOFACTS_FIXTURE_PATH" unless dir
+      raise Errno::ENOENT, "The provided fixture path #{dir} is invalid" unless File.directory?(dir)
+      filename = File.join(dir, filename)
+    end
+
+    Octofacts::Facts.new(backend: Octofacts::Backends::YamlFile.new(filename), options: opts)
+  end
+end

data/lib/octofacts/constructors/from_index.rb

@@ -0,0 +1,8 @@
+module Octofacts
+  # Octofacts.from_index(options) - Construct Octofacts::Facts from an index file.
+  #
+  # Returns an Octofacts::Facts object.
+  def self.from_index(opts = {})
+    Octofacts::Facts.new(backend: Octofacts::Backends::Index.new(opts), options: opts)
+  end
+end

data/lib/octofacts/errors.rb

@@ -0,0 +1,7 @@
+module Octofacts
+  class Errors
+    class FactNotIndexed < RuntimeError; end
+    class OperationNotPermitted < RuntimeError; end
+    class NoFactsError < RuntimeError; end
+  end
+end

data/lib/octofacts/facts.rb

@@ -0,0 +1,121 @@
+require "yaml"
+
+module Octofacts
+  class Facts
+    attr_writer :facts
+
+    # Constructor.
+    #
+    # backend - An Octofacts::Backends object (preferred)
+    # options - Additional options (e.g., downcase keys, symbolize keys, etc.)
+    def initialize(args = {})
+      @backend = args.fetch(:backend)
+      @facts_manipulated = false
+
+      options = args.fetch(:options, {})
+      @downcase_keys = args.fetch(:downcase_keys, options.fetch(:downcase_keys, true))
+    end
+
+    # To hash. (This method is intended to be called by rspec-puppet.)
+    #
+    # This loads the fact file and downcases, desymbolizes, and otherwise manipulates the keys.
+    # The output is suitable for consumption by rspec-puppet.
+    def to_hash
+      f = facts
+      downcase_keys!(f) if @downcase_keys
+      desymbolize_keys!(f)
+      f
+    end
+    alias_method :to_h, :to_hash
+
+    # To fact hash. (This method is intended to be called by developers.)
+    #
+    # This loads the fact file and downcases, symbolizes, and otherwise manipulates the keys.
+    # This is very similar to 'to_hash' except that it returns symbolized keys.
+    # The output is suitable for consumption by rspec-puppet (note that rspec-puppet will
+    # de-symbolize all the keys in the hash object though).
+    def facts
+      @facts ||= begin
+        f = @backend.facts
+        downcase_keys!(f) if @downcase_keys
+        symbolize_keys!(f)
+        f
+      end
+    end
+
+    # Calls to backend methods.
+    #
+    # These calls are passed through directly to backend methods.
+    def select(*args)
+      if @facts_manipulated
+        raise Octofacts::Errors::OperationNotPermitted, "Cannot call select() after backend facts have been manipulated"
+      end
+      @backend.select(*args)
+      self
+    end
+
+    def reject(*args)
+      if @facts_manipulated
+        raise Octofacts::Errors::OperationNotPermitted, "Cannot call reject() after backend facts have been manipulated"
+      end
+      @backend.reject(*args)
+      self
+    end
+
+    def prefer(*args)
+      if @facts_manipulated
+        raise Octofacts::Errors::OperationNotPermitted, "Cannot call prefer() after backend facts have been manipulated"
+      end
+      @backend.prefer(*args)
+      self
+    end
+
+    # Missing method - this is used to dispatch to manipulators or to call a Hash method in the facts.
+    #
+    # Try calling a Manipulator method, delegate to the facts hash or else error out.
+    #
+    # Returns this object (so that calls to manipulators can be chained).
+    def method_missing(name, *args, &block)
+      if Octofacts::Manipulators.run(self, name, *args, &block)
+        @facts_manipulated = true
+        return self
+      end
+
+      if facts.respond_to?(name, false)
+        if args[0].is_a?(String) || args[0].is_a?(Symbol)
+          args[0] = string_or_symbolized_key(args[0])
+        end
+        return facts.send(name, *args)
+      end
+
+      raise NameError, "Unknown method '#{name}' in #{self.class}"
+    end
+
+    def respond_to?(method, include_all = false)
+      camelized_name = (method.to_s).split("_").collect(&:capitalize).join
+      super || Kernel.const_get("Octofacts::Manipulators::#{camelized_name}")
+    rescue NameError
+      return facts.respond_to?(method, include_all)
+    end
+
+    private
+
+    def downcase_keys!(input)
+      Octofacts::Util::Keys.downcase_keys!(input)
+    end
+
+    def symbolize_keys!(input)
+      Octofacts::Util::Keys.symbolize_keys!(input)
+    end
+
+    def desymbolize_keys!(input)
+      Octofacts::Util::Keys.desymbolize_keys!(input)
+    end
+
+    def string_or_symbolized_key(input)
+      return input.to_s if facts.key?(input.to_s)
+      return input.to_sym if facts.key?(input.to_sym)
+      input
+    end
+  end
+end

data/lib/octofacts/manipulators.rb

@@ -0,0 +1,27 @@
+require_relative "manipulators/replace"
+
+# Octofacts::Manipulators - our fact manipulation API.
+# Each method in Octofacts::Manipulators will operate on one fact set at a time. These
+# methods do not need to be aware of the existence of multiple fact sets.
+module Octofacts
+  class Manipulators
+    # Locate and run manipulator.
+    #
+    # Returns true if the manipulator was located and executed, false otherwise.
+    def self.run(obj, name, *args, &block)
+      camelized_name = (name.to_s).split("_").collect(&:capitalize).join
+
+      begin
+        manipulator = Kernel.const_get("Octofacts::Manipulators::#{camelized_name}")
+      rescue NameError
+        return false
+      end
+
+      raise "Unable to run manipulator method '#{name}' on object type #{obj.class}" unless obj.is_a?(Octofacts::Facts)
+      facts = obj.facts
+      manipulator.send(:execute, facts, *args, &block)
+      obj.facts = facts
+      true
+    end
+  end
+end

data/lib/octofacts/manipulators/base.rb

@@ -0,0 +1,110 @@
+module Octofacts
+  class Manipulators
+    # Delete a fact from a hash.
+    #
+    # fact_set  - The hash of facts
+    # fact_name - Fact to delete, either as a string, symbol, or "multi::level::hash::key"
+    def self.delete(fact_set, fact_name)
+      if fact_name.to_s !~ /::/
+        fact_set.delete(fact_name.to_sym)
+        return
+      end
+
+      # Convert level1::level2::level3 into { "level1" => { "level2" => { "level3" => ... } } }
+      # The delimiter is 2 colons.
+      levels = fact_name.to_s.split("::")
+      key_name = levels.pop.to_sym
+      pointer = fact_set
+      while levels.any?
+        next_key = levels.shift.to_sym
+        return unless pointer.key?(next_key) && pointer[next_key].is_a?(Hash)
+        pointer = pointer[next_key]
+      end
+
+      pointer.delete(key_name)
+    end
+
+    # Determine if a fact exists in a hash.
+    #
+    # fact_set  - The hash of facts
+    # fact_name - Fact to check, either as a string, symbol, or "multi::level::hash::key"
+    #
+    # Returns true if the fact exists, false otherwise.
+    def self.exists?(fact_set, fact_name)
+      !get(fact_set, fact_name).nil?
+    end
+
+    # Retrieves the value of a fact from a hash.
+    #
+    # fact_set  - The hash of facts
+    # fact_name - Fact to retrieve, either as a string, symbol, or "multi::level::hash::key"
+    #
+    # Returns the value of the fact.
+    def self.get(fact_set, fact_name)
+      return fact_set[fact_name.to_sym] unless fact_name.to_s =~ /::/
+
+      # Convert level1::level2::level3 into { "level1" => { "level2" => { "level3" => ... } } }
+      # The delimiter is 2 colons.
+      levels = fact_name.to_s.split("::")
+      key_name = levels.pop.to_sym
+      pointer = fact_set
+      while levels.any?
+        next_key = levels.shift.to_sym
+        return unless pointer.key?(next_key) && pointer[next_key].is_a?(Hash)
+        pointer = pointer[next_key]
+      end
+      pointer[key_name]
+    end
+
+    # Sets the value of a fact in a hash.
+    #
+    # The new value can be a string, integer, etc., which will directly set the value of
+    # the fact. Instead, you may pass a lambda in place of the value, which will evaluate
+    # with three parameters: lambda { |fact_set|, |fact_name|, |old_value| ... },
+    # or with one parameter: lambda { |old_value| ...}.
+    # If the value of the fact as evaluated is `nil` then the fact is deleted instead of set.
+    #
+    # fact_set  - The hash of facts
+    # fact_name - Fact to set, either as a string, symbol, or "multi::level::hash::key"
+    # value     - A lambda with new code, or a string, integer, etc.
+    def self.set(fact_set, fact_name, value)
+      fact = fact_name.to_s
+
+      if fact !~ /::/
+        fact_set[fact_name.to_sym] = _set(fact_set, fact_name, fact_set[fact_name.to_sym], value)
+        fact_set.delete(fact_name.to_sym) if fact_set[fact_name.to_sym].nil?
+        return
+      end
+
+      # Convert level1::level2::level3 into { "level1" => { "level2" => { "level3" => ... } } }
+      # The delimiter is 2 colons.
+      levels = fact_name.to_s.split("::")
+      key_name = levels.pop.to_sym
+      pointer = fact_set
+      while levels.any?
+        next_key = levels.shift.to_sym
+        pointer[next_key] = {} unless pointer[next_key].is_a? Hash
+        pointer = pointer[next_key]
+      end
+      pointer[key_name] = _set(fact_set, fact_name, pointer[key_name], value)
+      pointer.delete(key_name) if pointer[key_name].nil?
+    end
+
+    # Internal method: Determine the value you're setting to.
+    #
+    # This handles dispatching to the lambda function or putting the new value in place.
+    def self._set(fact_set, fact_name, old_value, new_value)
+      if new_value.is_a?(Proc)
+        if new_value.arity == 1
+          new_value.call(old_value)
+        elsif new_value.arity == 3
+          new_value.call(fact_set, fact_name, old_value)
+        else
+          raise ArgumentError, "Lambda method expected 1 or 3 parameters, got #{new_value.arity}"
+        end
+      else
+        new_value
+      end
+    end
+  end
+end

data/lib/octofacts/manipulators/replace.rb

@@ -0,0 +1,20 @@
+require_relative "base"
+
+module Octofacts
+  class Manipulators
+    class Replace < Octofacts::Manipulators
+      # Public: Executor for the .replace command.
+      #
+      # Sets the fact to the specified value. If the fact didn't exist before, it's created.
+      #
+      # facts - Hash of current facts
+      # args  - Arguments, here consisting of an array of hashes with replacement parameters
+      def self.execute(facts, *args, &_block)
+        args.each do |arg|
+          raise ArgumentError, "Must pass a hash of target facts to .replace - got #{arg}" unless arg.is_a?(Hash)
+          arg.each { |key, val| set(facts, key, val) }
+        end
+      end
+    end
+  end
+end

data/lib/octofacts/util/config.rb

@@ -0,0 +1,28 @@
+# Retrieves configuration parameters from:
+#   - input hash
+#   - rspec configuration
+#   - environment
+module Octofacts
+  module Util
+    class Config
+      # Fetch a variable from various sources
+      def self.fetch(variable_name, hash_in = {}, default = nil)
+        if hash_in.key?(variable_name)
+          return hash_in[variable_name]
+        end
+
+        begin
+          rspec_value = RSpec.configuration.send(variable_name)
+          return rspec_value if rspec_value
+        rescue NoMethodError
+          # Just skip if undefined
+        end
+
+        env_key = variable_name.to_s.upcase
+        return ENV[env_key] if ENV.key?(env_key)
+
+        default
+      end
+    end
+  end
+end

data/lib/octofacts/util/keys.rb

@@ -0,0 +1,51 @@
+module Octofacts
+  module Util
+    class Keys
+      # Downcase all keys.
+      #
+      # rspec-puppet does this internally, but depending on how Octofacts is called, this logic may not
+      # be triggered. Therefore, we downcase all keys ourselves.
+      def self.downcase_keys!(input)
+        raise ArgumentError, "downcase_keys! expects Hash, not #{input.class}" unless input.is_a?(Hash)
+
+        input_keys = input.keys.dup
+        input_keys.each do |k|
+          downcase_keys!(input[k]) if input[k].is_a?(Hash)
+          next if k.to_s == k.to_s.downcase
+          new_key = k.is_a?(Symbol) ? k.to_s.downcase.to_sym : k.downcase
+          input[new_key] = input.delete(k)
+        end
+        input
+      end
+
+      # Symbolize all keys.
+      #
+      # Many people work with symbolized keys rather than string keys when dealing with fact fixtures.
+      # This method recursively converts all keys to symbols.
+      def self.symbolize_keys!(input)
+        raise ArgumentError, "symbolize_keys! expects Hash, not #{input.class}" unless input.is_a?(Hash)
+
+        input_keys = input.keys.dup
+        input_keys.each do |k|
+          symbolize_keys!(input[k]) if input[k].is_a?(Hash)
+          input[k.to_sym] = input.delete(k) unless k.is_a?(Symbol)
+        end
+        input
+      end
+
+      # De-symbolize all keys.
+      #
+      # rspec-puppet ultimately wants stringified keys, so this is a method to turn symbols back into strings.
+      def self.desymbolize_keys!(input)
+        raise ArgumentError, "desymbolize_keys! expects Hash, not #{input.class}" unless input.is_a?(Hash)
+
+        input_keys = input.keys.dup
+        input_keys.each do |k|
+          desymbolize_keys!(input[k]) if input[k].is_a?(Hash)
+          input[k.to_s] = input.delete(k) unless k.is_a?(String)
+        end
+        input
+      end
+    end
+  end
+end

data/lib/octofacts/version.rb

@@ -0,0 +1,3 @@
+module Octofacts
+  VERSION = File.read(File.expand_path("../../.version", File.dirname(__FILE__))).strip
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: octofacts
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- GitHub, Inc.
+- Kevin Paulisse
+- Antonio Santos
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-10-06 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Octofacts provides fact fixtures built from recently-updated Puppet facts to rspec-puppet tests.
+email: opensource+octofacts@github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".version"
+- lib/octofacts.rb
+- lib/octofacts/backends/base.rb
+- lib/octofacts/backends/index.rb
+- lib/octofacts/backends/yaml_file.rb
+- lib/octofacts/constructors/from_file.rb
+- lib/octofacts/constructors/from_index.rb
+- lib/octofacts/errors.rb
+- lib/octofacts/facts.rb
+- lib/octofacts/manipulators.rb
+- lib/octofacts/manipulators/base.rb
+- lib/octofacts/manipulators/replace.rb
+- lib/octofacts/util/config.rb
+- lib/octofacts/util/keys.rb
+- lib/octofacts/version.rb
+homepage: https://github.com/github/octofacts
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.5
+signing_key: 
+specification_version: 4
+summary: Run your rspec-puppet tests against fake hosts that present almost real facts
+test_files: []