pdk-akerl 1.9.1.1 → 1.14.0.1

data/lib/pdk/config/analytics_schema.json

@@ -0,0 +1,26 @@
+{
+  "definitions": {},
+  "$schema": "http://json-schema.org/draft-06/schema#",
+  "$id": "http://puppet.com/schema/does_not_exist.json",
+  "type": "object",
+  "title": "The PDK Analytics YAML Schema",
+  "properties": {
+    "disabled": {
+      "$id": "#/properties/disabled",
+      "type": "boolean",
+      "title": "Disabled property",
+      "examples": [
+        false
+      ]
+    },
+    "user-id": {
+      "$id": "#/properties/user-id",
+      "type": "string",
+      "title": "The User-id for analytics",
+      "examples": [
+        "cb9ed65f-37dc-48d8-9863-8bd09cbb61c7"
+      ],
+      "pattern": "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{4}\\-[0-9a-fA-F]{12}$"
+    }
+  }
+}

data/lib/pdk/config/errors.rb

@@ -0,0 +1,5 @@
+module PDK
+  class Config
+    class LoadError < StandardError; end
+  end
+end

data/lib/pdk/config/json.rb

@@ -0,0 +1,34 @@
+require 'pdk/config/namespace'
+
+module PDK
+  class Config
+    class JSON < Namespace
+      # Parses a JSON document.
+      #
+      # @see PDK::Config::Namespace.parse_file
+      def parse_file(filename)
+        raise unless block_given?
+        data = load_data(filename)
+        return if data.nil? || data.empty?
+
+        require 'json'
+
+        data = ::JSON.parse(data)
+        return if data.nil? || data.empty?
+
+        data.each { |k, v| yield k, PDK::Config::Setting.new(k, self, v) }
+      rescue ::JSON::ParserError => e
+        raise PDK::Config::LoadError, e.message
+      end
+
+      # Serializes object data into a JSON string.
+      #
+      # @see PDK::Config::Namespace.serialize_data
+      def serialize_data(data)
+        require 'json'
+
+        ::JSON.pretty_generate(data)
+      end
+    end
+  end
+end

data/lib/pdk/config/json_schema_namespace.rb

@@ -0,0 +1,143 @@
+require 'pdk/config/namespace'
+
+# Due to https://github.com/ruby-json-schema/json-schema/issues/439
+# Windows file paths "appear" as uri's with no host and a schema of drive letter
+# Also it is not possible to craft a URI with a Windows path due to the URI object
+# always prepending the path with forward slash (`/`) so Windows paths end up looking
+# like '/C:\schema.json', which can not be read.
+# Instead we need to monkey patch the Schema Reader reader to remove the errant forward slash
+require 'json-schema/schema/reader'
+module JSON
+  class Schema
+    class Reader
+      alias original_read_file read_file
+
+      def read_file(pathname)
+        new_pathname = JSON::Util::URI.unescaped_path(pathname.to_s)
+        # Munge the path if it looks like a Windows path e.g. /C:/Windows ...
+        # Note that UNC style paths do not have the same issue (\\host\path)
+        new_pathname.slice!(0) if new_pathname.start_with?('/') && new_pathname[2] == ':'
+        original_read_file(Pathname.new(new_pathname))
+      end
+    end
+  end
+end
+
+module PDK
+  class Config
+    class JSONSchemaNamespace < Namespace
+      # Initialises the PDK::Config::JSONSchemaNamespace object.
+      #
+      # @see PDK::Config::Namespace.initialize
+      #
+      # @option params [String] :schema_file Path to the JSON Schema document
+      def initialize(name = nil, file: nil, parent: nil, persistent_defaults: false, schema_file: nil, &block)
+        super(name, file: file, parent: parent, persistent_defaults: persistent_defaults, &block)
+        @schema_file = schema_file
+        @unmanaged_settings = {}
+      end
+
+      # The JSON Schema for the namespace
+      #
+      # @return [Hash]
+      def schema
+        document_schema.schema
+      end
+
+      # Whether the schema is valid but empty.
+      #
+      # @return [Boolean]
+      def empty_schema?
+        document_schema.schema.empty?
+      end
+
+      # Name of all the top level properties for the schema
+      #
+      # @return [String[]]
+      def schema_property_names
+        return [] if schema['properties'].nil?
+        schema['properties'].keys
+      end
+
+      # Extends the to_h namespace method to include unmanaged settings
+      #
+      # @see PDK::Config::Namespace.to_h
+      def to_h
+        # This may seem counter-intuitive but we need to call super first as the settings
+        # may not have been loaded yet, which means @unmanaged_settings will be empty.
+        # We call super first to force any file loading and then merge the unmanaged settings
+        settings_hash = super
+        @unmanaged_settings = {} if @unmanaged_settings.nil?
+        @unmanaged_settings.merge(settings_hash)
+      end
+
+      # Validates a document (Hash table) against the schema
+      #
+      # @return [Boolean]
+      def validate_document!(document)
+        ::JSON::Validator.validate!(schema, document)
+      end
+
+      protected
+
+      # @!attribute [w] unmanaged_settings
+      #   Sets the list of unmanaged settings. For subclass use only
+      #
+      #   @param unmanaged_settings [Hash<String, Object]] A hashtable of all unmanaged settings which will be persisted, but not visible
+      #   @protected
+      attr_writer :unmanaged_settings
+
+      private
+
+      # Override the create_setting method to always fail. This is called
+      # to dyanmically add settings. However as we're using a schema, no
+      # new settings can be created
+      #
+      # @see PDK::Config::Namespace.create_missing_setting
+      #
+      # @private
+      def create_missing_setting(key, _initial_value = nil)
+        raise ArgumentError, _("Setting '#{key}' does not exist'")
+      end
+
+      # Create a valid, but empty schema
+      #
+      # @return [JSON::Schema]
+      def create_empty_schema
+        require 'json-schema'
+        ::JSON::Schema.new({}, 'http://json-schema.org/draft-06/schema#')
+      end
+
+      # Lazily retrieve the JSON schema from disk for this namespace
+      #
+      # @return [JSON::Schema]
+      def document_schema
+        return @document_schema unless @document_schema.nil?
+
+        # Create an empty schema by default.
+        @document_schema = create_empty_schema
+
+        require 'json-schema'
+
+        return @document_schema if @schema_file.nil?
+        unless PDK::Util::Filesystem.file?(@schema_file)
+          raise PDK::Config::LoadError, _('Unable to open %{file} for reading. File does not exist') % {
+            file: @schema_file,
+          }
+        end
+
+        # The schema should not query external URI references, except for the meta-schema. Local files are allowed
+        schema_reader = ::JSON::Schema::Reader.new(
+          accept_file: true,
+          accept_uri:  proc { |uri| uri.host.nil? || ['json-schema.org'].include?(uri.host) },
+        )
+        @document_schema = schema_reader.read(Addressable::URI.convert_path(@schema_file))
+      rescue ::JSON::Schema::JsonParseError => e
+        raise PDK::Config::LoadError, _('Unable to open %{file} for reading. JSON Error: %{msg}') % {
+          file: @schema_file,
+          msg: e.message,
+        }
+      end
+    end
+  end
+end

data/lib/pdk/config/json_schema_setting.rb

@@ -0,0 +1,53 @@
+require 'pdk/config/json_schema_namespace'
+
+module PDK
+  class Config
+    class JSONSchemaSetting < PDK::Config::Setting
+      # Initialises the PDK::Config::JSONSchemaSetting object.
+      #
+      # @see PDK::Config::Setting.initialize
+      def initialize(_name, namespace, _initial_value)
+        raise 'The JSONSchemaSetting object can only be created within the JSONSchemaNamespace' unless namespace.is_a?(PDK::Config::JSONSchemaNamespace)
+        super
+      end
+
+      # Verifies that the new setting value is valid by calling the JSON schema validator on
+      # a hash which includes the new setting
+      #
+      # @see PDK::Config::Setting.validate!
+      def validate!(value)
+        # Get the existing namespace data
+        new_document = namespace.to_h
+        # ... set the new value
+        new_document[@name] = value
+        begin
+          # ... add validate it
+          namespace.validate_document!(new_document)
+        rescue ::JSON::Schema::ValidationError => e
+          raise ArgumentError, _('%{key} %{message}') % {
+            key:     qualified_name,
+            message: e.message,
+          }
+        end
+      end
+
+      # Evaluate the default setting, firstly from the JSON schema and then
+      # from any other default evaluators in the settings chain.
+      #
+      # @see PDK::Config::Setting.default
+      #
+      # @return [Object, nil] the result of evaluating the block given to
+      #   {#default_to}, or `nil` if the setting has no default.
+      def default
+        # Return the default from the schema document if it exists
+        if namespace.schema_property_names.include?(@name)
+          prop_schema = namespace.schema['properties'][@name]
+          return prop_schema['default'] unless prop_schema['default'].nil?
+        end
+        # ... otherwise call the settings chain default
+        # and if that doesn't exist, just return nil
+        @previous_setting.nil? ? nil : @previous_setting.default
+      end
+    end
+  end
+end

data/lib/pdk/config/json_with_schema.rb

@@ -0,0 +1,50 @@
+require 'pdk/config/json_schema_namespace'
+require 'pdk/config/json_schema_setting'
+
+module PDK
+  class Config
+    class JSONWithSchema < JSONSchemaNamespace
+      # Parses a JSON document with a schema.
+      #
+      # @see PDK::Config::Namespace.parse_file
+      def parse_file(filename)
+        raise unless block_given?
+        data = load_data(filename)
+        data = '{}' if data.nil? || data.empty?
+        require 'json'
+
+        @raw_data = ::JSON.parse(data)
+        @raw_data = {} if @raw_data.nil?
+
+        begin
+          # Ensure the parsed document is actually valid
+          validate_document!(@raw_data)
+        rescue ::JSON::Schema::ValidationError => e
+          raise PDK::Config::LoadError, _('The configuration file %{filename} is not valid: %{message}') % {
+            filename: filename,
+            message:  e.message,
+          }
+        end
+
+        schema_property_names.each do |key|
+          yield key, PDK::Config::JSONSchemaSetting.new(key, self, @raw_data[key])
+        end
+
+        # Remove all of the "known" settings from the schema and
+        # we're left with the settings that we don't manage.
+        self.unmanaged_settings = @raw_data.reject { |k, _| schema_property_names.include?(k) }
+      rescue ::JSON::ParserError => e
+        raise PDK::Config::LoadError, e.message
+      end
+
+      # Serializes object data into a JSON string.
+      #
+      # @see PDK::Config::Namespace.serialize_data
+      def serialize_data(data)
+        require 'json'
+
+        ::JSON.pretty_generate(data)
+      end
+    end
+  end
+end

data/lib/pdk/config/namespace.rb

@@ -0,0 +1,332 @@
+module PDK
+  class Config
+    class Namespace
+      # @param value [String] the new name of this namespace.
+      attr_writer :name
+
+      # @return [String] the path to the file associated with the contents of
+      #   this namespace.
+      attr_reader :file
+
+      # @return [self] the parent namespace of this namespace.
+      attr_accessor :parent
+
+      # Initialises the PDK::Config::Namespace object.
+      #
+      # @param name [String] the name of the namespace (defaults to nil).
+      # @param params [Hash{Symbol => Object}] keyword parameters for the
+      #   method.
+      # @option params [String] :file the path to the file associated with the
+      #   contents of the namespace (defaults to nil).
+      # @option params [self] :parent the parent {self} that this namespace is
+      #   a child of (defaults to nil).
+      # @option params [self] :persistent_defaults whether default values should be persisted
+      #   to disk when evaluated. By default they are not persisted to disk. This is typically
+      #   used for settings which a randomly generated, instead of being deterministic, e.g. analytics user-id
+      # @param block [Proc] a block that is evaluated within the new instance.
+      def initialize(name = nil, file: nil, parent: nil, persistent_defaults: false, &block)
+        @file = File.expand_path(file) unless file.nil?
+        @settings = {}
+        @name = name.to_s
+        @parent = parent
+        @persistent_defaults = persistent_defaults
+        @mounts = {}
+        @loaded_from_file = false
+
+        instance_eval(&block) if block_given?
+      end
+
+      # Pre-configure a value in the namespace.
+      #
+      # Allows you to specify validators and a default value for value in the
+      # namespace (see PDK::Config::Value#initialize).
+      #
+      # @param key [String,Symbol] the name of the value.
+      # @param block [Proc] a block that is evaluated within the new [self].
+      #
+      # @return [nil]
+      def setting(key, &block)
+        @settings[key.to_s] ||= PDK::Config::Setting.new(key.to_s, self)
+        @settings[key.to_s].instance_eval(&block) if block_given?
+      end
+
+      # Mount a provided [self] (or subclass) into the namespace.
+      #
+      # @param key [String,Symbol] the name of the namespace to be mounted.
+      # @param obj [self] the namespace to be mounted.
+      # @param block [Proc] a block to be evaluated within the instance of the
+      #   newly mounted namespace.
+      #
+      # @raise [ArgumentError] if the object to be mounted is not a {self} or
+      #   subclass thereof.
+      #
+      # @return [self] the mounted namespace.
+      def mount(key, obj, &block)
+        raise ArgumentError, _('Only PDK::Config::Namespace objects can be mounted into a namespace') unless obj.is_a?(PDK::Config::Namespace)
+        obj.parent = self
+        obj.name = key.to_s
+        obj.instance_eval(&block) if block_given?
+        @mounts[key.to_s] = obj
+      end
+
+      # Create and mount a new child namespace.
+      #
+      # @param name [String,Symbol] the name of the new namespace.
+      # @param block [Proc]
+      def namespace(name, &block)
+        mount(name, PDK::Config::Namespace.new, &block)
+      end
+
+      # Get the value of the named key.
+      #
+      # If there is a value for that key, return it. If not, follow the logic
+      # described in {#default_config_value} to determine the default value to
+      # return.
+      #
+      # @note Unlike a Ruby Hash, this will not return `nil` in the event that
+      #   the key does not exist (see #fetch).
+      #
+      # @param key [String,Symbol] the name of the value to retrieve.
+      #
+      # @return [Object] the requested value.
+      def [](key)
+        # Check if it's a mount first...
+        return @mounts[key.to_s] unless @mounts[key.to_s].nil?
+        # Check if it's a setting, otherwise nil
+        return nil if settings[key.to_s].nil?
+        return settings[key.to_s].value unless settings[key.to_s].value.nil?
+        default_value = settings[key.to_s].default
+        return default_value if default_value.nil? || !@persistent_defaults
+        # Persist the default value
+        settings[key.to_s].value = default_value
+        save_data
+        default_value
+      end
+
+      # Get the value of the named key or the provided default value if not
+      # present. Note that this does not trigger persistent defaults
+      #
+      # This differs from {#[]} in an important way in that it allows you to
+      # return a default value, which is not possible using `[] || default` as
+      # non-existent values when accessed normally via {#[]} will be defaulted
+      # to a new Hash.
+      #
+      # @param key [String,Symbol] the name of the value to fetch.
+      # @param default_value [Object] the value to return if the namespace does
+      #   not contain the requested value.
+      #
+      # @return [Object] the requested value.
+      def fetch(key, default_value)
+        # Check if it's a mount first...
+        return @mounts[key.to_s] unless @mounts[key.to_s].nil?
+        # Check if it's a setting, otherwise default_value
+        return default_value if settings[key.to_s].nil?
+        # Check if has a value, otherwise default_value
+        settings[key.to_s].value.nil? ? default_value : settings[key.to_s].value
+      end
+
+      # After the value has been set in memory, the value will then be
+      # persisted to disk.
+      #
+      # @param key [String,Symbol] the name of the configuration value.
+      # @param value [Object] the value of the configuration value.
+      #
+      # @return [nil]
+      def []=(key, value)
+        # You can't set the value of a mount
+        raise ArgumentError, _('Namespace mounts can not be set a value') unless @mounts[key.to_s].nil?
+        set_volatile_value(key, value)
+        # Persist the change
+        save_data
+      end
+
+      # Convert the namespace into a Hash of values, suitable for serialising
+      # and persisting to disk.
+      #
+      # Child namespaces that are associated with their own files are excluded
+      # from the Hash (as their values will be persisted to their own files)
+      # and nil values are removed from the Hash.
+      #
+      # @return [Hash{String => Object}] the values from the namespace that
+      #   should be persisted to disk.
+      def to_h
+        new_hash = {}
+        settings.each_pair { |k, v| new_hash[k] = v.value }
+        @mounts.each_pair { |k, mount_point| new_hash[k] = mount_point.to_h if mount_point.include_in_parent? }
+        new_hash.delete_if { |_, v| v.nil? }
+        new_hash
+      end
+
+      # Resolves all filtered settings, including child namespaces, fully namespaced and filling in default values.
+      #
+      # @param filter [String] Only resolve setting names which match the filter. See #be_resolved? for matching rules
+      # @return [Hash{String => Object}] All resolved settings for example {'user.module_defaults.author' => 'johndoe'}
+      def resolve(filter = nil)
+        resolved = {}
+        # Resolve the settings
+        settings.values.each do |setting|
+          setting_name = setting.qualified_name
+          if be_resolved?(setting_name, filter)
+            resolved[setting_name] = setting.value.nil? ? setting.default : setting.value
+          end
+        end
+        # Resolve the mounts
+        @mounts.values.each { |mount| resolved.merge!(mount.resolve(filter)) }
+        resolved
+      end
+
+      # @return [Boolean] true if the namespace has a parent, otherwise false.
+      def child_namespace?
+        !parent.nil?
+      end
+
+      # Determines the fully qualified name of the namespace.
+      #
+      # If this is a child namespace, then fully qualified name for the
+      # namespace will be "<parent>.<child>".
+      #
+      # @return [String] the fully qualifed name of the namespace.
+      def name
+        child_namespace? ? [parent.name, @name].join('.') : @name
+      end
+
+      # Determines if the contents of the namespace should be included in the
+      # parent namespace when persisting to disk.
+      #
+      # If the namespace has been mounted into a parent namespace and is not
+      # associated with its own file on disk, then the values in the namespace
+      # should be included in the parent namespace when persisting to disk.
+      #
+      # @return [Boolean] true if the values should be included in the parent
+      #   namespace.
+      def include_in_parent?
+        child_namespace? && file.nil?
+      end
+
+      private
+
+      # Determines whether a setting name should be resolved using the filter
+      #  Returns true when filter is nil.
+      #  Returns true if the filter is exactly the same name as the setting.
+      #  Returns true if the name is a sub-key of the filter e.g.
+      #    Given a filter of user.module_defaults, `user.module_defaults.author` will return true, but `user.analytics.disabled` will return false.
+      #
+      # @param name [String] The setting name to test.
+      # @param filter [String] The filter used to test on the name.
+      # @return [Boolean] Whether the name passes the filter.
+      def be_resolved?(name, filter = nil)
+        return true if filter.nil? # If we're not filtering, this value should always be resolved
+        return true if name == filter # If it's exactly the same name then it should be resolved
+        name.start_with?(filter + '.') # If name is a subkey of the filter then it should be resolved
+      end
+
+      # @abstract Subclass and override {#parse_file} to implement parsing logic
+      #   for a particular config file format.
+      #
+      # @param data [String] The content of the file to be parsed.
+      # @param filename [String] The path to the file to be parsed.
+      #
+      # @yield [String, Object] the data to be loaded into the
+      #   namespace.
+      def parse_file(_filename); end
+
+      # @abstract Subclass and override {#serialize_data} to implement generating
+      #   logic for a particular config file format.
+      #
+      # @param data [Hash{String => Object}] the data stored in the namespace
+      #
+      # @return [String] the serialized contents of the namespace suitable for
+      #   writing to disk.
+      def serialize_data(_data); end
+
+      # @abstract Subclass and override {#create_missing_setting} to implement logic
+      # when a setting is dynamically created, for example when attempting to
+      # set the value of an unknown setting
+      #
+      # @param data [Hash{String => Object}] the data stored in the namespace
+      #
+      # @return [String] the serialized contents of the namespace suitable for
+      #   writing to disk.
+      def create_missing_setting(key, initial_value = nil)
+        # Need to use `@settings` and `@mounts` here to stop recursive calls
+        return unless @mounts[key.to_s].nil?
+        return unless @settings[key.to_s].nil?
+        @settings[key.to_s] = PDK::Config::Setting.new(key.to_s, self, initial_value)
+      end
+
+      # Set the value of the named key.
+      #
+      # If the key has been pre-configured with {#value}, then the value of the
+      # key will be validated against any validators that have been configured.
+      #
+      # @param key [String,Symbol] the name of the configuration value.
+      # @param value [Object] the value of the configuration value.
+      def set_volatile_value(key, value)
+        # Need to use `settings` here to force the backing file to be loaded
+        return create_missing_setting(key, value) if settings[key.to_s].nil?
+        # Need to use `@settings` here to stop recursive calls from []=
+        @settings[key.to_s].value = value
+      end
+
+      # Helper method to read files.
+      #
+      # @raise [PDK::Config::LoadError] if the file is removed during read.
+      # @raise [PDK::Config::LoadError] if the user doesn't have the
+      #   permissions needed to read the file.
+      # @return [String,nil] the contents of the file or nil if the file does
+      #   not exist.
+      def load_data(filename)
+        return if filename.nil?
+        return unless PDK::Util::Filesystem.file?(filename)
+
+        PDK::Util::Filesystem.read_file(file)
+      rescue Errno::ENOENT => e
+        raise PDK::Config::LoadError, e.message
+      rescue Errno::EACCES
+        raise PDK::Config::LoadError, _('Unable to open %{file} for reading') % {
+          file: filename,
+        }
+      end
+
+      # Persist the contents of the namespace to disk.
+      #
+      # Directories will be automatically created and the contents of the
+      # namespace will be serialized automatically with {#serialize_data}.
+      #
+      # @raise [PDK::Config::LoadError] if one of the intermediary path components
+      #   exist but is not a directory.
+      # @raise [PDK::Config::LoadError] if the user does not have the
+      #   permissions needed to write the file.
+      #
+      # @return [nil]
+      def save_data
+        return if file.nil?
+
+        PDK::Util::Filesystem.mkdir_p(File.dirname(file))
+
+        PDK::Util::Filesystem.write_file(file, serialize_data(to_h))
+      rescue Errno::EACCES
+        raise PDK::Config::LoadError, _('Unable to open %{file} for writing') % {
+          file: file,
+        }
+      rescue SystemCallError => e
+        raise PDK::Config::LoadError, e.message
+      end
+
+      # Memoised accessor for the loaded data.
+      #
+      # @return [Hash<String => PDK::Config::Setting>] the contents of the namespace.
+      def settings
+        return @settings if @loaded_from_file
+        @loaded_from_file = true
+        return @settings if file.nil?
+        parse_file(file) do |key, parsed_setting|
+          # Create a settings chain if a setting already exists
+          parsed_setting.previous_setting = @settings[key] unless @settings[key].nil?
+          @settings[key] = parsed_setting
+        end
+        @settings
+      end
+    end
+  end
+end