puppet 3.2.4 → 3.3.0.rc2

data/lib/puppetx/puppet/bindings_scheme_handler.rb

@@ -0,0 +1,130 @@
+module Puppetx::Puppet
+  # BindingsSchemeHandler is a Puppet Extension Point for the purpose of extending Puppet with a
+  # handler of a URI scheme used in the Puppet Bindings / Injector system.
+  # The intended use is to create a class derived from this class and then register it with the
+  # Puppet Binder.
+  #
+  # Creating the Extension Class
+  # ----------------------------
+  # As an example, a class for getting LDAP data and transforming into bindings based on an LDAP URI scheme (such as RFC 2255, 4516)
+  # may be authored in say a puppet module called 'exampleorg/ldap'. The name of the class should start with `Puppetx::<user>::<module>`,
+  # e.g. 'Puppetx::Exampleorg::Ldap::LdapBindingsSchemeHandler" and
+  # be located in `lib/puppetx/exampleorg/Ldap/LdapBindingsSchemeHandler.rb`. (These rules are not enforced, but it make the class
+  # both auto-loadable, and guaranteed to not have a name that clashes with some other LdapBindingsSchemeHandler from some other
+  # author/organization.
+  #
+  # The Puppet Binder will auto-load the file when it
+  # has a binding to the class `Puppetx::Exampleorg::Ldap::LdapBindingsSchemeHandler'
+  # The Ruby Module `Puppetx` is created by Puppet, the remaining modules should be created by the loaded logic - e.g.:
+  #
+  # @example Defining an LdapBindingsSchemeHandler
+  #   module Puppetx::Exampleorg
+  #     module Ldap
+  #       class LdapBindingsSchemeHandler < Puppetx::Puppetlabs::BindingsSchemeHandler
+  #         # implement the methods
+  #       end
+  #     end
+  #   end
+  #
+  #
+  # The expand_included method
+  # --------------------------
+  # This method is given a URI (as entred by a user in a bindings configuration) and the handler's first task is to
+  # perform checking, transformation, and possible expansion into multiple URIs for loading. The result is always an array
+  # of URIs. This method allows users to enter wild-cards, or to represent something symbolic that is transformed into one or
+  # more "real URIs" to load. (It is allowed to change scheme!).
+  # If the "optional" feature is supported, the handler should not include the URI in the result unless it will be able to produce
+  # bindings for the given URI (as an option it may produce an empty set of bindings).
+  #
+  # The expand_excluded method
+  # ---------------------------
+  # This method is given an URI (as entered by the user in a bindings configuration), and it is the handler's second task
+  # to perform checking, transformation, and possible expansion into multiple URIs that should not be loaded. The result is always
+  # an array of URIs. The user may be allowed to enter wild-cards etc. The URIs produced by this method should have the same syntax
+  # as those produced by {#expand_included} since they are excluded by comparison.
+  #
+  # The contributed_bindings method
+  # -------------------------------
+  # As the last step, the handler is being called once per URI that was included, and not later excluded to produce the
+  # contributed bindings. It is given three arguments, uri (the uri to load), scope (to provide access to the rest of the
+  # environment), and an acceptor (of issues), on which issues can be recorded.
+  #
+  # Reporting Errors/Issues
+  # -----------------------
+  # Issues are reported by calling the given composer's acceptor, which takes a severity (e.g. `:error`,
+  # `:warning`, or `:ignore`), an {Puppet::Pops::Issues::Issue Issue} instance, and a {Puppet::Pops::Adapters::SourcePosAdapter
+  # SourcePosAdapter} (which describes details about linenumber, position, and length of the problem area). If the scheme is
+  # not based on file, line, pos - nil can be passed. The URI itself can be passed as file.
+  #
+  # @example Reporting an issue
+  #    # create an issue with a symbolic name (that can serve as a reference to more details about the problem),
+  #    # make the name unique
+  #    issue = Puppet::Pops::Issues::issue(:EXAMPLEORG_LDAP_ILLEGAL_URI) { "The URI is not a valid Ldap URI" }
+  #    source_pos = nil
+  #
+  #    # report it
+  #    composer.acceptor.accept(Puppet::Pops::Validation::Diagnostic.new(:error, issue, uri.to_s, source_pos, {}))
+  #
+  # Instead of reporting issues, an exception can be raised.
+  #
+  # @abstract
+  # @api public
+  #
+  class BindingsSchemeHandler
+
+    # Produces the bindings contributed to the binding system based on the given URI.
+    # @param uri [URI] the URI to load bindings from
+    # @param scope [Puppet::Pops::Parser::Scope] access to scope and the rest of the environment
+    # @param composer [Puppet::Pops::Binder::BindingsComposer] a composer giving access to modules by name, and a diagnostics acceptor
+    # @return [Puppet::Pops::Binder::Bindings::ContributedBindings] the bindings to contribute, most conveniently
+    #   created by calling {Puppet::Pops::Binder::BindingsFactory.contributed_bindings}.
+    # @api public
+    #
+    def contributed_bindings(uri, scope, composer)
+      raise NotImplementedError, "The BindingsProviderScheme for uri: '#{uri}' must implement 'contributed_bindings'"
+    end
+
+    # Expands the given URI for the purpose of including the bindings it refers to. The input may contain
+    # wild-cards (if supported by this handler), and it is this methods responsibility to transform such into
+    # real loadable URIs.
+    #
+    # A scheme handler that does not support optionality, or wildcards should simply return the given URI
+    # in an Array.
+    #
+    # @param uri [URI] the uri for which bindings are to be produced.
+    # @param composer [Puppet::Pops::Binder::BindingsComposer] a composer giving access to modules by name, and a diagnostics acceptor
+    # @return [Array<URI>] the transformed, and possibly expanded set of URIs to include.
+    # @api public
+    #
+    def expand_included(uri, composer)
+      [uri]
+    end
+
+    # Expands the given URI for the purpose of excluding the bindings it refers to. The input may contain
+    # wild-cards (if supported by this handler), and it is this methods responsibility to transform such into
+    # real loadable URIs (that match those produced by {#expand_included} that should be excluded from the result.
+    #
+    # A scheme handler that does not support optionality, or wildcards should simply return the given URI
+    # in an Array.
+    #
+    # @param uri [URI] the uri for which bindings are to be produced.
+    # @param composer [Puppet::Pops::Binder::BindingsComposer] a composer giving access to modules by name, and a diagnostics acceptor
+    # @return [Array<URI>] the transformed, and possibly expanded set of URIs to include-
+    # @api public
+    #
+    def expand_excluded(uri, composer)
+      [uri]
+    end
+
+    # Returns whether the uri is optional or not. A scheme handler does not have to use this method
+    # to determine optionality, but if it supports such a feature, and there is no technical problem in supporting
+    # it this way, it should be done the same (or at least similar) way across all scheme handlers.
+    #
+    # This method interprets a URI ending with `?` or has query that is '?optional' as optional.
+    #
+    # @return [Boolean] whether the uri is an optional reference or not.
+    def is_optional?(uri)
+      (query = uri.query) && query == '' || query == 'optional'
+    end
+  end
+end

data/lib/puppetx/puppet/hiera2_backend.rb

@@ -0,0 +1,31 @@
+module Puppetx::Puppet
+
+  # Hiera2Backend is a Puppet Extension Point for the purpose of extending Puppet with a hiera data compatible
+  # backend. The intended use is to create a class derived from this class and then register it with the
+  # Puppet Binder under a backend name in the `binder_config.yaml` file to map symbolic name to class name.
+  #
+  # The responsibility of a Hiera2 backend is minimal. It should read the given file (with some extesion(s) determined by
+  # the backend, and return a hash of the content. If the directory does not exist, or the file does not exist an empty
+  # hash should be produced.
+  #
+  # @abstract
+  # @api public
+  #
+  class Hiera2Backend
+    # Produces a hash with data read from the file in the given
+    # directory having the given file_name (with extensions appended under the discretion of this
+    # backend).
+    #
+    # Should return an empty hash if the directory or the file does not exist. May raise exception on other types of errors, but
+    # not return nil.
+    #
+    # @param directory [String] the path to the directory containing the file to read
+    # @param file_name [String] the file name (without extension) that should be read
+    # @return [Hash<String, Object>, Hash<Symbol, Object>] the produced hash with data, may be empty if there was no file
+    # @api public
+    #
+    def read_data(directory, file_name)
+      raise NotImplementedError, "The class #{self.class.name} should have implemented the method 'read_data(directory, file_name)'"
+    end
+  end
+end

data/lib/puppetx/puppet/syntax_checker.rb

@@ -0,0 +1,91 @@
+module Puppetx::Puppet
+  # SyntaxChecker is a Puppet Extension Point for the purpose of extending Puppet with syntax checkers.
+  # The intended use is to create a class derived from this class and then register it with the
+  # Puppet Binder.
+  #
+  # Creating the Extension Class
+  # ----------------------------
+  # As an example, a class for checking custom xml (aware of some custom schemes) may be authored in
+  # say a puppet module called 'exampleorg/xmldata'. The name of the class should start with `Puppetx::<user>::<module>`,
+  # e.g. 'Puppetx::Exampleorg::XmlData::XmlChecker" and
+  # be located in `lib/puppetx/exampleorg/xml_data/xml_checker.rb`. The Puppet Binder will auto-load this file when it
+  # has a binding to the class `Puppetx::Exampleorg::XmlData::XmlChecker'
+  # The Ruby Module `Puppetx` is created by Puppet, the remaining modules should be created by the loaded logic - e.g.:
+  #
+  # @example Defining an XmlChecker
+  #   module Puppetx::Exampleorg
+  #     module XmlData
+  #       class XmlChecker < Puppetx::Puppetlabs::SyntaxCheckers::SyntaxChecker
+  #         def check(text, syntax_identifier, acceptor, location_hash)
+  #            # do the checking
+  #         end
+  #       end
+  #     end
+  #   end
+  #
+  # Implementing the check method
+  # -----------------------------
+  # The implementation of the {#check} method should naturally perform syntax checking of the given text/string and
+  # produce found issues on the given `acceptor`. These can be warnings or errors. The method should return `false` if
+  # any warnings or errors were produced (it is up to the caller to check for error/warning conditions and report them
+  # to the user).
+  #
+  # Issues are reported by calling the given `acceptor`, which takes a severity (e.g. `:error`,
+  # or `:warning), an {Puppet::Pops::Issues::Issue} instance, and a {Puppet::Pops::Adapters::SourcePosAdapter}
+  # (which describes details about linenumber, position, and length of the problem area). Note that the
+  # `location_info` given to the check method holds information about the location of the string in its *container*
+  # (e.g. the source position of a Heredoc); this information can be used if more detailed information is not
+  # available, or combined if there are more details (relative to the start of the checked string).
+  #
+  # @example Reporting an issue
+  #    # create an issue with a symbolic name (that can serve as a reference to more details about the problem),
+  #    # make the name unique
+  #    issue = Puppet::Pops::Issues::issue(:EXAMPLEORG_XMLDATA_ILLEGAL_XML) { "syntax error found in xml text" }
+  #    source_pos = Puppet::Pops::Adapters::SourcePosAdapter.new()
+  #    source_pos.line = info[:line] # use this if there is no detail from the used parser
+  #    source_pos.pos = info[:pos]   # use this pos if there is no detail from used parser
+  #
+  #    # report it
+  #    acceptor.accept(Puppet::Pops::Validation::Diagnostic.new(:error, issue, info[:file], source_pos, {}))
+  #
+  # There is usually a cap on the number of errors/warnings that are presented to the user, this is handled by the
+  # reporting logic, but care should be taken to not generate too many as the issues are kept in memory until
+  # the checker returns. The acceptor may set a limit and simply ignore issues past a certain (high) number of reported
+  # issues (this number is typically higher than the cap on issues reported to the user).
+  #
+  # The `syntax_identifier`
+  # -----------------------
+  # The extension makes use of a syntax identifier written in mime-style. This identifier can be something simple
+  # as 'xml', or 'json', but can also consist of several segments joined with '+' where the most specific syntax variant
+  # is placed first. When searching for a syntax checker; say for JSON having some special traits, say 'userdata', the
+  # author of the text may indicate this as the text having the syntax "userdata+json" - when a checker is looked up it is
+  # first checked if there is a checker for "userdata+json", if none is found, a lookup is made for "json" (since the text
+  # must at least be valid json). The given identifier is passed to the checker (to allow the same checker to check for
+  # several dialects/specializations).
+  #
+  # Use in Puppet DSL
+  # -----------------
+  # The Puppet DSL Heredoc support and Puppet Templates makes use of the syntax checker extension. A user of a
+  # heredoc can specify the syntax in the heredoc tag, e.g.`@(END:userdata+json)`.
+  #
+  #
+  # @abstract
+  #
+  class SyntaxChecker
+    # Checks the text for syntax issues and reports them to the given acceptor.
+    # This implementation is abstract, it raises {NotImplementedError} since a subclass should have implemented the
+    # method.
+    #
+    # @param text [String] The text to check
+    # @param syntax_identifier [String] The syntax identifier in mime style (e.g. 'json', 'json-patch+json', 'xml', 'myapp+xml'
+    # @option location_info [String] :file The filename where the string originates
+    # @option location_info [Integer] :line The line number identifying the location where the string is being used/checked
+    # @option location_info [Integer] :position The position on the line identifying the location where the string is being used/checked
+    # @return [Boolean] Whether the checked string had issues (warnings and/or errors) or not.
+    # @api public
+    #
+    def check(text, syntax_identifier, acceptor, location_info)
+      raise NotImplementedError, "The class #{self.class.name} should have implemented the method check()"
+    end
+  end
+end

data/lib/puppetx/puppetlabs/syntax_checkers/json.rb

@@ -0,0 +1,39 @@
+# A syntax checker for JSON.
+# @api public
+class Puppetx::Puppetlabs::SyntaxCheckers::Json < Puppetx::Puppet::SyntaxChecker
+
+  # Checks the text for JSON syntax issues and reports them to the given acceptor.
+  # This implementation is abstract, it raises {NotImplementedError} since a subclass should have implemented the
+  # method.
+  #
+  # @param text [String] The text to check
+  # @param syntax [String] The syntax identifier in mime style (e.g. 'json', 'json-patch+json', 'xml', 'myapp+xml'
+  # @option location_info [String] :file The filename where the string originates
+  # @option location_info [Integer] :line The line number identifying the location where the string is being used/checked
+  # @option location_info [Integer] :position The position on the line identifying the location where the string is being used/checked
+  # @return [Boolean] Whether the checked string had issues (warnings and/or errors) or not.
+  # @api public
+  #
+  def check(text, syntax, acceptor, location_info={})
+    raise ArgumentError.new("Json syntax checker: the text to check must be a String.") unless text.is_a?(String)
+    raise ArgumentError.new("Json syntax checker: the syntax identifier must be a String, e.g. json, data+json") unless syntax.is_a?(String)
+    raise ArgumentError.new("Json syntax checker: invalid Acceptor, got: '#{acceptor.class.name}'.") unless acceptor.is_a?(Puppet::Pops::Validation::Acceptor)
+    raise ArgumentError.new("Json syntax checker: location_info must be a Hash") unless info.is_a?(Hash)
+
+    begin
+      JSON.parse(text)
+    rescue => e
+      # Cap the message to 100 chars and replace newlines
+      msg = "Json syntax checker:: Cannot parse invalid JSON string. \"#{e.message().slice(0,100).gsub(/\r?\n/, "\\n")}\""
+
+      # TODO: improve the pops API to allow simpler diagnostic creation while still maintaining capabilities
+      # and the issue code. (In this case especially, where there is only a single error message being issued).
+      #
+      issue = Puppet::Pops::Issues::issue(:ILLEGAL_JSON) { msg }
+      source_pos = Puppet::Pops::Adapters::SourcePosAdapter.new()
+      source_pos.line = location_info[:line]
+      source_pos.pos = location_info[:pos]
+      acceptor.accept(Puppet::Pops::Validation::Diagnostic.new(:error, issue, location_info[:file], source_pos, {}))
+    end
+  end
+end

data/lib/semver.rb

@@ -119,6 +119,6 @@ class SemVer < Numeric
   MIN.instance_variable_set(:@vstring, 'vMIN')
 
   MAX = SemVer.new('8.0.0')
-  MAX.instance_variable_set(:@major, (1.0/0)) # => Infinity
+  MAX.instance_variable_set(:@major, Float::INFINITY) # => Infinity
   MAX.instance_variable_set(:@vstring, 'vMAX')
 end

data/man/man8/puppet-kick.8

@@ -114,7 +114,7 @@ Print the hosts you would connect to but do not actually connect\. This option r
 .
 .TP
 \-\-ping
-Do a ICMP echo against the target host\. Skip hosts that don\'t respond to ping\.
+Do an ICMP echo against the target host\. Skip hosts that don\'t respond to ping\.
 .
 .SH "EXAMPLE"
 .

data/spec/fixtures/integration/provider/cron/crontab/unspecialized

@@ -0,0 +1,15 @@
+# HEADER: some simple
+# HEADER: header
+@daily /bin/unnamed_special_command >> /dev/null 2>&1
+
+# commend with blankline above and below
+
+17-19,22 0-23/2 * * 2 /bin/unnamed_regular_command
+
+# Puppet Name: My daily failure
+MAILTO=""
+* * * * * /bin/false
+# Puppet Name: Monthly job
+SHELL=/bin/sh
+MAILTO=mail@company.com
+15 14 1 * * $HOME/bin/monthly

data/spec/fixtures/unit/pops/binder/bindings_composer/hiera1config/binder_config.yaml

@@ -0,0 +1,18 @@
+---
+version: 1
+layers:
+  [{name: site, include: 'confdir-hiera:/'},
+   {name: modules, include: ['module-hiera:/*/', 'module:/*::default'] }
+  ]
+categories:
+  [['node', '$fqdn'],
+   ['environment', '${environment}'],
+   ['osfamily', '${osfamily}'],
+   ['common', 'true']
+  ]
+#extensions:
+#  scheme_handlers:
+#    echo: 'Puppetx::Awesome::EchoSchemeHandler'
+#
+#  hiera_backends:
+#    echo: 'Puppetx::Awesome::EchoBackend'

data/spec/fixtures/unit/pops/binder/bindings_composer/hiera1config/hiera.yaml

@@ -0,0 +1,8 @@
+---
+hierarchy:
+  - '%fqdn'
+  - 'common'
+
+backends:
+  - yaml
+  - json

data/spec/fixtures/unit/pops/binder/bindings_composer/hiera1config/modules/good/common.yaml

@@ -0,0 +1 @@
+the_meaning_of_life: 300

data/spec/fixtures/unit/pops/binder/bindings_composer/hiera1config/modules/good/hiera.yaml

@@ -0,0 +1,10 @@
+---
+version: 2
+hierarchy:
+  [ ['node', '${fqdn}', '${fqdn}' ],
+    ['common', 'true', 'common' ]
+  ]
+
+backends:
+  - yaml
+  - json

data/spec/fixtures/unit/pops/binder/bindings_composer/ok/binder_config.yaml

@@ -0,0 +1,19 @@
+---
+version: 1
+layers:
+  [{name: site, include: 'confdir-hiera:/'},
+   {name: test, include: 'echo:/quick/brown/fox'},
+   {name: modules, include: ['module-hiera:/*/', 'module:/*::default'], exclude: 'module-hiera:/bad/' }
+  ]
+categories:
+  [['node', '$fqdn'],
+   ['environment', '${environment}'],
+   ['osfamily', '${osfamily}'],
+   ['common', 'true']
+  ]
+extensions:
+  scheme_handlers:
+    echo: 'Puppetx::Awesome::EchoSchemeHandler'
+
+  hiera_backends:
+    echo: 'Puppetx::Awesome::EchoBackend'

data/spec/fixtures/unit/pops/binder/bindings_composer/ok/common.yaml

@@ -0,0 +1 @@
+has_funny_hat: 'the pope'

data/spec/fixtures/unit/pops/binder/bindings_composer/ok/hiera.yaml

@@ -0,0 +1,11 @@
+---
+version: 2
+
+hierarchy:
+  [ ['node', '${fqdn}', '${fqdn}' ],
+    ['common', 'true', 'common' ]
+  ]
+
+backends:
+  - yaml
+  - json

data/spec/fixtures/unit/pops/binder/bindings_composer/ok/localhost.yaml

@@ -0,0 +1 @@
+the_meaning_of_life: 42

data/spec/fixtures/unit/pops/binder/bindings_composer/ok/modules/awesome/common.yaml

@@ -0,0 +1,3 @@
+awesome_x: 'golden'
+the_meaning_of_life: 100
+has_funny_hat: 'kkk'

data/spec/fixtures/unit/pops/binder/bindings_composer/ok/modules/awesome/hiera.yaml

@@ -0,0 +1,13 @@
+---
+version: 2
+
+hierarchy:
+  [ ['node', '${fqdn}', '${fqdn}' ],
+#    ['osfamily', '${osfamily}', 'osfamily' ]
+    ['common', 'true', 'common' ]
+  ]
+
+backends:
+  - yaml
+  - json
+  - echo

data/spec/fixtures/unit/pops/binder/bindings_composer/ok/modules/awesome/lib/puppet/bindings/awesome/default.rb

@@ -0,0 +1,4 @@
+Puppet::Bindings.newbindings('awesome::default') do |scope|
+  bind.name('all your base').to('are belong to us')
+  bind.name('env_meaning_of_life').to(puppet_string("$environment thinks it is 42", __FILE__))
+end

data/spec/fixtures/unit/pops/binder/bindings_composer/ok/modules/awesome/lib/puppetx/awesome/echo_backend.rb

@@ -0,0 +1,11 @@
+require 'puppetx/puppet/hiera2_backend'
+
+module Puppetx
+  module Awesome
+    class EchoBackend < Puppetx::Puppet::Hiera2Backend
+      def read_data(directory, file_name)
+        {"echo::#{file_name}" => "echo... #{File.basename(directory)}/#{file_name}"}
+      end
+    end
+  end
+end