raptor-io 0.0.1

data/lib/raptor-io/protocol/http/request/manipulator.rb

@@ -0,0 +1,117 @@
+module RaptorIO
+module Protocol::HTTP
+
+class Request
+
+# Base manipulator class, all manipulator components should inherit from it.
+#
+# @author Tasos Laskos <tasos_laskos@rapid7.com>
+# @abstract
+class Manipulator
+
+  #
+  # {HTTP::Request::Manipulator} error namespace.
+  #
+  # All {HTTP::Request::Manipulator} errors inherit from and live under it.
+  #
+  # @author Tasos "Zapotek" Laskos
+  #
+  class Error < Request::Error
+
+    # Indicates invalid options for a manipulator.
+    #
+    # @author Tasos Laskos
+    class InvalidOptions < Error
+    end
+
+  end
+
+  # @return [HTTP::Client]  Current HTTP client instance.
+  attr_reader :client
+
+  # @return [HTTP::Request]  Request to manipulate.
+  attr_reader :request
+
+  # @return [Hash]  Manipulator options.
+  attr_reader :options
+
+  # @param  [HTTP::Client]  client
+  #   HTTP client which will handle the request.
+  # @param  [HTTP::Request]  request
+  #   Request to process.
+  def initialize( client, request, options = {} )
+    @client  = client
+    @request = request
+    @options = options
+  end
+
+  # Delivers the manipulator's payload.
+  # @abstract
+  def run
+  end
+
+  # Delegates the work to another manipulator.
+  #
+  # @param  [Symbol]  manipulator Manipulator to run.
+  # @param  [Hash]  opts  Manipulator options.
+  def delegate( manipulator, opts = options )
+    Request::Manipulators.process( manipulator, client, request, opts )
+  end
+
+  # @return [Hash]  Persistent storage -- per {HTTP::Client} instance.
+  def datastore
+    client.datastore[shortname]
+  end
+
+  # @return [String]  Shortname of `self`.
+  def shortname
+    self.class.shortname
+  end
+
+  # @return [Hash{Symbol=>Array<String>}]
+  #   Option names keys for and error messages for values.
+  def validate_options
+    self.class.validate_options!( options, client )
+  end
+
+  class <<self
+
+    # @return [Hash{Symbol=>Array<String>}]
+    #   Option names keys for and error messages for values.
+    def validate_options( &block )
+      fail ArgumentError, 'Missing block.' if !block_given?
+      @validator = block
+    end
+
+    #
+    # @param  [Hash]  options Manipulator options.
+    # @param  [HTTP::Client]  client  Applicable client.
+    #
+    # @return [Hash{Symbol=>Array<String>}]
+    #   Option names keys for and error messages for values.
+    #
+    # @abstract
+    def validate_options!( options, client )
+      @validator ? @validator.call( options, client ) : {}
+    end
+
+    # @return [String]  Shortname of `self`.
+    def shortname
+      @shortname ||= Request::Manipulators.class_to_name( self )
+    end
+
+    # Registers manipulators which inherit from this class.
+    #
+    # @see Request::Manipulators#register
+    def inherited( manipulator_klass )
+      Request::Manipulators.register(
+          Request::Manipulators.path_to_name( caller.first.split( ':' ).first ),
+          manipulator_klass
+      )
+    end
+  end
+
+end
+end
+end
+end

data/lib/raptor-io/protocol/http/request/manipulators.rb

@@ -0,0 +1,217 @@
+module RaptorIO
+module Protocol::HTTP
+
+class Request
+
+require_relative 'manipulator'
+
+# Namespace holding all Request manipulators and providing some helper methods
+# for management.
+#
+# @author Tasos Laskos <tasos_laskos@rapid7.com>
+module Manipulators
+
+  class <<self
+    include Enumerable
+
+    # @return [String]  Directory of the manipulators' repository.
+    attr_reader :library
+
+    # @param  [String]  manipulator
+    #   Manipulator to run -- will be loaded if needed.
+    # @param  [HTTP::Client]  client
+    #   Applicable client.
+    # @param  [HTTP::Request]  request
+    #   Request to process.
+    # @param  [Hash]  options
+    #   Manipulator options.
+    def process( manipulator, client, request, options = {} )
+      load( manipulator ).new( client, request, options ).run
+    end
+
+    # Performs batch validation of manipulator options.
+    #
+    # @param  [Hash{String=>Hash}]  manipulators
+    #   Manipulators for keys and their options as values.
+    # @param  [HTTP::Client]  client
+    #   Applicable client.
+    #
+    # @return [Hash{String=>Hash}]
+    #   Manipulators for keys and error hashes as values.
+    #
+    def validate_batch_options( manipulators, client )
+      errors = {}
+      manipulators.each do |manipulator, options|
+        errors[manipulator] =
+            validate_options( manipulator, options, client )
+      end
+      errors.reject { |_, errs| errs.empty? }
+    end
+
+    # Same as {.validate_batch_options} but raises exception on errors.
+    def validate_batch_options!( manipulators, client )
+      errors = validate_batch_options( manipulators, client )
+      if errors.any?
+        fail Request::Manipulator::Error::InvalidOptions, errors.to_s
+      end
+      nil
+    end
+
+    # @param  [String]  manipulator
+    # @param  [Hash]  options Manipulator options.
+    # @param  [HTTP::Client]  client  Applicable client.
+    #
+    # @return [Hash{Symbol=>Array<String>}]
+    #   Option names keys for and error messages for values.
+    def validate_options( manipulator, options, client )
+      load( manipulator ).validate_options!( options, client )
+    end
+
+    # @param  [String]  directory Directory including manipulators.
+    def library=( directory )
+      @library = File.expand_path( directory ) + '/'
+    end
+
+    # @return [Array<String>] Paths of all manipulators.
+    def paths
+      Dir.glob( "#{library}**/*.rb" )
+    end
+
+    # @return [Array<Symbol>] Names of all manipulators.
+    def available
+      paths.map { |path| path_to_name path }
+    end
+
+    # @param  [Symbol]  manipulator
+    #   Loads a manipulator by name.
+    #
+    # @return [Class] Loaded manipulator.
+    def load( manipulator )
+      manipulator = normalize_name( manipulator )
+      return @manipulators[manipulator] if @manipulators.include? manipulator
+
+      Kernel.load name_to_path( manipulator )
+      @manipulators[manipulator]
+    end
+
+    # Loads all manipulators.
+    #
+    # @return [Hash]  All manipulators.
+    def load_all
+      paths.each { |path| load path_to_name( path ) }
+      loaded
+    end
+
+    # @param  [Symbol]  manipulator
+    #   Unloads a manipulator by name.
+    #
+    # @return [Bool]
+    #   `true` if the manipulator was unloaded successfully, `false` if no
+    #   matching one was found.
+    def unload( manipulator )
+      klass = @manipulators.delete( normalize_name( manipulator ) )
+      return false if !klass
+
+      container = self
+      klass.to_s.gsub( "#{self}::", '' ).split( '::' )[0...-1].each do |c|
+        container = container.const_get( c.to_sym )
+      end
+
+      container.instance_eval do
+        remove_const klass.to_s.split( ':' ).last.to_sym
+      end
+
+      # Remove the container namespaces themselves if they're now empty.
+      container = self
+      klass.to_s.gsub( "#{self}::", '' ).split( '::' )[0...-1].each do |c|
+        container = container.const_get( c.to_sym )
+        if container != self && container.constants.empty?
+          remove_const container.to_s.split( ':' ).last.to_sym
+        end
+      end
+
+      true
+    end
+
+    # Unloads all manipulators.
+    def unload_all
+      @manipulators.keys.each { |manipulator| unload manipulator }
+      nil
+    end
+
+    # @param    [Block] block
+    #   Block to be passed each manipulator name=>class.
+    # @return   [Enumerator, Manipulators]
+    #   `Enumerator` if no `block` is given, `self` otherwise.
+    def each( &block )
+      return enum_for( __method__ ) if !block_given?
+      @manipulators.each( &block )
+      self
+    end
+
+    # @return [Hash]  All manipulators as a frozen hash.
+    def loaded
+      @manipulators.dup.freeze
+    end
+
+    # Registers a manipulator.
+    #
+    # @param  [Symbol]  name
+    # @param  [Base]  klass
+    #
+    # @return [Manipulator] `self`
+    #
+    # @private
+    def register( name, klass )
+      @manipulators[normalize_name( name )] = klass
+      self
+    end
+
+    # Resets the manipulators by unloading all and settings the {#library} to
+    # its default setting.
+    def reset
+      unload_all if @manipulators
+
+      @library      = File.expand_path( File.dirname( __FILE__ ) + '/manipulators' ) + '/'
+      @manipulators = {}
+    end
+
+    # @param  [String]  name  Manipulator name.
+    # @return [Bool]  `true` if the given manipulator exists, `false` otherwise.
+    def exist?( name )
+      File.exist? name_to_path( name )
+    end
+
+    # @param  [String]  path  FS path to a manipulator.
+    # @return [String]  Manipulator shortname.
+    def path_to_name( path )
+      normalize_name path.gsub( library, '' ).gsub( /(.+)\.rb$/, '\1' )
+    end
+
+    # @param  [Class]  klass  Manipulator class.
+    # @return [String, nil]
+    #   Manipulator shortname, `nil` if the manipulator isn't loaded.
+    def class_to_name( klass )
+      @manipulators.select { |name, k| return name if k == klass }
+      nil
+    end
+
+    # @param  [String]  name  Manipulator shortname.
+    # @return [String]  Manipulator FS path.
+    def name_to_path( name )
+      File.expand_path "#{library}/#{name}.rb"
+    end
+
+    # @param  [String, Symbol]  name  Manipulator name.
+    # @return [String]  Manipulator name.
+    def normalize_name( name )
+      name.to_s
+    end
+  end
+
+  reset
+
+end
+end
+end
+end

data/lib/raptor-io/protocol/http/request/manipulators/authenticator.rb

@@ -0,0 +1,110 @@
+module RaptorIO
+module Protocol::HTTP
+class Request
+
+module Manipulators
+
+# Namespace for all authenticator manipulators.
+module Authenticators
+end
+
+#
+# Implements automatic HTTP authentication.
+#
+# @author Tasos Laskos
+#
+class Authenticator < Manipulator
+
+  validate_options do |options, _|
+    errors = {}
+    next errors if options[:skip]
+
+    [:username, :password].each do |option|
+      errors[option] = [ "Can't be blank." ] if options[option].to_s.empty?
+    end
+
+    errors
+  end
+
+  def run
+    datastore[:tries] ||= 0
+    return if skip?
+
+    callbacks = request.callbacks.dup
+    request.clear_callbacks
+
+    # We need to block until authentication is complete, that's why we requeue
+    # and run.
+
+    requeue
+    request.on_complete do |response|
+      auth_type = type( response )
+
+      if !failed? && response.code == 401 && supported?( auth_type )
+        retry_with_auth( auth_type, response )
+      else
+        request.callbacks = callbacks
+        request.handle_response response
+        request.clear_callbacks
+      end
+    end
+    client.run
+  end
+
+  private
+
+  # @note Set by one of the authenticators, not `self`.
+  # @return [Bool]  `true` if authentication failed, `false` otherwise.
+  def failed?
+    !!datastore[:failed]
+  end
+
+  # Retries the request with authentication.
+  #
+  # @param  [Symbol]  type  Authenticator to use.
+  # @param  [RaptorIO::Protocol::HTTP::Response]  response
+  #   Response signaling the need to authenticate.
+  def retry_with_auth( type, response )
+    datastore[:tries] += 1
+
+    remove_client_authenticators if ![:ntlm, :negotiate].include?( type )
+    client.manipulators.merge!({
+      "authenticators/#{type}" => options.merge( response: response )
+    })
+    requeue
+  end
+
+  # Requeues the request after the proper authenticator has been enabled.
+  def requeue
+    client.queue( request, shortname => { skip: true } )
+  end
+
+  # @param  [RaptorIO::Protocol::HTTP::Response]  response
+  #   Response signaling the need to authenticate.
+  # @return [Symbol]  Authentication type.
+  def type( response )
+    response.headers['www-authenticate'].to_s.split( ' ' ).first.to_s.downcase.to_s.to_sym
+  end
+
+  def skip?
+    failed? || !!options[:skip]
+  end
+
+  # @param  [Symbol]  type  Authentication type to check.
+  # @return [Bool]
+  #   `true` if the authentication `type` is supported, `false` otherwise.
+  def supported?( type )
+    Request::Manipulators.exist? "authenticators/#{type}"
+  end
+
+  # Removes all enabled authenticators.
+  def remove_client_authenticators
+    client.manipulators.reject!{ |k, _| k.start_with? 'authenticator' }
+  end
+
+end
+
+end
+end
+end
+end

data/lib/raptor-io/protocol/http/request/manipulators/authenticators/basic.rb

@@ -0,0 +1,36 @@
+module RaptorIO
+module Protocol::HTTP
+class Request
+
+module Manipulators
+module Authenticators
+
+#
+# Implements HTTP Basic authentication.
+#
+# @author Tasos Laskos
+#
+class Basic < Manipulator
+
+  def run
+    request.headers['Authorization'] =
+        "Basic #{Base64.encode64("#{username}:#{password}").chomp}"
+  end
+
+  private
+
+  def username
+    options[:username]
+  end
+
+  def password
+    options[:password]
+  end
+
+end
+
+end
+end
+end
+end
+end