xolo-server 1.0.0 → 1.0.1

data/lib/xolo/core/base_classes/configuration.rb

@@ -0,0 +1,238 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+
+# frozen_string_literal: true
+
+module Xolo
+
+  module Core
+
+    module BaseClasses
+
+      # A class for working with pre-defined settings & preferences for Xolo
+      #
+      # This is the base class for Xolo::Server::Configuration and Xolo::Admin::Configuration
+      #
+      # The subclasses must 'include Singleton', making them use the Singleton Pattern, meaning
+      # only one instance can exist at a time.
+      #
+      # This parent class provides methods for loading and saving YAML files with configuration
+      # and prefs settings in the Server or Admin context.
+      #
+      # The YAML files store a Hash of keys and values relevent to the context
+      # they are used in.
+      #
+      # Subclasses must define these constants and related methods:
+      #
+      # Constant CONF_FILENAME [String]
+      #   The filename (not the full path) of the config yaml file to read and write.
+      #
+      # Instance method #conf_file [Pathname]
+      #  The full expanded absolute path to the config yaml file.
+      #
+      # Constant KEYS [Hash{Symbol: Hash}]
+      #   The keys of this Hash are the keys that may be found in the yaml file.
+      #   The Hash values here define the value in the YAML file, with these keys:
+      #
+      #     required: [Boolean] Is this key/value required in the YAML file? The server
+      #        will not start if a required key is missing.
+      #
+      #     type: [Symbol] The data-type of the value, one of the types supported by
+      #       Optimist: :boolean, :string, :integer, :float, :io, :date
+      #       See https://github.com/ManageIQ/optimist/wiki/Option-Types
+      #
+      #     default: [Object] If this key doesn't exist in the YAML file, this is the
+      #       value used by Xolo.
+      #
+      #     desc: [String] A full description of what this value is, how it is used,
+      #       possible values, etc. This is presented in help and/or walkthru.
+      #
+      #     load_method: [Symbol] The name of a method in the Configuration Instance
+      #       to which the YAML value will be passed to convert it into the real value
+      #       to be used.  For example, some YAML values might contain a command to be
+      #       executed, a pathname to be read, or a raw value to be used. These
+      #       values should be passed to the :data_from_command_file_or_string method
+      #       which will return the value to actually be used (the stdout of a command,
+      #       the contents of a file, or a raw value)
+      #
+      #     private: [Boolean] If true, the value is never presented in logs or normal
+      #       output. it is replaced with <private>. Use this for sensitive secrets.
+      #
+      #
+      #
+      class Configuration
+
+        # Mixins
+        #####################################
+        #####################################
+
+        # Constants
+        #####################################
+        #####################################
+
+        PIPE = '|'
+
+        PRIVATE = '<private>'
+
+        # Class Methods
+        #####################################
+        #####################################
+
+        def self.inherited(child_class)
+          Xolo.verbose_inherit child_class, self
+        end
+
+        # Attributes
+        #####################################
+        #####################################
+
+        # @return [Hash{Symbol: Object}] The data as read directly from the YAML file
+        attr_reader :raw_data
+
+        # @return
+
+        # Constructor
+        #####################################
+        #####################################
+
+        # # Initialize!
+        def initialize
+          keys.each_key { |attr| self.class.attr_accessor attr }
+          load_from_file
+        end
+
+        # Public Instance Methods
+        #####################################
+        #####################################
+
+        ###############
+        def to_h
+          data = {}
+          keys.each_key do |key|
+            data[key] = send(key)
+          end
+          data
+        end
+
+        ###############
+        def to_h_private
+          data = to_h
+          keys.each do |key, deets|
+            data[key] = PRIVATE if deets[:private]
+          end
+          data
+        end
+
+        # Save new data (or raw_data) to the config file. We don't save the
+        # actual instance variables, as they may be expanded from
+        # commands or file paths, and its the commands or file paths
+        # we want to save.
+        #
+        # @param data [Hash{Symbol: Object}] The data to save to the config file
+        #
+        # @return [void]
+        ###############
+        def save_to_file(data: nil)
+          data ||= raw_data
+          conf_file.parent.mkpath unless conf_file.parent.directory?
+          conf_file.pix_save YAML.dump(data)
+          conf_file.chmod 0o600
+        end
+
+        # If the given string starts with a pipe (|) then
+        # remove the pipe and execute the remainder, returning
+        # its stdout.
+        #
+        # If the given string is a path to an executable file path, return
+        # its stdout.
+        #
+        # If the given string is a path to a readable file path, return
+        # its contents.
+        #
+        # Otherwise, the string is the desired data, so just return it.
+        #
+        # @param str [String] a command, file path, or string
+        #
+        # @param enforce_secure_mode [Boolean] If true, and the str is
+        #   a path to a file, make sure that the file mode is 700 or 600.
+        #
+        # @return [String] The std output of the command, file contents, or string
+        #
+        ###############
+        def data_from_command_file_or_string(str, enforce_secure_mode: false)
+          # if it starts with a pipe, it's a command and args
+          # remove the pipe and execute the rest, returning stdout
+          return `#{str.delete_prefix(PIPE)}`.chomp if str.start_with? PIPE
+
+          path = Pathname.new(str)
+          return str unless path.file?
+
+          # this will return, e.g. "600" "775" etc as strings
+          mode = format '%o', (path.stat.mode & 0o777)
+
+          if path.executable?
+            if enforce_secure_mode && !mode.end_with?('00')
+              raise Xolo::Core::Exceptions::PermissionError,
+                    "Executable file #{str} must be mode 0700, 0500, or 0100"
+            end
+            `#{path.to_s.shellescape}`.chomp
+
+          elsif path.readable?
+            if enforce_secure_mode && mode != '600'
+              raise Xolo::Core::Exceptions::PermissionError,
+                    "Readable file #{str} must be mode 0600"
+            end
+            path.read.chomp
+
+          else
+            str
+          end
+        end
+
+        # Private Instance Methods
+        #####################################
+        #####################################
+        private
+
+        # Simpler access to the KEYS constant in subclasses
+        #
+        # @return [Hash]
+        #
+        ###############
+        def keys
+          self.class::KEYS
+        end
+
+        # Load in the values from the config file
+        #
+        # @return [void]
+        #
+        ###############
+        ###############
+        def load_from_file
+          conf_file.parent.mkpath unless conf_file.parent.directory?
+
+          unless conf_file.readable?
+            @raw_data = {}
+            return
+          end
+
+          @raw_data = YAML.load conf_file.read
+          @raw_data.each do |k, v|
+            next unless keys[k]
+
+            v = send(keys[k][:load_method], v) if keys[k][:load_method]
+            send "#{k}=", v
+          end
+        end
+
+      end # class Configuration
+
+    end # BaseClasses
+
+  end # Core
+
+end # Xolo

data/lib/xolo/core/base_classes/server_object.rb

@@ -0,0 +1,112 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+# frozen_string_literal: true
+
+# main module
+module Xolo
+
+  module Core
+
+    module BaseClasses
+
+      # The base class for dealing with Titles and Versions/Patches in the
+      # Xolo Server, Admin, and Client modules.
+      #
+      # The base class for "xolo objects stored on the xolo server", i.e.
+      # Titles and Versions/Patches - whether they are being used on the server,
+      # in xadm, or in the client.
+      #
+      # This class holds stuff common to all no matter where or how they are used.
+      #
+      # See also {Xolo::Core::BaseClasses::Title} and {Xolo::Core::BaseClasses::Version}
+      #############################
+      class ServerObject
+
+        # Mixins
+        #############################
+        #############################
+
+        extend Xolo::Core::JSONWrappers
+
+        include Xolo::Core::JSONWrappers
+
+        # Constants
+        #############################
+        #############################
+
+        # Attributes
+        #############################
+        #############################
+
+        # Constructor
+        ######################
+        ######################
+        def initialize(data_hash)
+          # log_debug "Instantiating a #{self.class}..."
+
+          self.class::ATTRIBUTES.each do |attr, deets|
+            val = data_hash[attr]
+
+            # log_debug "Initializing, setting ATTR '#{attr}' => '#{val}' (#{val.class})"
+
+            # anything not nil, esp empty arrays, needs to be set
+            next if val.nil?
+
+            # convert timestamps to Time objects if needed,
+            # All the other values shouldn't need converting
+            # when taking in JSON or xadm opts.
+            val = Time.parse(val.to_s) if deets[:type] == :time && !val.is_a?(Time)
+
+            # call the setter
+            send "#{attr}=", val
+          end
+        end
+
+        # Instance Methods
+        ######################
+        ######################
+
+        # Convert to a Hash for sending between xadm and the Xolo Server,
+        # or installing on clients.
+        #
+        # Only the values defined in ATTRIBUTES are sent, because all other
+        # other attributes are meant only for the local context, i.e.
+        # on the server, via xadm, or via 'xolo'.
+        #
+        # @return [String] The attributes of this title as JSON
+        #####################
+        def to_h
+          hash = {}
+          self.class::ATTRIBUTES.each do |attr, deets|
+            hash[attr] = send attr
+
+            # ensure multi values are arrays, even if they are empty
+            hash[attr] = [hash[attr]].compact if deets[:multi] && !hash[attr].is_a?(Array)
+          end
+          hash
+        end
+
+        # Convert to a JSON object for sending between xadm and the Xolo Server
+        # or storage on the server.
+        #
+        # Always make it 'pretty', i.e.  human readable, since it often
+        # gets stored in files that humans will look at
+        #
+        # @return [String] The attributes of this title as JSON
+        #####################
+        def to_json(*_args)
+          JSON.pretty_generate to_h
+        end
+
+      end # class Title
+
+    end # module BaseClasses
+
+  end # module Core
+
+end # module Xolo