animal 0.1.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3296620a0dcb0a63ba508e237b61fc602694605a
-  data.tar.gz: c87a5cf81777165105d7aabaa257d05646180f69
+  metadata.gz: 1140c1f29b1f085aa857b0d482ca652b35d7a163
+  data.tar.gz: 6db2af85595e560a055383d53f7d155298b40aea
 SHA512:
-  metadata.gz: 456b98beae377c1b89347d8fad2dc5ff1c2a8adfebaf0b002ebc36a065550a3c03b5708d2164ecb83a66c0f515b7e57c7726edf4e3189f01f68756d3f6a72174
-  data.tar.gz: 282ef5066e2b30767ff75a5af2d154d740c3413cfc25213b37159c4b14e440cef07cb0f9a244e28d4173fc78c14bc52a80ef70964135373bc81b6aee237b80c1
+  metadata.gz: f840514c53598913fe773fbd50db710ae76f5b0b481ae3da7b4f732fbec98d79040202c4b20f6c87cd853530c40d16bc7ceb0ee7ad83d98e1d1b580247fd0af4
+  data.tar.gz: fb70b089488a2081366c169ff5678e6c36d068c693db6efd9384d7e1944f73f762c0ce36040bd19b90db0032409408fb93b01b06cf3a4041f36c649402ddd4cb

data/.rubocop.yml

@@ -0,0 +1,17 @@
+Metrics/LineLength:
+  Max: 100
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/AbcSize:
+  Max: 22
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 8

data/.travis.yml

@@ -1,6 +1,14 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.2.5
-  - 2.3.1
+- 2.2.5
+- 2.3.1
 before_install: gem install bundler -v 1.12.5
+deploy:
+  provider: rubygems
+  api_key:
+    secure: Bvix9+hJrZhd9GTYZQ7yN+htm+iWpBigVdVybAu6NHx1+YwJbelCQ68hN1gpFI/bSTdUlaQup9M1SW2Nb4fzwGB2byya9bIgjrez6vDuZ6SbwrXnTVZ/w1lpDG2ZaPRDVYet7+Xn1WTEwDm/ANeL7Gi5CDB87w6vu/vBfoWcKU4jLZcAgVtZ1TlfBnM1rKKC896/Dt4wVh1PLDuKfx8XuLNFR4VCLjIM1S3vKD9vl/8VzuxJcZLCgRbNs5CmidQNPe3zEkTO9hvg1/p9UY6OardNeEPbkKNDNITJ5gggX6chZtni+1qYIWmeUHuo80PwrB/J1gODDkl4kmNtRdpf6UGbi/hJbXM7vDWr5VQzKmVVbHoNYaLWmnWCcmtRD0zk0BTEfemwFzqANKXpRFvQRvfwhLjwpg/agaKUwVzWoLHo3QBEbrMSsamY2uQcIlHxMgofrPVfDD+puLFOANKJB/M2Vrr6cVdGziavizYHPhRxXxr1/23oiOLk0B61PzfOZLKdk1v2/uPF44WkGSiqvvNJIJjw80EhNIFNGhDxlyZsM2z+1+CrW5FkaVlPS9mnVS6H21xHKLVWYwGLpAdG80YasVmGGpDXxEdHPpsn2qmFqSJWOPSPqsbb4FYKDnrCqYIYwESg6hNI7XDN65Bet3g/ve61D0K9EKeKAfdaNo4=
+  gem: animal
+  on:
+    tags: true
+    repo: knuedge/animal

data/README.md

@@ -1,8 +1,6 @@
 # Animal
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/animal`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Animal is a work-in-progress toward developing a flexible, modular, and powerful rule-based [Puppet](https://puppet.com/) [ENC](https://docs.puppet.com/guides/external_nodes.html) written in Ruby.
 
 ## Installation
 
@@ -22,7 +20,55 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Rules
+
+#### Rule Statement Syntax
+
+Animal uses a rules-based approach to classifying nodes, and its rules engine supports a simple yet powerful syntax for building conditions based on installed plugins. It utilizes a delayed merging approach for building a list of Puppet classes to apply to a node, meaning that _subtracting_ a class from a list of classes happens _after_ all the _add_ operations are complete, allowing a _subtract_ to be performed at any point in the rules system. The benefit is that rules need not be evaluated in any particular order.
+
+The actual syntax should be familiar enough for people used to writing either SQL or Puppet code. Here is an example of a simple rule statement:
+
+```
+Fact["certname"] = "machine.domain.tld"
+```
+
+This rule will use the `Fact` plugin (which is built-in to the core `Animal` library) to lookup the `certname` key and determines if it is equivalent to `"machine.domain.tld"`.
+
+A slightly more complicated rule might look like:
+
+```
+(Fact["machine_class"] = "server" AND Fact["os"] = "ubuntu") OR Fact["awesome"] = true
+```
+
+This rule will again use the `Fact` plugin (several times, in fact) to first check if both the `machine_class` fact is set to `"server"` _and_ the `os` fact is set to `"ubuntu"`, and only if either of those are `false`, the rule determines if the `awesome` fact is set to the literal `true` value.
+
+There are currently several limitations to the rules syntax, such as:
+
+* Parenthesis are required to force the order of operations for cojunctions (`AND` and `OR`), but is not used to determing which is actually applied first. Parenthesis are, in fact, collapsed before any preceeding conjunction is used, but in `A OR (B AND C)`, if `A` is `true` then `(B AND C)` is never evaluated.
+* Rules are recursively evaluated with an arity of 2, meaning they are always evaluated as `A then B` where `B` is one or more subrules. This means that `A AND B OR C` is equivalent to `A AND (B OR C)`.
+* Keys sent to plugins, such as `foo` in `Fact["foo"]`, must be double-quoted and can not contain `[`, `]`, or `"`.
+* Only these comparison operators are allowed for rules: `=`, `!=`, `>`, `>=`, `<`, `<=`, and `LIKE`. The `LIKE` comparison operator treats the provided value as a regular expression. Do not include the `/` before or after the regular expression.
+* Values used in comparisons must be either literal booleans (`true` or `false`), a double-quoted string (`"foo"`), or an Integer (`1`, `2`, etc.). Decimals must currently be treated as strings.
+
+#### Other Rule Components
+
+Besides the rule statement described above, rules also support two additional components, each with two subcomponents. When a rule evaluates to `true`, it is said to be applied successfully, so rules have a `success` component. Otherwise, rules provide a `failure` component for determining what to do when the rule evaluates to `false`. Both of these components are considered optional by the rules engine, though a rule that does nothing should be suspect.
+
+Each of these components support adding and subtracting Puppet classes from the final compiled list of classes returned by the ENC. These addition and subtraction operations are gathered then applied after all such operations are determined -- providing the delayed-merging capability of the tool. To add classes based on the outcome of a rule, define an Array of class names (usually roles or profiles) to return in an `add` section, either under `success` or `failure`. Likewise, define a `subtract` Array as needed.
+
+When using the YAML storage provider (currently the only supported storage provider for Animal), this could be an example rule:
+
+```
+- :statement: (Fact["machine_class"] = "server" AND Fact["os"] = "ubuntu") OR Fact["awesome"] = true
+  :success:
+    :add:
+    - roles::linux::server
+    - roles::awesome
+    :subtract:
+    - roles::linux::desktop
+```
+
+This rule will add `roles::linux::server` and `roles::awesome`, and will guarantee that `roles::linux::desktop` will not be present in the returned list of Puppet classes if the rule evaluates to `true` for a given Puppet node.
 
 ## Development
 
@@ -32,7 +78,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/animal.
+Bug reports and pull requests are welcome on GitHub at https://github.com/knuedge/animal.
 
 
 ## License

data/animal.gemspec

@@ -26,6 +26,8 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '~> 2.2'
   spec.post_install_message  = 'Thanks for installing Animal!'
 
+  spec.add_runtime_dependency 'treetop', '~> 1.6'
+
   spec.add_development_dependency 'bundler', '~> 1.12'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.1'

data/exe/animal_enc

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require 'animal'
+
+node_name = ARGV[0]
+
+# Must pass a node name
+raise 'Missing Node Name' unless node_name
+
+results = Animal::ENC.query(node_name, debug: true)
+exit unless results # no output on empty results
+
+puts results

data/exe/animal_import

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+
+require 'yaml'
+
+path_to_nodes_pp = ARGV[0]
+
+file_content = File.read(File.expand_path(path_to_nodes_pp))
+
+nodes = {}
+
+file_content.scan(/(^|\n)node ([^\s]+) ?\{([^}]+)\n(\s+)?\}/).each do |node|
+  name = node[1]
+  includes = node[2].delete("\n").split(/\s+include\s+/).select { |x| !x.empty? }.compact
+  nodes[name] = includes
+end
+
+# nodes.each { |k, v| puts "#{k} => [#{v.join(', ')}]" }
+
+rules = []
+nodes.each do |name, roles_and_profiles|
+  rule = {}
+  if name =~ %r{^/.+/$}
+    rule[:statement] = "Fact[\"certname\"] LIKE \"#{name}\""
+  else
+    rule[:statement] = "Fact[\"certname\"] = \"#{name.gsub(/(^['"]|['"]$)/, '')}\""
+  end
+
+  rule[:success] = { add: roles_and_profiles }
+  rules << rule
+end
+
+puts rules.to_yaml

data/lib/animal.rb

@@ -1,6 +1,18 @@
-require 'animal/version'
+ANIMAL_HOME = ENV['ANIMAL_HOME'] ? ENV['ANIMAL_HOME'] : File.expand_path(File.join('~', '.animal'))
+FileUtils.mkdir_p(ANIMAL_HOME) unless File.exist?(ANIMAL_HOME)
+
+# Standard Library requirements
+require 'yaml'
 
-# The Animal Puppet ENC
-module Animal
-  # Your code goes here...
-end
+# External requirements
+require 'treetop'
+
+# Internal requirements
+require 'animal/version'
+require 'animal/classifier'
+require 'animal/inventory_plugin'
+require 'animal/storage_plugin'
+require 'animal/plugins/inventory/fact'
+require 'animal/plugins/storage/yaml'
+require 'animal/rule'
+require 'animal/enc'

data/lib/animal/classifier.rb

@@ -0,0 +1,35 @@
+module Animal
+  # The class responsible for actually classifying a node
+  # The Classifier pulls together required plugins and config
+  class Classifier
+    def initialize(node_name)
+      @node_name = node_name
+    end
+
+    def classes
+      classify('classes')
+    end
+
+    def parameters
+      classify('parameters')
+    end
+
+    def environment
+      classify('environment')
+    end
+
+    def classify(type)
+      case type
+      when 'environment'
+        # TODO: look this up in a configuration somewhere
+        'production'
+      when 'classes'
+        Rule.apply_all_for(@node_name)
+      when 'parameters'
+        nil
+      else
+        raise 'Not Implemented'
+      end
+    end
+  end
+end

data/lib/animal/enc.rb

@@ -0,0 +1,23 @@
+module Animal
+  # As Animal is an ENC, this is the main class and entry point for Animal.
+  class ENC
+    def self.query(node_name, _opts = {})
+      classifier  = Classifier.new(node_name)
+      classes     = classifier.classes
+      parameters  = classifier.parameters
+      environment = classifier.environment
+      results     = {}
+
+      results['classes']     = classes if classes
+      results['parameters']  = parameters if parameters
+      results['environment'] = environment ? environment : 'production'
+
+      to_enc_output results
+    end
+
+    def self.to_enc_output(data = {})
+      return nil if data.empty? || (!data.key?('classes') && !data.key?('parameters'))
+      data.to_yaml
+    end
+  end
+end

data/lib/animal/inventory_plugin.rb

@@ -0,0 +1,9 @@
+module Animal
+  # The base class for inventory plugins
+  class InventoryPlugin
+    # Must be overridden
+    def self.get(_node, _key)
+      nil
+    end
+  end
+end

data/lib/animal/plugins/inventory/fact.rb

@@ -0,0 +1,25 @@
+module Animal
+  module Plugins
+    module Inventory
+      # The Facter integration inventory plugin mock-up
+      class Fact < InventoryPlugin
+        def self.get(node, key)
+          data = {
+            'dschaaff' => {
+              'certname' => 'dschaaff.local',
+              'machine_class' => 'server',
+              'os' => 'ubuntu'
+            },
+            'jgnagy' => {
+              'certname' => 'jgnagy.local',
+              'machine_class' => 'server',
+              'os' => 'darwin',
+              'awesome' => true
+            }
+          }
+          data.key?(node) && data[node].key?(key) ? data[node][key] : nil
+        end
+      end
+    end
+  end
+end

data/lib/animal/plugins/storage/yaml.rb

@@ -0,0 +1,19 @@
+module Animal
+  module Plugins
+    module Storage
+      # The basic, YAML storage plugin
+      class Yaml < StoragePlugin
+        def self.all(type)
+          # TODO: add caching in here...
+          results = []
+          Dir.chdir File.expand_path(File.join(ANIMAL_HOME, "#{type}.d")) do
+            Dir.glob('*.yml').each do |file|
+              results.concat ::YAML.load_file(file)
+            end
+          end
+          results
+        end
+      end
+    end
+  end
+end

data/lib/animal/rule.rb

@@ -0,0 +1,99 @@
+# The Animal namespace module
+module Animal
+  ## Treetop Rules Parsing
+  dir = File.expand_path(File.dirname(__FILE__))
+  Treetop.load File.expand_path(File.join(dir, 'rules'))
+
+  # The basis for the rules engine used for classifying nodes
+  class Rule
+    attr_reader :when_true, :when_false
+
+    def self.all
+      rules = []
+      Animal::Plugins::Storage::Yaml.all('rules').each do |data|
+        rules << if data.key?(:failure)
+                   Rule.new(data[:statement], data[:success], data[:failure])
+                 else
+                   Rule.new(data[:statement], data[:success])
+                 end
+      end
+      rules
+    end
+
+    def self.apply_all_for(node)
+      operations = { add: [], subtract: [] }
+      all.each do |rule|
+        result = rule.apply_for(node)
+        operations[:add].concat result[:add] if result.key?(:add)
+        operations[:subtract].concat result[:subtract] if result.key?(:subtract)
+      end
+      operations[:add].uniq - operations[:subtract]
+    end
+
+    def initialize(statement, when_true, when_false = {})
+      @statement  = statement
+      @when_true  = when_true
+      @when_false = when_false
+    end
+
+    def parse
+      parser = RulesParser.new
+      result = parser.parse(@statement)
+      result.conditions
+    end
+
+    # Used to evaluate the conditions provided by parsing a rule statement
+    # rubocop:disable Metrics/AbcSize
+    def evaluate(node, condition)
+      plugin = get_plugin_class(condition[:plugin]) if condition.key?(:plugin)
+      if [:and, :or].include?(condition[:conjunction])
+        recurse_on_conjunction(node, condition[:conditions], condition[:conjunction])
+      elsif condition[:operator] == :like
+        # Use the plugin to lookup a key and match it against the condition's value
+        plugin.get(node, condition[:key]).match(sanitize_regexp(condition[:value])) ? true : false
+      elsif condition[:operator] == '='.to_sym
+        plugin.get(node, condition[:key]) == condition[:value]
+      elsif ['!=', '>=', '<=', '>', '<'].include?(condition[:operator].to_s)
+        plugin.get(node, condition[:key]).send(condition[:operator], condition[:value])
+      else
+        false
+      end
+    end
+
+    def recurse_on_conjunction(node, conditions, conjunction)
+      subresult = nil
+      if conjunction == :and
+        conditions.each do |subcondition|
+          subresult = evaluate(node, subcondition)
+          break if subresult.is_a? FalseClass
+        end
+      elsif conjunction == :or
+        subresult = nil
+        conditions.each do |subcondition|
+          subresult = evaluate(node, subcondition)
+          break if subresult.is_a? TrueClass
+        end
+      end
+      subresult ? true : false
+    end
+
+    def sanitize_regexp(value)
+      value.gsub(%r{(^/|/$)}, '')
+    end
+
+    def apply_for(node)
+      evaluate(node, parse) ? @when_true : @when_false
+    rescue => e
+      # TODO: output something for debugging here since evaluate failed to run
+      STDERR.puts "Exception occurred on Rule#apply_for(#{node}) for `#{@statement}`: #{e.message}"
+      {}
+    end
+
+    private
+
+    # Constantize the plugin based on the class name
+    def get_plugin_class(name)
+      Class.const_get("Animal::Plugins::Inventory::#{name}")
+    end
+  end
+end

data/lib/animal/rules.treetop

@@ -0,0 +1,147 @@
+module Animal
+  grammar Rules
+    rule parenthesized_conditionals
+      parenthesized_conditional required_space boolean_join required_space parenthesized_conditionals {
+        def conditions
+          all_nodes = {}
+          all_nodes[:conditions]  = []
+          all_nodes[:conjunction] = boolean_join.conjunction
+          all_nodes[:conditions] << parenthesized_conditional.conditions
+          all_nodes[:conditions] << parenthesized_conditionals.conditions
+          all_nodes
+        end
+      }
+      / '(' parenthesized_conditionals ')' {
+        def conditions
+          parenthesized_conditionals.conditions
+        end
+      }
+      / parenthesized_conditional
+    end
+
+    rule parenthesized_conditional
+      '(' parenthesized_conditional ')' {
+          def conditions
+            parenthesized_conditional.conditions
+          end
+        }
+        / conditional_items
+    end
+
+    rule conditional_items
+      conditional_item required_space boolean_join required_space conditional_items {
+        def conditions
+          all_nodes = {}
+          all_nodes[:conditions]  = []
+          all_nodes[:conjunction] = boolean_join.conjunction
+          all_nodes[:conditions] << conditional_item.conditions
+          all_nodes[:conditions] << conditional_items.conditions
+          all_nodes
+        end
+      }
+      /
+      conditional_item
+    end
+
+    rule boolean_join
+      ( and_keyword / or_keyword ) {
+        def conjunction
+          text_value.downcase.to_sym
+        end
+      }
+    end
+
+    rule conditional_item
+      plugin_class quoted_text close_bracket space conditional_operator space compared_value {
+        def conditions
+          {
+            :operator => conditional_operator.value,
+            :plugin => plugin_class.name,
+            :key => quoted_text.content,
+            :value => compared_value.content
+          }
+        end
+      }
+    end
+
+    rule plugin_class
+      ([A-Z] [a-zA-Z0-9]+) open_bracket {
+        def name
+          elements[0].text_value
+        end
+      }
+    end
+
+    rule compared_value
+      (number / boolean / quoted_text)
+    end
+
+    rule open_bracket
+      '['
+    end
+
+    rule close_bracket
+      ']'
+    end
+
+    rule required_space
+      [\s]+
+    end
+
+    rule space
+      [\s]*
+    end
+
+    rule quoted_text
+      '"' text '"' {
+        def content
+          elements[1].content
+        end
+      }
+    end
+
+    rule conditional_operator
+      ('!=' / '>=' / '<=' / '=' / '>' / '<' / like_keyword) {
+        def value
+          text_value.downcase.to_sym
+        end
+      }
+    end
+
+    rule like_keyword
+      [lL] [iI] [kK] [eE]
+    end
+
+    rule and_keyword
+      [aA] [nN] [dD]
+    end
+
+    rule or_keyword
+      [oO] [rR]
+    end
+
+    rule number
+      ('-'? [1-9] [0-9]* / '0') {
+        def content
+          text_value.to_i
+        end
+      }
+    end
+
+    rule boolean
+      ('true' / 'false') {
+        def content
+          text_value == 'true'
+        end
+      }
+    end
+
+    rule text
+      [^"]* {
+        def content
+          text_value
+        end
+      }
+    end
+  end
+end

data/lib/animal/storage_plugin.rb

@@ -0,0 +1,14 @@
+module Animal
+  # The base class for storage plugins
+  class StoragePlugin
+    # Must be overridden
+    def self.get(_type, _id, _id_column = :id)
+      nil
+    end
+
+    # Must be overridden
+    def self.all(_type)
+      []
+    end
+  end
+end

data/lib/animal/version.rb

@@ -1,3 +1,3 @@
 module Animal
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.2'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: animal
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Daniel Schaaff
@@ -9,8 +9,22 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-01 00:00:00.000000000 Z
+date: 2017-01-11 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: treetop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -112,12 +126,15 @@ dependencies:
 description: Animal Puppet External Node Classifier
 email:
 - jgnagy@knuedge.com
-executables: []
+executables:
+- animal_enc
+- animal_import
 extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".travis.yml"
 - CONTRIBUTING.md
 - Gemfile
@@ -127,7 +144,17 @@ files:
 - animal.gemspec
 - bin/console
 - bin/setup
+- exe/animal_enc
+- exe/animal_import
 - lib/animal.rb
+- lib/animal/classifier.rb
+- lib/animal/enc.rb
+- lib/animal/inventory_plugin.rb
+- lib/animal/plugins/inventory/fact.rb
+- lib/animal/plugins/storage/yaml.rb
+- lib/animal/rule.rb
+- lib/animal/rules.treetop
+- lib/animal/storage_plugin.rb
 - lib/animal/version.rb
 homepage: https://github.com/knuedge/animal
 licenses:
@@ -150,7 +177,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Animal Puppet ENC