xolo-server 1.0.0

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

@@ -0,0 +1,145 @@
+# 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 Server
+
+    module Helpers
+
+      # This is mixed in to Xolo::Server::App (as a helper, available in route processing)
+      # and in Xolo::Server::Title and Xolo::Server::Version.
+      #
+      # This holds methods and constants for sending alerts and emails.
+      #
+      module Notification
+
+        # Constants
+        #####################
+        #####################
+
+        DFT_EMAIL_FROM = 'xolo-server-do-not-reply'
+
+        ALERT_TOOL_EMAIL_PREFIX = 'email:'
+
+        # Module Methods
+        #######################
+        #######################
+
+        # when this module is included
+        def self.included(includer)
+          Xolo.verbose_include includer, self
+        end
+
+        # Instance Methods
+        #######################
+        ######################
+
+        # Send a message thru the alert_tool, if one is defined in the config.
+        #
+        # Messages are prepended with "#{level} ALERT: "
+        # This should be called by passing alert: true to one of the
+        # logging wrapper methods
+        #
+        # @param msg [String] the message to send
+        # @param level [Symbol] the log level of the message
+        #
+        # @return [void]
+        ###############################
+        def send_alert(msg, level)
+          return unless Xolo::Server.config.alert_tool
+          return if send_email_alert(msg, level)
+
+          alerter = nil # just in case we need the ensure clause below.
+          alerter = IO.popen(Xolo::Server.config.alert_tool, 'w')
+          alerter.puts "#{level} ALERT: #{msg}"
+
+        # this catches the quitting of the alerter before expected
+        rescue Errno::EPIPE
+          true
+        ensure
+          # this flushes the pipe and makes the msg go
+          alerter&.close
+        end
+
+        # Send an alert via email
+        # @param msg [String] the message to send
+        # @param level [Symbol] the log level of the message
+        #
+        # @return [Boolean] true if the email was sent, false otherwise
+        ################################
+        def send_email_alert(msg, level)
+          return false unless Xolo::Server.config.smtp_server
+          return false unless Xolo::Server.config.alert_tool.start_with? ALERT_TOOL_EMAIL_PREFIX
+
+          send_email(
+            to: Xolo::Server.config.alert_tool.delete_prefix(ALERT_TOOL_EMAIL_PREFIX).strip,
+            subject: "#{level} ALERT from Xolo Server",
+            msg: msg
+          )
+          true
+        end
+
+        # Send an email, if the smtp_server is defined in the config.
+        #
+        # @param to [String] the email address to send to
+        # @param subject [String] the subject of the email
+        # @param msg [String] the body of the email
+        # @param html [Boolean] should the email be sent as HTML?
+        #
+        # @return [void]
+        ###############################
+        def send_email(to:, subject:, msg:, html: false)
+          return unless Xolo::Server.config.smtp_server
+
+          headers = [
+            "From: #{server_name} <#{email_from}>",
+            "Date: #{Time.now.rfc2822}",
+            "To: #{to} <#{to}>",
+            "Subject: #{subject}"
+          ]
+
+          if html
+            headers << 'MIME-Version: 1.0'
+            headers << 'Content-type: text/html'
+          end
+
+          msg = "#{headers.join "\n"}\n\n#{msg}"
+
+          Net::SMTP.start(Xolo::Server.config.smtp_server) do |smtp|
+            smtp.send_message msg, email_from, to
+          end
+        end
+
+        # @return [String] the from address for emails
+        ###############################
+        def email_from
+          @email_from ||= Xolo::Server.config.email_from || "#{DFT_EMAIL_FROM}@#{server_fqdn}"
+        end
+
+        # @return [String] the human-readable name of the server for sending emails
+        ###############################
+        def server_name
+          @server_name ||= "Xolo Server on #{server_fqdn}"
+        end
+
+        # @return [String] the server's fully qualified domain name
+        ###############################
+        def server_fqdn
+          @server_fqdn ||= Addrinfo.getaddrinfo(Socket.gethostname, nil).first.getnameinfo.first
+        end
+
+      end # Log
+
+    end # Helpers
+
+  end # Server
+
+end # module Xolo

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

@@ -0,0 +1,141 @@
+# 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 Server
+
+    module Helpers
+
+      # constants and methods for signing packages
+      module PkgSigning
+
+        # 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
+        #
+        ##############################
+        ##############################
+
+        # do we need to sign a pkg?
+        # TODO: sign zipped bundle installers? prob not, they shouldn't be used anymore
+        # (I'm looking at YOU Adobe)
+        # @param pkg [Pathname] Path to a .pkg to see if it's signed.
+        # @return [Boolean] should we sign it?
+        def need_to_sign?(pkg)
+          log_debug "Checking need to sign uploaded pkg '#{pkg}'"
+          unless Xolo::Server.config.sign_pkgs
+            log_debug "No need to sign '#{pkg.basename}': xolo server is not configured to sign pkgs."
+            return false
+          end
+          if pkg.extname == Xolo::DOT_ZIP
+            log_debug "No need to sign '#{pkg.basename}': It is a compressed .pkg bundle. TODO: maybe support signing these?"
+            return false
+          end
+
+          !pkg_signed?(pkg)
+        end
+
+        # @param pkg [Pathname] Path to a .pkg to see if it's already signed.
+        # @return [Boolean] is then pkg at the given pathname signed?
+        #########################
+        def pkg_signed?(pkg)
+          `/usr/sbin/pkgutil --check-signature #{Shellwords.escape pkg.to_s}`
+          already_signed = $CHILD_STATUS.success?
+          if already_signed
+            log_debug "No need to sign '#{pkg.basename}': It is already signed."
+          else
+            log_debug "About to sign '#{pkg.basename}'"
+          end
+          already_signed
+        end
+
+        # Sign a package
+        #
+        # @param unsigned_pkg [Pathname] the unsigned pkg to sign
+        # @param signed_pkg [Pathname] the destination file to write the signed version of the pkg.
+        #
+        # @return [void]
+        #######################################################
+        def sign_uploaded_pkg(unsigned_pkg, signed_pkg)
+          unlock_signing_keychain
+
+          sh_unsigned = Shellwords.escape unsigned_pkg.to_s
+          sh_signed = Shellwords.escape signed_pkg.to_s
+          sh_kch = Shellwords.escape Xolo::Server::Configuration::PKG_SIGNING_KEYCHAIN.to_s
+          sh_ident = Shellwords.escape Xolo::Server.config.pkg_signing_identity
+
+          cmd = "/usr/bin/productsign --sign #{sh_ident} --keychain #{sh_kch} #{sh_unsigned} #{sh_signed}"
+          log_debug "Signing #{signed_pkg.basename} using this command: #{cmd}"
+
+          stdouterr, exit_status = Open3.capture2e(cmd)
+          return if exit_status.success?
+
+          msg = "Failed to sign uploaded pkg: #{stdouterr}"
+          log_error msg
+          halt 400, { status: 400, error: msg }
+        end
+
+        # unlock the pkg signing keychain
+        # TODO: Be DRY with the keychain stuff in Xolo::Admin::Credentials
+        #############################
+        def unlock_signing_keychain
+          log_debug 'Unlocking the signing keychain'
+
+          pw = Xolo::Server.config.pkg_signing_keychain_pw
+          # first escape backslashes
+          pw = pw.to_s.gsub '\\', '\\\\\\'
+          # then single quotes
+          pw.gsub! "'", "\\\\'"
+          # then warp in sgl quotes
+          pw = "'#{pw}'"
+
+          outerrs = Xolo::BLANK
+          exit_status = nil
+
+          Open3.popen2e('/usr/bin/security -i') do |stdin, stdout_err, wait_thr|
+            stdin.puts "unlock-keychain -p #{pw} '#{Xolo::Server::Configuration::PKG_SIGNING_KEYCHAIN}'"
+            stdin.close
+            outerrs = stdout_err.read
+            exit_status = wait_thr.value # Process::Status object returned.
+          end # Open3.popen2e
+          return if exit_status.success?
+
+          msg = "Error unlocking signing keychain: #{outerrs}"
+          log_error msg
+          halt 400, { status: 400, error: msg }
+        end
+
+      end # JamfPro
+
+    end # Helpers
+
+  end # Server
+
+end # module Xolo

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

@@ -0,0 +1,252 @@
+# 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 Server
+
+    module Helpers
+
+      # This is used both as a 'helper' in the Sinatra server,
+      # and an included mixin for the Xolo::Server::Title and
+      # Xolo::Server::Version classes
+      # to provide common methods for long-running routes that deliver
+      # realtime progress updates via http streaming.
+      module ProgressStreaming
+
+        # Constants
+        #######################
+        #######################
+
+        PROGRESS_THREAD_NAME_PREFIX = 'xolo-progress-stream-'
+
+        # Module Methods
+        #######################
+        #######################
+
+        # when this module is included
+        def self.included(includer)
+          Xolo.verbose_include includer, self
+        end
+
+        # Instance Methods
+        #######################
+        #######################
+
+        # Call this from long-running routes.
+        #
+        # It runs a block in a thread with streaming
+        #
+        # The block should call #progress as needed to write
+        # to the progress file, and optionally the log
+        #
+        # Always sends back a JSON response body with
+        # {
+        #   status: :running,
+        #   progress_stream_url_path: progress_stream_url_path
+        # }
+        # Any errors should be written to the stream file,
+        # as will unhandled exceptions.
+        #
+        # @yield The block to run in the thread with streaming
+        ##########################
+        def with_streaming
+          raise 'No block given to run in streaming thread' unless block_given?
+
+          @streaming_now = true
+
+          # always call this first in a
+          # long-running route that will use progress streaming
+          setup_progress_streaming
+
+          log_debug 'Starting with_streaming block in thread'
+
+          @streaming_thread = Thread.new do
+            log_debug 'Thread with_streaming is starting and yielding to block'
+            yield
+            log_debug 'Thread with_streaming is finished'
+          rescue StandardError => e
+            progress "ERROR: #{e.class}: #{e}", log: :error
+            e.backtrace.each { |l| log_debug "..#{l}" }
+          ensure
+            stop_progress_streaming
+          end
+
+          @streaming_thread.name = "#{PROGRESS_THREAD_NAME_PREFIX}#{session[:xolo_id]}"
+
+          resp_body = {
+            status: :running,
+            progress_stream_url_path: progress_stream_url_path
+          }
+          body resp_body
+        end
+
+        # Setup for streaming:
+        # create the tmp file so that any threads will see it
+        # and do any other pre-streaming stuff
+        #
+        # @param xadm_command [String] the xadm command that is causing this stream.
+        #   may be used for finding a returning the progress file after the fact.
+        #
+        ##########################
+        def setup_progress_streaming
+          log_debug "Setting up for progress streaming. progress_stream_file is: #{progress_stream_file}"
+        end
+
+        # End che current progress stream
+        ###############################
+        def stop_progress_streaming
+          log_debug "Stopping progress streaming to file: #{progress_stream_file}"
+          progress Xolo::Server::PROGRESS_COMPLETE
+        end
+
+        # The file to which we write progess messages
+        # for long-running processes, which might in turn
+        # be streamed to xadm now or in the future
+        #
+        #############################
+        def progress_stream_file
+          return @progress_stream_file if @progress_stream_file
+
+          tempf = Tempfile.create "#{PROGRESS_THREAD_NAME_PREFIX}#{session[:xolo_id]}-"
+          tempf.close # we'll write to it later
+          log_debug "Created progress_stream_file: #{tempf.path}"
+          @progress_stream_file = Pathname.new(tempf.path)
+          @progress_stream_file.pix_touch
+          @progress_stream_file
+        end
+
+        # The file to which we write progess messages
+        # for long-running processes, which might in turn
+        # be streamed to xadm.
+        #############################
+        def progress_stream_url_path
+          "/streamed_progress/?stream_file=#{CGI.escape progress_stream_file.to_s}"
+        end
+
+        # Append a message to the progress stream file,
+        # optionally sending it also to the log
+        #
+        # @param message [String] the message to append
+        # @param log [Symbol] the level at which to log the message
+        #   one of :debug, :info, :warn, :error, :fatal, or :unknown.
+        #   Default is nil, which doesn't log the message at all.
+        #
+        # @return [void]
+        ###################
+        def progress(msg, log: :nil)
+          # log_debug "Progress method called from #{caller_locations.first}"
+
+          progress_stream_file.pix_append "#{msg.chomp}\n"
+
+          unless log
+            # log_debug 'Processed unlogged progress message'
+            return
+          end
+
+          case log
+          when :debug
+            log_debug msg
+          when :info
+            log_info msg
+          when :warn
+            log_warn msg
+          when :error
+            log_error msg
+          when :fatal
+            log_fatal msg
+          when :unknown
+            log_unknown msg
+          end
+        end
+
+        # Stream lines from the given file to the given stream
+        #
+        # @param stream_file: [Pathname] the file to stream from
+        # @param stream:  [Sinatra::Helpers::Stream] the stream to send to
+        #
+        # @return [void]
+        #############################
+        def stream_progress(stream_file:, stream:)
+          log_debug "About to tail: usr/bin/tail -f -c +1 #{Shellwords.escape stream_file.to_s}"
+
+          stdin, stdouterr, wait_thr = Open3.popen2e("/usr/bin/tail -f -c +1 #{Shellwords.escape stream_file.to_s}")
+          stdin.close
+
+          while line = stdouterr.gets
+            break if line.chomp == Xolo::Server::PROGRESS_COMPLETE
+
+            stream << line
+          end
+          stdouterr.close
+          wait_thr.exit
+          # TODO: deal with wait_thr.value.exitstatus > 0 ?
+        end
+
+        # TEMP TESTING  - Thisis happening in a thread and
+        # should send updates via #progress
+        #
+        ######################
+        def a_long_thing_with_streamed_feedback
+          log_debug 'Starting a_long_thing_with_streamed_feedback'
+
+          progress 'Doing a quick thing...'
+          sleep 3
+          progress 'Quick thing done.'
+
+          progress "Doing a slow thing at #{Time.now}  ..."
+          log_debug 'Starting thread in a_long_thing_with_streamed_feedback'
+
+          # even tho we are in a thread, if we want to
+          # send updates while some long sub-task is running
+          # we do it in another thread like this
+          long_thr = Thread.new { sleep 30 }
+          sleep 3
+
+          while long_thr.alive?
+            log_debug 'Thread still alive...'
+            progress "Slow thing still happening at #{Time.now} ..."
+            sleep 3
+          end
+
+          log_debug 'Thread in a_long_thing_with_streamed_feedback is done'
+
+          progress 'Slow thing done.'
+
+          progress "Doing a medium thing at #{Time.now}  ..."
+          log_debug 'Starting another thread in a_long_thing_with_streamed_feedback - sends output from the thread'
+
+          # Doing this in a thead is just for academics...
+          # as is doing anything in a thread and immediately doing thr.join
+          med_thr = Thread.new do
+            3.times do |x|
+              progress "the medium thing has done #{x + 1} things", log: :debug
+              sleep 5
+            end
+          end
+
+          progress 'Now waiting for medium thing to finish...'
+          med_thr.join
+
+          progress 'Medium thing is done.'
+        end
+
+        ########## TMP
+        def jsonify_stream_msg(msg)
+          @out_to_stream << { msg: msg }.to_json
+        end
+
+      end # Streaming
+
+    end # Helpers
+
+  end # Server
+
+end # module Xolo

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

@@ -0,0 +1,92 @@
+# 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 Server
+
+    module Helpers
+
+      # constants and methods for accessing the Title Editor server
+      #
+      # This is both uses as a 'helper' in the Sinatra server,
+      # and an included mixin for the Xolo::Server::Title and
+      # Xolo::Server::Version classes.
+      #
+      # This means methods here are available in instances of
+      # those classes, and in all routes, views, and helpers in
+      # Sinatra.
+      #
+      # NOTE: The names of various attributes of Title Editor SoftwareTitles
+      # and Xolo Titles are not always in sync.
+      # For example:
+      #   - the :display_name of the Xolo Title is the :name of a SoftwareTitle
+      #   - the :title of a Xolo Title id the :id of a SoftwareTitle
+      #   - the numeric :softwareTitleId of the SoftwareTitle doesn't exist in a Xolo Title
+      #
+      # See Windoo::SoftwareTitle::JSON_ATTRIBUTES for more details about them.
+      # The Xolo server code will deal with all the translations.
+      #
+      module TitleEditor
+
+        # 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
+
+        # Instance methods
+        #
+        # These are available directly in sinatra routes and views
+        #
+        ##############################
+        ##############################
+
+        # A connection to the Title Editor via Windoo
+        # We don't use the Windoo default connection but
+        # use this method to create standalone ones as needed
+        # and ensure they are disconnected, (or will timeout)
+        # when we are done.
+        #
+        # @return [Windoo::Connection] A connection object
+        ##############################
+        def ted_cnx
+          return @ted_cnx if @ted_cnx
+
+          @ted_cnx = Windoo::Connection.new(
+            name: "title-editor-cnx-#{Time.now.strftime('%F-%T')}",
+            host: Xolo::Server.config.ted_hostname,
+            user: Xolo::Server.config.ted_api_user,
+            pw: Xolo::Server.config.ted_api_pw,
+            open_timeout: Xolo::Server.config.ted_open_timeout,
+            timeout: Xolo::Server.config.ted_timeout,
+            keep_alive: false
+          )
+
+          log_debug "Title Editor: Connected at #{@ted_cnx.base_url}, user '#{Xolo::Server.config.ted_api_user}'. KeepAlive: #{@ted_cnx.keep_alive?}, Expires: #{@ted_cnx.token.expires}. cnxID: #{@ted_cnx.object_id}"
+
+          @ted_cnx
+        end
+
+      end # TitleEditor
+
+    end # Helpers
+
+  end # Server
+
+end # module Xolo