train-rest 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45c7cbd2b28a41c2eba5d219545d4ff7e0bfbaf6305f239630352ce463bf8424
-  data.tar.gz: 6e5de06f898f95a2a2c519ac45bae42c797e39840e2aec0c80bb6204d5e69591
+  metadata.gz: 1550899c2f8aad404793b83b1f7700ece96937efc8b78cb1eb7aebb8d6d2a2a2
+  data.tar.gz: b9251734100cc43233504afbe6e8d6fbd11bec1b07a16db7884720e907a164e2
 SHA512:
-  metadata.gz: 48c46e55522807433595d89e5bf414a3d487c9167b7f8fd365a8a64645789fd533fc614a835b319f8d8e6590d907b01c1fbf864ea80fc735d333d2961c065ddf
-  data.tar.gz: 9e24f8c14aa8000541aade240e46d0aaaac67a70a337672f821f9760336da98f482af80337e963ef64c218637f4ed36b059744c8dcc1a2d21cd08d73b5e5154d
+  metadata.gz: 1630381a0f378a7a4a275202fc19a60f71579b99f6b1ae50229c72b67cce2466e5d8b2f4a5b5c3c23f8c1c5c4ccc4817f768fc36cd65c3c8ac9c1b81609b1994
+  data.tar.gz: 02ed2d874ac736d016fc75f24a1c02e8b9209ec5f43cbb9281bf615106a04d53f4d49d26682e84cb7c2b7ab6a949dc2589823a769e9b87aa3c03aa428c50d919

data/README.md

@@ -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`

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

@@ -4,11 +4,13 @@ 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

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.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

@@ -86,6 +86,9 @@ 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, **keywords|
           request(path, method, **keywords)
@@ -93,6 +96,8 @@ module TrainPlugins
       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
@@ -106,7 +111,9 @@ module TrainPlugins
           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]
@@ -116,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

data/lib/train-rest/version.rb

@@ -1,5 +1,5 @@
 module TrainPlugins
   module Rest
-    VERSION = "0.3.2".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"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: train-rest
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Thomas Heinen
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-10-08 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