train-rest 0.2.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b0cc26cff4431701e6fba113884d8c06a943c16cb231e8a564c464e7ba01cf2
-  data.tar.gz: 78aa236a0c1b8a92480b096e9a40b9c3993be5dbafef907a01144cf630e4267f
+  metadata.gz: 45c7cbd2b28a41c2eba5d219545d4ff7e0bfbaf6305f239630352ce463bf8424
+  data.tar.gz: 6e5de06f898f95a2a2c519ac45bae42c797e39840e2aec0c80bb6204d5e69591
 SHA512:
-  metadata.gz: cb7767fe6dbc98466d9f8450a75f6849d21a8876f8672177db891a91edcdf07a075ab6f59ae98ae24759f827b87ce13ecaaa63934d94d44a8e469716c3e04116
-  data.tar.gz: 5f76c1a724b6b2c453f30240d71cd5717c818b722c0df527664980f94a32802492cfa267bab70bf105a37370e70dd61f0f28783980a2f584f7e9e9797298dce6
+  metadata.gz: 48c46e55522807433595d89e5bf414a3d487c9167b7f8fd365a8a64645789fd533fc614a835b319f8d8e6590d907b01c1fbf864ea80fc735d333d2961c065ddf
+  data.tar.gz: 9e24f8c14aa8000541aade240e46d0aaaac67a70a337672f821f9760336da98f482af80337e963ef64c218637f4ed36b059744c8dcc1a2d21cd08d73b5e5154d

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               |             |
@@ -60,6 +60,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 +80,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
@@ -119,15 +162,21 @@ conn   = train.connection
 conn.close
 ```
 
-Example for logging into a RedFish based system:
+Example for logging into a RedFish based system. Please note that the RedFish
+authentication handler will append `redfish/v1` to the endpoint automatically,
+if it is not present.
+
+Due to this, you can use RedFish systems either with a base URL like in the
+example below or with a full one. Your own code needs to match the style
+you choose.
 
 ```ruby
 require 'train-rest'
 
 # This will immediately do a login and add headers
 train  = Train.create('rest', {
-            endpoint: 'https://api.example.com/v1/',
-            validate_ssl: false,
+            endpoint: 'https://10.20.30.40',
+            verify_ssl: false,
 
             auth_type: :redfish,
             username: 'iloadmin',
@@ -170,5 +219,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/basic.rb

@@ -1,4 +1,6 @@
-require_relative "../auth_handler.rb"
+require "base64" unless defined?(Base64)
+
+require_relative "../auth_handler"
 
 module TrainPlugins
   module Rest
@@ -11,8 +13,9 @@ module TrainPlugins
 
       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/redfish.rb

@@ -1,4 +1,4 @@
-require_relative "../auth_handler.rb"
+require_relative "../auth_handler"
 
 module TrainPlugins
   module Rest
@@ -13,7 +13,7 @@ module TrainPlugins
 
       def login
         response = connection.post(
-          "SessionService/Sessions/",
+          login_url,
           headers: {
             "Content-Type" => "application/json",
             "OData-Version" => "4.0",
@@ -24,10 +24,11 @@ module TrainPlugins
           }
         )
 
-        raise StandardError.new("Authentication with Redfish failed") unless response.code === 201
-
         @session_token = response.headers["x-auth-token"].first
         @logout_url = response.headers["location"].first
+
+      rescue ::RestClient::RequestFailed => err
+        raise StandardError.new("Authentication with Redfish failed: " + err.message)
       end
 
       def logout
@@ -39,6 +40,15 @@ module TrainPlugins
 
         { "X-Auth-Token": @session_token }
       end
+
+      private
+
+      # Prepend the RedFish base, if not a global setting in the connection URL
+      def login_url
+        return "SessionService/Sessions/" if options[:endpoint].include?("redfish/v1")
+
+        "redfish/v1/SessionService/Sessions/"
+      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
@@ -13,9 +13,41 @@ module TrainPlugins
       def initialize(options)
         super(options)
 
+        # Plugin was called with an URI only
+        options[:endpoint] = options[:target].sub("rest://", "https://") unless options[:endpoint]
+
+        # 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
@@ -25,17 +57,19 @@ module TrainPlugins
       end
 
       def uri
-        components = URI.new(options[:endpoint])
+        components = URI(options[:endpoint])
         components.scheme = "rest"
         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: ["", "api"],
+          family_hierarchy: %w{rest api},
           family: "api",
           platform: "rest",
           platform_version: 0,
@@ -53,8 +87,8 @@ module TrainPlugins
       # User-faced API
 
       %i{get post put patch delete head}.each do |method|
-        define_method(method) do |path, *parameters|
-          request(path, method, *parameters)
+        define_method(method) do |path, **keywords|
+          request(path, method, **keywords)
         end
       end
 
@@ -65,8 +99,9 @@ module TrainPlugins
         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
@@ -139,11 +174,15 @@ module TrainPlugins
       end
 
       def login
+        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) unless %i{anonymous basic}.include? auth_type
+
         auth_handler.logout
       end
     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.0".freeze
+    VERSION = "0.3.2".freeze
   end
 end

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.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Thomas Heinen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-12 00:00:00.000000000 Z
+date: 2021-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: train