ruby-jss 1.6.4 → 2.0.0b1

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

@@ -0,0 +1,103 @@
+### 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
+
+    # Jamf module methods and aliases for dealing with the default connection
+    # This is extended into the Jamf module itself
+    ######################
+    module DefaultConnection
+
+      # The current default Jamf::Connection instance.
+      #
+      # @return [Jamf::Connection]
+      #
+      def cnx
+        @default_connection ||= Jamf::Connection.new name: :default
+      end
+      alias api cnx
+      alias api_connection cnx
+      alias connection cnx
+      alias default_connection cnx
+
+      # Create a new Connection object and use it as the default for all
+      # future API calls. This will replace the existing default connection with
+      # a totally new one
+      #
+      # @param (See Jamf::Connection#initialize)
+      #
+      # @return [String] the to_s output of the new connection
+      #
+      def connect(url = nil, **params)
+        params[:name] ||= :default
+        @default_connection = Jamf::Connection.new url, **params
+        @default_connection.to_s
+      end
+      alias login connect
+      alias new_api_connection connect
+      alias new_api connect
+      alias new_cnx connect
+      alias new_connection connect
+
+      # Use the given Jamf::Connection object as the default connection, replacing
+      # the one that currently exists.
+      #
+      # @param connection [Jamf::Connection] The default Connection to use for future
+      #   API calls
+      #
+      # @return [APIConnection] The connection now being used.
+      #
+      def cnx=(connection)
+        raise 'API connections must be instances of Jamf::Connection' unless connection.is_a? Jamf::Connection
+
+        @default_connection = connection
+      end
+      alias use_connection cnx=
+      alias use_api_connection cnx=
+      alias use_api cnx=
+      alias activate_connection cnx=
+
+      # Disconnect the default connection
+      #
+      def disconnect
+        @default_connection.disconnect if @default_connection&.connected?
+      end
+
+      # Log out the default connection
+      # This not only disconnects the connection, but tells the server to
+      # invalidate the token that was used, meaning that token cannot be used
+      # elsewhere before its expiration time.
+      def logout
+        @default_connection.logout if @default_connection&.connected?
+      end
+
+    end # module DefaultConnection
+
+  end # class Connection
+
+end # module Jamf

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

@@ -0,0 +1,174 @@
+### 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 Jamf Pro API.
+    # This includes creating the Faraday connection, sending HTTP requests and
+    # handling responses
+    module JamfProAPI
+
+      # create the faraday JPAPI connection object
+      #######################################################
+      def create_jp_connection(parse_json: true)
+        Faraday.new(@jp_base_url, ssl: ssl_options) do |cnx|
+          cnx.authorization :Bearer, @token.token
+
+          cnx.options[:timeout] = @timeout
+          cnx.options[:open_timeout] = @open_timeout
+
+          if parse_json
+            cnx.request :json
+            cnx.response :json, parser_options: { symbolize_names: true }
+          end
+
+          cnx.adapter Faraday::Adapter::NetHttp
+        end
+      end
+
+      # @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) 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
+      end
+      # backward compatibility
+      alias get jp_get
+
+      # Create a JPAPI resource via POST
+      #
+      # @param rsrc[String] the resource to POST
+      #   (the part of the API url after the '/api/' )
+      #
+      # @param data[String] the JSON data to POST
+      #
+      # @return [String] the response body
+      #######################################################
+      def jp_post(rsrc, data)
+        validate_connected @jp_cnx
+        resp = @jp_cnx.post(rsrc) do |req|
+          req.body = data
+        end
+        @last_http_response = resp
+        return resp.body if resp.success?
+
+        raise Jamf::Connection::JamfProAPIError, resp
+      end
+      # backward compatibility
+      alias post jp_post
+
+      # Replace an existing Jamf Pro API resource
+      #
+      # @param rsrc[String] the API resource being changed, the URL part after 'api/'
+      #
+      # @param data[String] the json specifying the changes.
+      #
+      # @return [String] the response from the server.
+      #
+      #######################################################
+      def jp_put(rsrc, data)
+        validate_connected @jp_cnx
+        resp = @jp_cnx.put(rsrc) do |req|
+          req.body = data
+        end
+        @last_http_response = resp
+        return resp.body if resp.success?
+
+        raise Jamf::Connection::JamfProAPIError, resp
+      end
+      # backward compatibility
+      alias put jp_put
+
+      # Update an existing Jamf Pro API resource
+      #
+      # @param rsrc[String] the API resource being changed, the URL part after 'api/'
+      #
+      # @param data[String] the json specifying the changes.
+      #
+      # @return [String] the response from the server.
+      #
+      #######################################################
+      def jp_patch(rsrc, data)
+        validate_connected @jp_cnx
+        resp = @jp_cnx.patch(rsrc) do |req|
+          req.body = data
+        end
+        @last_http_response = resp
+        return resp.body if resp.success?
+
+        raise Jamf::Connection::JamfProAPIError, resp
+      end
+      # backward compatibility
+      alias patch jp_patch
+
+      # Delete an existing Jamf Pro API resource
+      #
+      # @param rsrc[String] the API resource being deleted, the URL part after 'api/'
+      #
+      # @return [String] the response from the server.
+      #
+      #######################################################
+      def jp_delete(rsrc)
+        validate_connected @jp_cnx
+        resp = @jp_cnx.delete rsrc
+        @last_http_response = resp
+        return resp.body if resp.success?
+
+        raise Jamf::Connection::JamfProAPIError, resp
+      end
+      # backward compatibility
+      alias delete jp_delete
+
+      # GET a rsrc without doing any JSON parsing, using
+      # a temporary Faraday connection object
+      #######################################################
+      def jp_download(rsrc)
+        temp_cnx = create_jp_connection(parse_json: false)
+        resp = temp_cnx.get rsrc
+        @last_http_response = resp
+        return resp.body if resp.success?
+
+        raise Jamf::Connection::JamfProAPIError, resp
+      end
+
+    end # module
+
+  end # class
+
+end # module Jamf

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

@@ -0,0 +1,109 @@
+# 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 module
+module Jamf
+
+  class Connection
+
+    # An exception class that's a wrapper around Jamf::OAPIObject::ApiError
+    #
+    class JamfProAPIError < RuntimeError
+
+      RSRC_NOT_FOUND = 'Resource Not Found'.freeze
+
+      # @return [Faraday::Response]
+      attr_reader :http_response
+
+      # @return [Jamf::OAPIObject::ApiError]
+      attr_reader :api_error
+
+      # @param http_response [Faraday::Response]
+      def initialize(http_response)
+        @http_response = http_response
+        @api_error = Jamf::OAPISchemas::ApiError.new @http_response.body
+
+        add_common_basic_error_causes if @api_error.errors.empty?
+        super
+      end
+
+      # If no actual errors causes came with the APIError, try to add
+      # some common basic ones
+      def add_common_basic_error_causes
+        return unless api_error.errors.empty?
+
+        case http_response.status
+        when 403
+          code = 'INVALID_PRIVILEGE'
+          desc = 'Forbidden'
+          id = nil
+          field = ''
+        when 404
+          code = 'NOT_FOUND'
+          desc = "'#{http_response.env.url.path}' was not found on the server"
+          id = nil
+          field = ''
+        else
+          return
+        end # case
+
+        api_error.errors_append Jamf::OAPISchemas::ApiErrorCause.new(field: field, code: code, description: desc, id: id)
+      end
+
+      # http status, from the server http response
+      def http_status
+        http_response.status
+      end
+
+      # http status, from the API error
+      def api_status
+        api_error.httpStatus
+      end
+
+      # @return [Array<Jamf::OAPIObject::ApiErrorCause>] the causes of the error
+      def errors
+        api_error.errors
+      end
+
+      # To string, this shows up as the exception msg when raising the exception
+      def to_s
+        msg = +"HTTP #{http_status}"
+        msg << ':' unless errors.empty?
+        msg << errors.map do |err|
+          err_str = +''
+          err_str << " Field: #{err.field}" unless err.field.to_s.empty?
+          err_str << ' Error:' if err.code || err.description
+          err_str << " #{err.code}" if err.code
+          err_str << " #{err.description}" if err.description
+          err_str << " Object ID: '#{err.id}'" if err.id
+          err_str
+        end.join('; ')
+        msg
+      end
+
+    end # class APIError
+
+  end # class Connection
+
+end # module Jamf