rflow-components-http 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 79e24768d609cc10c8e73a69b385f0a6adf75796
-  data.tar.gz: 5e4d61fbe3a1d235e2983909fda709765f6f8b0a
+  metadata.gz: 97f9bcce41e96a58c58513b6edb0ea9d02c1f5d4
+  data.tar.gz: 161ef0f6852b256d9270a641e541e56bc1e60bfe
 SHA512:
-  metadata.gz: cb3f4b7aee8590a9eb80f5307930ffe05466d8a869f3a36efadb58a587795be6ef604355395e6ad976a0ed62102136261bfde0116b56d41826c86bb794e117f8
-  data.tar.gz: 787b9b10ec5eafe8bcf1c9277c1784e1f974fa41c2da72bd207ecf3593c844dfba05cf290f3145bb3769ed6c61487e803602b1371795cd0a92e4b80010ececc2
+  metadata.gz: 98a0c1e856216c7332bab76d5f45c05ca07dded321ef20b60e5a3a54b771895c3ab9690a38f35d44bc54282547bcc3ce3bc38480015c2f485111d9c88e1880e9
+  data.tar.gz: 1b35d706f8d764a859c4877641e90dd62dca32c639f6416e528709ca10bb00ad92acf734b1e1397b6027f5b4197004b8976f7dee754ae0a88f35c89cdeefdda4

data/.gitignore

@@ -4,3 +4,5 @@ Gemfile.lock
 pkg/*
 \#*
 .\#*
+doc/
+.yardoc/

data/.ruby-version

@@ -1 +1 @@
-ruby-2.1.2
+ruby-2.3.1

data/.yardopts

@@ -0,0 +1 @@
+--output ./doc --main README.md --files schema/*.avsc lib/**/*.rb - README.md LICENSE

data/Gemfile

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

data/README.md

@@ -48,8 +48,7 @@ run across:
   https://github.com/eventmachine/evma_httpserver/blob/master/ext/http.h#L78
 
 * No support for HTTP chunked transfer encoding, mostly because it
-  does not sent a Content-Length HTTP header.
-
+  does not send a Content-Length HTTP header.
 
 ## Client
 

data/Rakefile

@@ -1,6 +1,6 @@
 require 'bundler'
 require 'rspec/core/rake_task'
-require 'rdoc/task'
+require 'yard'
 Bundler::GemHelper.install_tasks
 
 RSpec::Core::RakeTask.new(:spec) do |t|
@@ -8,8 +8,4 @@ RSpec::Core::RakeTask.new(:spec) do |t|
   t.rspec_opts = '--tty --color'
 end
 
-Rake::RDocTask.new do |rd|
-  rd.main = "README.md"
-  rd.rdoc_files.include("README.md", "lib/**/*.rb")
-  rd.rdoc_dir = File.join('doc', 'html')
-end
+YARD::Rake::YardocTask.new

data/lib/rflow/components/http/extensions.rb

@@ -1,7 +1,110 @@
 class RFlow
+  # @!parse
+  #   # Fake classes in this tree to document the actual message types.
+  #   class Message
+  #     # Fake classes in this tree to document the actual message types.
+  #     class Data
+  #       # HTTP messages.
+  #       module HTTP
+  #         # RFlow message representing an HTTP request.
+  #         class Request
+  #           # @!attribute client_ip
+  #           # The IP the request originated from.
+  #           # @return [String]
+  #
+  #           # @!attribute client_port
+  #           #   The port the request originated from.
+  #           #   @return [Integer]
+  #
+  #           # @!attribute server_ip
+  #           #   The IP the request went to.
+  #           #   @return [String]
+  #
+  #           # @!attribute server_port
+  #           #   The port the request went to.
+  #           #   @return [Integer]
+  #
+  #           # @!attribute method
+  #           #   The HTTP method (POST, GET, etc.).
+  #           #   @return [String]
+  #
+  #           # @!attribute uri
+  #           #   The URI the request was for.
+  #           #   @return [String]
+  #
+  #           # @!attribute query_string
+  #           #   The query string attached to the URI.
+  #           #   @return [String]
+  #
+  #           # @!attribute protocol
+  #           #   The HTTP protocol being used for the request.
+  #           #   @return [String]
+  #
+  #           # @!attribute headers
+  #           #   The HTTP request headers.
+  #           #   @return [Hash]
+  #
+  #           # @!attribute content
+  #           #   The HTTP body content.
+  #           #   @return [String]
+  #
+  #           # Just here to force Yard to create documentation.
+  #           # @!visibility private
+  #           def initialize; end
+  #         end
+  #
+  #         # RFlow message representing an HTTP response.
+  #         class Response
+  #           # @!attribute client_ip
+  #           #   The IP the response is going to.
+  #           #   @return [String]
+  #
+  #           # @!attribute client_port
+  #           #   The port the response is going to.
+  #           #   @return [Integer]
+  #
+  #           # @!attribute server_ip
+  #           #   The IP the response is coming from.
+  #           #   @return [String]
+  #
+  #           # @!attribute server_port
+  #           #   The port the response is coming from.
+  #           #   @return [Integer]
+  #
+  #           # @!attribute protocol
+  #           #   The HTTP protocol being used for the response.
+  #           #   @return [String]
+  #
+  #           # @!attribute status_code
+  #           #   The HTTP response code.
+  #           #   @return [Integer]
+  #
+  #           # @!attribute status_reason_phrase
+  #           #   The server-supplied reason phrase (+OK+, +Moved Temporarily+, etc.) for the {status_code}.
+  #           #   @return [String]
+  #
+  #           # @!attribute headers
+  #           #   The HTTP response headers.
+  #           #   @return [Hash]
+  #
+  #           # @!attribute content
+  #           #   The HTTP response body content.
+  #           #   @return [String]
+  #
+  #           # Just here to force Yard to create documentation.
+  #           # @!visibility private
+  #           def initialize; end
+  #         end
+  #       end
+  #     end
+  #   end
+
+  # Code for RFlow components.
   module Components
     module HTTP
+      # @!visibility private
       module Extensions
+        # @!visibility private
         module IPConnectionExtension
           # Default accessors
           # TODO: validate the stuffs
@@ -16,7 +119,9 @@ class RFlow
         end
 
         # Need to be careful when extending to not clobber data already in data_object
+        # @!visibility private
         module HTTPRequestExtension
+          # @!visibility private
           def self.extended(base_data)
             base_data.data_object ||= {'uri' => '/', 'method' => 'GET', 'protocol' => 'HTTP/1.0', 'headers' => {}, 'content' => ''}
           end
@@ -33,7 +138,9 @@ class RFlow
         end
 
         # Need to be careful when extending to not clobber data already in data_object
+        # @!visibility private
         module HTTPResponseExtension
+          # @!visibility private
           def self.extended(base_data)
             base_data.data_object ||= {'protocol' => 'HTTP/1.0', 'status_code' => 200, 'status_reason_phrase' => 'OK', 'headers' => {}, 'content' => ''}
           end

data/lib/rflow/components/http/server.rb

@@ -5,14 +5,42 @@ require 'rflow'
 class RFlow
   module Components
     module HTTP
+      # Implements a HTTP server based on +eventmachine_httpserver+. Accepts incoming HTTP
+      # connections, marshals the HTTP request into an RFlow message, annotates the message
+      # with a bit of provenance (see below) and then sends the message out its {request_port}.
+      # When a HTTP response message is received on {response_port}, checks the provenance to see
+      # if it matches an underlying TCP/HTTP connection and, if so, creates an actual HTTP
+      # response from the incoming message and sends it to the client.
+      #
+      # The HTTP request message sent from the HTTP server component utilizes the
+      # +RFlow::Message+ provenance feature to annotate a request message with a bit of metadata
+      # that allows subsequent response messages to be matched to their underlying TCP/HTTP
+      # connections. This means that any component that processes HTTP request messages to
+      # generate response messages must copy the provenance from the request message to the
+      # response message.
       class Server < RFlow::Component
+        # @!attribute [r] response_port
+        #   Expects +RFlow::Message+s of type {RFlow::Message::Data::HTTP::Response}
+        #   representing responses being sent back corresponding to previously received
+        #   requests. Each response should have +provenance+ copied from the request it's
+        #   responding to.
+        #   @return [RFlow::Component::InputPort]
         input_port :response_port
+
+        # @!attribute [r] request_port
+        #   Produces +RFlow::Message+s of type {RFlow::Message::Data::HTTP::Request}
+        #   representing requests that have arrived on the socket managed by the component.
+        #   Each features +provenance+ that must be copied to any response message.
+        #   @return [RFlow::Component::OutputPort]
         output_port :request_port
 
+        # @!visibility private
         attr_accessor :port, :listen, :server_signature, :connections, :closed_connections,
           :proxy_real_client_ip_header, :proxy_real_client_port_header,
           :proxy_real_server_ip_header, :proxy_real_server_port_header
 
+        # RFlow-called method at startup.
+        # @return [void]
         def configure!(config)
           @listen = config['listen'] ? config['listen'] : '127.0.0.1'
           @port = config['port'] ? config['port'].to_i : 8000
@@ -24,6 +52,8 @@ class RFlow
           @closed_connections = ActiveSupport::Cache::MemoryStore.new(expires_in: 5.minutes)
         end
 
+        # RFlow-called method at startup.
+        # @return [void]
         def run!
           @server_signature = EM.start_server(@listen, @port, Connection) do |conn|
             conn.server = self
@@ -32,10 +62,13 @@ class RFlow
           end
         end
 
-        # Getting all messages to response_port, which we need to filter for
-        # those that pertain to this component and have active connections.
-        # This is done by inspecting the provenance, specifically the
-        # context attribute that we stored originally
+        # RFlow-called method upon message arrival.
+        #
+        # Filters for messages that pertain to this component and have active connections
+        # by inspecting the provenance, specifically the context attribute that we stored
+        # originally.
+        #
+        # @return [void]
         def process_message(input_port, input_port_key, connection, message)
           return unless message.data_type_name == 'RFlow::Message::Data::HTTP::Response'
           my_events = message.provenance.find_all {|processing_event| processing_event.component_instance_uuid == uuid}
@@ -55,19 +88,23 @@ class RFlow
           end
         end
 
+        # @!visibility private
         class ClosedConnection
           attr_accessor :client_details
+          # @!visibility private
           def initialize(client_details)
             @client_details = client_details
           end
         end
 
+        # @!visibility private
         class Connection < EventMachine::Connection
           include EventMachine::HttpServer
 
           attr_accessor :server
           attr_reader :client_ip, :client_port, :server_ip, :server_port
 
+          # @!visibility private
           def post_init
             @client_port, @client_ip = Socket.unpack_sockaddr_in(get_peername) rescue ["?", "?.?.?.?"]
             @server_port, @server_ip = Socket.unpack_sockaddr_in(get_sockname) rescue ["?", "?.?.?.?"]
@@ -75,6 +112,7 @@ class RFlow
             no_environment_strings
           end
 
+          # @!visibility private
           def client_details
             if @real_client_ip
               "#{client_ip}:#{client_port} (proxied from #{@real_client_ip}:#{@real_client_port})"
@@ -83,6 +121,7 @@ class RFlow
             end
           end
 
+          # @!visibility private
           def server_details
             if @real_server_ip
               "#{server_ip}:#{server_port} (proxied as #{@real_server_ip}:#{@real_server_port})"
@@ -91,11 +130,13 @@ class RFlow
             end
           end
 
+          # @!visibility private
           def receive_data(data)
             RFlow.logger.debug { "#{server.name}: Received #{data.bytesize} bytes of data from #{client_details} to #{server_details}" }
             super
           end
 
+          # @!visibility private
           def process_http_request
             RFlow.logger.debug { "#{server.name}: Received HTTP request from #{client_details} to #{server_details} for #{@http_request_uri}" }
 
@@ -135,6 +176,7 @@ class RFlow
             RFlow.logger.error "#{server.name}: Error processing HTTP request from #{client_details} to #{server_details} for #{@http_request_uri}: #{e.class.name}: #{e.message}, because: #{e.backtrace.inspect}"
           end
 
+          # @!visibility private
           def send_http_response(response_message = nil)
             resp = EventMachine::DelegatedHttpResponse.new(self).tap do |r|
               # Default values
@@ -160,6 +202,7 @@ class RFlow
 
           # Called when a connection is torn down for whatever reason.
           # Remove this connection from the server's list
+          # @!visibility private
           def unbind(reason = nil)
             RFlow.logger.debug { "#{server.name}: Disconnected from HTTP client #{client_details}#{reason.nil? ? '' : " due to '#{reason}'"}" }
             server.closed_connections.write(signature.to_s, ClosedConnection.new(client_details))

data/lib/rflow/components/http/version.rb

@@ -1,7 +1,8 @@
 class RFlow
   module Components
     module HTTP
-      VERSION = "1.1.0"
+      # The gem version.
+      VERSION = "1.1.1"
     end
   end
 end

data/lib/rflow/components/http.rb

@@ -1,12 +1,17 @@
 require 'rflow/components/http/extensions'
 require 'rflow/components/http/server'
 
+# RFlow classes.
 class RFlow
+  # RFlow component classes.
   module Components
+    # HTTP RFlow component classes.
     module HTTP
       # Load the schemas
+      # @!visibility private
       SCHEMA_DIRECTORY = ::File.expand_path(::File.join(::File.dirname(__FILE__), '..', '..', '..', 'schema'))
 
+      # @!visibility private
       SCHEMA_FILES = {
         'http_response.avsc' => 'RFlow::Message::Data::HTTP::Response',
         'http_request.avsc'  => 'RFlow::Message::Data::HTTP::Request',

data/rflow-components-http.gemspec

@@ -22,9 +22,10 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_dependency 'rflow', '~> 1.0'
-  s.add_dependency 'eventmachine_httpserver_update', '~> 0.2.1'
+  s.add_dependency 'eventmachine_httpserver_update', '~> 0.2', '>= 0.2.1'
 
   s.add_development_dependency 'rspec', '~> 3.0'
   s.add_development_dependency 'rspec-collection_matchers', '~> 1.0'
   s.add_development_dependency 'rake', '>= 10.3'
+  s.add_development_dependency 'yard', '~> 0.9'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rflow-components-http
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Michael L. Artz
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-09 00:00:00.000000000 Z
+date: 2017-10-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rflow
@@ -29,6 +29,9 @@ dependencies:
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.2.1
   type: :runtime
@@ -36,6 +39,9 @@ dependencies:
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.2.1
 - !ruby/object:Gem::Dependency
@@ -80,6 +86,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '10.3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  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'
 description: HTTP client and server components for the RFlow FBP framework.  Also
   includes the necessary HTTP::Request and HTTP::Response message types
 email:
@@ -93,6 +113,7 @@ files:
 - ".ruby-gemset"
 - ".ruby-version"
 - ".travis.yml"
+- ".yardopts"
 - Gemfile
 - LICENSE
 - README.md
@@ -129,7 +150,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: rflow-components-http
-rubygems_version: 2.2.2
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: HTTP client and server components for the RFlow FBP framework