openvox 8.19.0

data/lib/puppet/pops/serialization/time_factory.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Puppet::Pops
+module Serialization
+  # Implements all the constructors found in the Time class and ensures that
+  # the created Time object can be serialized and deserialized using its
+  # seconds and nanoseconds without loss of precision.
+  #
+  # @deprecated No longer in use. Functionality replaced by Timestamp
+  # @api private
+  class TimeFactory
+    NANO_DENOMINATOR = 10**9
+
+    def self.at(*args)
+      sec_nsec_safe(Time.at(*args))
+    end
+
+    def self.gm(*args)
+      sec_nsec_safe(Time.gm(*args))
+    end
+
+    def self.local(*args)
+      sec_nsec_safe(Time.local(*args))
+    end
+
+    def self.mktime(*args)
+      sec_nsec_safe(Time.mktime(*args))
+    end
+
+    def self.new(*args)
+      sec_nsec_safe(Time.new(*args))
+    end
+
+    def self.now
+      sec_nsec_safe(Time.now)
+    end
+
+    def self.utc(*args)
+      sec_nsec_safe(Time.utc(*args))
+    end
+
+    # Creates a Time object from a Rational defined as:
+    #
+    # (_sec_ * #NANO_DENOMINATOR + _nsec_) / #NANO_DENOMINATOR
+    #
+    # This ensures that a Time object can be reliably serialized and using its
+    # its #tv_sec and #tv_nsec values and then recreated again (using this method)
+    # without loss of precision.
+    #
+    # @param sec [Integer] seconds since Epoch
+    # @param nsec [Integer] nano seconds
+    # @return [Time] the created object
+    #
+    def self.from_sec_nsec(sec, nsec)
+      Time.at(Rational(sec * NANO_DENOMINATOR + nsec, NANO_DENOMINATOR))
+    end
+
+    # Returns a new Time object that is adjusted to ensure that precision is not
+    # lost when it is serialized and deserialized using its seconds and nanoseconds
+    # @param t [Time] the object to adjust
+    # @return [Time] the adjusted object
+    #
+    def self.sec_nsec_safe(t)
+      from_sec_nsec(t.tv_sec, t.tv_nsec)
+    end
+  end
+end
+end

data/lib/puppet/pops/serialization/to_data_converter.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+module Puppet::Pops
+module Serialization
+  # Class that can process an arbitrary object into a value that is assignable to `Data`.
+  #
+  # @api public
+  class ToDataConverter
+    include Evaluator::Runtime3Support
+
+    # Convert the given _value_ according to the given _options_ and return the result of the conversion
+    #
+    # @param value [Object] the value to convert
+    # @param options {Symbol => <Boolean,String>} options hash
+    # @option options [Boolean] :rich_data `true` if rich data is enabled
+    # @option options [Boolean] :local_reference use local references instead of duplicating complex entries
+    # @option options [Boolean] :type_by_reference `true` if Object types are converted to references rather than embedded.
+    # @option options [Boolean] :symbol_as_string `true` if Symbols should be converted to strings (with type loss)
+    # @option options [String] :message_prefix String to prepend to in warnings and errors
+    # @return [Data] the processed result. An object assignable to `Data`.
+    #
+    # @api public
+    def self.convert(value, options = EMPTY_HASH)
+      new(options).convert(value)
+    end
+
+    # Create a new instance of the processor
+    #
+    # @param options {Symbol => Object} options hash
+    # @option options [Boolean] :rich_data `true` if rich data is enabled
+    # @option options [Boolean] :local_references use local references instead of duplicating complex entries
+    # @option options [Boolean] :type_by_reference `true` if Object types are converted to references rather than embedded.
+    # @option options [Boolean] :symbol_as_string `true` if Symbols should be converted to strings (with type loss)
+    # @option options [String] :message_prefix String to prepend to path in warnings and errors
+    # @option semantic [Object] :semantic object to pass to the issue reporter
+    def initialize(options = EMPTY_HASH)
+      @type_by_reference = options[:type_by_reference]
+      @type_by_reference = true if @type_by_reference.nil?
+
+      @local_reference = options[:local_reference]
+      @local_reference = true if @local_reference.nil?
+
+      @symbol_as_string = options[:symbol_as_string]
+      @symbol_as_string = false if @symbol_as_string.nil?
+
+      @rich_data = options[:rich_data]
+      @rich_data = false if @rich_data.nil?
+
+      @message_prefix = options[:message_prefix]
+      @semantic = options[:semantic]
+    end
+
+    # Convert the given _value_
+    #
+    # @param value [Object] the value to convert
+    # @return [Data] the processed result. An object assignable to `Data`.
+    #
+    # @api public
+    def convert(value)
+      @path = []
+      @values = {}
+      to_data(value)
+    end
+
+    private
+
+    def path_to_s
+      s = String.new(@message_prefix || '')
+      s << JsonPath.to_json_path(@path)[1..]
+      s
+    end
+
+    def to_data(value)
+      if value.nil? || Types::PScalarDataType::DEFAULT.instance?(value)
+        if @rich_data && value.is_a?(String) && value.encoding == Encoding::ASCII_8BIT
+          # Transform the binary string to rich Binary
+          {
+            PCORE_TYPE_KEY => PCORE_TYPE_BINARY,
+            PCORE_VALUE_KEY => Puppet::Pops::Types::PBinaryType::Binary.from_binary_string(value).to_s
+          }
+        else
+          value
+        end
+      elsif :default == value
+        if @rich_data
+          { PCORE_TYPE_KEY => PCORE_TYPE_DEFAULT }
+        else
+          serialization_issue(Issues::SERIALIZATION_DEFAULT_CONVERTED_TO_STRING, :path => path_to_s)
+          'default'
+        end
+      elsif value.is_a?(Symbol)
+        if @symbol_as_string
+          value.to_s
+        elsif @rich_data
+          { PCORE_TYPE_KEY => PCORE_TYPE_SYMBOL, PCORE_VALUE_KEY => value.to_s }
+        else
+          unknown_to_string_with_warning(value)
+        end
+      elsif value.instance_of?(Array)
+        process(value) do
+          result = []
+          value.each_with_index do |elem, index|
+            with(index) { result << to_data(elem) }
+          end
+          result
+        end
+      elsif value.instance_of?(Hash)
+        process(value) do
+          if value.keys.all? { |key| key.is_a?(String) && key != PCORE_TYPE_KEY }
+            result = {}
+            value.each_pair { |key, elem| with(key) { result[key] = to_data(elem) } }
+            result
+          else
+            non_string_keyed_hash_to_data(value)
+          end
+        end
+      elsif value.instance_of?(Types::PSensitiveType::Sensitive)
+        process(value) do
+          { PCORE_TYPE_KEY => PCORE_TYPE_SENSITIVE, PCORE_VALUE_KEY => to_data(value.unwrap) }
+        end
+      else
+        unknown_to_data(value)
+      end
+    end
+
+    # If `:local_references` is enabled, then the `object_id` will be associated with the current _path_ of
+    # the context the first time this method is called. The method then returns the result of  yielding to
+    # the given block. Subsequent calls with a value that has the same `object_id` will instead return a
+    # reference based on the given path.
+    #
+    # If `:local_references` is disabled, then this method performs a check for endless recursion before
+    # it yields to the given block. The result of yielding is returned.
+    #
+    # @param value [Object] the value
+    # @yield The block that will produce the data for the value
+    # @return [Data] the result of yielding to the given block, or a hash denoting a reference
+    #
+    # @api private
+    def process(value, &block)
+      if @local_reference
+        id = value.object_id
+        ref = @values[id]
+        if ref.nil?
+          @values[id] = @path.dup
+          yield
+        elsif ref.instance_of?(Hash)
+          ref
+        else
+          json_ref = JsonPath.to_json_path(ref)
+          if json_ref.nil?
+            # Complex key and hence no way to reference the prior value. The value must therefore be
+            # duplicated which in turn introduces a risk for endless recursion in case of self
+            # referencing structures
+            with_recursive_guard(value, &block)
+          else
+            @values[id] = { PCORE_TYPE_KEY => PCORE_LOCAL_REF_SYMBOL, PCORE_VALUE_KEY => json_ref }
+          end
+        end
+      else
+        with_recursive_guard(value, &block)
+      end
+    end
+
+    # Pushes `key` to the end of the path and yields to the given block. The
+    # `key` is popped when the yield returns.
+    # @param key [Object] the key to push on the current path
+    # @yield The block that will produce the returned value
+    # @return [Object] the result of yielding to the given block
+    #
+    # @api private
+    def with(key)
+      @path.push(key)
+      value = yield
+      @path.pop
+      value
+    end
+
+    # @param value [Object] the value to use when checking endless recursion
+    # @yield The block that will produce the data
+    # @return [Data] the result of yielding to the given block
+    def with_recursive_guard(value)
+      id = value.object_id
+      if @recursive_lock
+        if @recursive_lock.include?(id)
+          serialization_issue(Issues::SERIALIZATION_ENDLESS_RECURSION, :type_name => value.class.name)
+        end
+        @recursive_lock[id] = true
+      else
+        @recursive_lock = { id => true }
+      end
+      v = yield
+      @recursive_lock.delete(id)
+      v
+    end
+
+    def unknown_to_data(value)
+      @rich_data ? value_to_data_hash(value) : unknown_to_string_with_warning(value)
+    end
+
+    def unknown_key_to_string_with_warning(value)
+      str = unknown_to_string(value)
+      serialization_issue(Issues::SERIALIZATION_UNKNOWN_KEY_CONVERTED_TO_STRING, :path => path_to_s, :klass => value.class, :value => str)
+      str
+    end
+
+    def unknown_to_string_with_warning(value)
+      str = unknown_to_string(value)
+      serialization_issue(Issues::SERIALIZATION_UNKNOWN_CONVERTED_TO_STRING, :path => path_to_s, :klass => value.class, :value => str)
+      str
+    end
+
+    def unknown_to_string(value)
+      value.is_a?(Regexp) ? Puppet::Pops::Types::PRegexpType.regexp_to_s_with_delimiters(value) : value.to_s
+    end
+
+    def non_string_keyed_hash_to_data(hash)
+      if @rich_data
+        to_key_extended_hash(hash)
+      else
+        result = {}
+        hash.each_pair do |key, value|
+          if key.is_a?(Symbol) && @symbol_as_string
+            key = key.to_s
+          elsif !key.is_a?(String)
+            key = unknown_key_to_string_with_warning(key)
+          end
+          with(key) { result[key] = to_data(value) }
+        end
+        result
+      end
+    end
+
+    # A Key extended hash is a hash whose keys are not entirely strings. Such a hash
+    # cannot be safely represented as JSON or YAML
+    #
+    # @param hash {Object => Object} the hash to process
+    # @return [String => Data] the representation of the extended hash
+    def to_key_extended_hash(hash)
+      key_value_pairs = []
+      hash.each_pair do |key, value|
+        key = to_data(key)
+        key_value_pairs << key
+        key_value_pairs << with(key) { to_data(value) }
+      end
+      { PCORE_TYPE_KEY => PCORE_TYPE_HASH, PCORE_VALUE_KEY => key_value_pairs }
+    end
+
+    def value_to_data_hash(value)
+      pcore_type = value.is_a?(Types::PuppetObject) ? value._pcore_type : Types::TypeCalculator.singleton.infer(value)
+      if pcore_type.is_a?(Puppet::Pops::Types::PRuntimeType)
+        unknown_to_string_with_warning(value)
+      else
+        pcore_tv = pcore_type_to_data(pcore_type)
+        if pcore_type.roundtrip_with_string?
+          {
+            PCORE_TYPE_KEY => pcore_tv,
+
+            # Scalar values are stored using their default string representation
+            PCORE_VALUE_KEY => Types::StringConverter.singleton.convert(value)
+          }
+        elsif pcore_type.implementation_class.respond_to?(:_pcore_init_from_hash)
+          process(value) do
+            {
+              PCORE_TYPE_KEY => pcore_tv,
+            }.merge(to_data(value._pcore_init_hash))
+          end
+        else
+          process(value) do
+            (names, _, required_count) = pcore_type.parameter_info(value.class)
+            args = names.map { |name| value.send(name) }
+
+            # Pop optional arguments that are default
+            while args.size > required_count
+              break unless pcore_type[names[args.size - 1]].default_value?(args.last)
+
+              args.pop
+            end
+            result = {
+              PCORE_TYPE_KEY => pcore_tv
+            }
+            args.each_with_index do |val, idx|
+              key = names[idx]
+              with(key) { result[key] = to_data(val) }
+            end
+            result
+          end
+        end
+      end
+    end
+
+    def pcore_type_to_data(pcore_type)
+      type_name = pcore_type.name
+      if @type_by_reference || type_name.start_with?('Pcore::')
+        type_name
+      else
+        with(PCORE_TYPE_KEY) { to_data(pcore_type) }
+      end
+    end
+    private :pcore_type_to_data
+
+    def serialization_issue(issue, options = EMPTY_HASH)
+      semantic = @semantic
+      if semantic.nil?
+        tos = Puppet::Pops::PuppetStack.top_of_stack
+        if tos.empty?
+          semantic = Puppet::Pops::SemanticError.new(issue, nil, EMPTY_HASH)
+        else
+          file, line = stacktrace
+          semantic = Puppet::Pops::SemanticError.new(issue, nil, { :file => file, :line => line })
+        end
+      end
+      optionally_fail(issue, semantic, options)
+    end
+  end
+end
+end

data/lib/puppet/pops/serialization/to_stringified_converter.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Puppet::Pops
+module Serialization
+  # Class that can process an arbitrary object into a value that is assignable to `Data`
+  # and where contents is converted from rich data to one of:
+  # * Numeric (Integer, Float)
+  # * Boolean
+  # * Undef (nil)
+  # * String
+  # * Array
+  # * Hash
+  #
+  # The conversion is lossy - the result cannot be deserialized to produce the original data types.
+  # All rich values are transformed to strings..
+  # Hashes with rich keys are transformed to use string representation of such keys.
+  #
+  # @api public
+  class ToStringifiedConverter
+    include Evaluator::Runtime3Support
+
+    # Converts the given _value_ according to the given _options_ and return the result of the conversion
+    #
+    # @param value [Object] the value to convert
+    # @param options {Symbol => <Boolean,String>} options hash
+    # @option options [String] :message_prefix String to prepend to in warnings and errors
+    # @option options [String] :semantic object (AST) to pass to the issue reporter
+    # @return [Data] the processed result. An object assignable to `Data` with rich data stringified.
+    #
+    # @api public
+    def self.convert(value, options = EMPTY_HASH)
+      new(options).convert(value)
+    end
+
+    # Creates a new instance of the processor
+    #
+    # @param options {Symbol => Object} options hash
+    # @option options [String] :message_prefix String to prepend to path in warnings and errors
+    # @option semantic [Object] :semantic object to pass to the issue reporter
+    def initialize(options = EMPTY_HASH)
+      @message_prefix = options[:message_prefix]
+      @semantic = options[:semantic]
+    end
+
+    # Converts the given _value_
+    #
+    # @param value [Object] the value to convert
+    # @return [Data] the processed result. An object assignable to `Data` with rich data stringified.
+    #
+    # @api public
+    def convert(value)
+      @path = []
+      @values = {}
+      to_data(value)
+    end
+
+    private
+
+    def path_to_s
+      s = @message_prefix || ''
+      s << JsonPath.to_json_path(@path)[1..]
+      s
+    end
+
+    def to_data(value)
+      if value.instance_of?(String)
+        to_string_or_binary(value)
+      elsif value.nil? || Types::PScalarDataType::DEFAULT.instance?(value)
+        value
+      elsif :default == value
+        'default'
+      elsif value.is_a?(Symbol)
+        value.to_s
+      elsif value.instance_of?(Array)
+        process(value) do
+          result = []
+          value.each_with_index do |elem, index|
+            with(index) { result << to_data(elem) }
+          end
+          result
+        end
+      elsif value.instance_of?(Hash)
+        process(value) do
+          if value.keys.all? { |key| key.is_a?(String) && key != PCORE_TYPE_KEY && key != PCORE_VALUE_KEY }
+            result = {}
+            value.each_pair { |key, elem| with(key) { result[key] = to_data(elem) } }
+            result
+          else
+            non_string_keyed_hash_to_data(value)
+          end
+        end
+      else
+        unknown_to_string(value)
+      end
+    end
+
+    # Turns an ASCII-8BIT encoded string into a Binary, returns US_ASCII encoded and transforms all other strings to UTF-8
+    # with replacements for non Unicode characters.
+    # If String cannot be represented as UTF-8
+    def to_string_or_binary(value)
+      encoding = value.encoding
+      if encoding == Encoding::ASCII_8BIT
+        Puppet::Pops::Types::PBinaryType::Binary.from_binary_string(value).to_s
+      else
+        # Transform to UTF-8 (do not assume UTF-8 is correct) with source invalid byte
+        # sequences and UTF-8 undefined characters replaced by the default unicode uFFFD character
+        # (black diamond with question mark).
+        value.encode(Encoding::UTF_8, encoding, :invalid => :replace, :undef => :replace)
+      end
+    end
+
+    # Performs a check for endless recursion before
+    # it yields to the given block. The result of yielding is returned.
+    #
+    # @param value [Object] the value
+    # @yield The block that will produce the data for the value
+    # @return [Data] the result of yielding to the given block, or a hash denoting a reference
+    #
+    # @api private
+    def process(value, &block)
+      with_recursive_guard(value, &block)
+    end
+
+    # Pushes `key` to the end of the path and yields to the given block. The
+    # `key` is popped when the yield returns.
+    # @param key [Object] the key to push on the current path
+    # @yield The block that will produce the returned value
+    # @return [Object] the result of yielding to the given block
+    #
+    # @api private
+    def with(key)
+      @path.push(key)
+      value = yield
+      @path.pop
+      value
+    end
+
+    # @param value [Object] the value to use when checking endless recursion
+    # @yield The block that will produce the data
+    # @return [Data] the result of yielding to the given block
+    def with_recursive_guard(value)
+      id = value.object_id
+      if @recursive_lock
+        if @recursive_lock.include?(id)
+          serialization_issue(Issues::SERIALIZATION_ENDLESS_RECURSION, :type_name => value.class.name)
+        end
+        @recursive_lock[id] = true
+      else
+        @recursive_lock = { id => true }
+      end
+      v = yield
+      @recursive_lock.delete(id)
+      v
+    end
+
+    # A hash key that is non conforming
+    def unknown_key_to_string(value)
+      unknown_to_string(value)
+    end
+
+    def unknown_to_string(value)
+      if value.is_a?(Regexp)
+        return Puppet::Pops::Types::PRegexpType.regexp_to_s_with_delimiters(value)
+
+      elsif value.instance_of?(Types::PSensitiveType::Sensitive)
+        # to_s does not differentiate between instances - if they were used as keys in a hash
+        # the stringified result would override all Sensitive keys with the last such key's value
+        # this adds object_id.
+        #
+        return "#<#{value}:#{value.object_id}>"
+
+      elsif value.is_a?(Puppet::Pops::Types::PObjectType)
+        # regular to_s on an ObjectType gives the entire definition
+        return value.name
+
+      end
+
+      # Do a to_s on anything else
+      result = value.to_s
+
+      # The result may be ascii-8bit encoded without being a binary (low level object.inspect returns ascii-8bit string)
+      # This can be the case if runtime objects have very simple implementation (no to_s or inspect method).
+      # They are most likely not of Binary nature. Therefore the encoding is forced and only if it errors
+      # will the result be taken as binary and encoded as base64 string.
+      if result.encoding == Encoding::ASCII_8BIT
+        begin
+          result.force_encoding(Encoding::UTF_8)
+        rescue
+          # The result cannot be represented in UTF-8, make it a binary Base64 encoded string
+          Puppet::Pops::Types::PBinaryType::Binary.from_binary_string(result).to_s
+        end
+      end
+      result
+    end
+
+    def non_string_keyed_hash_to_data(hash)
+      result = {}
+      hash.each_pair do |key, value|
+        if key.is_a?(Symbol)
+          key = key.to_s
+        elsif !key.is_a?(String)
+          key = unknown_key_to_string(key)
+        end
+        if key == "__ptype" || key == "__pvalue"
+          key = "reserved key: #{key}"
+        end
+        with(key) { result[key] = to_data(value) }
+      end
+      result
+    end
+
+    def serialization_issue(issue, options = EMPTY_HASH)
+      semantic = @semantic
+      if semantic.nil?
+        tos = Puppet::Pops::PuppetStack.top_of_stack
+        if tos.empty?
+          semantic = Puppet::Pops::SemanticError.new(issue, nil, EMPTY_HASH)
+        else
+          file, line = stacktrace
+          semantic = Puppet::Pops::SemanticError.new(issue, nil, { :file => file, :line => line })
+        end
+      end
+      optionally_fail(issue, semantic, options)
+    end
+  end
+end
+end

data/lib/puppet/pops/serialization.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Puppet::Pops
+module Serialization
+  def self.not_implemented(impl, method_name)
+    raise NotImplementedError, "The class #{impl.class.name} should have implemented the method #{method_name}()"
+  end
+
+  class SerializationError < Puppet::Error
+  end
+
+  PCORE_TYPE_KEY = '__ptype'
+
+  # Key used when the value can be represented as, and recreated from, a single string that can
+  # be passed to a `from_string` method or an array of values that can be passed to the default
+  # initializer method.
+  PCORE_VALUE_KEY = '__pvalue'
+
+  # Type key used for hashes that contain keys that are not of type String
+  PCORE_TYPE_HASH = 'Hash'
+
+  # Type key used for symbols
+  PCORE_TYPE_SENSITIVE = 'Sensitive'
+  PCORE_TYPE_BINARY = 'Binary'
+
+  # Type key used for symbols
+  PCORE_TYPE_SYMBOL = 'Symbol'
+
+  # Type key used for Default
+  PCORE_TYPE_DEFAULT = 'Default'
+
+  # Type key used for document local references
+  PCORE_LOCAL_REF_SYMBOL = 'LocalRef'
+end
+end
+
+require_relative 'serialization/json_path'
+require_relative 'serialization/from_data_converter'
+require_relative 'serialization/to_data_converter'
+require_relative 'serialization/to_stringified_converter'
+require_relative 'serialization/serializer'
+require_relative 'serialization/deserializer'
+require_relative 'serialization/json'
+require_relative 'serialization/time_factory'
+require_relative 'serialization/object'