windoo 1.0.1

data/lib/windoo/configuration.rb

@@ -0,0 +1,221 @@
+# Copyright 2025 Pixar
+#
+#    Licensed under the terms set forth in the LICENSE.txt file available at
+#    at the root of this project.
+#
+#
+
+require 'singleton'
+
+module Windoo
+
+  # A class for working with pre-defined settings & preferences for Windoo
+  #
+  # This is a singleton class, only one instance can exist at a time.
+  #
+  # When the module loads, that instance is created, and is used to provide default
+  # values throughout Windoo. It can be accessed via Windoo.config in applications.
+  #
+  # @note Many values in Windoo will also have a hard-coded default, if not defined
+  # in the configuration.
+  #
+  # When the Windoo::Configuration instance is created, the {GLOBAL_CONF} file (/etc/windoo.conf)
+  # is examined if it exists, and the items in it are loaded into the attributes.
+  #
+  # Then the user-specific {USER_CONF} file (~/.windoo.conf) is examined if it exists, and
+  # any attributes defined there will override those values from the {GLOBAL_CONF}.
+  #
+  # The file format is one attribute per line, thus:
+  #   attr_name: value
+  #
+  # Lines that don't start with a known attribute name followed by a colon are ignored.
+  # If an attribute is defined more than once, the last one wins.
+  #
+  # See {CONF_KEYS} for the available attributes, and how they are converted to the appropriate
+  # Ruby class when loaded.
+  #
+  # At any point, the attributes can read or changed using standard Ruby getter/setter methods
+  # matching the name of the attribute,
+  # e.g.
+  #
+  #   # read the current title_editor_server_name configuration value
+  #   Windoo.config.title_editor_server_name  # => 'foobar.appcatalog.jamfcloud.com'
+  #
+  #   # sets the title_editor_server_name to a new value
+  #   Windoo.config.title_editor_server_name = 'baz.appcatalog.jamfcloud.com'
+  #
+  #
+  # The current settings may be saved to the GLOBAL_CONF file, the USER_CONF file, or an arbitrary
+  # file using {#save}.  The argument to {#save} should be either :user, :global, or a String or
+  # Pathname file path.
+  # NOTE: This overwrites any existing file with the current values of the Configuration object.
+  #
+  # To re-load the configuration use {#reload}. This clears the current settings, and re-reads
+  # both the global and user files. If a pathname is provided, e.g.
+  #   Windoo.config.reload '/path/to/other/file'
+  # the current settings are cleared and reloaded from that other file.
+  #
+  # To view the current settings, use {#print}.
+  #
+  class Configuration
+
+    include Singleton
+
+    # Class Constants
+    #####################################
+
+    # The filename for storing the config, globally or user-level.
+    # The first matching file is used - the array provides
+    # backward compatibility with earlier versions.
+    # Saving will always happen to the first filename
+    CONF_FILENAME = 'windoo.conf'
+
+    # The Pathname to the machine-wide preferences plist
+    GLOBAL_CONF = Pathname.new "/etc/#{CONF_FILENAME}"
+
+    # The Pathname to the user-specific preferences plist
+    USER_CONF = Pathname.new("~/.#{CONF_FILENAME}").expand_path
+
+    # The attribute keys we maintain, and the type they should be stored as
+    CONF_KEYS = {
+      title_editor_server_name: :to_s,
+      title_editor_server_port: :to_i,
+      title_editor_ssl_version: :to_s,
+      title_editor_verify_cert: :to_bool,
+      title_editor_username: :to_s,
+      title_editor_open_timeout: :to_i,
+      title_editor_timeout: :to_i
+    }
+
+    # Attributes
+    #####################################
+
+    # automatically create accessors for all the CONF_KEYS
+    CONF_KEYS.keys.each { |k| attr_accessor k }
+
+    # Constructor
+    #####################################
+
+    # Initialize!
+    #
+    def initialize
+      read GLOBAL_CONF
+      read USER_CONF
+    end
+
+    # Public Instance Methods
+    #####################################
+
+    # Clear all values
+    #
+    # @return [void]
+    #
+    def clear_all
+      CONF_KEYS.keys.each { |k| send "#{k}=", nil }
+    end
+
+    # Clear the settings and reload the prefs files, or another file if provided
+    #
+    # @param file[String,Pathname] a non-standard prefs file to load
+    #
+    # @return [void]
+    #
+    def reload(file = nil)
+      clear_all
+      if file
+        read file
+        return true
+      end
+      read GLOBAL_CONF
+      read USER_CONF
+      true
+    end
+
+    # Save the prefs into a file
+    #
+    # @param file[Symbol,String,Pathname] either :user, :global, or an arbitrary file to save.
+    #
+    # @return [void]
+    #
+    def save(file)
+      path =
+        case file
+        when :global then GLOBAL_CONF
+        when :user then USER_CONF
+        else Pathname.new(file)
+        end
+
+      # file already exists? read it in and update the values.
+      if path.readable?
+        data = path.read
+
+        # go thru the known attributes/keys
+        CONF_KEYS.keys.sort.each do |k|
+          curr_val = send(k)
+
+          # if the key exists, update it.
+          if data =~ /^\s*#{k}:/
+            data.sub!(/^\s*#{k}:.*$/, "#{k}: #{curr_val}")
+
+          # if not, add it to the end unless it's nil
+          else
+            data += "\n#{k}: #{curr_val}" unless curr_val.nil?
+          end # if data =~ /^#{k}:/
+        end # each do |k|
+
+      else # not readable, make a new file
+        data = ''
+        CONF_KEYS.keys.sort.each do |k|
+          data << "#{k}: #{send k}\n" unless send(k).nil?
+        end
+      end # if path readable
+
+      # make sure we end with a newline, the save it.
+      data << "\n" unless data.end_with?("\n")
+      path.x_save data
+    end # read file
+
+    # Print out the current settings to stdout
+    #
+    # @return [void]
+    #
+    def print
+      CONF_KEYS.keys.sort.each { |k| puts "#{k}: #{send k}" }
+    end
+
+    # Private Instance Methods
+    #####################################
+    private
+
+    # Read in any prefs file
+    #
+    # @param file[String,Pathname] the file to read
+    #
+    # @return [void]
+    #
+    def read(file)
+      file = Pathname.new file
+      return unless file.readable?
+
+      file.read.each_line do |line|
+        # skip blank lines and those starting with #
+        next if line =~ /^\s*(#|$)/
+
+        # parse the line
+        next unless line.strip =~ /^\s*(\w+?):\s*(\S.*)$/
+
+        attr = Regexp.last_match(1).to_sym
+        next unless CONF_KEYS.key? attr
+
+        setter = "#{attr}=".to_sym
+        value = Regexp.last_match(2).strip
+        # convert the value to the correct class
+        value &&= value.send(CONF_KEYS[attr])
+
+        send(setter, value)
+      end # do line
+    end # read file
+
+  end # class Configuration
+
+end # module Windoo

data/lib/windoo/connection/actions.rb

@@ -0,0 +1,152 @@
+# 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 Windoo
+
+  class Connection
+
+    # This module defines methods used for interacting with the TitleEditor API.
+    # This includes sending HTTP requests and handling responses
+    module Actions
+
+      def self.included(includer)
+        Windoo.verbose_include(includer, self)
+      end
+
+      # @param rsrc[String] the resource path to get
+      #
+      # @return [Object] The parsed JSON from the result of the request
+      #
+      def get(rsrc)
+        validate_connected
+
+        resp = cnx.get(rsrc)
+        @last_http_response = resp
+        return resp.body if resp.success?
+
+        handle_http_error resp
+      end # get
+
+      # Create a new API resource via POST
+      #
+      # @param rsrc[String] the API resource being created, the URL part after 'JSSResource/'
+      #
+      # @param content[String] the content specifying the new object.
+      #
+      # @return [Object] The parsed JSON from the result of the request
+      #
+      def post(rsrc, content)
+        validate_connected
+
+        # send the data
+        resp = cnx.post(rsrc) { |req| req.body = content }
+        @last_http_response = resp
+        return resp.body if resp.success?
+
+        handle_http_error resp
+      end # post
+
+      # Update an existing API resource via PUT
+      #
+      # @param rsrc[String] the API resource being changed, the URL part after 'JSSResource/'
+      #
+      # @param content[String] the content specifying the changes.
+      #
+      # @return [Object] The parsed JSON from the result of the request
+      #
+      def put(rsrc, content)
+        validate_connected
+
+        # send the data
+        resp = cnx.put(rsrc) { |req| req.body = content }
+        @last_http_response = resp
+        return resp.body if resp.success?
+
+        handle_http_error resp
+      end # put
+
+      # Delete a resource from the API
+      #
+      # @param rsrc[String] the resource to delete
+      #
+      # @return [Object] The parsed JSON from the result of the request
+      #
+      def delete(rsrc)
+        validate_connected
+
+        # send the data
+        resp = cnx.delete(rsrc)
+        @last_http_response = resp
+        return resp.body if resp.success?
+
+        handle_http_error resp
+      end # delete_rsrc
+
+      #############################
+      private
+
+      # Parses the given http response
+      # and raises a Jamf::APIError with a useful error message.
+      #
+      # @return [void]
+      #
+      def handle_http_error(resp)
+        return if resp.success?
+
+        case resp.status
+        when 404
+          err = Windoo::NoSuchItemError
+          msg = 'Not Found'
+
+        when 401
+          if resp.body[:errors].find { |e| e[:description] =~ /token not found/i }
+            err = Windoo::InvalidTokenError
+            msg = 'Connection Token is not valid.'
+
+          elsif resp.body[:errors].find { |e| e[:description] =~ /expired token/i }
+            err = Windoo::InvalidTokenError
+            msg = 'Connection Token has expired.'
+          else
+            err = Windoo::PermissionError
+            msg = 'You are not authorized to do that.'
+          end
+        when (500..599)
+          err = Windoo::ConnectionError
+          msg = 'There was an internal server error'
+
+        else
+          err = Windoo::ConnectionError
+          msg = "There was a error processing your request, status: #{resp.status}"
+
+        end # case
+        msg = "#{msg}\nStatus: #{resp.status}\nResponse Body:\n#{parse_http_error_body(resp)}"
+        raise err, msg
+      end
+
+      # get the body of the error response in a readable format
+      def parse_http_error_body(resp)
+        err_text = +''
+        resp.body[:errors].map do |err_hash|
+          err_text << "Code: #{err_hash[:code]}\n"
+          err_hash.each do |k, v|
+            next if k == :code
+
+            err_text << "  #{k}: #{v}\n"
+          end
+        end
+        err_text.chomp
+      rescue StandardError
+        resp.body
+      end
+
+    end # module Actions
+
+  end # class Connection
+
+end # module Windoo

data/lib/windoo/connection/attributes.rb

@@ -0,0 +1,156 @@
+# 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 Windoo
+
+  class Connection
+
+    # This module defines general attributes of a connection object
+    #
+    # These attributes actually come from the token:
+    #   base_url, host, port, user, keep_alive?, ssl_version,
+    #   verify_cert?, pw_fallback
+    #
+    # There are convience getters defined for them below
+    #############################################################
+    module Attributes
+
+      def self.included(includer)
+        Windoo.verbose_include(includer, self)
+      end
+
+      # @return [String] the name of this connection, an arbitrary string
+      attr_reader :name
+
+      # @return [Integer] Seconds before an http request times out
+      attr_reader :timeout
+
+      # @return [Integer] Seconds before an http connection open times out
+      attr_reader :open_timeout
+
+      # @return [Windoo::Connection::Token] the token used for connecting
+      attr_reader :token
+
+      # @return [Faraday::Response] The response from the most recent API call
+      attr_reader :last_http_response
+
+      # @return [Time] when this connection was connected
+      attr_reader :connect_time
+      alias login_time connect_time
+
+      # @return [Faraday::Connection] The underlying connection object
+      attr_reader :cnx
+
+      # @return [Boolean] are we connected right now?
+      attr_reader :connected
+      alias connected? connected
+
+      # Set the name, but always note if we are the default connection
+      #
+      # Reset the response timeout for the rest connection
+      #
+      # @param timeout[Integer] the new timeout in seconds
+      #
+      # @return [void]
+      #
+      def name=(newname)
+        @name = default? ? "#{newname} (default)" : newname
+      end
+
+      # Reset the response timeout for the rest connection
+      #
+      # @param timeout[Integer] the new timeout in seconds
+      #
+      # @return [void]
+      #
+      def timeout=(new_timeout)
+        validate_connection
+        @timeout = new_timeout.to_i
+        @cnx.options[:timeout] = @timeout if @cnx
+      end
+
+      # Reset the open-connection timeout for the rest connection
+      #
+      # @param timeout[Integer] the new timeout in seconds
+      #
+      # @return [void]
+      #
+      def open_timeout=(new_timeout)
+        validate_connection
+        @open_timeout = new_timeout.to_i
+        @cnx.options[:open_timeout] = @open_timeout if @cnx
+      end
+
+      # @return [URI::HTTPS] the base URL to the server
+      def base_url
+        validate_connection
+        @token&.base_url
+      end
+
+      # @return [String] the hostname of the Jamf Pro server API connection
+      def host
+        validate_connection
+        @token&.host
+      end
+      alias server host
+      alias hostname host
+
+      # @return [Integer] The port of the Jamf Pro server API connection
+      def port
+        validate_connection
+        @token&.port
+      end
+
+      # @return [String] the username who's connected to the JSS API
+      def user
+        validate_connection
+        @token&.user
+      end
+
+      # @return [Boolean] Is the connection token being automatically refreshed?
+      def keep_alive?
+        validate_connection
+        @token&.keep_alive?
+      end
+
+      # @return [Boolean] If keep_alive is true, is the password Cached in memory
+      #   to use if the refresh fails?
+      def pw_fallback?
+        validate_connection
+        @token&.pw_fallback?
+      end
+
+      # @return [String] SSL version used for the connection
+      def ssl_version
+        validate_connection
+        @token&.ssl_version
+      end
+
+      # @return [Boolean] Should the SSL certifcate from the server be verified?
+      def verify_cert?
+        validate_connection
+        @token&.verify_cert?
+      end
+      alias verify_cert verify_cert?
+
+      # @return [Hash] the ssl version and verify cert, to pass into faraday connections
+      def ssl_options
+        validate_connection
+        @token&.ssl_options
+      end
+
+      # raise an error if no token yet
+      # @return [void]
+      def validate_connection
+        raise Windoo::NotConnectedError, 'Not connected, use #connect first' unless connected?
+      end
+
+    end # module
+
+  end # class Connection
+
+end # module Windoo