ruby-jss 0.14.0 → 1.0.0b2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b50f5c9f41b90f37fd146d236cb0a5934337321b
-  data.tar.gz: a8e3308d642f4f595cf0a0ade55e1b9e965ec672
+  metadata.gz: e2cda3beb0c57a922fa2bae9be0ed07ddb0ad3f4
+  data.tar.gz: a5c707f859c044e7d7021b9e6c7d4a0c5f6900a9
 SHA512:
-  metadata.gz: 77b67a03425123953b9dac37453834c746f81c0339eb33a1d5b0edcf0cc6b8552ee8d5b4ca4b0dd8108e390b802aa702fa9d3d4a9fa6d8f975660206baeb12fd
-  data.tar.gz: 397fd3251d80dbf3bd8a4d0eedeec6d3eb6541881bcfdc7d0c18494f9acc7aebf29194fa111a8da53691135f6ecf6b05bf037a475536bfd555f4df9cc997dbee
+  metadata.gz: 2f655fcf07b79416bcccef6eceacec0c023e7fccb4507c4588df60c38c7a40c226951539eecdaa85dd094e3fbcd9682417e04e20b371ceeb1e2f1ac6d1422b8c
+  data.tar.gz: 60e672418b4fff07a72df15cbe2e8aa5963566db72425c1640a11bf0355a8f79ef196783c74dbeff2f983da143a3d10971d333598ee243190279d3199c22acef

data/CHANGES.md

@@ -1,5 +1,36 @@
 # Change History
 
+## v 1.0.0b2, 2018-06-x26
+
+Finally we're going to version 1.0, which we should have done when we went opensource.
+
+- requirement: Jamf Pro API version must be 10.4 or higher
+
+- add: JSS::PatchSource metaclass and the subclassses JSS::PatchInternalSource, and JSS::PatchExternalSource. These provide acecss to the patchavailabletitles enpoint, which is needed to acquire name_id's for creating/activating JSS::PatchTitles
+
+- add: JSS::PatchTitle, which also gives access to the patchreports endpoint. Also uses the JSS::PatchTitle::Version class to handle patch versions within a title, and assign packages to them.
+
+- add: JSS::PatchPolicy. PatchPolicies are creatable when providing an active PatchTitle and an approiate PatchTitle::Version that has a package assigned to it.
+
+- add: the Group metaclass now has a calculate_members option (bool) to the #create method. When true, the membership of the group will be updated in the existing ruby instance immediately after the group is created in the JSS. Doesn't do much for static groups, but is useful for smart groups. Defaults to true. If you don't care about the membership immediately, or don't want to wait for the membership to be calculated on the server, set this to false.
+
+- improvement: better handling of http error responses
+
+- add: more generic data validation methods in JSS::Validate module, and more use of them throughout the code.
+
+- add: 'support' in SelfServable for notifications - note that there are API bugs limiting the usefulness of this.
+
+- add: regex options to JSS::Criteriable::Criterion objects
+
+- remove: the .new class method on APIObject subclasses no longer works. Even thought its the standard ruby way to create instances of a class, it was confusing, since it implied creating new objects in the JSS.  Instead you must now use .fetch to instantiate existing objects and .make to instantiate local instances of objects to be created in the JSS.
+
+- update: API connections now default to TLSv1.2. If you're connecting from a machine that doesn't support  TLSv1.2 (like the os-supplied ruby in macOS < 10.13) then you can specify `ssl_version: 'TLSv1'` when you connect, as long as your Jamf Pro server supports it.
+
+- add: there is now a, sort-of, spec/testing framework. While based on ruby's minitest specifications, its wrapped in a very custom executable with a helper module. See the README in the test directory for details.  Specs will be added slowly over time.
+
+- fix: as Apple says: various bugfixes and improvements.
+
+
 ## v 0.14.0, 2018-05-30
 
 - Fix: RestClient no longer uses RestClient::Request::Unauthorized, only RestClient::Unauthorized

data/lib/jss.rb

@@ -65,9 +65,9 @@ module JSS
   ### Constants
   #####################################
 
-  ### The minimum JSS version that works with this gem, as returned by the API
+  ### The minimum JSS version that works with this module, as returned by the API
   ### in the deprecated 'jssuser' resource
-  MINIMUM_SERVER_VERSION = '9.4'.freeze
+  MINIMUM_SERVER_VERSION = '10.4.0'.freeze
 
   ### The current local UTC offset as a fraction of a day  (Time.now.utc_offset is the offset in seconds,
   ### 60*60*24 is the seconds in a day)
@@ -120,8 +120,7 @@ module JSS
   class Server; end
   class Icon; end
   class Preferences; end
-  class Client; end
-
+  class Client; end # TODO: see if this can be made into a module.
 
   ### SubClasses
   #####################################
@@ -192,6 +191,7 @@ module JSS
   module MDM; end
   module ManagementHistory; end
 
+
 end # module JSS
 
 ### Load the rest of the module
@@ -209,3 +209,4 @@ require 'jss/configuration'
 require 'jss/db_connection'
 require 'jss/validate'
 require 'jss/version'
+require 'jss/xml_workaround'

data/lib/jss/api_connection.rb

@@ -320,17 +320,16 @@ module JSS
     DFT_TIMEOUT = 60
 
     # The Default SSL Version
-    # As of Casper 9.61 we can't use SSL, must use TLS, since SSLv3 was susceptible to poodles.
-    # NOTE - this requires rest-client v 1.7.0 or higher
-    # which requires mime-types 2.0 or higher, which requires ruby 1.9.2 or higher!
-    # That means that support for ruby 1.8.7 stops with Casper 9.6
-    DFT_SSL_VERSION = 'TLSv1'.freeze
+    DFT_SSL_VERSION = 'TLSv1_2'.freeze
+
+    RSRC_NOT_FOUND_MSG = 'The requested resource was not found'.freeze
 
     # Attributes
     #####################################
 
     # @return [String] the username who's connected to the JSS API
-    attr_reader :jss_user
+    attr_reader :user
+    alias jss_user user
 
     # @return [RestClient::Resource] the underlying connection resource
     attr_reader :cnx
@@ -433,7 +432,7 @@ module JSS
       # parse our ssl situation
       verify_ssl args
 
-      @jss_user = args[:user]
+      @user = args[:user]
 
       @rest_url = build_rest_url args
 
@@ -445,7 +444,7 @@ module JSS
 
       verify_server_version
 
-      @name = "#{@jss_user}@#{@server_host}:#{@port}" if @name.nil? || @name == :disconnected
+      @name = "#{@user}@#{@server_host}:#{@port}" if @name.nil? || @name == :disconnected
       @connected ? hostname : nil
     end # connect
 
@@ -454,7 +453,7 @@ module JSS
     # @return [String]
     #
     def to_s
-      @connected ? "Using #{@rest_url} as user #{@jss_user}" : 'not connected'
+      @connected ? "Using #{@rest_url} as user #{@user}" : 'not connected'
     end
 
     # Reset the response timeout for the rest connection
@@ -483,7 +482,7 @@ module JSS
     # @return [void]
     #
     def disconnect
-      @jss_user = nil
+      @user = nil
       @rest_url = nil
       @server_host = nil
       @cnx = nil
@@ -509,10 +508,16 @@ module JSS
     #
     def get_rsrc(rsrc, format = :json)
       # puts object_id
-      raise JSS::InvalidConnectionError, 'Not Connected. Use .connect first.' unless @connected
+      validate_connected
+      raise JSS::InvalidDataError, 'format must be :json or :xml' unless %i[json xml].include? format
+
       rsrc = URI.encode rsrc
-      @last_http_response = @cnx[rsrc].get(accept: format)
-      return JSON.parse(@last_http_response, symbolize_names: true) if format == :json
+      begin
+        @last_http_response = @cnx[rsrc].get(accept: format)
+      rescue RestClient::ExceptionWithResponse => e
+        handle_http_error e
+      end
+      format == :json ? JSON.parse(@last_http_response, symbolize_names: true) : @last_http_response
     end
 
     # Change an existing JSS resource
@@ -524,15 +529,15 @@ module JSS
     # @return [String] the xml response from the server.
     #
     def put_rsrc(rsrc, xml)
-      raise JSS::InvalidConnectionError, 'Not Connected. Use .connect first.' unless @connected
+      validate_connected
 
       # convert CRs & to 
       xml.gsub!(/\r/, '
')
 
       # send the data
       @last_http_response = @cnx[rsrc].put(xml, content_type: 'text/xml')
-    rescue RestClient::Conflict => exception
-      raise_conflict_error(exception)
+    rescue RestClient::ExceptionWithResponse => e
+      handle_http_error e
     end
 
     # Create a new JSS resource
@@ -544,15 +549,15 @@ module JSS
     # @return [String] the xml response from the server.
     #
     def post_rsrc(rsrc, xml = '')
-      raise JSS::InvalidConnectionError, 'Not Connected. Use .connect first.' unless @connected
+      validate_connected
 
       # convert CRs & to 
       xml.gsub!(/\r/, '
') if xml
 
       # send the data
       @last_http_response = @cnx[rsrc].post xml, content_type: 'text/xml', accept: :json
-    rescue RestClient::Conflict => exception
-      raise_conflict_error(exception)
+    rescue RestClient::ExceptionWithResponse => e
+      handle_http_error e
     end # post_rsrc
 
     # Delete a resource from the JSS
@@ -562,7 +567,7 @@ module JSS
     # @return [String] the xml response from the server.
     #
     def delete_rsrc(rsrc, xml = nil)
-      raise JSS::InvalidConnectionError, 'Not Connected. Use .connect first.' unless @connected
+      validate_connected
       raise MissingDataError, 'Missing :rsrc' if rsrc.nil?
 
       # payload?
@@ -570,6 +575,8 @@ module JSS
 
       # delete the resource
       @last_http_response = @cnx[rsrc].delete
+    rescue RestClient::ExceptionWithResponse => e
+      handle_http_error e
     end # delete_rsrc
 
     # Test that a given hostname & port is a JSS API server
@@ -623,7 +630,6 @@ module JSS
     alias connected? connected
     alias host hostname
 
-
     #################
 
     # Call one of the 'all*' methods on a JSS::APIObject subclass
@@ -641,7 +647,7 @@ module JSS
     #
     # @return [Array] The list of items for the class
     #
-    def all(class_name, refresh = false, only: nil )
+    def all(class_name, refresh = false, only: nil)
       the_class = JSS.api_object_class(class_name)
       list_method = only ? :"all_#{only}" : :all
 
@@ -813,7 +819,7 @@ module JSS
       @master_distribution_point =
         case all_dps.size
         when 0
-          raise JSS::NoSuchItemError, "No distribution points defined"
+          raise JSS::NoSuchItemError, 'No distribution points defined'
         when 1
           JSS::DistributionPoint.fetch id: all_dps.first[:id], api: self
         else
@@ -919,6 +925,11 @@ module JSS
     ####################################
     private
 
+    # raise exception if not connected
+    def validate_connected
+      raise JSS::InvalidConnectionError, 'Not Connected. Use .connect first.' unless connected?
+    end
+
     # Apply defaults from the JSS::CONFIG,
     # then from the JSS::Client,
     # then from the module defaults
@@ -1020,11 +1031,12 @@ module JSS
       begin
         @server = JSS::Server.new get_rsrc('jssuser')[:user], self
       rescue RestClient::Unauthorized
-        raise JSS::AuthenticationError, "Incorrect JSS username or password for '#{@jss_user}@#{@server_host}:#{@port}'."
+        raise JSS::AuthenticationError, "Incorrect JSS username or password for '#{@user}@#{@server_host}:#{@port}'."
       end
 
       min_vers = JSS.parse_jss_version(JSS::MINIMUM_SERVER_VERSION)[:version]
-      return unless @server.version < min_vers
+      return if @server.version >= min_vers # we're good...
+
       err_msg = "JSS version #{@server.raw_version} to low. Must be >= #{min_vers}"
       @connected = false
       raise JSS::UnsupportedError, err_msg
@@ -1091,19 +1103,37 @@ module JSS
         end
     end
 
-    # Parses the HTTP body of a RestClient::Conflict (409 conflict)
-    # exception and re-raises a JSS::ConflictError with a more
+    # Parses the HTTP body of a RestClient::ExceptionWithResponse
+    # (the parent of all HTTP error responses) and its subclasses
+    # and re-raises a JSS::APIError with a more
     # useful error message.
     #
-    # @param exception[RestClient::Conflict] the exception to parse
+    # @param exception[RestClient::ExceptionWithResponse] the exception to parse
     #
     # @return [void]
     #
-    def raise_conflict_error(exception)
-      exception.http_body =~ %r{<p>Error:(.*)</p>}
-      conflict_reason = Regexp.last_match(1)
-      conflict_reason ||= exception.http_body
-      raise JSS::ConflictError, conflict_reason
+    def handle_http_error(exception)
+      @last_http_response = exception.response
+      case exception
+      when RestClient::ResourceNotFound
+        # other methods catch this and report more details
+        raise exception
+      when RestClient::Conflict
+        err = JSS::ConflictError
+        msg_matcher = /<p>Error:(.*)(<|$)/m
+      when RestClient::BadRequest
+        err = JSS::BadRequestError
+        msg_matcher = %r{>Bad Request</p>\n<p>(.*?)</p>\n<p>You can get technical detail}m
+      when RestClient::Unauthorized
+        raise
+      else
+        err = JSS::APIRequestError
+        msg_matcher = %r{<body.*?>(.*)</body>}m
+      end
+      exception.http_body =~ msg_matcher
+      msg = Regexp.last_match(1)
+      msg ||= exception.http_body
+      raise err, msg
     end
 
     # RestClient::Resource#delete doesn't take an HTTP payload,
@@ -1134,6 +1164,8 @@ module JSS
         ),
         &(block || @block)
       )
+    rescue RestClient::ExceptionWithResponse => e
+      handle_http_error e
     end # delete_with_payload
 
   end # class APIConnection
@@ -1186,6 +1218,7 @@ module JSS
 
   # aliases of module methods
   class << self
+
     alias api_connection api
     alias connection api
     alias active_connection api
@@ -1196,6 +1229,7 @@ module JSS
     alias use_api use_api_connection
     alias use_connection use_api_connection
     alias activate_connection use_api_connection
+
   end
 
   # create the default connection

data/lib/jss/api_object.rb

@@ -120,6 +120,11 @@ module JSS
   #
   class APIObject
 
+    # Constants
+    ####################################
+
+    OK_INSTANTIATORS = ['make', 'fetch', 'block in fetch'].freeze
+
     # Class Methods
     #####################################
 
@@ -288,13 +293,12 @@ module JSS
     #
     def self.valid_id(identifier, refresh = false, api: JSS.api)
       return identifier if all_ids(refresh, api: api).include? identifier
-      id = nil
       all_lookup_keys.keys.each do |key|
         next if key == :id
         id = map_all_ids_to(key).invert[identifier]
         return id if id
       end # do key
-      id
+      nil
     end
 
     # Convert an Array of Hashes of API object data to a
@@ -426,14 +430,13 @@ module JSS
     # Retrieve an object from the API.
     #
     # This is the preferred way to retrieve existing objects from the JSS.
-    # It's a wrapper for using APIObject.new
-    # and avoids the confusion of using ruby's .new class method when you're not
-    # creating a new object.
+    # It's a wrapper for using APIObject.new and avoids the confusion of using
+    # ruby's .new class method when you're not creating a new object in the JSS
     #
     # For creating new objects in the JSS, use {APIObject.make}
     #
     # @param args[Hash] The data for fetching an object, such as id: or name:
-    #  See {APIObject#initialize}
+    #  Each APIObject subclass can define additional lookup keys for fetching.
     #
     # @return [APIObject] The ruby-instance of a JSS object
     #
@@ -456,7 +459,7 @@ module JSS
       end # each key
 
       # if we're here, we couldn't find a matching object
-      raise NoSuchItemError, "No #{self::RSRC_OBJECT_KEY} found matching '#{arg}'"
+      raise NoSuchItemError, "No matching #{self::RSRC_OBJECT_KEY} found"
     end # fetch
 
     # Make a ruby instance of a not-yet-existing APIObject.
@@ -483,6 +486,15 @@ module JSS
       new args
     end
 
+    # Disallow direct use of ruby's .new class method for creating instances.
+    # Require use of .fetch or .make
+    def self.new(**args)
+      calling_method = caller_locations(1..1).first.label
+      # puts "Called By: #{calling_method}"
+      raise JSS::UnsupportedError, 'Use .fetch or .make to instantiate APIObject classes' unless OK_INSTANTIATORS.include? calling_method
+      super
+    end
+
     # Delete one or more API objects by jss_id without instantiating them.
     # Non-existent id's are skipped and an array of skipped ids is returned.
     #
@@ -609,30 +621,22 @@ module JSS
     #
     # @option args :name[String] the name to look up
     #
-    # @option args :data[Hash] the JSON output of a separate {JSS::APIConnection} query
-    #   NOTE: This arg is deprecated and will be removed in a future release.
+    # @option args :fetch_rsrc[String] a non-standard resource for fetching
+    #   API data e.g. to limit the data returned
     #
     #
     def initialize(args = {})
       args[:api] ||= JSS.api
       @api = args[:api]
-      raise JSS::UnsupportedError, 'JSS::APIObject cannot be instantiated' if self.class == JSS::APIObject
-
-      ####### Previously looked-up JSON data
-      # DEPRECATED: pre-lookedup data is never used
-      # and support for it will be going away.
-      if args[:data]
-
-        @init_data = args[:data]
+      raise JSS::UnsupportedError, 'JSS::APIObject is a metaclass and cannot be instantiated' if self.class == JSS::APIObject
 
-        validate_external_init_data
-
-      ###### Make a new one in the JSS, but only if we've included the Creatable module
-      elsif args[:id] == :new
+      # we're making a new one in the JSS
+      if args[:id] == :new
         validate_init_for_creation(args)
         setup_object_for_creation(args)
         @need_to_update = true
-      ###### Look up the data via the API
+
+      # we're instantiating an existing one in the jss
       else
         @init_data = look_up_object_data(args)
         @need_to_update = false
@@ -771,6 +775,7 @@ module JSS
       vars = instance_variables.sort
       vars.delete :@api
       vars.delete :@init_data
+      vars.delete :@main_subset
       vars
     end
 
@@ -871,6 +876,7 @@ module JSS
 
     # Private Instance Methods
     #####################################
+
     private
 
     # Raise an exception if object history is not
@@ -892,6 +898,8 @@ module JSS
     # DEPRECATED: pre-lookedup data is never used
     # and support for it will be going away.
     #
+    # TODO: delete this and all defined VALID_DATA_KEYS
+    #
     # @return [void]
     #
     def validate_external_init_data
@@ -937,21 +945,64 @@ module JSS
     # @return [Hash] The parsed JSON data for the object from the API
     #
     def look_up_object_data(args)
-      # what lookup key are we using?
+      rsrc =
+        if args[:fetch_rsrc]
+          args[:fetch_rsrc]
+        else
+          # what lookup key are we using?
+          # TODO: simplify this, see the notes at #find_rsrc_keys
+          rsrc_key, lookup_value = find_rsrc_keys(args)
+          "#{self.class::RSRC_BASE}/#{rsrc_key}/#{lookup_value}"
+        end
+
+      # if needed, a non-standard object key can be passed by a subclass.
+      # e.g. User when loookup is by email.
+      args[:rsrc_object_key] ||= self.class::RSRC_OBJECT_KEY
+
+      raw_json =
+        if defined? self.class::USE_XML_WORKAROUND
+          # if we're here, the API JSON is borked, so use the XML
+          JSS::XMLWorkaround.data_via_xml rsrc, self.class::USE_XML_WORKAROUND, @api
+        else
+          # otherwise
+          @api.get_rsrc(rsrc)
+        end
+      raw_json[args[:rsrc_object_key]]
+    rescue RestClient::ResourceNotFound
+      raise NoSuchItemError, "No #{self.class::RSRC_OBJECT_KEY} found matching resource #{rsrc}"
+    end
+
+    # Given initialization args, determine the rsrc key and
+    # lookup value to be used in building the GET resource.
+    # E.g. for looking up something with id 345,
+    # return the rsrc_key :id, and the value 345, which
+    # can be used to create the resrouce
+    # '/things/id/345'
+    #
+    # CHANGE: some the new patch-related objects don't have
+    # GET resources by name, only id. So this method now always
+    # returns the id-based resource.
+    #
+    # TODO: clean up this and the above methods, since the
+    # id-only get rsrcs actually should simplify the code.
+    #
+    # @param args[Hash] The args passed to #initialize
+    #
+    # @return [Array] Two item array: [ rsrc_key, lookup_value]
+    #
+    def find_rsrc_keys(args)
       lookup_keys = self.class.lookup_keys
       lookup_key = (self.class.lookup_keys & args.keys)[0]
+
       raise JSS::MissingDataError, "Args must include a lookup key, one of: :#{lookup_keys.join(', :')}" unless lookup_key
-      rsrc_key = self.class.rsrc_keys[lookup_key]
 
-      rsrc = "#{self.class::RSRC_BASE}/#{rsrc_key}/#{args[lookup_key]}"
+      vid = self.class.valid_id args[lookup_key], :refresh
 
-      # if needed, a non-standard object key can be passed by a subclass.
-      # e.g. User when loookup is by email.
-      rsrc_object_key = args[:rsrc_object_key] ? args[:rsrc_object_key] : self.class::RSRC_OBJECT_KEY
+      raise NoSuchItemError, "No #{self.class::RSRC_OBJECT_KEY} found with #{lookup_key} '#{args[lookup_key]}'" unless vid
 
-      return @api.get_rsrc(rsrc)[rsrc_object_key]
-    rescue RestClient::ResourceNotFound
-      raise NoSuchItemError, "No #{self.class::RSRC_OBJECT_KEY} found matching: #{rsrc_key}/#{args[lookup_key]}"
+      [:id, vid]
+      # rsrc_key = self.class.rsrc_keys[lookup_key]
+      # [rsrc_key, args[lookup_key]]
     end
 
     # Start examining the @init_data recieved from the API
@@ -971,7 +1022,7 @@ module JSS
         @id = 0
         @in_jss = false
       else
-        @id = @main_subset[:id]
+        @id = @main_subset[:id].to_i
         @in_jss = true
       end
 
@@ -1017,7 +1068,7 @@ module JSS
     # @return [void]
     #
     def initialize_category
-      parse_category if categorizable?
+      parse_category if categorizable? && @in_jss
     end
 
     # parse site data during initialization
@@ -1145,6 +1196,7 @@ require 'jss/api_object/advanced_search'
 require 'jss/api_object/configuration_profile'
 require 'jss/api_object/extension_attribute'
 require 'jss/api_object/group'
+require 'jss/api_object/patch_source'
 
 ### APIObject SubClasses without SubClasses
 require 'jss/api_object/account'
@@ -1162,7 +1214,7 @@ require 'jss/api_object/mobile_device_application'
 require 'jss/api_object/netboot_server'
 require 'jss/api_object/network_segment'
 require 'jss/api_object/package'
-require 'jss/api_object/patch'
+require 'jss/api_object/patch_title'
 require 'jss/api_object/patch_policy'
 require 'jss/api_object/peripheral_type'
 require 'jss/api_object/peripheral'