train-rest 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f3aacbd72d0d4bb229c8db525be41ba6b6c8bb77b64a54856583a1857a52e81f
+  data.tar.gz: 8264209bde949d82b767a7f51934a48fbee744778a6982f042faf56ace809732
+SHA512:
+  metadata.gz: 9b69087f1538a58e734943553f5cd4c738f47182fd3388d9855231309ed457db020c7a1f78517ff3a84bd8a6a5747be32b7051deb5a0ac7c30089b5fb403e396
+  data.tar.gz: 9c21069c170943fb1e93d42713388c1c4b5e04e143269d6dea8f0ce43ed61bd242c427d723a43cd110c79dba3c31ab2e112325b2b11463029caeb1e1d45e4bdd

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,142 @@
+# train-rest - Train transport
+
+Provides a transport to communicate easily with RESTful APIs.
+
+## Requirements
+
+- Gem `rest-client` in Version 2.1
+
+## Installation
+
+You will have to build this gem yourself to install it as it is not yet on
+Rubygems.Org. For this there is a rake task which makes this a one-liner:
+
+```bash
+rake install:local
+```
+
+## Transport parameters
+
+| Option               | Explanation                             | Default     |
+| -------------------- | --------------------------------------- | ----------- |
+| `endpoint`           | Endpoint of the REST API                | _required_  |
+| `validate_ssl`       | Check certificate and chain             | true        |
+| `auth_type`          | Authentication type                     | `anonymous` |
+| `debug_rest`         | Enable debugging of HTTP traffic        | false       |
+| `logger`             | Alternative logging class               |             |
+
+## Authenticators
+
+### Anonymous
+
+Identifier: `auth_type: :anonymous`
+
+No actions for authentication, logging in/out or session handing are made. This
+assumes a public API.
+
+### Basic Authentication
+
+Identifier: `auth_type: :basic`
+
+| Option               | Explanation                             | Default     |
+| -------------------- | --------------------------------------- | ----------- |
+| `username`           | Username for `basic` authentication     | _required_  |
+| `password`           | Password for `basic` authentication     | _required_  |
+
+If you supply a `username` and a `password`, authentication will automatically
+switch to `basic`.
+
+### Redfish
+
+Identifier: `auth_type: :redfish`
+
+| Option               | Explanation                             | Default     |
+| -------------------- | --------------------------------------- | ----------- |
+| `username`           | Username for `redfish` authentication   | _required_  |
+| `password`           | Password for `redfish` authentication   | _required_  |
+
+For access to integrated management controllers on standardized server hardware.
+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.
+
+## Debugging and use in Chef
+
+You can activate debugging by setting the `debug_rest` flag to `true'. Please
+note, that this will also log any confidential parts of HTTP traffic as well.
+
+For better integration into Chef custom resources, all REST debug output will
+be printed on `info` level. This allows debugging Chef resources without
+crawling through all other debug output:
+
+```ruby
+train  = Train.create('rest', {
+            endpoint:   'https://api.example.com/v1/',
+            debug_rest: true,
+            logger:     Chef::Log
+         })
+```
+
+## Example use
+
+```ruby
+require 'train-rest'
+
+train  = Train.create('rest', {
+            endpoint: 'https://api.example.com/v1/',
+
+            logger:   Logger.new($stdout, level: :info)
+         })
+conn   = train.connection
+
+# Get some hypothetical data
+data   = conn.get('device/1/settings')
+
+# Modify + Patch
+data['disabled'] = false
+conn.patch('device/1/settings', data)
+
+conn.close
+```
+
+Example for basic authentication:
+
+```ruby
+require 'train-rest'
+
+# This will immediately do a login and add headers
+train  = Train.create('rest', {
+            endpoint: 'https://api.example.com/v1/',
+
+            auth_type: :basic,
+            username: 'admin',
+            password: '*********'
+         })
+conn   = train.connection
+
+# ... do work, each request will resend Basic authentication headers ...
+
+conn.close
+```
+
+Example for logging into a RedFish based system:
+
+```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,
+
+            auth_type: :redfish,
+            username: 'iloadmin',
+            password: '*********'
+         })
+conn   = train.connection
+
+# ... do work ...
+
+# Handles logout as well
+conn.close
+```

data/lib/train-rest.rb

@@ -0,0 +1,11 @@
+libdir = File.dirname(__FILE__)
+$LOAD_PATH.unshift(libdir) unless $LOAD_PATH.include?(libdir)
+
+require "train-rest/version"
+
+require "train-rest/transport"
+require "train-rest/connection"
+
+require "train-rest/auth_handler/anonymous"
+require "train-rest/auth_handler/basic"
+require "train-rest/auth_handler/redfish"

data/lib/train-rest/auth_handler.rb

@@ -0,0 +1,61 @@
+module TrainPlugins
+  module Rest
+    # Class to derive authentication handlers from.
+    class AuthHandler
+      attr_accessor :connection
+      attr_reader :options
+
+      def initialize(connection = nil)
+        @connection = connection
+      end
+
+      # Return name of handler
+      #
+      # @return [String]
+      def self.name
+        self.to_s.split("::").last.downcase
+      end
+
+      # Store authenticator options and trigger validation
+      #
+      # @param [Hash] All transport options
+      def options=(options)
+        @options = options
+
+        check_options
+      end
+
+      # Verify transport options
+      # @raise [ArgumentError] if options are not as needed
+      def check_options; end
+
+      # Handle Login
+      def login; end
+
+      # Handle Logout
+      def logout; end
+
+      # Headers added to the rest-client call
+      #
+      # @return [Hash]
+      def auth_headers
+        {}
+      end
+
+      # These will get added to the rest-client call.
+      #
+      # @return [Hash]
+      # @see https://www.rubydoc.info/gems/rest-client/RestClient/Request
+      def auth_parameters
+        { headers: auth_headers }
+      end
+
+      # List authentication handlers
+      #
+      # @return [Array] Classes derived from `AuthHandler`
+      def self.descendants
+        ObjectSpace.each_object(Class).select { |klass| klass < self }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,8 @@
+require_relative "../auth_handler.rb"
+
+module TrainPlugins
+  module Rest
+    # No Authentication
+    class Anonymous < AuthHandler; end
+  end
+end

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

@@ -0,0 +1,20 @@
+require_relative "../auth_handler.rb"
+
+module TrainPlugins
+  module Rest
+    # Authentication via HTTP Basic Authentication
+    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]
+      end
+
+      def auth_parameters
+        {
+          user: options[:username],
+          password: options[:password],
+        }
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+require_relative "../auth_handler.rb"
+
+module TrainPlugins
+  module Rest
+    # Authentication and Session handling for the Redfish 1.0 API
+    #
+    # @see http://www.dmtf.org/standards/redfish
+    class Redfish < AuthHandler
+      def check_options
+        raise ArgumentError.new("Need username for Redfish authentication") unless options[:username]
+        raise ArgumentError.new("Need password for Redfish authentication") unless options[:password]
+      end
+
+      def login
+        response = connection.post(
+          "SessionService/Sessions/",
+          headers: {
+            "Content-Type" => "application/json",
+            "OData-Version" => "4.0",
+          },
+          data: {
+            "UserName" => options[:username],
+            "Password" => options[:password],
+          }
+        )
+
+        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
+      end
+
+      def logout
+        connection.delete(@logout_url)
+      end
+
+      def auth_headers
+        return {} unless @session_token
+
+        { "X-Auth-Token": @session_token }
+      end
+    end
+  end
+end

data/lib/train-rest/connection.rb

@@ -0,0 +1,135 @@
+require "json"
+require "ostruct"
+require "uri"
+
+require "rest-client"
+require "train"
+
+module TrainPlugins
+  module Rest
+    class Connection < Train::Plugins::Transport::BaseConnection
+      attr_reader :options
+
+      def initialize(options)
+        super(options)
+
+        connect
+      end
+
+      def connect
+        login if auth_handlers.include? auth_type
+      end
+
+      def close
+        logout if auth_handlers.include? auth_type
+      end
+
+      def uri
+        components = URI.new(options[:endpoint])
+        components.scheme = "rest"
+        components.to_s
+      end
+
+      def platform
+        force_platform!("rest", { endpoint: uri })
+      end
+
+      # User-faced API
+
+      %i{get post put patch delete head}.each do |method|
+        define_method(method) do |path, *parameters|
+          request(path, method, *parameters)
+        end
+      end
+
+      def request(path, method = :get, request_parameters: {}, data: nil, headers: {}, json_processing: true)
+        parameters = global_parameters.merge(request_parameters)
+
+        parameters[:method] = method
+        parameters[:url] = full_url(path)
+
+        if json_processing
+          parameters[:headers]["Content-Type"] = "application/json"
+          parameters[:payload] = JSON.generate(data)
+        else
+          parameters[:payload] = data
+        end
+
+        parameters[:headers].merge! headers
+        parameters.compact!
+
+        logger.info format("[REST] => %s", parameters.to_s) if options[:debug_rest]
+        response = RestClient::Request.execute(parameters)
+
+        logger.info format("[REST] <= %s", response.to_s) if options[:debug_rest]
+        transform_response(response, json_processing)
+      end
+
+      # Auth Handlers-faced API
+
+      def auth_parameters
+        auth_handler.auth_parameters
+      end
+
+      private
+
+      def global_parameters
+        params = {
+          verify_ssl: options[:verify_ssl] ? OpenSSL::SSL::VERIFY_PEER : OpenSSL::SSL::VERIFY_NONE,
+          timeout: options[:timeout],
+          proxy: options[:proxy],
+          headers: options[:headers],
+        }
+
+        params.merge!(auth_parameters)
+
+        params
+      end
+
+      def full_url(path)
+        (URI(@options[:endpoint]) + path).to_s
+      end
+
+      def transform_response(response, json_processing = true)
+        OpenStruct.new(
+          code: response.code,
+          headers: response.raw_headers,
+          data: json_processing ? JSON.load(response.to_s) : response.to_s,
+          duration: response.duration
+        )
+      end
+
+      def auth_type
+        return options[:auth_type] if options[:auth_type]
+
+        :basic if options[:username] && options[:password]
+      end
+
+      attr_writer :auth_handler
+
+      def auth_handler_classes
+        AuthHandler.descendants
+      end
+
+      def auth_handlers
+        auth_handler_classes.map { |handler| handler.name.to_sym }
+      end
+
+      def auth_handler
+        desired_handler = auth_handler_classes.detect { |handler| handler.name == auth_type.to_s }
+        raise NameError.new(format("Authentication handler %s not found", auth_type.to_s)) unless desired_handler
+
+        @auth_handler ||= desired_handler.new(self)
+      end
+
+      def login
+        auth_handler.options = options
+        auth_handler.login
+      end
+
+      def logout
+        auth_handler.logout
+      end
+    end
+  end
+end

data/lib/train-rest/transport.rb

@@ -0,0 +1,24 @@
+require "train-rest/connection"
+
+module TrainPlugins
+  module Rest
+    class Transport < Train.plugin(1)
+      name "rest"
+
+      option :endpoint, required: true
+      option :verify_ssl, default: true
+      option :proxy, default: nil
+      option :headers, default: nil
+      option :timeout, default: 120
+
+      option :auth_type, default: :anonymous
+      option :username, default: nil
+      option :password, default: nil
+      option :debug_rest, default: false
+
+      def connection(_instance_opts = nil)
+        @connection ||= TrainPlugins::Rest::Connection.new(@options)
+      end
+    end
+  end
+end

data/lib/train-rest/version.rb

@@ -0,0 +1,5 @@
+module TrainPlugins
+  module Rest
+    VERSION = "0.1.0".freeze
+  end
+end

data/train-rest.gemspec

@@ -0,0 +1,30 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "train-rest/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "train-rest"
+  spec.version       = TrainPlugins::Rest::VERSION
+  spec.authors       = ["Thomas Heinen"]
+  spec.email         = ["theinen@tecracer.de"]
+  spec.summary       = "Train transport for REST"
+  spec.description   = "Provides a transport to communicate easily with RESTful APIs."
+  spec.homepage      = "https://github.com/sgre-chef/train-rest"
+  spec.license       = "Apache-2.0"
+
+  spec.files = %w{
+    README.md train-rest.gemspec Gemfile
+  } + Dir.glob(
+    "lib/**/*", File::FNM_DOTMATCH
+  ).reject { |f| File.directory?(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "train", "~> 3.0"
+  spec.add_dependency "rest-client", "~> 2.1"
+
+  spec.add_development_dependency "bump", "~> 0.9"
+  spec.add_development_dependency "chefstyle", "~> 0.14"
+  spec.add_development_dependency "guard", "~> 2.16"
+  spec.add_development_dependency "mdl", "~> 0.9"
+  spec.add_development_dependency "rake", "~> 13.0"
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: train-rest
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Thomas Heinen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-05-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: train
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rest-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.1'
+- !ruby/object:Gem::Dependency
+  name: bump
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: chefstyle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+- !ruby/object:Gem::Dependency
+  name: guard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.16'
+- !ruby/object:Gem::Dependency
+  name: mdl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Provides a transport to communicate easily with RESTful APIs.
+email:
+- theinen@tecracer.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- lib/train-rest.rb
+- lib/train-rest/auth_handler.rb
+- lib/train-rest/auth_handler/anonymous.rb
+- lib/train-rest/auth_handler/basic.rb
+- lib/train-rest/auth_handler/redfish.rb
+- lib/train-rest/connection.rb
+- lib/train-rest/transport.rb
+- lib/train-rest/version.rb
+- train-rest.gemspec
+homepage: https://github.com/sgre-chef/train-rest
+licenses:
+- Apache-2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Train transport for REST
+test_files: []