pdk 1.13.0 → 1.14.0

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/json.rb

@@ -3,16 +3,27 @@ require 'pdk/config/namespace'
 module PDK
   class Config
     class JSON < Namespace
-      def parse_data(data, _filename)
-        return {} if data.nil? || data.empty?
+      # 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'
 
-        ::JSON.parse(data)
+        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'
 

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

@@ -26,10 +26,12 @@ module PDK
       # @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?
-        @values = {}
+        @settings = {}
         @name = name.to_s
         @parent = parent
         @persistent_defaults = persistent_defaults
+        @mounts = {}
+        @loaded_from_file = false
 
         instance_eval(&block) if block_given?
       end
@@ -43,9 +45,9 @@ module PDK
       # @param block [Proc] a block that is evaluated within the new [self].
       #
       # @return [nil]
-      def value(key, &block)
-        @values[key.to_s] ||= PDK::Config::Value.new(key.to_s)
-        @values[key.to_s].instance_eval(&block) if block_given?
+      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.
@@ -64,7 +66,7 @@ module PDK
         obj.parent = self
         obj.name = key.to_s
         obj.instance_eval(&block) if block_given?
-        data[key.to_s] = obj
+        @mounts[key.to_s] = obj
       end
 
       # Create and mount a new child namespace.
@@ -88,11 +90,21 @@ module PDK
       #
       # @return [Object] the requested value.
       def [](key)
-        data[key.to_s]
+        # 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.
+      # 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
@@ -105,7 +117,12 @@ module PDK
       #
       # @return [Object] the requested value.
       def fetch(key, default_value)
-        data.fetch(key.to_s, 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
@@ -116,6 +133,8 @@ module PDK
       #
       # @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
@@ -131,14 +150,11 @@ module PDK
       # @return [Hash{String => Object}] the values from the namespace that
       #   should be persisted to disk.
       def to_h
-        data.inject({}) do |new_hash, (key, value)|
-          new_hash[key] = if value.is_a?(PDK::Config::Namespace)
-                            value.include_in_parent? ? value.to_h : nil
-                          else
-                            value
-                          end
-          new_hash.delete_if { |_, v| v.nil? }
-        end
+        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.
@@ -146,20 +162,16 @@ module PDK
       # @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)
-        # Explicitly force values to be loaded if they have not already
-        # done so. This will not cause them to be persisted to disk
-        (@values.keys - data.keys).each { |key_name| self[key_name] }
         resolved = {}
-        data.each do |data_name, obj|
-          case obj
-          when PDK::Config::Namespace
-            # Query the child namespace
-            resolved.merge!(obj.resolve(filter))
-          else
-            setting_name = [name, data_name.to_s].join('.')
-            resolved[setting_name] = self[data_name] if be_resolved?(setting_name, filter)
+        # 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
 
@@ -208,16 +220,38 @@ module PDK
         name.start_with?(filter + '.') # If name is a subkey of the filter then it should be resolved
       end
 
-      # @abstract Subclass and override {#parse_data} to implement parsing logic
+      # @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.
       #
-      # @return [Hash{String => Object}] the data to be loaded into the
+      # @yield [String, Object] the data to be loaded into the
       #   namespace.
-      def parse_data(_data, _filename)
-        {}
+      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.
@@ -228,40 +262,32 @@ module PDK
       # @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)
-        @values[key.to_s].validate!([name, key.to_s].join('.'), value) if @values.key?(key.to_s)
-
-        data[key.to_s] = 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
 
-      # Read the file associated with the namespace.
+      # 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
-        return if file.nil?
-        return unless PDK::Util::Filesystem.file?(file)
+      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: file,
+          file: filename,
         }
       end
 
-      # @abstract Subclass and override {#save_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
-
       # Persist the contents of the namespace to disk.
       #
       # Directories will be automatically created and the contents of the
@@ -289,35 +315,17 @@ module PDK
 
       # Memoised accessor for the loaded data.
       #
-      # @return [Hash<String => Object>] the contents of the namespace.
-      def data
-        # It's possible for parse_data to return nil, so just return an empty hash
-        @data ||= parse_data(load_data, file).tap do |h|
-          h.default_proc = default_config_value unless h.nil?
-        end || {}
-      end
-
-      # The default behaviour of the namespace when the requested value does
-      # not exist.
-      #
-      # If the value has been pre-configured with {#value} to have a default
-      # value, resolve the default value and set it in the namespace and optionally
-      # save the new default.
-      # Otherwise, set the value to a new Hash to allow for arbitrary level of nested values.
-      #
-      # @return [Proc] suitable for use by {Hash#default_proc}.
-      def default_config_value
-        ->(hash, key) do
-          if @values.key?(key) && @values[key].default?
-            set_volatile_value(key, @values[key].default)
-            save_data if @persistent_defaults
-            hash[key]
-          else
-            hash[key] = {}.tap do |h|
-              h.default_proc = default_config_value
-            end
-          end
+      # @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