train-rest 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59770f2304519af69df3caaac4f4ef19f964a0a4700952ff6a3b96834867bf13
-  data.tar.gz: 39546783f42569561a1f740c094d0f2adb1a31c49c710b5c9736f172a961306f
+  metadata.gz: 807facd5f597c5fd42ed7044f360601931d8f2ca60cfd79b41969c777e0f631a
+  data.tar.gz: 87a040c1f16c24f1efe30f7252e02f2100717b4cb241e4cce974a61f9dba095d
 SHA512:
-  metadata.gz: c8b2b55eb1723538a552ecbc7ce452a3545bd8ae3e35a82c263f3bbc16d6bfed161d053a6a711b0e34723c4f332e6d7797a40035d6142fc9957618a10ad6dac6
-  data.tar.gz: 967e71707994db3086ea1f71e5d987324c405930ecb4473b9ad886ca59b32d15efb2e4c42f4f4075a607d642a11d78d4fe5e4fe6946468eb348735dd24bde514
+  metadata.gz: d08b4e78394e02f51701ac0927de49e541b38589508d8f28e4327579a296fb074049c706d56d302dd1cf1b03d930727f1b12720303bdceb986f06fb145e27888
+  data.tar.gz: e518d02e65d85cc826c29f19619250246038e8ed329b72a6e3e9825e8078f594bdc7cb1f971d632574b6f766b899d0aee81b01bd5e6dc074444f021b6f858c54

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
@@ -133,7 +176,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 +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/connection.rb

@@ -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"
+
+        # 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

data/lib/train-rest/transport.rb

@@ -1,3 +1,5 @@
+require "rubygems"
+
 require "train-rest/connection"
 
 module TrainPlugins
@@ -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.3.0".freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: train-rest
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Thomas Heinen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-06-24 00:00:00.000000000 Z
+date: 2020-08-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: train