ruby-jss 2.0.0a11 → 2.0.0b5

data/lib/jamf/api/classic/base_classes/group.rb

@@ -112,7 +112,7 @@ module Jamf
       cnx = api if api
 
       raise Jamf::NoSuchItemError, "No #{self} matching '#{group}'" unless (group_id = valid_id group, cnx: cnx)
-      raise Jamf::UnsupportedError, "Not a static group, can't change membership directly" if map_all_ids_to(:is_smart, cnx: cnx)[group_id]
+      raise Jamf::UnsupportedError, "Not a static group, can't change membership" if map_all(:id, to: :is_smart, cnx: cnx)[group_id]
 
       add_members = [add_members].flatten
       remove_members = [remove_members].flatten
@@ -123,6 +123,8 @@ module Jamf
       # that isn't in the group (which is kinda lame - it should just
       # ignore this, like it does when we add a member that's already
       # in the group.)
+      # Its even more lame because we have to instantiate the group
+      # and part of the point of this class method is to avoid that.
       current_member_ids = fetch(id: group_id, cnx: cnx).member_ids
 
       # nil if no changes to be made
@@ -189,7 +191,6 @@ module Jamf
     end
     private_class_method :member_removals_xml
 
-
     # Attributes
     #####################################
 
@@ -207,10 +208,12 @@ module Jamf
 
     # @return [Boolean] is this a smart group
     attr_reader :is_smart
+    alias smart? is_smart
 
     # @return [Boolean] does this group send notifications when it changes?
     attr_reader :notify_on_change
-
+    alias notify_on_change? notify_on_change
+    alias notify? notify_on_change
 
     # Constructor
     #####################################
@@ -221,20 +224,14 @@ module Jamf
     # @see Jamf::APIObject
     #
     def initialize(**args)
-      if args[:id] == :new
-        raise Jamf::InvalidDataError, 'New group creation must specify a :type of :smart or :static' unless GROUP_TYPES.include? args[:type]
-      end
+      raise Jamf::InvalidDataError, 'New group creation must specify a :type of :smart or :static' if args[:id] == :new && !(GROUP_TYPES.include? args[:type])
 
       super
 
       @is_smart = @init_data[:is_smart] || (args[:type] == :smart)
 
       @members =
-        if @init_data[self.class::MEMBER_CLASS::RSRC_LIST_KEY]
-          @init_data[self.class::MEMBER_CLASS::RSRC_LIST_KEY]
-        else
-          []
-        end
+        @init_data[self.class::MEMBER_CLASS::RSRC_LIST_KEY] || []
     end # init
 
     # Public Instance Methods
@@ -251,9 +248,8 @@ module Jamf
     #   happens, try again this many times with a 1 second pause between attempts.
     #
     def create(calculate_members: true, retries: 10)
-      if @is_smart
-        raise Jamf::MissingDataError, 'No criteria specified for smart group' unless @criteria
-      end
+      raise Jamf::MissingDataError, 'No criteria specified for smart group' if @is_smart && !@criteria
+
       super()
 
       if calculate_members
@@ -289,10 +285,10 @@ module Jamf
       if @in_jss
         raise Jamf::UnsupportedError, 'Updating this object in the JSS is currently not supported by ruby-jss' unless updatable?
 
-
         update refresh: params[:refresh]
       else
         raise Jamf::UnsupportedError, 'Creating this object in the JSS is currently not supported by ruby-jss' unless creatable?
+
         create calculate_members: params[:calculate_members], retries: params[:retries]
       end
     end
@@ -321,8 +317,10 @@ module Jamf
     #
     # @param args[Hash] the options and settings use for switching the computer group from static group to smart group
     #
-    # @option args criteria[Array] The criterias to be user for the smart group
-    def set_smart(*params)
+    # @option args criteria[Array] The criteria to be user for the smart group
+    #
+    # @return [void]
+    def make_smart(**params)
       return if @is_smart
 
       params[:criteria] = [] if params[:criteria].nil?
@@ -332,22 +330,28 @@ module Jamf
       @is_smart = true
       @need_to_update = true
     end
+    # backward compatility
+    alias set_smart make_smart
 
     # Change smart group to static group
     #
     # @param args[Hash] the options and settings use for switching the computer group from smart group to static group
     #
     # @option args preserve_members[Boolean] Should the smart group preserve it's current members?
-    def set_static(*params)
+    #
+    # @return [void]
+    def make_static(**params)
       return unless @is_smart
 
       preserve_members = params.include? :preserve_members
 
       @is_smart = false
 
-      clear() unless preserve_members
+      clear unless preserve_members
     end
-
+    # backward compatility
+    alias set_static make_static
+        
     # How many members of the group?
     #
     # @return [Integer] the number of members of the group
@@ -355,6 +359,13 @@ module Jamf
     def size
       @members.count
     end
+    alias count size
+
+    # @return [Boolean] Is this a static group?
+    def static?
+      !smart?
+    end
+    alias is_static static?
 
     # @return [Array<String>] the names of the group members
     #
@@ -381,6 +392,7 @@ module Jamf
     def members=(new_members)
       raise UnsupportedError, "Smart group members can't be changed." if @is_smart
       raise InvalidDataError, 'Arg must be an array of names and/or ids' unless new_members.is_a? Array
+
       ok_members = []
       new_members.each do |m|
         ok_members << check_member(m)
@@ -390,6 +402,7 @@ module Jamf
 
       # make sure we've actually changed...
       return if members.map { |m| m[:id] }.sort == ok_members.map { |m| m[:id] }.sort
+
       @members = ok_members
       @need_to_update = true
     end
@@ -401,22 +414,32 @@ module Jamf
     # @return [void]
     #
     def add_member(mem)
-      raise UnsupportedError, "Smart group members can't be changed." if @is_smart
+      raise UnsupportedError, "Smart group members can't be changed." if smart?
+
       @members << check_member(mem)
       @need_to_update = true
     end
 
     # Remove a member by id, or name
     #
-    # @param m[Integer,String] the id or name of the member to remove
+    # @param m[Integer,String] an identifier for the item to remove
     #
     # @return [void]
     #
     def remove_member(mem)
-      raise InvalidDataError, "Smart group members can't be changed." if @is_smart
-      raise InvalidDataError, "Can't remove nil" if mem.nil?
-      removed = @members.reject! { |mm| [mm[:id], mm[:name], mm[:username]].include? mem }
-      @need_to_update = true if removed
+      raise UnsupportedError, "Smart group members can't be changed." if smart?
+
+      # See if we have the identifier in the @members hash
+      id_to_remove = @members.select { |mm| mm.values.include? mem }.first&.dig :id
+      # But the members hash might not have SN, macaddr, etc, and never has udid, so
+      # look at the MEMBER_CLASS if needed
+      id_to_remove ||= self.class::MEMBER_CLASS.valid_id mem
+
+      # nothing to do if that id isn't one of our members
+      return unless id_to_remove && member_ids.include?(id_to_remove)
+
+      @members.delete_if { |k, v| k == :id && v == id_to_remove }
+      @need_to_update = true 
     end
 
     # Remove all members
@@ -426,6 +449,7 @@ module Jamf
     def clear
       raise InvalidDataError, "Smart group members can't be changed." if @is_smart
       return if @members.empty?
+
       @members.clear
       @need_to_update = true
     end
@@ -458,13 +482,7 @@ module Jamf
     def refresh_members
       @members = @cnx.c_get(@rest_rsrc)[self.class::RSRC_OBJECT_KEY][self.class::MEMBER_CLASS::RSRC_LIST_KEY]
     end
-
-    # aliases
-
-    alias smart? is_smart
-    alias notify_on_change? notify_on_change
-    alias notify? notify_on_change
-    alias count size
+  
 
     # Public Instance Methods
     #####################################
@@ -477,13 +495,12 @@ module Jamf
     # @return [Hash{:id=>Integer,:name=>String}] the valid id and name
     #
     def check_member(m)
-      potential_members = self.class::MEMBER_CLASS.map_all_ids_to(:name, cnx: @cnx)
-      if m.to_s =~ /^\d+$/
-        return { id: m.to_i, name: potential_members[m] } if potential_members.key?(m.to_i)
-      else
-        return { name: m, id: potential_members.invert[m] } if potential_members.value?(m)
-      end
-      raise Jamf::NoSuchItemError, "No #{self.class::MEMBER_CLASS::RSRC_OBJECT_KEY} matching '#{m}' in the JSS."
+      desired_id = self.class::MEMBER_CLASS.valid_id m, cnx: @cnx
+      raise Jamf::NoSuchItemError, "No #{self.class::MEMBER_CLASS::RSRC_OBJECT_KEY} matching '#{m}' in the JSS." unless desired_id
+
+      desired_name = self.class::MEMBER_CLASS.map_all(:id, to: :name, cnx: @cnx)[desired_id]
+
+      { name: desired_name, id: desired_id }      
     end
 
     # the xml formated data for adding or updating this in the JSS,

data/lib/jamf/api/classic/base_classes/patch_source.rb

@@ -128,8 +128,9 @@ module Jamf
 
     # Fetch either an internal or external patch source
     #
-    # BUG: there's an API bug: fetching a non-existent
-    # which is why we rescue internal server errors.
+    # BUG: there's an API bug when fetching a non-existent patch source
+    # which is why we rescue 500 internal server errors and report them
+    # as 'no matching patch source'
     #
     # @see APIObject.fetch
     #
@@ -162,7 +163,7 @@ module Jamf
     # @see APIObject.make
     #
     def self.create(**args)
-      case self.name
+      case name
       when 'Jamf::PatchSource'
         Jamf::PatchExternalSource.make args
       when 'Jamf::PatchExternalSource'
@@ -184,7 +185,7 @@ module Jamf
     def self.delete(victims, api: nil, cnx: Jamf.cnx)
       cnx = api if api
 
-      case self.name
+      case name
       when 'Jamf::PatchSource'
         Jamf::PatchExternalSource victims, cnx: cnx
       when 'Jamf::PatchExternalSource'
@@ -292,6 +293,7 @@ module Jamf
 
       return :internel if Jamf::PatchInternalSource.valid_id ident, refresh, cnx: cnx
       return :external if Jamf::PatchExternalSource.valid_id ident, refresh, cnx: cnx
+
       nil
     end
 
@@ -324,7 +326,10 @@ module Jamf
 
     # Init
     def initialize(**args)
-      raise Jamf::UnsupportedError, 'PatchSource is an abstract metaclass. Please use PatchInternalSource or PatchExternalSource' if self.class == Jamf::PatchSource
+      if instance_of?(Jamf::PatchSource)
+        raise Jamf::UnsupportedError, 
+              'PatchSource is an abstract metaclass. Please use PatchInternalSource or PatchExternalSource'
+      end
 
       super
 

data/lib/jamf/api/connection/attributes.rb

@@ -70,6 +70,53 @@ module Jamf
       attr_reader :connect_time
       alias login_time connect_time
 
+      # @return [Boolean] are we using a sticky session?
+      attr_reader :sticky_session
+      alias sticky_session? sticky_session
+      alias sticky? sticky_session
+      
+      # @return [String, nil] The current sticky_session cookie. nil unless
+      #   sticky_session is set to true, either as a param to 'connect' or via
+      #   #sticky_session=
+      #
+      #   When set via .connect, the cookie is gleaned from the token creation 
+      #   reponse. When set via #sticky_session=, a HEAD request is made, and the
+      #   cookie will be in the response.
+      #   
+      #    Only valid when the connection is to a Jamf Cloud server.
+      attr_reader :sticky_session_cookie
+
+      ##########################################
+
+      # Turn sticky-sessions on or off. If turning on, host must be a Jamf Cloud
+      # server, with a hostname ending with Jamf::Connection::JAMFCLOUD_DOMAIN
+      #
+      # @param value [Boolean] should we use a sticky session?
+      #
+      # @return [void]
+      #
+      def sticky_session=(value)
+        @sticky_session ||= false
+
+        # convert boolean-y to boolean
+        value = value ? true : false
+        
+        return if @sticky_session == value
+
+        if value
+          raise Jamf::UnsupportedError, 'Sticky Sessions may only be used with Jamf Cloud servers.' unless host.end_with? Jamf::Connection::JAMFCLOUD_DOMAIN
+
+          @sticky_session = true
+          enable_sticky_session Jamf.cnx.jp_cnx.head.headers
+
+        else
+          @sticky_session = false
+          @sticky_session_cookie = nil
+          @c_cnx&.headers&.delete Jamf::Connection::COOKIE_HEADER
+          @jp_cnx&.headers&.delete Jamf::Connection::COOKIE_HEADER
+        end
+      end
+
       # Reset the response timeout for the rest connection
       #
       # @param timeout[Integer] the new timeout in seconds
@@ -78,8 +125,8 @@ module Jamf
       #
       def timeout=(new_timeout)
         @timeout = new_timeout.to_i
-        @c_cnx.options[:timeout] = @timeout if @c_cnx
-        @jp_cnx.options[:timeout] = @timeout if @jp_cnx
+        @c_cnx&.options[:timeout] = @timeout 
+        @jp_cnx&.options[:timeout] = @timeout 
       end
 
       # Reset the open-connection timeout for the rest connection
@@ -90,8 +137,8 @@ module Jamf
       #
       def open_timeout=(new_timeout)
         @open_timeout = new_timeout.to_i
-        @c_cnx.options[:open_timeout] = @open_timeout if @c_cnx
-        @jp_cnx.options[:open_timeout] = @open_timeout if @jp_cnx
+        @c_cnx&.options[:open_timeout] = @open_timeout
+        @jp_cnx&.options[:open_timeout] = @open_timeout 
       end
 
       # @return [URI::HTTPS] the base URL to the server

data/lib/jamf/api/connection/classic_api.rb

@@ -65,6 +65,7 @@ module Jamf
         resp =
           @c_cnx.get(rsrc) do |req|
             req.headers[Jamf::Connection::HTTP_ACCEPT_HEADER] = format == :json ? Jamf::Connection::MIME_JSON : Jamf::Connection::MIME_XML
+            # puts "Classic API Cookie is: #{req.headers['Cookie']}"
           end
         @last_http_response = resp
         unless resp.success?
@@ -222,7 +223,7 @@ module Jamf
 
           cnx.options[:timeout] = @timeout
           cnx.options[:open_timeout] = @open_timeout
-
+          
           cnx.request :multipart
           cnx.request :url_encoded
 

data/lib/jamf/api/connection/connect.rb

@@ -138,10 +138,23 @@ module Jamf
       #   token this many seconds before it expires.
       #   Must be >= Jamf::Connection::Token::MIN_REFRESH_BUFFER, which is the default
       #
-      # @option params :pw_fallback  [Boolean] If keep_alive, should the passwd be
+      # @option params :pw_fallback [Boolean] If keep_alive, should the passwd be
       #   cached in memory and used to create a new token, if there are problems
       #   with the normal token refresh process?
       #
+      # @option params :sticky_session [Boolean] Use a 'sticky session'? Default is false.
+      #   The hostname of Jamf Cloud urls does not point to a single https server,
+      #   but any node of a cluster. Those nodes often take time to see changes
+      #   made in other node. Sometimes, its important to perform a series of API 
+      #   actions to the same node, to avoid sync-timing problems between node. Setting
+      #   sticky_session to true will cause all communication for this Connection to go
+      #   through the one specific node it first connected ith.
+      #   This is only relevant to Jamf Cloud connections, and will raise an exception
+      #   is used with on-prem Jamf Pro servers.
+      #   NOTE: It is not always appropriate to use this feature, and inapproriate use
+      #   may negatively impact server performance. For more info, see
+      #   https://developer.jamf.com/developer-guide/docs/sticky-sessions-for-jamf-cloud
+      #
       # @return [String] connection description, the output of #to_s
       #
       #######################################################
@@ -185,12 +198,44 @@ module Jamf
         @c_cnx = create_classic_connection
         @jp_cnx = create_jp_connection
 
+        # set the connection objects to sticky if desired. enforce booleans
+        self.sticky_session = params[:sticky_session] ? true : false
+
         @connected = true
 
         to_s
       end # connect
       alias login connect
 
+      # If a sticky_session was requested when the connection was made, and
+      # we are connected to a jamf cloud server, the token's http response 
+      # contains the cookie we need to send with every request to ensure a 
+      # stickey session.
+      #################################
+      def enable_sticky_session(headers) 
+        # commas separate the cookies
+        raw_cookies = headers[Jamf::Connection::SET_COOKIE_HEADER].split(/\s*,\s*/)
+
+        raw_cookies.each do |rc|
+          # semicolons separate the attributes of the cookie,
+          # with its name and value being the first pair.
+          cookie_data = rc.split(/\s*;\s*/).first
+
+          # attribute name and value are separated by '='
+          cookie_name, cookie_value = cookie_data.split('=')
+          next unless cookie_name == Jamf::Connection::STICKY_SESSION_COOKIE_NAME
+
+          @sticky_session_cookie = "#{Jamf::Connection::STICKY_SESSION_COOKIE_NAME}=#{cookie_value}"
+          jp_cnx.headers[Jamf::Connection::COOKIE_HEADER] = @sticky_session_cookie
+          c_cnx.headers[Jamf::Connection::COOKIE_HEADER] = @sticky_session_cookie 
+          return @sticky_session_cookie
+        end
+        # be sure to return nil if there was no appropriate cookie,
+        # which means we aren't using Jamf Cloud
+
+        nil
+      end
+
       # raise exception if not connected, and make sure we're using
       # the current token
       def validate_connected(subcnx)
@@ -224,6 +269,8 @@ module Jamf
         @jp_base_url = nil
         @server_path = nil
         @token = nil
+        @sticky_session_cookie = nil
+        @sticky_session = nil
         @connected = false
         :disconnected
       end # disconnect
@@ -429,7 +476,7 @@ module Jamf
         token_params[:token_string] = params[:token] if type == :token_string
         token_params[:pw] = params[:pw] unless params[:pw].is_a? Symbol
 
-        self.class::Token.new **token_params
+        self.class::Token.new(**token_params)
       end
 
       # Build the base URL for the API connection

data/lib/jamf/api/connection/constants.rb

@@ -99,6 +99,12 @@ module Jamf
         @connect_time
       ].freeze
 
+      SET_COOKIE_HEADER = 'set-cookie'.freeze
+
+      COOKIE_HEADER = 'Cookie'.freeze
+
+      STICKY_SESSION_COOKIE_NAME = 'APBALANCEID'.freeze
+
     end # module
 
   end # class

data/lib/jamf/api/connection/jamf_pro_api.rb

@@ -53,13 +53,17 @@ module Jamf
 
       # @param rsrc[String] the resource to get
       #   (the part of the API url after the '/api/' )
-      #
+  
       # @return [Hash] the result of the get
       #######################################################
       def jp_get(rsrc)
         validate_connected @jp_cnx
-        resp = @jp_cnx.get rsrc
+        resp = @jp_cnx.get(rsrc) do |req|
+          # Modify the request here if needed.
+          # puts "JPAPI Cookie is: #{req.headers['Cookie']}"
+        end
         @last_http_response = resp
+
         return resp.body if resp.success?
 
         raise Jamf::Connection::JamfProAPIError, resp

data/lib/jamf/api/connection/token.rb

@@ -87,6 +87,7 @@ module Jamf
       # @return [String] The token data
       attr_reader :token
       alias token_string token
+      alias auth_token token
 
       # @return [URI] The base API url, e.g. https://myjamf.jamfcloud.com/
       attr_reader :base_url
@@ -112,6 +113,12 @@ module Jamf
       attr_reader :pw_fallback
       alias pw_fallback? pw_fallback
 
+      # @return [Faraday::Response] The response object from instantiating
+      #   a new Token object by creating a new token or validating a token 
+      #   string. This is not updated when refreshing a token, only when
+      #   calling Token.new
+      attr_reader :creation_http_response
+
       # @param params [Hash] The data for creating and maintaining the token
       #
       # @option params [String] :token_string An existing valid token string.
@@ -139,7 +146,6 @@ module Jamf
       #
       # @option params [Boolean] :verify_cert (see Connection#connect)
       #
-      #
       ###########################################
       def initialize(**params)
         @valid = false
@@ -164,10 +170,11 @@ module Jamf
       #################################
       def init_from_pw
         resp = token_connection(NEW_TOKEN_RSRC).post
-
+        
         if resp.success?
           parse_token_from_response resp
           @last_refresh = Time.now
+          @creation_http_response = resp
         elsif resp.status == 401
           raise Jamf::AuthenticationError, 'Incorrect name or password'
         else
@@ -184,6 +191,7 @@ module Jamf
         resp = token_connection(AUTH_RSRC, token: str).get
         raise Jamf::InvalidDataError, 'Token is not valid' unless resp.success?
 
+        @creation_http_response = resp
         @token = str
         @user = resp.body.dig :account, :username
 
@@ -348,7 +356,6 @@ module Jamf
       end
       alias keep_alive refresh
 
-
       # Make this token invalid
       #################################
       def invalidate

data/lib/jamf/api/connection.rb

@@ -106,7 +106,7 @@ module Jamf
   # If you provide connection details when calling 'new', they will be passed
   # to the {#connect} method immediately. Otherwise you can call {#connect} later.
   #
-  #   production_api = Jamf::Connection.new(
+  #   production_server = Jamf::Connection.new(
   #     'https://produser@prodserver.address.org:8443/'
   #     name: 'prod',
   #     pw: :prompt

data/lib/jamf/api/jamf_pro/api_objects/inventory_preload_record.rb

@@ -42,6 +42,7 @@ module Jamf
   #
   #
   class InventoryPreloadRecord < Jamf::OAPISchemas::InventoryPreloadRecordV2
+
     # Mix-Ins
     #####################################
     include Jamf::CollectionResource
@@ -109,6 +110,12 @@ module Jamf
     # Must define this when extending Filterable
     FILTER_KEYS = OAPI_PROPERTIES.keys - [:extensionAttributes]
 
+    DEVICE_TYPE_COMPUTER = 'Computer'.freeze
+
+    DEVICE_TYPE_MOBILE_DEV = 'Mobile Device'.freeze
+
+    DEVICE_TYPE_UNKNOWN = 'Unknown'.freeze
+
     # InvPreload Recs have a non-standard /history path
     def self.history_path(_id)
       'v2/inventory-preload/history'
@@ -128,7 +135,7 @@ module Jamf
       new_val
     end
 
-    # remove an EA value
+    # remove an EA totally (vs setting its value to nil)
     def remove_ext_attr(ea_name)
       idx = extensionAttributes.index { |ea| ea.name == ea_name }
       extensionAttributes_delete_at idx if idx
@@ -158,6 +165,7 @@ module Jamf
     def history_path(_id)
       raise Jamf::UnsupportedError, 'InventoryPreloadRecords do not have individual change logs. Use Jamf::InventoryPreloadRecord.change_log'
     end
+
   end # class
 
 end # module