ruby-jss 1.6.4 → 2.0.0a10

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

@@ -0,0 +1,148 @@
+### Copyright 2022 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.
+###
+###
+
+# THe main module
+module Jamf
+
+  # The connection class
+  class Connection
+
+    # This module defines attributes and methods related to the caching of certain
+    # data from the API.
+    # TODO: Remove this when we no longer support caching from either API
+    module Cache
+
+      # These classes are extendable, their Extension Attributes in the
+      # classic API are cached locally in the connection object..
+      # NOTE: These are strings, not references to the actual classes.
+      # Otherwise, they and all the classes they reference get loaded
+      # when ruby-jss is required
+      EXTENDABLE_CLASSES = %w[Jamf::Computer Jamf::MobileDevice Jamf::User].freeze
+
+      # @return [Concurrent::Map.new] This Hash-like object caches the results of
+      #   C-API queries for an APIObject
+      #   subclass's .all summary list, keyed by the subclass's RSRC_LIST_KEY.
+      #   See the APIObject.all class method.
+      #
+      #   It also caches related data items for speedier processing:
+      #
+      #   - The Hashes created by APIObject.map_all_ids_to(other_key), keyed by
+      #     "#{RSRC_LIST_KEY}_map_#{other_key}".to_sym
+      #
+      #   - This hash also holds a cache of the rarely-used APIObject.all_objects
+      #     hash, keyed by "#{RSRC_LIST_KEY}_objects".to_sym
+      #
+      #
+      #   When APIObject.all, and related methods are called without an argument,
+      #   and this hash has a matching value, the value is returned, rather than
+      #   requerying the API. The first time a class calls .all, or whenever refresh
+      #   is not false, the API is queried and the value in this hash is updated.
+      def c_object_list_cache
+        @c_object_list_cache ||= Concurrent::Map.new
+      end
+
+      # @return [Hash{Class: Hash{String => Jamf::ExtensionAttribute}}]
+      #   This Hash caches the C-API Extension Attribute
+      #   definition objects for the three types of ext. attribs:
+      #   ComputerExtensionAttribute, MobileDeviceExtensionAttribute, and
+      #   UserExtensionAttribute, whenever they are fetched for parsing or
+      #   validating extention attribute data.
+      #
+      #   The top-level keys are the EA classes themselves:
+      #   - ComputerExtensionAttribute
+      #   - MobileDeviceExtensionAttribute
+      #   - UserExtensionAttribute
+      #
+      #   These each point to a Hash of their instances, keyed by name, e.g.
+      #     {
+      #      "A Computer EA" => <Jamf::ComputerExtensionAttribute...>,
+      #      "A different Computer EA" => <Jamf::ComputerExtensionAttribute...>,
+      #      ...
+      #     }
+      #
+      def c_ext_attr_definition_cache
+        @c_ext_attr_definition_cache ||= Concurrent::Map.new
+      end
+
+      # Empty cached lists from this connection
+      # then run garbage collection to clear any available memory
+      #
+      # See the getters for
+      # - c_object_list_cache
+      # - c_ext_attr_definition_cache
+      #
+      # NOTE since all ruby variables are references to objects in memory,
+      # if you've referenced objects in these caches, those objects
+      # won't be removed from memory by garbage collection but all cached data
+      # will be recached as needed.
+      #
+      # e.g.s
+      #  my_ref = Jamf::SomeClass.all
+      #  # my_ref now points to the same cached hash that Jamf::SomeClass.all does
+      #
+      #  my_connection.flushcache
+      #  # Jamf::SomeClass.all now points to an empty hash in the cache, but the one
+      #  # that my_ref points to still exists, full of the original data. Because
+      #  # my_ref still points to it, garbage collection doesn't remove it from
+      #  # memory
+      #
+      #  Jamf::SomeClass.all
+      #  # Jamf::SomeClass.all re-reads the data from the API and populates the
+      #  # Hash in the cache with new data, potentially different from that you're
+      #  # still seeing in my_ref
+      #
+      #
+      # @param key_or_klass[Symbol, Class] Flush only the caches for the given
+      #   RSRC_LIST_KEY. or the EAdef cache for the given extendable class.
+      #   If nil (the default), flushes all caches
+      #
+      # @return [void]
+      #
+      def flushcache(key_or_klass = nil)
+        # EA defs for just one extendable class?
+        if EXTENDABLE_CLASSES.include? key_or_klass.to_s
+          @c_ext_attr_definition_cache[key_or_klass] = Concurrent::Hash.new
+
+        # one API object class?
+        elsif key_or_klass
+          map_key_pfx = "#{key_or_klass}_map_"
+          @c_object_list_cache.delete_if do |cache_key, _cache|
+            cache_key == key_or_klass || cache_key.to_s.start_with?(map_key_pfx)
+          end
+
+
+        # flush everything
+        else
+          @c_object_list_cache = Concurrent::Hash.new
+          @c_ext_attr_definition_cache = Concurrent::Hash.new
+        end
+
+        GC.start
+      end
+
+    end # module
+
+  end # class
+
+end # module Jamf

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

@@ -0,0 +1,287 @@
+### Copyright 2022 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.
+###
+###
+
+# THe main module
+module Jamf
+
+  # The connection class
+  class Connection
+
+    # This module defines methods used for interacting with the Classic API.
+    # This includes creating the Faraday connection, sending HTTP requests and
+    # handling responses
+    module ClassicAPI
+
+      # Get a Classic API resource via GET
+      #
+      # The first argument is the resource to get (the part of the API url
+      # after the 'JSSResource/' ) The resource must be properly URL escaped
+      # beforehand. Note: URL.encode is deprecated, use CGI.escape
+      #
+      # By default we get the data in JSON, and parse it into a ruby Hash
+      # with symbolized Hash keys.
+      #
+      # If the second parameter is :xml then the XML version is retrieved and
+      # returned as a String.
+      #
+      # To get the raw JSON string as it comes from the API, pass raw_json: true
+      #
+      # @param rsrc[String] the resource to get
+      #   (the part of the API url after the 'JSSResource/' )
+      #
+      # @param format[Symbol] either ;json or :xml
+      #   If the second argument is :xml, the XML data is returned as a String.
+      #
+      # @param raw_json[Boolean] When GETting JSON, return the raw unparsed string
+      #   (the XML is always returned as a raw string)
+      #
+      # @return [Hash,String] the result of the get
+      #
+      def c_get(rsrc, format = :json, raw_json: false)
+        validate_connected @c_cnx
+        raise Jamf::InvalidDataError, 'format must be :json or :xml' unless Jamf::Connection::GET_FORMATS.include?(format)
+
+        resp =
+          @c_cnx.get(rsrc) do |req|
+            req.headers[Jamf::Connection::HTTP_ACCEPT_HEADER] = format == :json ? Jamf::Connection::MIME_JSON : Jamf::Connection::MIME_XML
+          end
+        @last_http_response = resp
+        unless resp.success?
+          handle_classic_http_error resp
+          return
+        end
+
+        return JSON.parse(resp.body, symbolize_names: true) if format == :json && !raw_json
+
+        # the raw body, either json or xml
+        resp.body
+      end # c_get
+      # backward compatibility
+      alias get_rsrc c_get
+
+      # Create a new Classic API resource via POST
+      #
+      # @param rsrc[String] the API resource being created, the URL part after 'JSSResource/'
+      #
+      # @param xml[String] the xml specifying the new object.
+      #
+      # @return [String] the xml response from the server.
+      #
+      def c_post(rsrc, xml)
+        validate_connected @c_cnx
+
+        # convert CRs & to 
+        xml&.gsub!(/\r/, '
')
+
+        # send the data
+        resp =
+          @c_cnx.post(rsrc) do |req|
+            req.headers[Jamf::Connection::HTTP_CONTENT_TYPE_HEADER] = Jamf::Connection::MIME_XML
+            req.headers[Jamf::Connection::HTTP_ACCEPT_HEADER] = Jamf::Connection::MIME_XML
+            req.body = xml
+          end
+        @last_http_response = resp
+
+        unless resp.success?
+          handle_classic_http_error resp
+          return
+        end
+
+        resp.body
+      end # c_post
+      # backward compatibility
+      alias post_rsrc c_post
+
+      # Update an existing Classic API resource
+      #
+      # @param rsrc[String] the API resource being changed, the URL part after 'JSSResource/'
+      #
+      # @param xml[String] the xml specifying the changes.
+      #
+      # @return [String] the xml response from the server.
+      #
+      def c_put(rsrc, xml)
+        validate_connected @c_cnx
+
+        # convert CRs & to 
+        xml.gsub!(/\r/, '
')
+
+        # send the data
+        resp =
+          @c_cnx.put(rsrc) do |req|
+            req.headers[Jamf::Connection::HTTP_CONTENT_TYPE_HEADER] = Jamf::Connection::MIME_XML
+            req.headers[Jamf::Connection::HTTP_ACCEPT_HEADER] = Jamf::Connection::MIME_XML
+            req.body = xml
+          end
+        @last_http_response = resp
+
+        unless resp.success?
+          handle_classic_http_error resp
+          return
+        end
+
+        resp.body
+      end
+      # backward compatibility
+      alias put_rsrc c_put
+
+      # Delete a resource from the Classic API
+      #
+      # @param rsrc[String] the resource to create, the URL part after 'JSSResource/'
+      #
+      # @return [String] the xml response from the server.
+      #
+      def c_delete(rsrc)
+        validate_connected @c_cnx
+        raise MissingDataError, 'Missing :rsrc' if rsrc.nil?
+
+        # delete the resource
+        resp =
+          @c_cnx.delete(rsrc) do |req|
+            req.headers[Jamf::Connection::HTTP_CONTENT_TYPE_HEADER] = Jamf::Connection::MIME_XML
+            req.headers[Jamf::Connection::HTTP_ACCEPT_HEADER] = Jamf::Connection::MIME_XML
+          end
+        @last_http_response = resp
+
+        unless resp.success?
+          handle_classic_http_error resp
+          return
+        end
+
+        resp.body
+      end # delete_rsrc
+      # backward compatibility
+      alias delete_rsrc c_delete
+
+      # Upload a file. This is really only used for the
+      # 'fileuploads' endpoint of the classic API, as implemented in the
+      # Uploadable mixin module, q.v.
+      #
+      # @param rsrc[String] the API resource being uploadad-to,
+      #   the URL part after 'JSSResource/'
+      #
+      # @param local_file[String, Pathname] the local file to upload
+      #
+      # @return [String] the xml response from the server.
+      #
+      def upload(rsrc, local_file)
+        validate_connected @c_cnx
+
+        # the upload file object for faraday
+        local_file = Pathname.new local_file
+        upfile = Faraday::UploadIO.new(
+          local_file.to_s,
+          'application/octet-stream',
+          local_file.basename.to_s
+        )
+
+        # send it and get the response
+        resp =
+          @c_cnx.post rsrc do |req|
+            req.headers['Content-Type'] = 'multipart/form-data'
+            req.body = { name: upfile }
+          end
+        @last_http_response = resp
+
+        unless resp.success?
+          handle_classic_http_error resp
+          return false
+        end
+
+        true
+      end # upload
+
+      #############################
+      private
+
+      # create the faraday CAPI connection object
+      def create_classic_connection
+        Faraday.new(@c_base_url, ssl: ssl_options) do |cnx|
+          cnx.authorization :Bearer, @token.token
+
+          cnx.options[:timeout] = @timeout
+          cnx.options[:open_timeout] = @open_timeout
+
+          cnx.request :multipart
+          cnx.request :url_encoded
+
+          cnx.adapter Faraday::Adapter::NetHttp
+        end
+      end
+
+      # Parses the given http response
+      # and raises a Jamf::APIError with a useful error message.
+      #
+      # @return [void]
+      #
+      def handle_classic_http_error(resp)
+        return if resp.success?
+
+        case resp.status
+        when 404
+          err = Jamf::NoSuchItemError
+          msg = 'Not Found'
+        when 409
+          err = Jamf::ConflictError
+
+          # TODO: Clean this up
+          resp.body =~ /<p>(The server has not .*?)(<|$)/m
+          msg = Regexp.last_match(1)
+
+          unless msg
+            resp.body =~ %r{<p>Error: (.*?)</p>}
+            msg = Regexp.last_match(1)
+          end
+
+          unless msg
+            resp.body =~ /<p>(Unable to complete file upload.*?)(<|$)/m
+            msg = Regexp.last_match(1)
+          end
+        when 400
+          err = Jamf::BadRequestError
+          resp.body =~ %r{>Bad Request</p>\n<p>(.*?)</p>\n<p>You can get technical detail}m
+          msg = Regexp.last_match(1)
+        when 401
+          if resp.body.include? 'INVALID_TOKEN'
+            err = Jamf::InvalidConnectionError
+            msg = 'Connection token is not valid'
+          else
+            err = Jamf::AuthorizationError
+            msg = 'You are not authorized to do that.'
+          end
+        when (500..599)
+          err = Jamf::APIRequestError
+          msg = 'There was an internal server error'
+        else
+          err = Jamf::APIRequestError
+          msg = "There was a error processing your request, status: #{resp.status}"
+        end
+        raise err, msg
+      end
+
+    end # module
+
+  end # class
+
+end # module Jamf