train-rest 0.2.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59770f2304519af69df3caaac4f4ef19f964a0a4700952ff6a3b96834867bf13
-  data.tar.gz: 39546783f42569561a1f740c094d0f2adb1a31c49c710b5c9736f172a961306f
+  metadata.gz: 1550899c2f8aad404793b83b1f7700ece96937efc8b78cb1eb7aebb8d6d2a2a2
+  data.tar.gz: b9251734100cc43233504afbe6e8d6fbd11bec1b07a16db7884720e907a164e2
 SHA512:
-  metadata.gz: c8b2b55eb1723538a552ecbc7ce452a3545bd8ae3e35a82c263f3bbc16d6bfed161d053a6a711b0e34723c4f332e6d7797a40035d6142fc9957618a10ad6dac6
-  data.tar.gz: 967e71707994db3086ea1f71e5d987324c405930ecb4473b9ad886ca59b32d15efb2e4c42f4f4075a607d642a11d78d4fe5e4fe6946468eb348735dd24bde514
+  metadata.gz: 1630381a0f378a7a4a275202fc19a60f71579b99f6b1ae50229c72b67cce2466e5d8b2f4a5b5c3c23f8c1c5c4ccc4817f768fc36cd65c3c8ac9c1b81609b1994
+  data.tar.gz: 02ed2d874ac736d016fc75f24a1c02e8b9209ec5f43cbb9281bf615106a04d53f4d49d26682e84cb7c2b7ab6a949dc2589823a769e9b87aa3c03aa428c50d919

data/README.md

@@ -20,7 +20,7 @@ rake install:local
 | Option               | Explanation                             | Default     |
 | -------------------- | --------------------------------------- | ----------- |
 | `endpoint`           | Endpoint of the REST API                | _required_  |
-| `validate_ssl`       | Check certificate and chain             | true        |
+| `verify_ssl`         | Check certificate and chain             | true        |
 | `auth_type`          | Authentication type                     | `anonymous` |
 | `debug_rest`         | Enable debugging of HTTP traffic        | false       |
 | `logger`             | Alternative logging class               |             |
@@ -34,7 +34,18 @@ Identifier: `auth_type: :anonymous`
 No actions for authentication, logging in/out or session handing are made. This
 assumes a public API.
 
-### Basic Authentication
+### Authtype Apikey
+
+This will inject a HTTP header `Authorization: Apikey xxxx` with the passed
+API key into requests.
+
+Identifier: `auth_type: :authtype_apikey`
+
+| Option               | Explanation                             | Default     |
+| -------------------- | --------------------------------------- | ----------- |
+| `apikey`             | API Key for authentication              | _required_  |
+
+### Basic (RFC 2617)
 
 Identifier: `auth_type: :basic`
 
@@ -46,6 +57,29 @@ Identifier: `auth_type: :basic`
 If you supply a `username` and a `password`, authentication will automatically
 switch to `basic`.
 
+### Bearer (RFC 7650)
+
+This will inject a HTTP header `Authorization: Bearer xxxx` with the passed
+token into requests.
+
+Identifier: `auth_type: :bearer`
+
+| Option               | Explanation                             | Default     |
+| -------------------- | --------------------------------------- | ----------- |
+| `token`              | Tokenb to pass                          | _required_  |
+
+### Header-based
+
+This will inject an additional HTTP header with the passed value. If no name
+for the header is passed, it will default to `X-API-Key`.
+
+Identifier: `auth_type: :header`
+
+| Option               | Explanation                             | Default     |
+| -------------------- | --------------------------------------- | ----------- |
+| `apikey`             | API Key for authentication              | _required_  |
+| `header`             | Name of the HTTP header to include      | `X-API-Key` |
+
 ### Redfish
 
 Identifier: `auth_type: :redfish`
@@ -60,6 +94,9 @@ The Redfish standard is defined in <http://www.dmtf.org/standards/redfish> and
 this handler does initial login, reuses the received session and logs out when
 closing the transport cleanly.
 
+Known vendors which implement RedFish based management for their systems include
+HPE, Dell, IBM, SuperMicro, Lenovo, Huawei and others.
+
 ## Debugging and use in Chef
 
 You can activate debugging by setting the `debug_rest` flag to `true'. Please
@@ -77,6 +114,46 @@ train  = Train.create('rest', {
          })
 ```
 
+## Request Methods
+
+This transport does not implement the `run_command` method, as there is no
+line-based protocol to execute commands against. Instead, it implements its own
+custom methods which suit REST interfaces. Trying to call this method will
+throw an Exception.
+
+### Generic Request
+
+The `request` methods allows to send free-form requests against any defined or
+custom methods.
+
+`request(path, method = :get, request_parameters: {}, data: nil, headers: {},
+json_processing: true)`
+
+- `path`: The path to request, which will be appended to the `endpoint`
+- `method`: The HTTP method in Ruby Symbol syntax
+- `request_parameters`: A hash of parameters to the `rest-client` request
+  method for additional settings
+- `data`: Data for actions like `:post` or `:put`. Not all methods accept
+  a data body.
+- `headers`: Additional headers for the request
+- `json_processing`: If the response is a JSON and you want to receive a
+  processed Hash/Array instead of text
+
+For `request_parameters` and `headers`, there is data mixed in to add
+authenticator responses, JSON processing etc. Please check the
+implementation in `connection.rb` for details.
+
+### Convenience Methods
+
+Simplified wrappers are generated for the most common request types:
+
+- `delete(path, request_parameters: {}, headers: {}, json_processing: true)`
+- `head(path, request_parameters: {}, headers: {}, json_processing: true)`
+- `get(path, request_parameters: {}, headers: {}, json_processing: true)`
+- `post(path, request_parameters: {}, data: nil, headers: {}, json_processing: true)`
+- `put(path, request_parameters: {}, data: nil, headers: {}, json_processing: true)`
+- `patch(path, request_parameters: {}, data: nil, headers: {}, json_processing: true)`
+
 ## Example use
 
 ```ruby
@@ -133,7 +210,7 @@ require 'train-rest'
 # This will immediately do a login and add headers
 train  = Train.create('rest', {
             endpoint: 'https://10.20.30.40',
-            validate_ssl: false,
+            verify_ssl: false,
 
             auth_type: :redfish,
             username: 'iloadmin',
@@ -176,5 +253,28 @@ conn.close
 1. Run against the defiend targets via Chef Target Mode:
 
    ```shell
-   chef-client --local-mode --target 10.0.0.1 --runlist 'recipe[my-cookbook:setup]'
+   chef-client --local-mode --target 10.0.0.1 --runlist 'recipe[my-cookbook::setup]'
    ```
+
+## Use with Prerecorded API responses
+
+For testing during and after development, not all APIs can be used to verify your solution against.
+The VCR gem offers the possibility to hook into web requests and intercept them to play back canned
+responses.
+
+Please read the documentation of the VCR gem on how to record your API and the concepts like
+"cassettes", "libraries" and matchers.
+
+The following options are available in train-rest for this:
+
+| Option               | Explanation                             | Default      |
+| -------------------- | --------------------------------------- | ------------ |
+| `vcr_cassette`       | Name of the response file               | nil          |
+| `vcr_library`        | Directory to search responses in        | `vcr`        |
+| `vcr_match_on`       | Elements to match request by            | `method uri` |
+| `vcr_record`         | Recording mode                          | `none`       |
+| `vcr_hook_into`      | Base library for intercepting           | `webmock`    |
+
+VCR will only be required as a Gem and activated, if you supply a cassette name.
+
+You can use all these settings in your Chef Target Mode `credentials` file as well.

data/lib/train-rest/auth_handler/anonymous.rb

@@ -1,4 +1,4 @@
-require_relative "../auth_handler.rb"
+require_relative "../auth_handler"
 
 module TrainPlugins
   module Rest

data/lib/train-rest/auth_handler/authtype-apikey.rb

@@ -0,0 +1,24 @@
+require "base64" unless defined?(Base64)
+
+require_relative "../auth_handler"
+
+module TrainPlugins
+  module Rest
+    # Authentication via "Apikey" type in Authorization headers.
+    #
+    # Could not find a norm for this, just references in e.g. ElasticSearch & Cloud Conformity APIs.
+    class AuthtypeApikey < AuthHandler
+      def check_options
+        raise ArgumentError.new("Need :apikey for `Authorization: Apikey` authentication") unless options[:apikey]
+      end
+
+      def auth_parameters
+        {
+          headers: {
+            "Authorization" => format("Apikey %s", options[:apikey]),
+          },
+        }
+      end
+    end
+  end
+end

data/lib/train-rest/auth_handler/basic.rb

@@ -1,18 +1,23 @@
-require_relative "../auth_handler.rb"
+require "base64" unless defined?(Base64)
+
+require_relative "../auth_handler"
 
 module TrainPlugins
   module Rest
-    # Authentication via HTTP Basic Authentication
+    # Authentication via Basic Authentication.
+    #
+    # @see https://www.rfc-editor.org/rfc/rfc2617#section-4.1
     class Basic < AuthHandler
       def check_options
-        raise ArgumentError.new("Need username for Basic authentication") unless options[:username]
-        raise ArgumentError.new("Need password for Basic authentication") unless options[:password]
+        raise ArgumentError.new("Need :username for Basic authentication") unless options[:username]
+        raise ArgumentError.new("Need :password for Basic authentication") unless options[:password]
       end
 
       def auth_parameters
         {
-          user: options[:username],
-          password: options[:password],
+          headers: {
+            "Authorization" => format("Basic %s", Base64.encode64(options[:username] + ":" + options[:password]).chomp),
+          },
         }
       end
     end

data/lib/train-rest/auth_handler/bearer.rb

@@ -0,0 +1,24 @@
+require "base64" unless defined?(Base64)
+
+require_relative "../auth_handler"
+
+module TrainPlugins
+  module Rest
+    # Authentication via Bearer Authentication.
+    #
+    # @see https://datatracker.ietf.org/doc/html/rfc6750#section-2.1
+    class Bearer < AuthHandler
+      def check_options
+        raise ArgumentError.new("Need :token for Bearer authentication") unless options[:token]
+      end
+
+      def auth_parameters
+        {
+          headers: {
+            "Authorization" => format("Bearer %s", options[:token]),
+          },
+        }
+      end
+    end
+  end
+end

data/lib/train-rest/auth_handler/header.rb

@@ -0,0 +1,24 @@
+require_relative "../auth_handler"
+
+module TrainPlugins
+  module Rest
+    # Authentication via additional Header.
+    #
+    # Header name defaults to "X-API-Key"
+    class Header < AuthHandler
+      def check_options
+        raise ArgumentError.new("Need :apikey for Header-based authentication") unless options[:apikey]
+
+        options[:header] = "X-API-Key" unless options[:header]
+      end
+
+      def auth_parameters
+        {
+          headers: {
+            options[:header] => options[:apikey],
+          },
+        }
+      end
+    end
+  end
+end

data/lib/train-rest/auth_handler/redfish.rb

@@ -1,4 +1,4 @@
-require_relative "../auth_handler.rb"
+require_relative "../auth_handler"
 
 module TrainPlugins
   module Rest

data/lib/train-rest/auth_handler.rb

@@ -13,7 +13,16 @@ module TrainPlugins
       #
       # @return [String]
       def self.name
-        self.to_s.split("::").last.downcase
+        class_name = self.to_s.split("::").last
+
+        convert_to_snake_case(class_name)
+      end
+
+      # List authentication handlers
+      #
+      # @return [Array] Classes derived from `AuthHandler`
+      def self.descendants
+        ObjectSpace.each_object(Class).select { |klass| klass < self }
       end
 
       # Store authenticator options and trigger validation
@@ -29,10 +38,18 @@ module TrainPlugins
       # @raise [ArgumentError] if options are not as needed
       def check_options; end
 
-      # Handle Login
+      # Handle login
       def login; end
 
-      # Handle Logout
+      # Handle session renewal
+      def renew_session; end
+
+      # Return if session renewal needs to happen soon
+      #
+      # @return [Boolean]
+      def renewal_needed?; end
+
+      # Handle logout
       def logout; end
 
       # Headers added to the rest-client call
@@ -50,11 +67,21 @@ module TrainPlugins
         { headers: auth_headers }
       end
 
-      # List authentication handlers
-      #
-      # @return [Array] Classes derived from `AuthHandler`
-      def self.descendants
-        ObjectSpace.each_object(Class).select { |klass| klass < self }
+      class << self
+        private
+
+        # Convert a class name to snake case.
+        #
+        # @param [String] Class name
+        # @return [String]
+        # @see https://github.com/chef/chef/blob/main/lib/chef/mixin/convert_to_class_name.rb
+        def convert_to_snake_case(str)
+          str = str.dup
+          str.gsub!(/[A-Z]/) { |s| "_" + s }
+          str.downcase!
+          str.sub!(/^\_/, "")
+          str
+        end
       end
     end
   end

data/lib/train-rest/connection.rb

@@ -1,9 +1,9 @@
-require "json"
-require "ostruct"
-require "uri"
+require "json" unless defined?(JSON)
+require "ostruct" unless defined?(OpenStruct)
+require "uri" unless defined?(URI)
 
-require "rest-client"
-require "train"
+require "rest-client" unless defined?(RestClient)
+require "train" unless defined?(Train)
 
 module TrainPlugins
   module Rest
@@ -19,9 +19,35 @@ module TrainPlugins
         # Accept string (CLI) and boolean (API) options
         options[:verify_ssl] = options[:verify_ssl].to_s == "false" ? false : true
 
+        setup_vcr
+
         connect
       end
 
+      def setup_vcr
+        return unless options[:vcr_cassette]
+
+        require "vcr" unless defined?(VCR)
+
+        # TODO: Starts from "/" :(
+        library = options[:vcr_library]
+        match_on = options[:vcr_match_on].split.map(&:to_sym)
+
+        VCR.configure do |config|
+          config.cassette_library_dir = library
+          config.hook_into options[:vcr_hook_into]
+          config.default_cassette_options = {
+            record: options[:vcr_record].to_sym,
+            match_requests_on: match_on,
+          }
+        end
+
+        VCR.insert_cassette options[:vcr_cassette]
+      rescue LoadError
+        logger.fatal "Install the vcr gem to use HTTP(S) playback capability"
+        raise
+      end
+
       def connect
         login if auth_handlers.include? auth_type
       end
@@ -36,10 +62,12 @@ module TrainPlugins
         components.to_s
       end
 
+      # Allow overwriting to refine the type of REST API
+      attr_writer :detected_os
+
       def inventory
-        # Faking it for Chef Target Mode only
         OpenStruct.new({
-          name: "rest",
+          name: @detected_os || "rest",
           release: TrainPlugins::Rest::VERSION,
           family_hierarchy: %w{rest api},
           family: "api",
@@ -58,27 +86,34 @@ module TrainPlugins
 
       # User-faced API
 
+      # Allow (programmatically) setting additional headers apart from global transport configuration
+      attr_accessor :override_headers
+
       %i{get post put patch delete head}.each do |method|
-        define_method(method) do |path, *parameters|
-          # TODO: "warning: Using the last argument as keyword parameters is deprecated; maybe ** should be added to the call"
-          request(path, method, *parameters)
+        define_method(method) do |path, **keywords|
+          request(path, method, **keywords)
         end
       end
 
       def request(path, method = :get, request_parameters: {}, data: nil, headers: {}, json_processing: true)
+        auth_handler.renew_session if auth_handler.renewal_needed?
+
         parameters = global_parameters.merge(request_parameters)
 
         parameters[:method] = method
         parameters[:url] = full_url(path)
 
         if json_processing
+          parameters[:headers]["Accept"]       = "application/json"
           parameters[:headers]["Content-Type"] = "application/json"
-          parameters[:payload] = JSON.generate(data)
+          parameters[:payload] = JSON.generate(data) unless data.nil?
         else
           parameters[:payload] = data
         end
 
-        parameters[:headers].merge! headers
+        # Merge override headers + request specific headers
+        parameters[:headers].merge!(override_headers || {})
+        parameters[:headers].merge!(headers)
         parameters.compact!
 
         logger.info format("[REST] => %s", parameters.to_s) if options[:debug_rest]
@@ -88,6 +123,27 @@ module TrainPlugins
         transform_response(response, json_processing)
       end
 
+      # Allow switching generic handlers for an API-specific one.
+      #
+      # New handler needs to be loaded prior and be derived from TrainPlugins::REST::AuthHandler.
+      def switch_auth_handler(new_handler)
+        return if active_auth_handler == new_handler
+
+        logout
+
+        options[:auth_type] = new_handler.to_sym
+        @auth_handler = nil
+
+        login
+      end
+
+      # Return active auth handler.
+      #
+      # @return [Symbol]
+      def active_auth_handler
+        options[:auth_type]
+      end
+
       # Auth Handlers-faced API
 
       def auth_parameters
@@ -146,14 +202,14 @@ module TrainPlugins
       end
 
       def login
-        logger.info format("REST Login via %s authentication handler", auth_type.to_s) if auth_type != :anonymous
+        logger.info format("REST Login via %s authentication handler", auth_type.to_s) unless %i{anonymous basic}.include? auth_type
 
         auth_handler.options = options
         auth_handler.login
       end
 
       def logout
-        logger.info format("REST Logout via %s authentication handler", auth_type.to_s) if auth_type != :anonymous
+        logger.info format("REST Logout via %s authentication handler", auth_type.to_s) unless %i{anonymous basic}.include? auth_type
 
         auth_handler.logout
       end

data/lib/train-rest/transport.rb

@@ -1,3 +1,5 @@
+require "rubygems" unless defined?(Gem)
+
 require "train-rest/connection"
 
 module TrainPlugins
@@ -8,7 +10,7 @@ module TrainPlugins
       option :endpoint, required: true
       option :verify_ssl, default: true
       option :proxy, default: nil
-      option :headers, default: nil
+      option :headers, default: {}
       option :timeout, default: 120
 
       option :auth_type, default: :anonymous
@@ -16,9 +18,32 @@ module TrainPlugins
       option :password, default: nil
       option :debug_rest, default: false
 
+      option :vcr_cassette, default: nil
+      option :vcr_library, default: "vcr"
+      option :vcr_match_on, default: "method uri"
+      option :vcr_record, default: "none"
+      option :vcr_hook_into, default: "webmock"
+
       def connection(_instance_opts = nil)
+        dependency_checks
+
         @connection ||= TrainPlugins::Rest::Connection.new(@options)
       end
+
+      private
+
+      def dependency_checks
+        return unless @options[:vcr_cassette]
+
+        raise Gem::LoadError.new("Install VCR Gem for API playback capability") unless gem_installed?("vcr")
+
+        stubber = @options[:vcr_hook_into]
+        raise Gem::LoadError.new("Install #{stubber} Gem for API playback capability") unless gem_installed?(stubber)
+      end
+
+      def gem_installed?(name)
+        Gem::Specification.find_all_by_name(name).any?
+      end
     end
   end
 end

data/lib/train-rest/version.rb

@@ -1,5 +1,5 @@
 module TrainPlugins
   module Rest
-    VERSION = "0.2.1".freeze
+    VERSION = "0.4.0".freeze
   end
 end

data/lib/train-rest.rb

@@ -7,5 +7,8 @@ require "train-rest/transport"
 require "train-rest/connection"
 
 require "train-rest/auth_handler/anonymous"
+require "train-rest/auth_handler/authtype-apikey"
+require "train-rest/auth_handler/header"
 require "train-rest/auth_handler/basic"
+require "train-rest/auth_handler/bearer"
 require "train-rest/auth_handler/redfish"

data/train-rest.gemspec

@@ -1,4 +1,4 @@
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path("lib", __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "train-rest/version"
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: train-rest
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Thomas Heinen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-24 00:00:00.000000000 Z
+date: 2021-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: train
@@ -120,7 +120,10 @@ files:
 - lib/train-rest.rb
 - lib/train-rest/auth_handler.rb
 - lib/train-rest/auth_handler/anonymous.rb
+- lib/train-rest/auth_handler/authtype-apikey.rb
 - lib/train-rest/auth_handler/basic.rb
+- lib/train-rest/auth_handler/bearer.rb
+- lib/train-rest/auth_handler/header.rb
 - lib/train-rest/auth_handler/redfish.rb
 - lib/train-rest/connection.rb
 - lib/train-rest/transport.rb