xolo-server 1.0.0 → 1.0.1

data/lib/xolo/core/exceptions.rb

@@ -0,0 +1,52 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+module Xolo
+
+  module Core
+
+    module Exceptions
+
+      # General errors
+
+      class MissingDataError < RuntimeError; end
+
+      class InvalidDataError < RuntimeError; end
+
+      class NoSuchItemError < RuntimeError; end
+
+      class UnsupportedError < RuntimeError; end
+
+      class KeychainError < RuntimeError; end
+
+      class ActionRequiredError < RuntimeError; end
+
+      # Connections & Access
+
+      class ConnectionError < RuntimeError; end
+
+      class NotConnectedError < ConnectionError; end
+
+      class TimeoutError < ConnectionError; end
+
+      class AuthenticationError < ConnectionError; end
+
+      class PermissionError < ConnectionError; end
+
+      class InvalidTokenError < ConnectionError; end
+
+      class ServerError < ConnectionError; end
+
+      # Parsing errors
+
+      class DisallowedYAMLDumpClass; end
+
+    end # module Exceptions
+
+  end # module Core
+
+end # module Xolo

data/lib/xolo/core/json_wrappers.rb

@@ -0,0 +1,43 @@
+# 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
+
+    # constants and methods for consistent JSON processing on the server
+    module JSONWrappers
+
+      # when this module is extended
+      def self.extended(extender)
+        Xolo.verbose_extend extender, self
+      end
+
+      # when this module is included
+      def self.included(includer)
+        Xolo.verbose_include includer, self
+      end
+
+      # A wrapper for JSON.parse that always uses :symbolize_names
+      # def self.parse_json(str)
+      #   JSON.parse str, symbolize_names: true
+      # end
+
+      # A wrapper for JSON.parse that always uses :symbolize_names
+      # and ensures UTF-8 encoding
+      def parse_json(str)
+        JSON.parse str.force_encoding('UTF-8'), symbolize_names: true
+      end
+
+    end # JSON
+
+  end # Core
+
+end # module Xolo

data/lib/xolo/core/loading.rb

@@ -0,0 +1,59 @@
+# 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 Loading
+
+      # touch this file to make mixins send text to stderr as things load
+      # or get mixed in
+      VERBOSE_LOADING_FILE = Pathname.new('/tmp/xolo-verbose-loading')
+
+      # Or, set this ENV var to also make mixins send text to stderr
+      VERBOSE_LOADING_ENV = 'XOLO_VERBOSE_LOADING'
+
+      def self.extended(extender)
+        Xolo.verbose_extend extender, self
+      end
+
+      # Only look at the filesystem once.
+      def verbose_loading?
+        return @verbose_loading unless @verbose_loading.nil?
+
+        @verbose_loading = VERBOSE_LOADING_FILE.file?
+        @verbose_loading ||= ENV.include? VERBOSE_LOADING_ENV
+        @verbose_loading
+      end
+
+      # Send a message to stderr if verbose loading is enabled
+      def load_msg(msg)
+        warn msg if verbose_loading?
+      end
+
+      # Mention that a module is being included into something
+      def verbose_include(includer, includee)
+        load_msg "--> #{includer} is including #{includee}"
+      end
+
+      # Mention that a module is being extended into something
+      def verbose_extend(extender, extendee)
+        load_msg "--> #{extender} is extending #{extendee}"
+      end
+
+      # Mention that a module is being extended into something
+      def verbose_inherit(child_class, parent_class)
+        load_msg "--> #{child_class} is a Subclass inheriting from #{parent_class}"
+      end
+
+    end # module
+
+  end # module
+
+end # module Xolo

data/lib/xolo/core/output.rb

@@ -0,0 +1,292 @@
+# 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
+
+require 'io/console'
+
+module Xolo
+
+  module Core
+
+    # Methods for formattng and sending output to stdout
+    # Should be included in classes as needed
+    #
+    # NOTE: Help output is auto-generated by 'optimist'
+    # The methods here are mostly for presenting info like
+    # columnizd lists and reports and the like.
+    module Output
+
+      # Constants
+      #############################
+      #############################
+
+      # This is used when we are not outputting to a terminal
+      # usually we're being piped or not running in a terminal
+      # so the lines should be as long as they want
+      DEFAULT_LINE_WIDTH = 2000
+
+      # Module methods
+      #
+      # These are available as module methods but not as 'helper'
+      # methods in sinatra routes & views.
+      #
+      ##############################
+      ##############################
+
+      # when this module is included
+      ##############################
+      def self.included(includer)
+        Xolo.verbose_include includer, self
+      end
+
+      # when this module is extended
+      def self.extended(extender)
+        Xolo.verbose_extend extender, self
+      end
+
+      # Instance methods
+      #
+      # These are available directly in sinatra routes and views
+      #
+      ##############################
+      ##############################
+
+      # @return [Integer] how many rows high is our terminal?
+      #########################
+      def terminal_height
+        IO.console.winsize.first
+      end
+
+      # @return [Integer] how many columns wide is our terminal?
+      #########################
+      def terminal_width
+        IO.console.winsize.last
+      end
+
+      # @return [Integer] how wide is our word wrap? terminal-width minus 5
+      #########################
+      def terminal_word_wrap
+        @terminal_word_wrap ||= terminal_width - 5
+      end
+
+      # format a multi-line value by  prepending the desired indentation
+      # to all but the first line, which is expected to be indented in-place where
+      # its being used.
+      #
+      # @param value [String] the value to format
+      # @param indent [Integer] the number of spaces to indent all but the first line
+      # @return [String] the formatted value
+      #######################
+      def format_multiline_indent(value, indent:)
+        value = value.to_s
+        return value unless value.include? "\n"
+
+        lines = value.split("\n")
+        lines[1..-1].each { |line| line.prepend ' ' * indent }
+        lines.join("\n")
+      end
+
+      # TODO: Move this out of Xolo::Core
+      # Display a list of items in as many columns as possible
+      # based on terminal width, e.g. with 3 cols:
+      #
+      #   a thing        another thing    third thing
+      #   thing2         line2 thing      third line 2
+      #   line3 thing    another one      and yet a 3rd
+      #   oh my line4    4 line ok?       yes, this is it
+      #
+      # and if the list is longer than terminal height,
+      # pipe it through 'less'
+      #
+      # @param header [String] A string to display at the top prepended with a '#'
+      #    and appended with a newline and a line of ######'s of the same length.
+      #
+      # @param list [Array<String>] the items to list
+      #
+      # @return [void]
+      ############################
+      def list_in_cols(header, list)
+        longest_list_item = list.map(&:size).max
+        use_columns = (longest_list_item + 5) < terminal_width
+
+        list_to_display = use_columns ? highline_cli.list(list, :columns_down) : list.join("\n")
+
+        output = +"# #{header}\n"
+        output << '#' * (terminal_width - 5)
+        output << "\n"
+        output << list_to_display
+
+        show_text output
+      end
+
+      # Generate a report of rowed/columned data, either fixed-width or tab-delimited.
+      #
+      # Title and header lines are pre-pended with '# ' for easier exclusion
+      # when using the report as input for some other program.
+      # If the :type is :fixed, so will the column header line.
+      # (however, for parsing this data, try using the --json option)
+      #
+      # @param lines [Array<Array>] the rows and columns of data
+      #
+      # @param type [Symbol] :fixed or :tab, defaults to :fixed
+      #
+      # @params title [String] a descriptive text or title, shown above the
+      #   column headers. Every line is pre-pended with '# '.
+      #   Only used on :fixed reports.
+      #
+      # @params header_row [Array<String>] the column headers. optional.
+      #
+      # @return [String] the formatted report.
+      #
+      ############################
+      def generate_report(lines, type: :fixed, header_row: [], title: nil)
+        return Xolo::BLANK if lines.pix_empty?
+
+        raise ArgumentError, 'The first argument must be an Array' unless lines.is_a?(Array)
+        raise ArgumentError, 'The header_row must be an Array' unless header_row.is_a? Array
+
+        # tab delim is easy
+        if type == :tab
+          report_tab = header_row.join("\t")
+          lines.each { |line| report_tab += "\n#{line.join("\t")}" }
+          return report_tab.strip
+        end # if :tab
+
+        # below here, fixed width
+
+        line_width, format_str = width_and_format(lines, header_row)
+
+        # title if given
+        report = title ? +"# #{title}\n" : +''
+
+        unless header_row.empty?
+          unless header_row.size == lines[0].size
+            raise ArgumentError,
+                  "Header row must have #{lines[0].count} items"
+          end
+
+          # then the header line if given
+          report +=  format_str % header_row
+          # add a separator
+          report +=  '#' + ('-' * (line_width - 1)) + "\n"
+        end
+        # add the rows
+        lines.each { |line| report += format_str % line }
+
+        report
+      end # generate report
+
+      # Given an Array of Arrays representing rows and columns of data,
+      # figure out the appropriate line-width for the longest line
+      # and the printf format string to create the columns
+      #
+      #
+      # @param lines [Array<Array>] The rows and columns of data
+      #
+      # @param header_row [Array] An optional header row to include in the
+      #   width calculation.
+      #
+      # @return [Array<Integer, String>] the line width and format string
+      #
+      ############################
+      def width_and_format(lines, header_row = [])
+        # below here, fixed width
+        format_str = +''
+        line_width = 0
+        header_row[0] = "# #{header_row[0]}"
+
+        col_widths(lines, header_row).each do |w|
+          # make sure there's a space between columns
+          col_width = w + 1
+
+          # add the column to the printf format
+          format_str += "%-#{col_width}s"
+          line_width += col_width
+        end
+        format_str += "\n"
+
+        # if needed, limit the total line width for the header the width of the terminal
+        max_width = $stdout.tty? ? terminal_word_wrap : DEFAULT_LINE_WIDTH
+        line_width = max_width if line_width > max_width
+
+        [line_width, format_str]
+      end
+
+      # Given an Array of Arrays representing rows and columns of data
+      # figure out the widest width of each column and return an array
+      # of integers representing those widths
+      #
+      # @param data [Array<Array>] The rows and columns of data
+      #
+      # @param header_row [Array] An optional header row to include in the
+      #   width calculation.
+      #
+      # @return [Array<Integer>] the max widths of each column of data.
+      #
+      ############################
+      def col_widths(data, header_row = [])
+        widths = header_row.map { |c| c.to_s.length }
+        data.each do |row|
+          row.each_index do |col|
+            this_width = row[col].to_s.length
+            widths[col] = this_width if this_width > widths[col].to_i
+          end # do field
+        end # do line
+        widths
+      end
+
+      # Should a given string be displayed via /usr/bin/less?
+      # true if stdout is a tty AND the string is > (terminal height - 2)
+      # The - 2 accounts for the final newline and an extra line at the
+      # bottom of the terminal, for better visual results
+      #########################
+      def use_less?(text)
+        $stdout.tty? && text.lines.size > (terminal_height - 2)
+      end
+
+      # Send a string to the terminal, possibly piping it through 'less'
+      # if the number of lines is greater than the number of terminal lines
+      #
+      # @param text[String] the text to send to the terminal
+      #
+      # @param show_help[Boolean] should the text have a line at the top
+      #   showing basic 'less' key commands.
+      #
+      # @result [void]
+      #
+      ############################
+      def show_text(text, show_help = true)
+        unless use_less?(text)
+          puts text
+          return
+        end
+
+        if show_help
+          help = "# -- Using /usr/bin/less: ' ' next, 'b' prev, 'q' exit, 'h' help --"
+          text = "#{help}\n#{text}"
+        end
+
+        # point stdout through less, print, then restore stdout
+        less = IO.popen('/usr/bin/less', 'w')
+
+        begin
+          less.puts text
+
+        # this catches the quitting of 'less' before all the output
+        # is displayed
+        rescue Errno::EPIPE
+          true
+        ensure
+          less&.close
+        end
+      end
+
+    end
+
+  end
+
+end # module

data/lib/xolo/core/version.rb

@@ -0,0 +1,21 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+# main module
+module Xolo
+
+  module Core
+
+    module Version
+
+      VERSION = '1.0.1'.freeze
+
+    end
+
+  end
+
+end # module

data/lib/xolo/core.rb

@@ -0,0 +1,46 @@
+# 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
+
+# Load the core xolo functionality
+#
+# This is done automatically when you `require 'xolo/admin'` or
+# `require 'xolo/server'`
+
+# Ruby Standard Libraries
+######
+require 'English'
+require 'date'
+require 'time'
+require 'pathname'
+require 'json'
+
+# Other Gems to include at this level
+require 'pixar-ruby-extensions'
+
+# Internal requires - order matters
+require 'xolo/core/loading'
+require 'xolo/core/version'
+require 'xolo/core/constants'
+require 'xolo/core/exceptions'
+
+# The main module
+module Xolo
+
+  extend Xolo::Core::Loading
+  include Xolo::Core::Version
+  include Xolo::Core::Constants
+  include Xolo::Core::Exceptions
+
+end # module Xolo
+
+require 'xolo/core/json_wrappers'
+require 'xolo/core/base_classes/configuration'
+require 'xolo/core/base_classes/server_object'
+require 'xolo/core/base_classes/title'
+require 'xolo/core/base_classes/version'
+require 'xolo/core/output'

data/lib/xolo/server/configuration.rb

@@ -395,7 +395,6 @@ module Xolo
         # @!attribute jamf_gui_hostname
         #   @return [String] The hostname of the Jamf Pro server used for links to the GUI webapp
         jamf_gui_hostname: {
-          required: true,
           type: :string,
           desc: <<~ENDDESC
             The hostname of the Jamf Pro server used for links to the GUI webapp, if different from the jamf_hostname.
@@ -478,7 +477,7 @@ module Xolo
           desc: <<~ENDDESC
             The password for the username that connects to the Jamf Pro APIs.
 
-            If you start this value with a vertical bar '|', everything after the bar is a command to be executed by the server at start-time. The command must return the certificate to standard output. This is useful when using a secret-storage system to manage secrets.
+            If you start this value with a vertical bar '|', everything after the bar is a command to be executed by the server at start-time. The command must return the password to standard output. This is useful when using a secret-storage system to manage secrets.
 
             If the value is a path to a readable file, the file's contents are used.
 

data/lib/xolo/server/helpers/jamf_pro.rb

@@ -68,6 +68,7 @@ module Xolo
 
           host = Xolo::Server.config.jamf_gui_hostname
           host ||= Xolo::Server.config.jamf_hostname
+
           port = Xolo::Server.config.jamf_gui_port
           port ||= Xolo::Server.config.jamf_port
 

data/lib/xolo/server/mixins/title_jamf_access.rb

@@ -346,21 +346,16 @@ module Xolo
         # @return [void]
         ################################
         def configure_jamf_normal_ea
+          # nothing to do if its nil, if we need to delete it, that'll happen later
+          return if version_script_contents.pix_empty?
+
           progress "Jamf: Configuring regular extension attribute '#{jamf_normal_ea_name}'", log: :info
 
           jamf_normal_ea.description = "The version of xolo title '#{title}' installed on the machine"
-          jamf_normal_ea.data_type = :string
-
-          # this is our incoming or already-existing EA script
-          if version_script_contents.pix_empty?
-            # nothing to do if its nil, if we need to delete it, that'll happen later
-          else
-            jamf_normal_ea.enabled = true
-            jamf_normal_ea.input_type = 'script'
-            jamf_normal_ea.script = version_script_contents
-          end
-
-          jamf_normal_ea.script = scr
+          jamf_normal_ea.data_type = 'String'
+          jamf_normal_ea.input_type = 'script'
+          jamf_normal_ea.enable
+          jamf_normal_ea.script = version_script_contents
           jamf_normal_ea.save
         end
 

data/lib/xolo/server/mixins/title_ted_access.rb

@@ -86,8 +86,10 @@ module Xolo
           sleep 2
 
           # re-fetch the title from ted and enable it
+          progress "Title Editor: Enabling SoftwareTitle '#{title}'", log: :info
           ted_title(refresh: true).enable
 
+          # cache the new title object id
           self.ted_id_number = ted_title.softwareTitleId
         end
 
@@ -197,6 +199,9 @@ module Xolo
           # This will also apply the changes to all patch component criteria
           apply_requirement_changes
 
+          # re-enable all patches, after any change, which might have disabled them
+          reenable_all_ted_patches
+
           # mucking with the patches often disables the title, make sure its enabled.
           enable_ted_title
 
@@ -416,6 +421,8 @@ module Xolo
         #
         # Re-enable the title in ted after updating any patches
         #
+        # TODO: Now that we are using stub patches, do we need the loop?
+        #
         # @return [void]
         ##############################
         def enable_ted_title
@@ -430,10 +437,10 @@ module Xolo
           loop do
             raise Xolo::TimeoutError, "Title Editor: Timed out waiting for SoftwareTitle '#{title}' to enable" if Time.now > breaktime
 
-            sleep 5
             ted_title(refresh: true).enable
             break
           rescue Windoo::MissingDataError => e
+            sleep 5
             log_debug "Title Editor: Looping up to #{Xolo::Server::Constants::MAX_JAMF_WAIT_FOR_TITLE_EDITOR} secs while re-enabling SoftwareTitle '#{title}': #{e}"
 
             # make sure all patches are enabled, even tho at least one should have been
@@ -500,16 +507,25 @@ module Xolo
           if ted_title.patches.empty?
             create_and_enable_stub_patch_in_ted(ted_title)
           else
-            # make sure at least one patch is enabled
-            unless ted_title.patches.to_a.any?(&:enabled?)
-              progress "Title Editor: Enabling at least the first patch for title '#{title}'", log: :info
-              ted_title.patches.first.enable
+            # repair all patches, because reparing the title might have changed the requirements
+            progress "Title Editor: Re-enabling all patches for '#{title}'", log: :info
+            version_objects.each do |vobj|
+              vobj.repair_ted_patch
             end
           end
 
           ted_title.enable unless ted_title(refresh: true).enabled?
         end
 
+        # Re-enable all patches in the title editor
+        # @return [void]
+        ###########################
+        def reenable_all_ted_patches
+          # re-enable all patches, after any change, which might have disabled them
+          progress "Title Editor: Re-enabling all patches for '#{title}'", log: :info
+          version_objects.each { |vobj| vobj.enable_ted_patch }
+        end
+
       end # TitleEditorTitle
 
     end # Mixins