Module: Puppet::ResourceApi

Defined in:

lib/puppet/resource_api/transport.rb,
lib/puppet/resource_api/glue.rb,
lib/puppet/resource_api/version.rb,
lib/puppet/resource_api/property.rb,
lib/puppet/resource_api/parameter.rb,
lib/puppet/resource_api/base_context.rb,
lib/puppet/resource_api/value_creator.rb,
lib/puppet/resource_api/simple_provider.rb,
lib/puppet/resource_api/type_definition.rb,
lib/puppet/resource_api/data_type_handling.rb,
lib/puppet/resource_api/provider_get_cache.rb,
lib/puppet/resource_api.rb

Overview

This module contains the main API to register and access types, providers and transports.

Defined Under Namespace

Modules: DataTypeHandling, Transport, ValueCreator Classes: BaseContext, BaseTypeDefinition, IOContext, MonkeyHash, Parameter, Property, ProviderGetCache, PuppetContext, ReadOnlyParameter, ResourceShim, SimpleProvider, TransportSchemaDef, TypeDefinition

Constant Summary

VERSION =

'2.0.0'

Class Attribute Summary

• .warning_count ⇒ Object

  Returns the value of attribute warning_count.

Class Method Summary

• .caller_is_resource_app? ⇒ Boolean
• .class_name_from_type_name(type_name) ⇒ Object
• .load_default_provider(class_name, type_name_sym) ⇒ Object
• .load_device_provider(class_name, type_name_sym, device_class_name, device_name_sym) ⇒ Object
• .load_provider(type_name) ⇒ Object
• .register_transport(schema) ⇒ Object

  keeps the existing register API format.

• .register_type(definition) ⇒ Object

Class Attribute Details

.warning_count ⇒ Object

Returns the value of attribute warning_count.

# File 'lib/puppet/resource_api.rb', line 24

def warning_count
  @warning_count
end

Class Method Details

.caller_is_resource_app? ⇒ Boolean

Returns:

• (Boolean)

# File 'lib/puppet/resource_api.rb', line 581

def self.caller_is_resource_app?
  caller.any? { |c| c.match(%r{application/resource.rb:}) }
end

.class_name_from_type_name(type_name) ⇒ Object

# File 'lib/puppet/resource_api.rb', line 577

def self.class_name_from_type_name(type_name)
  type_name.to_s.split('_').map(&:capitalize).join
end

.load_default_provider(class_name, type_name_sym) ⇒ Object

# File 'lib/puppet/resource_api.rb', line 552

def load_default_provider(class_name, type_name_sym)
  # loads the "puppet/provider/#{type_name}/#{type_name}" file through puppet
  Puppet::Type.type(type_name_sym).provider(type_name_sym)
  Puppet::Provider.const_get(class_name, false).const_get(class_name, false)
end

.load_device_provider(class_name, type_name_sym, device_class_name, device_name_sym) ⇒ Object

# File 'lib/puppet/resource_api.rb', line 559

def load_device_provider(class_name, type_name_sym, device_class_name, device_name_sym)
  # loads the "puppet/provider/#{type_name}/#{device_name}" file through puppet
  Puppet::Type.type(type_name_sym).provider(device_name_sym)
  provider_module = Puppet::Provider.const_get(class_name, false)
  if provider_module.const_defined?(device_class_name, false)
    provider_module.const_get(device_class_name, false)
  else
    load_default_provider(class_name, type_name_sym)
  end
end

.load_provider(type_name) ⇒ Object

# File 'lib/puppet/resource_api.rb', line 523

def load_provider(type_name)
  class_name = class_name_from_type_name(type_name)
  type_name_sym = type_name.to_sym
  device_name = if Puppet::Util::NetworkDevice.current.nil?
                  nil
                elsif Puppet::Util::NetworkDevice.current.is_a? Puppet::ResourceApi::Transport::Wrapper
                  # extract the device type from the currently loaded device's class
                  Puppet::Util::NetworkDevice.current.schema.name
                else
                  Puppet::Util::NetworkDevice.current.class.name.split('::')[-2].downcase
                end
  device_class_name = class_name_from_type_name(device_name)

  if device_name
    device_name_sym = device_name.to_sym if device_name
    load_device_provider(class_name, type_name_sym, device_class_name, device_name_sym)
  else
    load_default_provider(class_name, type_name_sym)
  end
rescue NameError
  if device_name # line too long # rubocop:disable Style/GuardClause
    raise Puppet::DevError, "Found neither the device-specific provider class Puppet::Provider::#{class_name}::#{device_class_name} in puppet/provider/#{type_name}/#{device_name} " \
                            "nor the generic provider class Puppet::Provider::#{class_name}::#{class_name} in puppet/provider/#{type_name}/#{type_name}"
  else
    raise Puppet::DevError, "provider class Puppet::Provider::#{class_name}::#{class_name} not found in puppet/provider/#{type_name}/#{type_name}"
  end
end

.register_transport(schema) ⇒ Object

keeps the existing register API format. e.g. Puppet::ResourceApi.register_type

# File 'lib/puppet/resource_api.rb', line 572

def register_transport(schema)
  Puppet::ResourceApi::Transport.register(schema)
end

.register_type(definition) ⇒ Object

# File 'lib/puppet/resource_api.rb', line 27

def register_type(definition)
  # Attempt to create a TypeDefinition from the input hash
  # This will validate and throw if its not right
  type_def = TypeDefinition.new(definition)

  # prepare the ruby module for the provider
  # this has to happen before Puppet::Type.newtype starts autoloading providers
  # it also needs to be guarded against the namespace already being defined by something
  # else to avoid ruby warnings
  Puppet::Provider.const_set(class_name_from_type_name(definition[:name]), Module.new) unless Puppet::Provider.const_defined?(class_name_from_type_name(definition[:name]), false)

  Puppet::Type.newtype(definition[:name].to_sym) do
    # The :desc value is already cleaned up by the TypeDefinition validation
    @doc = definition[:desc]
    @type_definition = type_def

    # Keeps a copy of the provider around. Weird naming to avoid clashes with puppet's own `provider` member
    define_singleton_method(:my_provider) do
      @my_provider ||= Hash.new { |hash, key| hash[key] = Puppet::ResourceApi.load_provider(definition[:name]).new }

      if Puppet::Util::NetworkDevice.current.is_a? Puppet::ResourceApi::Transport::Wrapper
        @my_provider[Puppet::Util::NetworkDevice.current.transport.class]
      else
        @my_provider[Puppet::Util::NetworkDevice.current.class]
      end
    end

    # make the provider available in the instance's namespace
    def my_provider
      self.class.my_provider
    end

    define_singleton_method(:type_definition) do
      @type_definition
    end

    def type_definition
      self.class.type_definition
    end

    apply_to_device if type_definition.feature?('remote_resource')

    define_singleton_method(:rsapi_provider_get_cache) do
      # This gives a new cache per resource provider on each Puppet run:
      @rsapi_provider_get_cache ||= Puppet::ResourceApi::ProviderGetCache.new
    end

    def rsapi_provider_get_cache
      self.class.rsapi_provider_get_cache
    end

    def initialize(attributes)
      # $stderr.puts "A: #{attributes.inspect}"
      if attributes.is_a? Puppet::Resource
        @title = attributes.title
        @catalog = attributes.catalog
        sensitives = attributes.sensitive_parameters
        attributes = attributes.to_hash
      else
        @ral_find_absent = true
        sensitives = []
      end

      # undo puppet's unwrapping of Sensitive values to provide a uniform experience for providers
      # See https://tickets.puppetlabs.com/browse/PDK-1091 for investigation and background
      sensitives.each do |name|
        attributes[name] = Puppet::Pops::Types::PSensitiveType::Sensitive.new(attributes[name]) if attributes.key?(name) && !attributes[name].is_a?(Puppet::Pops::Types::PSensitiveType::Sensitive)
      end

      # $stderr.puts "B: #{attributes.inspect}"
      attributes = my_provider.canonicalize(context, [attributes])[0] if type_definition.feature?('canonicalize')

      # the `Puppet::Resource::Ral.find` method, when `instances` does not return a match, uses a Hash with a `:name` key to create
      # an "absent" resource. This is often hit by `puppet resource`. This needs to work, even if the namevar is not called `name`.
      # This bit here relies on the default `title_patterns` (see below) to match the title back to the first (and often only) namevar
      if type_definition.attributes[:name].nil? && attributes[:title].nil?
        attributes[:title] = attributes.delete(:name)
        attributes[:title] = @title if attributes[:title].nil? && !type_definition.namevars.empty?
      end

      super
    end

    def name
      title
    end

    def self.build_title(type_definition, resource_hash)
      if type_definition.namevars.size > 1
        # use a MonkeyHash to allow searching in Puppet's RAL
        Puppet::ResourceApi::MonkeyHash[type_definition.namevars.map { |attr| [attr, resource_hash[attr]] }]
      else
        resource_hash[type_definition.namevars[0]]
      end
    end

    def rsapi_title
      @rsapi_title ||= self.class.build_title(type_definition, self)
      @rsapi_title
    end

    def rsapi_canonicalized_target_state
      @rsapi_canonicalized_target_state ||= begin
        # skip puppet's injected metaparams
        actual_params = @parameters.select { |k, _v| type_definition.attributes.key? k }
        target_state = actual_params.transform_values(&:rs_value)
        target_state = my_provider.canonicalize(context, [target_state]).first if type_definition.feature?('canonicalize')
        target_state
      end
      @rsapi_canonicalized_target_state
    end

    # Method is used to custom generate resources which are then applied by Puppet
    def generate
      # If feature `custom_generate` has been set then call the generate function within the provider and return the given results
      return unless type_definition&.feature?('custom_generate')

      should_hash = rsapi_canonicalized_target_state
      is_hash     = rsapi_current_state
      title       = rsapi_title

      # Ensure that a custom `generate` method has been created within the provider
      raise(Puppet::DevError, 'No generate method found within the types provider') unless my_provider.respond_to?(:generate)

      # Call the providers custom `generate` method
      my_provider.generate(context, title, is_hash, should_hash)

      # Return array of resources
    end

    def rsapi_current_state
      return @rsapi_current_state if @rsapi_current_state

      # If the current state is not set, then check the cache and, if a value is
      # found, ensure it passes strict_check before allowing it to be used:
      cached_value = rsapi_provider_get_cache.get(rsapi_title)
      strict_check(cached_value) if cached_value
      @rsapi_current_state = cached_value
    end

    def rsapi_current_state=(value)
      rsapi_provider_get_cache.add(rsapi_title, value)
      @rsapi_current_state = value
    end

    def to_resource
      to_resource_shim(super)
    end

    def to_resource_shim(resource)
      resource_hash = Hash[resource.keys.map { |k| [k, resource[k]] }]
      resource_hash[:title] = resource.title
      ResourceShim.new(resource_hash, type_definition.name, type_definition.namevars, type_definition.attributes, catalog)
    end

    validate do
      # enforce mandatory attributes
      @missing_attrs = []
      @missing_params = []

      # do not validate on known-absent instances
      return if @ral_find_absent

      definition[:attributes].each do |name, options|
        type = Puppet::ResourceApi::DataTypeHandling.parse_puppet_type(
          :name,
          options[:type]
        )

        # skip read only vars and the namevar
        next if i[read_only namevar].include? options[:behaviour]

        # skip properties if the resource is being deleted
        next if definition[:attributes][:ensure] &&
                value(:ensure) == 'absent' &&
                options[:behaviour].nil?

        if value(name).nil? && !(type.instance_of? Puppet::Pops::Types::POptionalType)
          @missing_attrs << name
          @missing_params << name if options[:behaviour] == :parameter
        end
      end

      @missing_attrs -= [:ensure]

      raise_missing_params if @missing_params.any?
    end

    # If the custom_insync feature is specified but no insyncable attributes are included
    # in the definition, add the hidden rsapi_custom_insync_trigger property.
    # This property exists *only* to allow a resource without properties to still execute an
    # insync check; there's no point in specifying it in a manifest as it can only have one
    # value; it cannot be specified in a type definition as it should only exist in this case.
    if type_definition.feature?('custom_insync') && type_definition.insyncable_attributes.empty?
      custom_insync_trigger_options = {
        type: 'Enum[do_not_specify_in_manifest]',
        desc: 'A hidden property which enables a type with custom insync to perform an insync check without specifying any insyncable properties',
        default: 'do_not_specify_in_manifest'
      }

      type_definition.create_attribute_in(self, :rsapi_custom_insync_trigger, :newproperty, Puppet::ResourceApi::Property, custom_insync_trigger_options)
    end

    definition[:attributes].each do |name, options|
      # puts "#{name}: #{options.inspect}"

      raise Puppet::ResourceError, "`#{options[:behaviour]}` is not a valid behaviour value" if options[:behaviour] && !(i[read_only namevar parameter init_only].include? options[:behaviour])

      # TODO: using newparam everywhere would suppress change reporting
      #       that would allow more fine-grained reporting through context,
      #       but require more invest in hooking up the infrastructure to emulate existing data
      if i[parameter namevar].include? options[:behaviour]
        param_or_property = :newparam
        parent = Puppet::ResourceApi::Parameter
      elsif options[:behaviour] == :read_only
        param_or_property = :newparam
        parent = Puppet::ResourceApi::ReadOnlyParameter
      else
        param_or_property = :newproperty
        parent = Puppet::ResourceApi::Property
      end

      type_definition.create_attribute_in(self, name, param_or_property, parent, options)
    end

    def self.rsapi_provider_get(names = nil)
      # If the cache has been marked as having all instances, then just return the
      # full contents:
      return rsapi_provider_get_cache.all if rsapi_provider_get_cache.cached_all? && names.nil?

      fetched = if type_definition.feature?('simple_get_filter')
                  my_provider.get(context, names)
                else
                  my_provider.get(context)
                end

      fetched.each do |resource_hash|
        type_definition.check_schema(resource_hash)
        rsapi_provider_get_cache.add(build_title(type_definition, resource_hash), resource_hash)
      end

      if names.nil? && !type_definition.feature?('simple_get_filter')
        # Mark the cache as having all possible instances:
        rsapi_provider_get_cache.cached_all
      end

      fetched
    end

    def self.instances
      # puts 'instances'
      # force autoloading of the provider
      provider(type_definition.name)

      rsapi_provider_get.map do |resource_hash|
        # allow a :title from the provider to override the default
        result = if resource_hash.key? :title
                   new(title: resource_hash[:title])
                 else
                   new(title: build_title(type_definition, resource_hash))
                 end
        # Cache the state in the generated resource, but unfortunately
        # this only benefits "puppet resource", not apply runs:
        result.cache_current_state(resource_hash)
        result
      end
    end

    def refresh_current_state
      current_state = self.class.rsapi_provider_get([rsapi_title]).find { |h| namevar_match?(h) }

      if current_state
        strict_check(current_state)
      else
        current_state = if rsapi_title.is_a? Hash
                          rsapi_title.dup
                        else
                          { title: rsapi_title }
                        end
        current_state[:ensure] = :absent if type_definition.ensurable?
      end
      self.rsapi_current_state = current_state
    end

    # Use this to set the current state from the `instances` method. "puppet resources"
    # needs this to minimize provider get() calls, but during a Puppet apply run
    # the instances() method is only used by resource generation, and resource
    # generators use and then discard the resources created by `instances``, so this
    # does not help with that:
    def cache_current_state(resource_hash)
      self.rsapi_current_state = resource_hash
      strict_check(resource_hash)
    end

    def retrieve
      refresh_current_state unless rsapi_current_state
      Puppet.debug("Current State: #{rsapi_current_state.inspect}")

      result = Puppet::Resource.new(self.class, title, parameters: rsapi_current_state)
      # puppet needs ensure to be a symbol
      result[:ensure] = result[:ensure].to_sym if type_definition.ensurable? && result[:ensure].is_a?(String)

      raise_missing_attrs

      result
    end

    def namevar_match?(item)
      context.type.namevars.all? do |namevar|
        item[namevar] == @parameters[namevar].value if @parameters[namevar].respond_to? :value
      end
    end

    def flush
      raise_missing_attrs

      # puts 'flush'
      target_state = rsapi_canonicalized_target_state

      retrieve unless rsapi_current_state

      return if rsapi_current_state == target_state

      Puppet.debug("Target State: #{target_state.inspect}")

      # enforce init_only attributes
      if Puppet.settings[:strict] != :off && rsapi_current_state && (rsapi_current_state[:ensure] == 'present' && target_state[:ensure] == 'present')
        target_state.each do |name, value|
          next unless type_definition.attributes[name][:behaviour] == :init_only && value != rsapi_current_state[name]

          message = "Attempting to change `#{name}` init_only attribute value from `#{rsapi_current_state[name]}` to `#{value}`"
          case Puppet.settings[:strict]
          when :warning
            Puppet.warning(message)
          when :error
            raise Puppet::ResourceError, message
          end
        end
      end

      if type_definition.feature?('supports_noop')
        my_provider.set(context, { rsapi_title => { is: rsapi_current_state, should: target_state } }, noop: noop?)
      else
        my_provider.set(context, rsapi_title => { is: rsapi_current_state, should: target_state }) unless noop?
      end
      if context.failed?
        context.reset_failed
        raise 'Execution encountered an error'
      end

      # remember that we have successfully reached our desired state
      self.rsapi_current_state = target_state
    end

    def raise_missing_attrs
      error_msg = "The following mandatory attributes were not provided:\n    *  #{@missing_attrs.join(", \n    *  ")}"
      raise Puppet::ResourceError, error_msg if @missing_attrs.any? && (value(:ensure) != :absent && !value(:ensure).nil?)
    end

    def raise_missing_params
      error_msg = "The following mandatory parameters were not provided:\n    *  #{@missing_params.join(", \n    *  ")}"
      raise Puppet::ResourceError, error_msg
    end

    def strict_check(current_state)
      return if Puppet.settings[:strict] == :off

      strict_check_canonicalize(current_state) if type_definition.feature?('canonicalize')
      strict_check_title_parameter(current_state) if type_definition.namevars.size > 1 && !type_definition.title_patterns.empty?

      nil
    end

    def strict_message(message)
      case Puppet.settings[:strict]
      when :warning
        Puppet.warning(message)
      when :error
        raise Puppet::DevError, message
      end
    end

    def strict_check_canonicalize(current_state)
      # if strict checking is on we must notify if the values are changed by canonicalize
      # make a deep copy to perform the operation on and to compare against later
      state_clone = Marshal.load(Marshal.dump(current_state))
      state_clone = my_provider.canonicalize(context, [state_clone]).first

      # compare the clone against the current state to see if changes have been made by canonicalize
      return unless state_clone && (current_state != state_clone)

      # :nocov:
      # codecov fails to register this multiline as covered, even though simplecov does.
      message = "        \#{type_definition.name}[\#{@title}]#get has not provided canonicalized values.\n        Returned values:       \#{current_state.inspect}\n        Canonicalized values:  \#{state_clone.inspect}\n      MESSAGE\n      # :nocov:\n      strict_message(message)\n    end\n\n    def strict_check_title_parameter(current_state)\n      unless current_state.key?(:title)\n        strict_message(\"\#{type_definition.name}[\#{@title}]#get has not provided a title attribute.\")\n        return\n      end\n\n      # Logic borrowed from Puppet::Resource.parse_title\n      title_hash = {}\n      self.class.title_patterns.each do |regexp, symbols|\n        captures = regexp.match(current_state[:title])\n        next if captures.nil?\n\n        symbols.zip(captures[1..-1]).each do |symbol_and_lambda, capture|\n          # The Resource API does not support passing procs in title_patterns\n          # so, unlike Puppet::Resource, we do not need to handle that here.\n          symbol = symbol_and_lambda[0]\n          title_hash[symbol] = capture\n        end\n        break\n      end\n\n      return if title_hash == rsapi_title\n\n      namevars = type_definition.namevars.reject { |namevar| title_hash[namevar] == rsapi_title[namevar] }\n\n      # :nocov:\n      # codecov fails to register this multiline as covered, even though simplecov does.\n      message = <<~MESSAGE.strip\n        \#{type_definition.name}[\#{@title}]#get has provided a title attribute which does not match all namevars.\n        Namevars which do not match: \#{namevars.inspect}\n        Returned parsed title hash:  \#{title_hash.inspect}\n        Expected hash:               \#{rsapi_title.inspect}\n      MESSAGE\n      # :nocov:\n      strict_message(message)\n    end\n\n    define_singleton_method(:context) do\n      @context ||= PuppetContext.new(TypeDefinition.new(definition))\n    end\n\n    def context\n      self.class.context\n    end\n\n    def self.title_patterns\n      @title_patterns ||= if type_definition.definition.key? :title_patterns\n                            parse_title_patterns(type_definition.definition[:title_patterns])\n                          else\n                            [[/(.*)/m, [[type_definition.namevars.first]]]]\n                          end\n    end\n\n    # Creates a `title_pattern` compatible data structure to pass to the underlying puppet runtime environment.\n    # It uses the named items in the regular expression to connect the dots\n    #\n    # @example `[ %r{^(?<package>.*[^-])-(?<manager>.*)$} ]` becomes\n    #   [\n    #     [\n    #       %r{^(?<package>.*[^-])-(?<manager>.*)$},\n    #       [ [:package], [:manager] ]\n    #     ],\n    #   ]\n    def self.parse_title_patterns(patterns)\n      patterns.map do |item|\n        regex = Regexp.new(item[:pattern])\n        [item[:pattern], regex.names.map { |x| [x.to_sym] }]\n      end\n    end\n\n    %i[autorequire autobefore autosubscribe autonotify].each do |auto|\n      next unless definition[auto]\n\n      definition[auto].each do |type, values|\n        Puppet.debug(\"Registering \#{auto} for \#{type}: \#{values.inspect}\")\n        send(auto, type.downcase.to_sym) do\n          resolved = [values].flatten.map do |v|\n            match = /\\A\\$(.*)\\Z/.match(v) if v.is_a? String\n            if match.nil?\n              v\n            else\n              self[match[1].to_sym]\n            end\n          end\n          # Flatten to handle any resolved array properties and filter any nil\n          # values resulting from unspecified optional parameters:\n          resolved.flatten.reject(&:nil?)\n        end\n      end\n    end\n  end\nend\n".strip