puppet_metadata 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1b9da6033c7aa055e1e88289211ad3356764ea737184fd594fce1c31e1e94c27
+  data.tar.gz: 8fdfd523619505b15568769eb276424cffcc5c257c3a08377ee8a7abd8571701
+SHA512:
+  metadata.gz: 574fb26918bdd3c5b7a7ccad604557cb130797f704c87102d552fe3ef5a121acd15d4be22ba67bd273ba3d0d35a4c5b44c1ed8fe48e09b019da3785f9a149a9f
+  data.tar.gz: fcf0a1b46a59fdfbd3f6269f430495a63acbfc387c187658b25b4466fd8c0a0b5835cf221a5f6b7fcfdcd8f15208ab28141815edb8701666f9cefc47a422f99b

data/README.md

@@ -0,0 +1,3 @@
+# puppet_metadata
+
+The gem intends to provide an abstraction over Puppet's metadata.json file. Its API allow easy iteration over its illogical data structures.

data/lib/puppet_metadata.rb

@@ -0,0 +1,20 @@
+# A module that provides abstractions around Puppet's metadata format.
+module PuppetMetadata
+  autoload :Beaker, 'puppet_metadata/beaker'
+  autoload :Metadata, 'puppet_metadata/metadata'
+  autoload :OperatingSystem, 'puppet_metadata/operatingsystem'
+
+  # Parse a JSON encoded metadata string
+  # @param data A JSON encoded metadata string
+  # @return [PuppetMetadata::Metadata] A Metadata object
+  def self.parse(data)
+    Metadata.new(JSON.parse(data))
+  end
+
+  # Read and parse a path containing metadata
+  # @param path The path metadata.json
+  # @return [PuppetMetadata::Metadata] A Metadata object
+  def self.read(path)
+    parse(File.read(path))
+  end
+end

data/lib/puppet_metadata/beaker.rb

@@ -0,0 +1,51 @@
+module PuppetMetadata
+  # A class to provide abstractions for integration with beaker
+  #
+  # @see https://rubygems.org/gems/beaker
+  # @see https://rubygems.org/gems/beaker-hostgenerator
+  class Beaker
+    # Convert an Operating System name with a release to a Beaker setfile
+    #
+    # @param [String] os
+    #   The Operating System string as metadata.json knows it, which in turn is
+    #   based on Facter's operatingsystem fact.
+    # @param [String] release The OS release
+    # @param [Boolean] use_fqdn
+    #   Whether or not to use a FQDN, ensuring a domain
+    # @param [Boolean] pidfile_workaround
+    #   Whether or not to apply the systemd PIDFile workaround. This is only
+    #   needed when the daemon uses PIDFile in its service file and using
+    #   Docker as a Beaker hypervisor. This is to work around Docker's
+    #   limitations.
+    #
+    # @return [String] The beaker setfile description or nil
+    def self.os_release_to_setfile(os, release, use_fqdn: false, pidfile_workaround: false)
+      return unless os_supported?(os)
+
+      name = "#{os.downcase}#{release.tr('.', '')}-64"
+
+      options = {}
+      options[:hostname] = "#{name}.example.com" if use_fqdn
+      # Docker messes up cgroups and modern systemd can't deal with that when
+      # PIDFile is used.
+      if pidfile_workaround
+        case os
+        when 'CentOS'
+          options[:image] = 'centos:7.6.1810' if release == '7'
+        when 'Ubuntu'
+          options[:image] = 'ubuntu:xenial-20191212' if release == '16.04'
+        end
+      end
+
+      setfile = name
+      setfile += "{#{options.map { |key, value| "#{key}=#{value}" }.join(',')}}" if options.any?
+      setfile
+    end
+
+    # Return whether a Beaker setfile can be generated for the given OS
+    # @param [String] os The operating system
+    def self.os_supported?(os)
+      ['CentOS', 'Fedora', 'Debian', 'Ubuntu'].include?(os)
+    end
+  end
+end

data/lib/puppet_metadata/metadata.rb

@@ -0,0 +1,210 @@
+require 'json'
+
+module PuppetMetadata
+  # An exception indicating the metadata is invalid
+  #
+  # @attr_reader [Array[Hash[Symbol, String]]] errors
+  #   The errors in the metadata
+  class InvalidMetadataException < Exception
+    attr_reader :errors
+
+    # Returns a new instance of InvalidMetadataException
+    # @param [Array[Hash[Symbol, String]]] errors
+    #   The errors in the metadata
+    def initialize(errors)
+      messages = errors.map { |error| error[:message] }
+      super("Invalid metadata: #{messages.join(', ')}")
+      @errors = errors
+    end
+  end
+
+  # An abstraction over Puppet metadata
+  class Metadata
+    attr_reader :metadata
+
+    # @param [Hash[String, Any]] metadata
+    #   The metadata as a data structure
+    # @param [Boolean] validate
+    #   Whether to validate the metadata using metadata-json-lint
+    # @raise [PuppetMetadata::InvalidMetadataException]
+    #   When the provided metadata is invalid according to metadata.json-lint
+    # @see PuppetMetadata.parse
+    # @see PuppetMetadata.read
+    # @see https://rubygems.org/gems/metadata-json-lint
+    def initialize(metadata, validate = true)
+      if validate
+        require 'metadata_json_lint'
+        schema_errors = MetadataJsonLint::Schema.new.validate(metadata)
+        raise InvalidMetadataException.new(schema_errors) if schema_errors.any?
+      end
+
+      @metadata = metadata
+    end
+
+    # The name
+    # @return [String] The name
+    def name
+      metadata['name']
+    end
+
+    # The version
+    # @return [String]
+    def version
+      metadata['version']
+    end
+
+    # The license
+    # @return [String] The license
+    def license
+      metadata['license']
+    end
+
+    # @return [Hash[String, Array[String]]]
+    #   The supported operating system and its major releases
+    def operatingsystems
+      @operatingsystems ||= begin
+        return {} if metadata['operatingsystem_support'].nil?
+
+        supported = metadata['operatingsystem_support'].map do |os|
+          next unless os['operatingsystem']
+          [os['operatingsystem'], os['operatingsystemrelease']]
+        end
+
+        Hash[supported.compact]
+      end
+    end
+
+    # Returns whether an operating system's release is supported
+    #
+    # @param [String] operatingsystem The operating system
+    # @param [String] release The major release of the OS
+    # @return [Boolean] Whether an operating system's release is supported
+    def os_release_supported?(operatingsystem, release)
+      # If no OS is present, everything is supported. An example of this is
+      # modules with only functions.
+      return true if operatingsystems.empty?
+
+      # if the key present, nil indicates all releases are supported
+      return false unless operatingsystems.key?(operatingsystem)
+
+      releases = operatingsystems[operatingsystem]
+      releases.nil? || releases.include?(release)
+    end
+
+    # @param [Date] at The date to check the EOL time. Today is used when nil.
+    # @return [Hash[String, Array[String]]]
+    def eol_operatingsystems(at = nil)
+      at ||= Date.today
+
+      unsupported = operatingsystems.map do |os, rels|
+        next unless rels
+        eol = rels.select { |rel| OperatingSystem.eol?(os, rel, at) }
+        [os, eol] if eol.any?
+      end
+
+      Hash[unsupported.compact]
+    end
+
+    # A hash representation of the requirements
+    #
+    # Every element in the original array is converted. The name is used as a
+    # key while version_requirement is used as a value. No value indicates any
+    # version is accepted.
+    #
+    # @see #satisfies_requirement?
+    # @return [Hash[String, SemanticPuppet::VersionRange]]
+    #   The requirements of the module
+    #
+    # @example
+    #   metadata = Metadata.new(data)
+    #   metadata.requirements.each do |requirement, version_requirement|
+    #     if version_requirement
+    #       puts "#{metadata.name} requires #{requirement} #{version_requirement}"
+    #     else
+    #       puts "#{metadata.name} requires any #{requirement}"
+    #     end
+    #   end
+    def requirements
+      @requirements ||= build_version_requirement_hash(metadata['requirements'])
+    end
+
+    # @param [String] name The name of the requirement
+    # @param [String] version The version of the requirement
+    # @see #requirements
+    def satisfies_requirement?(name, version)
+      matches?(requirements[name], version)
+    end
+
+    # A hash representation of the dependencies
+    #
+    # Every element in the original array is converted. The name is used as a
+    # key while version_requirement is used as a value. No value indicates any
+    # version is accepted.
+    #
+    # @see #satisfies_dependency?
+    # @return [Hash[String, SemanticPuppet::VersionRange]]
+    #   The dependencies of the module
+    #
+    # @example
+    #   metadata = Metadata.new(data)
+    #   metadata.dependencies.each do |os, releases|
+    #     if releases
+    #       releases.each do |release|
+    #         puts "#{metadata.name} supports #{os} #{release}"
+    #       end
+    #     else
+    #       puts "#{metadata.name} supports all #{os} releases"
+    #     end
+    #   end
+    def dependencies
+      @dependencies ||= build_version_requirement_hash(metadata['dependencies'])
+    end
+
+    # @param [String] name The name of the dependency
+    # @param [String] version The version of the dependency
+    # @see #dependencies
+    def satisfies_dependency?(name, version)
+      matches?(dependencies[name], version)
+    end
+
+    # @param [Boolean] use_fqdn
+    #   Whether to set the hostname to a fully qualified domain name
+    # @param [Boolean] pidfile_workaround
+    #   Whether to apply the Docker pidfile workaround
+    # @yieldparam [String] setfile
+    #   The supported setfile configurations
+    # @see PuppetMetadata::Beaker#os_release_to_setfile
+    def beaker_setfiles(use_fqdn: false, pidfile_workaround: false)
+      operatingsystems.each do |os, releases|
+        next unless PuppetMetadata::Beaker.os_supported?(os)
+        releases&.each do |release|
+          setfile = PuppetMetadata::Beaker.os_release_to_setfile(os, release, use_fqdn: use_fqdn, pidfile_workaround: pidfile_workaround)
+          yield setfile if setfile
+        end
+      end
+    end
+
+    private
+
+    def build_version_requirement_hash(array)
+      return {} if array.nil?
+
+      require 'semantic_puppet'
+
+      reqs = array.map do |requirement|
+        next unless requirement['name']
+        version_requirement = requirement['version_requirement'] || '>= 0'
+        [requirement['name'], SemanticPuppet::VersionRange.parse(version_requirement)]
+      end
+
+      Hash[reqs.compact]
+    end
+
+    def matches?(required_version, provided_version)
+      return false unless required_version
+
+      provided_version = SemanticPuppet::Version.parse(provided_version) if provided_version.is_a?(String)
+      required_version.include?(provided_version)
+    end
+  end
+end

data/lib/puppet_metadata/operatingsystem.rb

@@ -0,0 +1,159 @@
+require 'date'
+
+module PuppetMetadata
+  # An abstraction layer over operating systems. Mostly to determine End Of
+  # Life dates.
+  #
+  # @see https://endoflife.software/operating-systems
+  class OperatingSystem
+    # The EOL dates for the various operating systems
+    # @see .eol_date
+    EOL_DATES = {
+      # https://endoflife.software/operating-systems/linux/centos
+      'CentOS' => {
+        '8' => '2029-05-31',
+        '7' => '2024-06-30',
+        '6' => '2020-11-30',
+        '5' => '2017-03-31',
+        '4' => '2012-02-29',
+        '3' => '2010-10-30',
+      },
+      # https://endoflife.software/operating-systems/linux/debian
+      # https://wiki.debian.org/DebianReleases
+      'Debian' => {
+        # TODO: EOL is standard support, not the extended life cycle
+        '10' => nil, # '~2022',
+        '9' => nil, # '~2020',
+        '8' => '2018-06-06',
+        '7' => '2016-04-26',
+        '6' => '2015-05-31',
+        '5' => '2012-02-06',
+        '4' => '2010-02-15',
+        '3.1' => '2008-03-31',
+        '3.0' => '2006-06-30',
+        '2.2' => '2003-06-30',
+        '2.1' => '2000-09-30',
+      },
+      # https://endoflife.software/operating-systems/linux/fedora
+      'Fedora' => {
+        '32' => nil,
+        '31' => nil,
+        '30' => nil,
+        '29' => '2019-11-26',
+        '28' => '2019-05-28',
+        '27' => '2018-11-30',
+        '26' => '2018-05-29',
+        '25' => '2017-12-12',
+        '24' => '2017-08-08',
+        '23' => '2016-12-20',
+        '22' => '2016-07-19',
+        '21' => '2015-12-01',
+        '20' => '2015-06-23',
+        '19' => '2015-01-06',
+        '18' => '2014-01-14',
+        '17' => '2013-07-30',
+        '16' => '2013-02-12',
+        '15' => '2012-06-26',
+        '14' => '2011-12-08',
+        '13' => '2011-06-24',
+        '12' => '2010-12-02',
+        '11' => '2010-06-25',
+        '10' => '2009-12-18',
+        '9' => '2009-07-10',
+        '8' => '2009-01-07',
+        '7' => '2008-06-13',
+        '6' => '2007-12-07',
+        '5' => '2007-07-02',
+        '4' => '2006-08-07',
+        '3' => '2006-01-16',
+        '2' => '2005-04-11',
+        '1' => '2004-09-20',
+      },
+      # https://endoflife.software/operating-systems/linux/red-hat-enterprise-linux-rhel
+      'RedHat' => {
+        # TODO: EOL is standard support, not the extended life cycle
+        '8' => '2029-05-31',
+        '7' => '2024-06-30',
+        '6' => '2020-11-30',
+        '5' => '2017-03-31',
+        '4' => '2012-02-29',
+        '3' => '2010-10-31',
+      },
+      # https://endoflife.software/operating-systems/linux/ubuntu
+      'Ubuntu' => {
+        '20.04' => '2025-04-15',
+        '19.10' => '2020-07-15',
+        '19.04' => '2020-01-15',
+        '18.10' => '2019-07-15',
+        '18.04' => '2023-04-15',
+        '17.10' => '2018-07-15',
+        '17.04' => '2018-01-15',
+        '16.10' => '2017-07-20',
+        '16.04' => '2021-04-15',
+        '15.10' => '2016-07-28',
+        '15.04' => '2016-02-04',
+        '14.10' => '2015-07-23',
+        '14.04' => '2019-04-15',
+        '13.10' => '2014-07-17',
+        '13.04' => '2014-01-27',
+        '12.04' => '2017-04-28',
+        '11.10' => '2013-05-09',
+        '11.04' => '2012-10-28',
+        '10.10' => '2012-04-10',
+        '10.04' => '2015-04-30',
+        '9.10' => '2011-04-30',
+        '9.04' => '2010-10-23',
+        '8.10' => '2010-04-30',
+        '8.04' => '2013-05-09',
+        '7.10' => '2009-04-18',
+        '7.04' => '2008-10-19',
+        '6.10' => '2008-04-26',
+        '6.06' => '2011-06-01',
+        '5.10' => '2007-04-13',
+        '5.04' => '2006-10-31',
+        '4.10' => '2006-04-30',
+      },
+    }
+
+    # Return the EOL date for the given operating system release
+    # @param [String] operatingsystem
+    #   The operating system
+    # @param [String] release
+    #   The major version of the operating system
+    # @return [optional, Date]
+    #   The EOL date for the given operating system release. Nil is returned
+    #   when the either when the OS, the release or the EOL date is unknown
+    def self.eol_date(operatingsystem, release)
+      releases = EOL_DATES[operatingsystem]
+      return unless releases
+      date = releases[release]
+      return unless date
+      Date.parse(date)
+    end
+
+    # Return whether the given operating system release is EOL at the given
+    # date
+    #
+    # @param [String] operatingsystem
+    #   The operating system
+    # @param [String] release
+    #   The major version of the operating system
+    # @return [Boolean]
+    #   The EOL date for the given operating system release. Nil is returned
+    #   when the either when the OS, the release or the EOL date is unknown
+    def self.eol?(operatingsystem, release, at = nil)
+      date = eol_date(operatingsystem, release)
+      date && date < (at || Date.today)
+    end
+
+    # Return the latest known release for a given operating system
+    # @param [String] operatingsystem The operating system
+    # @return [optional, String]
+    #   The latest major release for the given operating system, if any is
+    #   known
+    def self.latest_release(operatingsystem)
+      releases = EOL_DATES[operatingsystem]
+      releases&.keys&.max_by { |release| Gem::Version.new(release) }
+    end
+  end
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: puppet_metadata
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vox Pupuli
+- Ewoud Kohl van Wijngaarden
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-10-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: metadata-json-lint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: semantic_puppet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !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: A package that provides abstractions for the Puppet Metadata
+email:
+- voxpupuli@groups.io
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/puppet_metadata.rb
+- lib/puppet_metadata/beaker.rb
+- lib/puppet_metadata/metadata.rb
+- lib/puppet_metadata/operatingsystem.rb
+homepage: http://github.com/voxpupuli/puppet_metadata
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message:
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
+summary: Data structures for the Puppet Metadata
+test_files: []