ruby-jss 0.14.0 → 1.0.0b2

data/lib/jss/api_object/self_servable/icon.rb

@@ -179,6 +179,18 @@ module JSS
         path.jss_save @data
       end
 
+      # Remove the data  object from
+      # the instance_variables used to create
+      # pretty-print (pp) output.
+      #
+      # @return [Array] the desired instance_variables
+      #
+      def pretty_print_instance_variables
+        vars = instance_variables.sort
+        vars.delete :@data
+        vars
+      end
+
     end # class icon
 
 end # module

data/lib/jss/api_object/sitable.rb

@@ -80,7 +80,7 @@ module JSS
     # @return [String] The name of the site for this object.
     #
     def site_name
-      @site_name
+      @site_name || NO_SITE_NAME
     end # cat name
     alias site site_name
 
@@ -89,7 +89,7 @@ module JSS
     # @return [Integer] The id of the site for this object.
     #
     def site_id
-      @site_id
+      @site_id || NO_SITE_ID
     end # cat id
 
     # The JSS::Site instance for this object's site
@@ -165,7 +165,7 @@ module JSS
         elsif @init_data[self.class::SITE_SUBSET]
           @init_data[self.class::SITE_SUBSET][:site]
         end
-      site_data ||= {}
+      site_data ||= { name: NO_SITE_NAME, id: NO_SITE_ID }
 
       @site_name = site_data[:name]
       @site_id = site_data[:id]
@@ -187,7 +187,7 @@ module JSS
           parent_elem ||= root.add_element(self.class::SITE_SUBSET.to_s)
           parent_elem.add_element 'site'
         end
-      site_elem.add_element('name').text = @site_name.to_s
+      site_elem.add_element('name').text = site_name.to_s
     end # add_site_to_xml
 
   end # module categorizable

data/lib/jss/api_object/updatable.rb

@@ -76,7 +76,7 @@ module JSS
     #
     def name=(newname)
       return nil if @name == newname
-      raise JSS::UnsupportedError, "Editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless UPDATABLE
+      raise JSS::UnsupportedError, "Editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless updatable?
       raise JSS::InvalidDataError, "Names can't be empty!" if newname.to_s.empty?
       raise JSS::AlreadyExistsError, "A #{self.class::RSRC_OBJECT_KEY} named '#{newname}' already exsists in the JSS" \
         if self.class.all_names(:refresh, api: @api).include? newname
@@ -91,7 +91,7 @@ module JSS
     #
     def update
       return nil unless @need_to_update
-      raise JSS::UnsupportedError, "Editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless UPDATABLE
+      raise JSS::UnsupportedError, "Editing #{self.class::RSRC_LIST_KEY} isn't yet supported. Please use other Casper workflows." unless updatable?
       raise JSS::NoSuchItemError, "Not In JSS! Use #create to create this #{self.class::RSRC_OBJECT_KEY} in the JSS before updating it." unless @in_jss
       @api.put_rsrc @rest_rsrc, rest_xml
       @need_to_update = false

data/lib/jss/exceptions.rb

@@ -26,79 +26,82 @@
 ###
 module JSS
 
-  #####################################
   ### Exceptions
   #####################################
 
-  ###
   ### MissingDataError - raise this error when we
   ### are missing args, or other simliar stuff.
   ###
   class MissingDataError < RuntimeError; end
 
-  ###
   ### InvalidDataError - raise this error when
   ### a data item isn't what we expected.
   ###
   class InvalidDataError < RuntimeError; end
 
-  ###
   ### InvalidConnectionError - raise this error when we
   ### don't have a usable connection to a network service, or
   ### don't have proper authentication/authorization.
   ###
   class InvalidConnectionError < RuntimeError; end
 
-  ###
   ### NoSuchItemError - raise this error when
   ### a desired item doesn't exist.
   ###
   class NoSuchItemError < RuntimeError; end
 
-  ###
   ### AlreadyExistsError - raise this error when
   ### trying to create something that already exists.
   ###
   class AlreadyExistsError < RuntimeError; end
 
-  ###
   ### FileServiceError - raise this error when
   ### there's a problem accessing file service on a
   ### distribution point.
   ###
   class FileServiceError < RuntimeError; end
 
-  ###
   ### UnmanagedError - raise this when we
   ### try to do something managerial to
   ### an unmanaged object
   ###
-  class UnmanagedError <  RuntimeError; end
+  class UnmanagedError < RuntimeError; end
 
-  ###
   ### UnsupportedError - raise this when we
   ### try to do something not yet supported
   ###
-  class UnsupportedError <  RuntimeError; end
+  class UnsupportedError < RuntimeError; end
 
-  ###
   ### TimeoutError - raise this when we
   ### try to do and it times out
   ###
-  class TimeoutError <  RuntimeError; end
+  class TimeoutError < RuntimeError; end
 
-  ###
   ### AuthenticationError - raise this when
   ### a name/pw are wrong
   ###
-  class AuthenticationError <  RuntimeError; end
+  class AuthenticationError < RuntimeError; end
 
-  ###
   ### ConflictError - raise this when
   ### attempts to PUT or PUSH to the API
   ### result in a 409 Conflict http error.
-  ### See JSS::APIConnect.instance.raise_conflict_error
+  ### See {JSS::APIConnection#raise_conflict_error}
+  ###
+  class ConflictError < RuntimeError; end
+
+  ### BadRequestError - raise this when
+  ### attempts to PUT or PUSH or DELETE to the API
+  ### result in a 400 Bad Request http error.
+  ### See {JSS::APIConnection.raise_bad_request_error}
+  ###
+  class BadRequestError < RuntimeError; end
+
+  ### APIRequestError - raise this when
+  ### attempts API actions generate an error not dealt with
+  ### by ConflictError or BadRequestError
+  ### result in a 400 Bad Request http error.
+  ### See {JSS::APIConnection.raise_api_error}
   ###
-  class ConflictError <  RuntimeError; end
+  class APIRequestError < RuntimeError; end
 
-end  # module JSS
+end # module JSS

data/lib/jss/ruby_extensions/hash.rb

@@ -78,7 +78,7 @@ class Hash
 
   # Since a lot of JSON data from the API comes as deeply-nested structures
   # of Hashes and Arrays, it can be a pain to reference some of the deeper
-  # data inside, and it isn't worth coding them out into Class attributes.
+  # data inside, and it isn't worth coding them out into instance attributes.
   #
   # For example see the 'hardware' subset of a JSS::Computer's API data,
   # which is stored as a Hash in the {JSS::Computer.hardware} attribute.
@@ -94,7 +94,7 @@ class Hash
   # But, there are two problems with just storing #hardware as an OpenStruct:
   # 1) we'd lose some important Hash methods, like #keys and #values, breaking
   # backward compatibility. 2) OpenStructs only work on the Hash itself, not
-  # not it's contents.
+  # its contents.
   #
   # So to get the best of both worlds, we use the RecursiveOpenStruct gem
   #
@@ -112,20 +112,25 @@ class Hash
   # CAVEAT: Treat these as read-only.
   #
   # While the Hashes themselves may be mutable, their use in ruby-jss Classes
-  # should be usually be considered read-only - and the RecursiveOpenStruct
-  # object created by this method should not be changed. Changes to the Hash
-  # or the RecursiveOpenStruct are NOT synced between them
+  # should usually be considered read-only - neither the Hash, nor the
+  # RecursiveOpenStruct  object created by this method should be changed.
+  # Changes to the Hash or the RecursiveOpenStruct are NOT synced between them,
+  # and ruby-jss won't know to send such changes back to the API when #update
+  # is called.
   #
   # This should be fine for the intended uses. Data like Computer#hardware
   # isn't sent back to the JSS via Computer#update, since it must come
-  # from a 'recon' anyway. Data that is sent back to the JSS will have
-  # setter methods defined in the class or a mixin module (e.g. the
-  # Locatable module).
-  #
-  # Since the data is read-only, why not use the ImmutableStruct gem, used
-  # elsewhere in ruby-jss?  Because ImmutableStruct is really for creating
-  # fully-fleshed-out read-only classes, with a known set of attributes rather
-  # than just giving us a nicer way to access Hash data with arbitrary keys.
+  # from a 'recon' anyway.
+  #
+  # Data that is sent back to the JSS will have setter methods defined in the
+  # class or a mixin module (e.g. the Locatable module).
+  #
+  # Since the data is functionally read-only, why not use the ImmutableStruct
+  # gem, used elsewhere in ruby-jss?
+  #
+  # Because ImmutableStruct is really for creating fully-fleshed-out read-only
+  # classes, with a known set of attributes rather than just giving us a nicer
+  # way to access Hash data with arbitrary keys.
   #
   def jss_recursive_ostruct
     @jss_ros ||= RecursiveOpenStruct.new(self, recurse_over_arrays: true)

data/lib/jss/utility.rb

@@ -415,35 +415,17 @@ module JSS
 
   # Parse a JSS Version number into something comparable.
   #
-  # With Jamf Pro 9.99, "Semantic Versioning" is used, see http://semver.org/
-  #
-  # For versions less than 9.99 parsing is like this:
-  #   - Digits before the first dot are the Major Version
-  #   - The first digit after the first dot is the Minor Version
-  #   - Any other digits after the first dot but before a non-digit
-  #     are the Revision
-  #   - Anything after a second dot is the build identifier
-  #   - Any non-digit anywhere means that it and everything after it
-  #     are the build identifier
-  #
-  # So 9.32 becomes major-9, minor-3, rev-2, build-''
-  # and 9.32.3764 becomes major-9, minor-3, rev-2, build-3764
-  # and 9.32a3764 becomes major-9, minor-3, rev-2, build-a3764
-  # and 9.32a1234.t234 becomes major-9, minor-3, rev-2, build-a1234.t234
-  #
-  # This old style method of parsing will break if digits between the first
-  # dot and the second (or the end) ever gets above 99, since '100' will
-  # become minor-1, rev-0
-  #
   # This method returns a Hash with these keys:
   # * :major => the major version, Integer
   # * :minor => the minor version, Integor
-  # * :maint => the revision, Integer
-  #   (this is also available with the keys :patch and :revision)
+  # * :maint => the revision, Integer (also available as :patch and :revision)
   # * :build => the revision, String
   # * :version => a Gem::Version object built from :major, :minor, :revision
   #   which can be easily compared with other Gem::Version objects.
   #
+  # NOTE: the :version value ignores build numbers, so comparisons
+  # only compare major.minor.maint
+  #
   # @param version[String] a JSS version number from the API
   #
   # @return [Hash{Symbol => String, Gem::Version}] the parsed version data.
@@ -452,17 +434,8 @@ module JSS
     major, second_part, *_rest = version.split('.')
     raise JSS::InvalidDataError, 'JSS Versions must start with "x.x" where x is one or more digits' unless major =~ /\d$/ && second_part =~ /^\d/
 
-    # since ruby-jss requires 9.4 and up, this check works fine.
-    if major == '9' && (second_part.to_i < 99)
-      parse_jss_version_oldstyle version
-    else
-      parse_jss_version_newstyle version
-    end
-  end
+    release, build = version.split(/-/)
 
-  # (see parse_jss_version)
-  def self.parse_jss_version_newstyle(version)
-    release, build = version.split '-'
     major, minor, revision = release.split '.'
     minor ||= 0
     revision ||= 0
@@ -474,46 +447,9 @@ module JSS
       maint:  revision.to_i,
       patch:  revision.to_i,
       build:  build,
-      # version: Gem::Version.new(version)
-      version: Gem::Version.new("#{major}.#{minor}.#{revision}#{build}")
-    }
-  end # parse_jss_version_oldstyle
-
-  # (see parse_jss_version)
-  def self.parse_jss_version_oldstyle(version)
-    version =~ /^(\d+?)\.(.*)$/
-    major = Regexp.last_match[1]
-    second_part = Regexp.last_match[2].to_s
-
-    minor = second_part[0]
-    revision = second_part[1..-1]
-
-    # if there's a non-digit anywhere in any part, it and everything after
-    # is the build.
-    if revision.to_s =~ /^(\d*)(\D.*)$/
-      revision = Regexp.last_match[1]
-      build = Regexp.last_match[2]
-      # but remove a leading dot
-      build = build[1..-1] if build.start_with? '.'
-    end
-    minor ||= ''
-    revision ||= ''
-
-    version_string = major.to_s
-    unless minor.empty?
-      version_string << ".#{minor}"
-      version_string << ".#{revision}" unless revision.empty?
-    end
-    {
-      major: major.to_i,
-      minor:  minor.to_i,
-      revision:  revision.to_i,
-      maint:  revision.to_i,
-      patch:  revision.to_i,
-      build:  build.to_s,
-      version:  Gem::Version.new(version_string)
+      version: Gem::Version.new("#{major}.#{minor}.#{revision}")
     }
-  end # parse_jss_version_oldstyle
+  end
 
   # @return [Boolean] is this code running as root?
   #

data/lib/jss/validate.rb

@@ -22,7 +22,6 @@
 #
 #
 
-#
 module JSS
 
   # A collection of methods for validating values. Mostly for
@@ -60,13 +59,18 @@ module JSS
       ok = true
       parts = val.strip.split '.'
       ok = false unless parts.size == 4
-      parts.each { |p| ok = false unless p.jss_integer? && p.to_i < 256 }
+      parts.each { |p| ok = false unless p.jss_integer? && p.to_i < 256 && p.to_i >= 0 }
       raise JSS::InvalidDataError, "Not a valid IPv4 address: '#{val}'" unless ok
       val
     end
 
     # Validate that a value doesn't already exist for a given identifier of a given class
     #
+    # e.g. when klass = JSS::Computer, identifier = :name, and val = 'foo'
+    # will raise an error when a computer named 'foo' exists
+    #
+    # Otherwise returns val.
+    #
     # @param klass[JSS::APIObject] A subclass of JSS::APIObject, e.g. JSS::Computer
     #
     # @param identifier[Symbol] One of the keys of an Item of the class's #all Array
@@ -76,10 +80,71 @@ module JSS
     # @return [Object] the validated unique value
     #
     def self.unique_identifier(klass, identifier, val, api: JSS.api)
-      raise JSS::AlreadyExistsError, "A #{klass} already exists with #{identifier} '#{val}'" if klass.all(:refresh, api: api).map { |i| i[identifier] }.include? val
+      return val unless klass.all(:refresh, api: api).map { |i| i[identifier] }.include? val
+      raise JSS::AlreadyExistsError, "A #{klass} already exists with #{identifier} '#{val}'"
+    end
+
+    # Confirm that the given value is a boolean value, accepting
+    # strings and symbols and returning real booleans as needed
+    # Accepts: true, false, 'true', 'false', :true, :false, 'yes', 'no', :yes,
+    # or :no (all Strings and Symbols are case insensitive)
+    #
+    # TODO: use this throughout ruby-jss
+    #
+    # @param bool [Boolean,String,Symbol] The value to validate
+    #
+    # @return [Boolean] the valid boolean
+    #
+    def self.boolean(bool)
+      return bool if JSS::TRUE_FALSE.include? bool
+      return true if bool.to_s =~ /^(true|yes)$/i
+      return false if bool.to_s =~ /^(false|no)$/i
+      raise JSS::InvalidDataError, 'Value must be boolean true or false'
+    end
+
+    # Confirm that a value is an integer or a string representation of an
+    # integer. Return the integer, or raise an error
+    #
+    # TODO: use this throughout ruby-jss
+    #
+    # @param val[Object] the value to validate
+    #
+    # @return [void]
+    #
+    def self.integer(val)
+      val = val.to_i if val.is_a?(String) && val.jss_integer?
+      raise JSS::InvalidDataError, 'Value must be an integer' unless val.is_a? Integer
+      val
+    end
+
+    # validate that the given value is a non-empty string
+    #
+    # @param val [Object] the thing to validate
+    #
+    # @return [String] the valid non-empty string
+    #
+    def self.non_empty_string(val)
+      raise JSS::InvalidDataError, 'value must be a non-empty String' unless val.is_a?(String) && !val.empty?
       val
     end
 
+    # Confirm that the given value is a boolean value, accepting
+    # strings and symbols and returning real booleans as needed
+    # Accepts: true, false, 'true', 'false', :true, :false, 'yes', 'no', :yes,
+    # or :no (all Strings and Symbols are case insensitive)
+    #
+    #
+    # @param bool [Boolean,String,Symbol] The value to validate
+    #
+    # @return [Boolean] the valid boolean
+    #
+    def self.boolean(bool)
+      return bool if JSS::TRUE_FALSE.include? bool
+      return true if bool.to_s =~ /^(true|yes)$/i
+      return false if bool.to_s =~ /^(false|no)$/i
+      raise JSS::InvalidDataError, 'Value must be boolean true or false'
+    end
+
   end # module validate
 
 end # module JSS

data/lib/jss/version.rb

@@ -27,6 +27,6 @@
 module JSS
 
   ### The version of the JSS ruby gem
-  VERSION = '0.14.0'.freeze
+  VERSION = '1.0.0b2'.freeze
 
 end # module

data/lib/jss/xml_workaround.rb

@@ -0,0 +1,208 @@
+### Copyright 2018 Pixar
+
+###
+###    Licensed under the Apache License, Version 2.0 (the "Apache License")
+###    with the following modification; you may not use this file except in
+###    compliance with the Apache License and the following modification to it:
+###    Section 6. Trademarks. is deleted and replaced with:
+###
+###    6. Trademarks. This License does not grant permission to use the trade
+###       names, trademarks, service marks, or product names of the Licensor
+###       and its affiliates, except as required to comply with Section 4(c) of
+###       the License and to reproduce the content of the NOTICE file.
+###
+###    You may obtain a copy of the Apache License at
+###
+###        http://www.apache.org/licenses/LICENSE-2.0
+###
+###    Unless required by applicable law or agreed to in writing, software
+###    distributed under the Apache License with the above modification is
+###    distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+###    KIND, either express or implied. See the Apache License for the specific
+###    language governing permissions and limitations under the Apache License.
+###
+###
+
+###
+module JSS
+
+  # Since a non-trivial amounts of the JSON data from the API are borked, the
+  # methods here can be used to parse the XML data into usable JSON, which we
+  # can then treat normally.
+  #
+  # For classes with borked JSON, set the constant USE_XML_WORKAROUND to a Hash
+  # with a single key that maps the structure of the XML and resultant Ruby data.
+  #
+  # As an example, here's the data map from JSS::PatchTitle
+  #
+  # USE_XML_WORKAROUND = {
+  #   patch_software_title: {
+  #     id: -1,
+  #     name: JSS::BLANK,
+  #     name_id: JSS::BLANK,
+  #     source_id: -1,
+  #     notifications: {
+  #       email_notification: nil,
+  #       web_notification: nil
+  #     },
+  #     category: {
+  #       id: -1,
+  #       name: JSS::BLANK
+  #     },
+  #     versions: [
+  #       {
+  #         software_version: JSS::BLANK,
+  #         package: -1,
+  #           name: JSS::BLANK
+  #         }
+  #       }
+  #     ]
+  #   }
+  # }.freeze
+  #
+  # The constant must always be a hash that represents the data structure
+  # of the object. The keys match the names of the XML elements, and the
+  # values indicate how to handle the element values.
+  #
+  # Single-value attributes will be converted based on the provided map example
+  # The class of the map example is the class of the desired data, and the value
+  # of the map example is the value to use when the XML data is nil or empty.
+  #
+  # So a map example of '' (an empty string, a.k.a. JSS::BLANK) indicates
+  # that the value should be a String and if the XML element is nil or empty,
+  # use '' in the Ruby data. If its -1, that means the value should be an
+  # Integer, and if its empty or nil, use -1 in Ruby.
+  #
+  # Booleans are special: the map example must be nil, and nil is used when the
+  # xml is empty, since you want to be able to know that the XML value was
+  # neither true nor false.
+  #
+  # Allowed single value classes and common default examples are:
+  #   String, common default: '' or JSS::BLANK
+  #   Integer, common default: -1
+  #   Float, common default: -1.0
+  #   Boolean, required default: nil
+  #
+  # Arrays and Hashes will be recognized as such, and their contents will be
+  # converted recursively using the same process.
+  #
+  # For Arrays, provide one example in the map of an Array
+  # item, and all sub elements will be processd like the example. See
+  # the ':versions' array defiend in the example above
+  #
+  # For sub-hashes, use the same technique as for the main hash.
+  # see the :category value above.
+  #
+  # IMPORTANT NOTE: Lots of Arrays in the XML have a matching 'size' element
+  # containing an integer indicating how many items are in the array. Unfortunately
+  # there is zero consistency about their existence or location. If they exist at
+  # all, sometimes the are adjacent to the Array element, sometimes within it.
+  #
+  # Fortunately in Ruby, all container/enumerable classes have a 'size' or 'count'
+  # method to easily get that number.
+  # As such, when parsing XML elements, any 'size' element that exists with no
+  # other 'size' elements, and contains only an integer value and no sub-
+  # elements, are ignored. I haven't yet found any cases of a 'size' element
+  # that is used for anything else.
+  #
+  module XMLWorkaround
+
+    BOOLEAN_STRINGS = %w[true false].freeze
+    TRUE_STRING = BOOLEAN_STRINGS.first
+    SIZE_ELEM_NAME = 'size'.freeze
+
+    # When APIObject classes are fetched, API JSON data is retrieved by the
+    # APIObject#lookup_object_data method, which parses the JSON into Ruby data.
+    #
+    # If the APIObject class has the constant USE_XML_WORKAROUND defined, that
+    # means the JSON data from the API is invalid, incorrect, or otherwise
+    # borked. So instead, the  XML is retrieved from the API here.
+    #
+    # It is then parsed by using the methods in this module and returned
+    # to the APIObject#lookup_object_data method, which then
+    # treats it normally.
+    #
+    def self.data_via_xml(rsrc, map, api)
+      raw_xml = api.get_rsrc(rsrc, :xml)
+      xmlroot = REXML::Document.new(raw_xml).root
+      hash_from_xml = {}
+      map.each do |key, model|
+        hash_from_xml[key] = process_map_item model, xmlroot
+      end
+      hash_from_xml
+    end
+
+    # given a REXML element, return its ruby value
+    #
+    # This method is then called recursively as needed when traversing XML
+    # elements that contain sub-elements.
+    #
+    # XML Elements that do not contain other elements are converted to a
+    # single ruby value.
+    #
+    def self.process_map_item(model, element)
+      case model
+      when String
+        element ? element.text : model
+      when Integer
+        element ? element.text.to_i : model
+      when Float
+        element ? element.text.to_f : model
+      when nil
+        return nil unless element
+        element.text.downcase == TRUE_STRING ? true : false
+      when Array
+        element ? elem_as_array(model.first, element) : []
+      when Hash
+        element ? elem_as_hash(model, element) : {}
+      end # case type
+    end
+
+    # remove the 'size' sub element from a given element as long as:
+    # - a sub element named 'size' exists
+    # - there's only one sub element named 'size'
+    # - it doesn't have sub elements itself
+    # - and it contains an integer value
+    # Such elements are extraneous for the most part, and are not consistently
+    # located - sometimes they are in the Array-ish elements they reference,
+    # sometimes they are alongside them. In any case they confuse the logic
+    # when deciding if an element with sub-elements should become an
+    # Array or a Hash.
+    #
+    def self.remove_size_sub_elem(elem)
+      size_elems = elem.elements.to_a.select { |subel| subel.name == SIZE_ELEM_NAME }
+      size_elem = size_elems.first
+      return unless size_elem
+      return unless size_elems.count == 1
+      return if size_elem.has_elements?
+      return unless size_elem.text.jss_integer?
+      elem.delete_element size_elem
+    end
+
+    # convert an XML element into an Array
+    def self.elem_as_array(model, elem)
+      remove_size_sub_elem elem
+      arr = []
+      elem.each do |subelem|
+        # Recursion for the win!
+        arr << process_map_item(model, subelem)
+      end # each subelem
+      arr.compact
+    end
+
+    # convert an XML element into a Hash
+    def self.elem_as_hash(model, elem)
+      remove_size_sub_elem elem
+      hsh = {}
+      model.each do |key, mod|
+        val = process_map_item(mod, elem.elements[key.to_s])
+        val = [] if  mod.is_a?(Array) && val.to_s.empty?
+        val = {} if  mod.is_a?(Hash) && val.to_s.empty?
+        hsh[key] = val
+      end
+      hsh
+    end
+
+  end # module XMLWorkarounds
+
+end # module