muxer 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9c099bf28c0a17f50c8da1a7381989a4e25866ec
-  data.tar.gz: af12d1654b31029139cc0826562bcd156454df5b
+  metadata.gz: 5b6bf490074eecb77f38826926df3d98ed41c346
+  data.tar.gz: 6aa3894bd41fd4e01b7ed9dc4873443f8c741196
 SHA512:
-  metadata.gz: 1dc26e64b8369c8369b6c2dec8993ee0c56e49359e7e1b51b7cd57e91c5a8d0df0798e3b0b8bf6d05216521a0296c6c18380a6c4ce9fabc7c1e46a26aa3ef457
-  data.tar.gz: 54edfbb509c55f742aa55eef14626156fc7bd0f44808debdc614a1851344a92c2ddcd14b4bc60927151ba0f5814da8d16e4f2a5ef12f688fc3d32d34015132c4
+  metadata.gz: b816181726162c1b342811f43d8e4f8f23f9772cf69728a7e9621e0f7ecd90efb3adf2ad52c3f5c8039481bac9f3349706c55233c5f23347feab71f8ebb8ba3c
+  data.tar.gz: 3375538c04cd1793dd4364a8def79be7689a241c14ba7dc2265ebe5d83348481c6371c7fe9b354665b7eb635fe014a0173322335c643363426a32286b419db73

data/README.md

@@ -4,6 +4,7 @@
 [![Coverage](https://img.shields.io/codeclimate/coverage/github/ChrisMacNaughton/muxer.svg?style=flat-square)](https://codeclimate.com/github/ChrisMacNaughton/muxer)
 [![Build](https://img.shields.io/travis-ci/ChrisMacNaughton/muxer.svg?style=flat-square)](https://travis-ci.org/ChrisMacNaughton/muxer)
 [![Dependencies](https://img.shields.io/gemnasium/ChrisMacNaughton/muxer.svg?style=flat-square)](https://gemnasium.com/ChrisMacNaughton/muxer)
+[![Docs](https://inch-ci.org/github/ChrisMacNaughton/muxer.svg?branch=master)](http://inch-ci.org/github/ChrisMacNaughton/muxer/branch/master)
 [![Downloads](https://img.shields.io/gem/dtv/muxer.svg?style=flat-square)](https://rubygems.org/gems/muxer)
 [![Tags](https://img.shields.io/github/tag/ChrisMacNaughton/muxer.svg?style=flat-square)](https://github.com/ChrisMacNaughton/muxer/tags)
 [![Releases](https://img.shields.io/github/release/ChrisMacNaughton/muxer.svg?style=flat-square)](https://github.com/ChrisMacNaughton/muxer/releases)

data/lib/muxer.rb

@@ -5,7 +5,32 @@ require 'muxer/version'
 require 'muxer/request'
 require 'muxer/multiplexer'
 
+# Muxer is a parallel request module that allows timeouts for each
+# individual request as well as a global timeout for all requests.
+# In addition to the specific timeouts, Muxer will allow a pending
+# request to continue pending even if its timeout has passed as long
+# as there is still a request waiting that has a longer timeout
+
 module Muxer
+  # Example Usage:
+  #
+  # response = Muxer.execute do |muxer|
+  #   muxer.add_url "http://www.rubydoc.info", timeout: 0.5
+  #   muxer.add_url "https://www.google.com", timeout: 0.25
+  # end
+  #
+  # In the above example, Google's response could continue pending if
+  # rubydoc.info had not yet returned or passed its timeout.
+  #
+  # Returns a hash like:
+  # ```ruby
+  # {
+  #   failed: [],
+  #   completed: []
+  # }
+  # ```
+  #
+  # @return [Hash]
   def self.execute
     multiplexer = Multiplexer.new
 

data/lib/muxer/multiplexer.rb

@@ -1,12 +1,40 @@
 module Muxer
+  # Multiplexer is the core class of Muxer that actually multiplexes
+  # web requests. Multiplexer has a lists of Muxer::Requests that will
+  # be executed and added to the completed or failed response when the
+  # timeouts have been reached.
+  #
+  # @!attribute requests
+  #   @return [Array] Muxer::Requests that are setup in this Multiplexer
+  # @!attribute timeout
+  #   @return [Number] Seconds for the timeout
   class Multiplexer
     attr_reader :requests
     attr_writer :timeout
+    # multiplexer = Multiplexer.new
     def initialize
       @requests = []
       @timeout = nil
     end
 
+    # add_url builds a Request object and passes it to add_request
+    #
+    # m.add_url('https://www.google.com', {timeout: 3}) # gives a 3 second
+    # timeout to a request to https://www.google.com
+    # 
+    # url is merely the target  URL
+    #
+    # `options` is a hash describing the web request
+    # {
+    #   timeout: nil,
+    #   method: :get,
+    #   params: {},
+    #   redirects: nil
+    # }
+    #
+    # @param url [string] The URL for the web request
+    # @param options [{symbol => Object}] The parameters for the web request
+    # @return true
     def add_url(url, options = {})
       options.keys.each do |key|
         options[key.to_sym] = options.delete(key)
@@ -20,12 +48,29 @@ module Muxer
         request.send("#{key}=".to_sym, val) if val
       end
       add_request request
+      true
     end
 
+    # add_request adds a request to Multiplexer
+    #
+    # request = Muxer::Request.new
+    # request.url = 'https://www.google.com'
+    # request.timeout = 3
+    # m.add_request request
+    #
+    # gives a 3 second timeout to a request to https://www.google.com
+    #
+    # @param request [Muxer::Request] the Request to add to the multiplexer
+    # @return true
     def add_request(request)
       requests << request
+      true
     end
 
+    # executes the actual event loop that manages creating, sending,
+    # and processing the finished / timed out web requests
+    #
+    # @return [Hash] Keys are :succeeded, :failed
     def execute
       @responses = {succeeded: [], failed: [], pending: []}
       @start = Time.now

data/lib/muxer/request.rb

@@ -1,4 +1,23 @@
 module Muxer
+  # Muxer::Request is designed to wrap the requests that Muxer uses
+  # to parallelize the web requests and handle timeouts.
+  #
+  # @!attribute url
+  #   @return [String] URL to use
+  # @!attribute timeout
+  #   @return [Number] Seconds for the timeout
+  # @!attribute headers
+  #   @return [Hash] Request headers to use with the request
+  # @!attribute params
+  #   @return [Hash] request parameters
+  # @!attribute redirects
+  #   @return [Integer] How many redirects to follow
+  # @!attribute method
+  #   @return [Symbol] HTTP method to use
+  # @!attribute completed
+  #   @return [Boolean] Is the request completed
+  # @!attribute error
+  #   @return [Boolean] Have we had an error?
   class Request
     attr_accessor :url, :timeout, :headers, :params, :redirects
     attr_reader :method, :completed, :error
@@ -14,12 +33,25 @@ module Muxer
       @error = nil
     end
 
+    # sets the HTTP method of the request as long as the method
+    # is one off the standard http methods. The method can be sent
+    # in as a string or a symbol.
+    # The valid options are:
+    # :get, :post, :head, :options, :put, :delete
+    #
+    # @param method [string, symbol] HTTP Method of the request
+    # @return true
     def method=(method)
       method = method.downcase.to_sym
 
       @method = method if [:get, :post, :head, :options, :put, :delete].include? method
+      true
     end
 
+    # process! executes the web request. It cannot be called from
+    # outside of an EventMachine loop.
+    #
+    # @return self
     def process!
       http = EventMachine::HttpRequest.new(url,
         connect_timeout: timeout,
@@ -35,6 +67,7 @@ module Muxer
       self
     end
 
+    # response is the actual http request's response. 
     def response
       if @request
         @request.response

data/lib/muxer/version.rb

@@ -1,3 +1,3 @@
 module Muxer
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: muxer
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Chris MacNaughton
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-15 00:00:00.000000000 Z
+date: 2015-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: eventmachine