train-rest 0.1.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3aacbd72d0d4bb229c8db525be41ba6b6c8bb77b64a54856583a1857a52e81f
-  data.tar.gz: 8264209bde949d82b767a7f51934a48fbee744778a6982f042faf56ace809732
+  metadata.gz: fd4a52ed234249cf9ae6c2de31b9883061ca31a9d34eb155a5f11e09b461b239
+  data.tar.gz: af4665c3c3637eb4c961f5419af4f145c85a2a60ff4125cfa9bc49800e21dae1
 SHA512:
-  metadata.gz: 9b69087f1538a58e734943553f5cd4c738f47182fd3388d9855231309ed457db020c7a1f78517ff3a84bd8a6a5747be32b7051deb5a0ac7c30089b5fb403e396
-  data.tar.gz: 9c21069c170943fb1e93d42713388c1c4b5e04e143269d6dea8f0ce43ed61bd242c427d723a43cd110c79dba3c31ab2e112325b2b11463029caeb1e1d45e4bdd
+  metadata.gz: db180b1416450c343f28be8d2223d5610b4a7ec75216d43f4343842250a47149bad30f5f2436e336bff1d3504e5cb817916ef44adf95ae9c65663f8cc56af0ef
+  data.tar.gz: 586b34568e078702c3ecabf1f40c6a61bdd4557cf95b953389813563f9d023d5239574d621870f319092e7d33bd436bfc8674a8ca8dc4635d52ef8564f125814

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',
@@ -140,3 +189,58 @@ conn   = train.connection
 # Handles logout as well
 conn.close
 ```
+
+## Use with Redfish, Your Custom Resources and Chef Target Mode
+
+1. Set up a credentials file under `~/.chef/credentials` or `/etc/chef/credentials`:
+
+   ```toml
+   ['10.0.0.1']
+   endpoint = 'https://10.0.0.1/redfish/v1/'
+   username = 'user'
+   password = 'pass'
+   verify_ssl = false
+   auth_type = 'redfish'
+   ```
+
+1. Configure Chef to use the REST transport in `client.rb`:
+
+   ```toml
+   target_mode.protocol = "rest"
+   ```
+
+1. Write your custom resources for REST APIs
+1. Mark them up using the REST methods for target mode:
+
+   ```ruby
+   provides :rest_resource, target_mode: true, platform: 'rest'
+   ```
+
+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]'
+   ```
+
+## 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,19 +57,38 @@ 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
+        OpenStruct.new({
+          name: @detected_os || "rest",
+          release: TrainPlugins::Rest::VERSION,
+          family_hierarchy: %w{rest api},
+          family: "api",
+          platform: "rest",
+          platform_version: 0,
+        })
+      end
+
+      alias os inventory
+
       def platform
-        force_platform!("rest", { endpoint: uri })
+        Train::Platforms.name("rest").in_family("api")
+
+        force_platform!("rest", { release: TrainPlugins::Rest::VERSION })
       end
 
       # User-faced API
 
       %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)
         end
       end
@@ -49,8 +100,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
@@ -100,7 +152,7 @@ module TrainPlugins
       end
 
       def auth_type
-        return options[:auth_type] if options[:auth_type]
+        return options[:auth_type].to_sym if options[:auth_type]
 
         :basic if options[:username] && options[:password]
       end
@@ -123,11 +175,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.1.0".freeze
+    VERSION = "0.3.1".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.1.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Thomas Heinen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-07 00:00:00.000000000 Z
+date: 2021-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: train