pubcontrol 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 067d5122d7e3b2c0330f38dcd1984955d941c62a
-  data.tar.gz: 044dfe46f63a3c7cc1ef0b49554c83d66c8485d7
+  metadata.gz: 2b9cbc03efff0d5b151b06fe26ae636a3bd2b051
+  data.tar.gz: 080f28bded46f251eaf25d259f3628c6142759bc
 SHA512:
-  metadata.gz: a0f628d0a1c540f36c9c05d2cbb4327aff13d3e878e9bbf571bf55352a0198b99b6468a69a9781eaa18003554424b6a04aa8e82f4a3526b7fc96ad98bd8936a0
-  data.tar.gz: 625e8ac7931c3c69995bd3d565da318327b4b1e2b3f3b73355caf769c78049ffa30d7f95bce7a8de57d66f0f588bda591ed4b202676f800c3815bea9c12950ee
+  metadata.gz: 35d714d4f918aadfd8ce7b59be9f66a98e1a1a85344e284e55185db13ea2330063c31af682fcb67b672a4ddc56d19433b3e8b734d0ec4373170551a813d01334
+  data.tar.gz: cb0649c9d4ad939ab10daedcf68783a0f0e1d08f0d977846ae01a55cd8169511ab183d22a18d53ce110a69b8dc72e697fc6f642e77dbd0d2d718985725a5573d

data/lib/format.rb

@@ -5,11 +5,19 @@
 #    :copyright: (c) 2015 by Fanout, Inc.
 #    :license: MIT, see LICENSE for more details.
 
+# The Format class is provided as a base class for all publishing
+# formats that are included in the Item class. Examples of format
+# implementations include JsonObjectFormat and HttpStreamFormat.
 class Format
+
+  # The name of the format which should return a string. Examples
+  # include 'json-object' and 'http-response'
   def name
     raise NotImplementedError
   end
 
+  # The export method which should return a format-specific hash
+  # containing the required format-specific data.
   def export
     raise NotImplementedError
   end

data/lib/item.rb

@@ -7,7 +7,17 @@
 
 require_relative 'format.rb'
 
+# The Item class is a container used to contain one or more format
+# implementation instances where each implementation instance is of a
+# different type of format. An Item instance may not contain multiple
+# implementations of the same type of format. An Item instance is then
+# serialized into a hash that is used for publishing to clients.
 class Item
+
+  # The initialize method can accept either a single Format implementation
+  # instance or an array of Format implementation instances. Optionally
+  # specify an ID and/or previous ID to be sent as part of the message
+  # published to the client.
   def initialize(formats, id=nil, prev_id=nil)
     @id = id
     @prev_id = prev_id
@@ -17,7 +27,18 @@ class Item
     @formats = formats
   end
 
+  # The export method serializes all of the formats, ID, and previous ID
+  # into a hash that is used for publishing to clients. If more than one
+  # instance of the same type of Format implementation was specified then
+  # an error will be raised.
   def export
+    format_types = []
+    @formats.each do |format|
+      if !format_types.index(format.class.name).nil?
+        raise 'more than one instance of ' + format.class.name + ' specified'
+      end
+      format_types.push(format.class.name)
+    end
     out = Hash.new
     if !@id.nil?
       out['id'] = @id

data/lib/pcccbhandler.rb

@@ -5,7 +5,19 @@
 #    :copyright: (c) 2015 by Fanout, Inc.
 #    :license: MIT, see LICENSE for more details.
 
+# The PubControlClientCallbackHandler class is used internally for allowing
+# an async publish call made from the PubControl class to execute a callback
+# method only a single time. A PubControl instance can potentially contain
+# many PubControlClient instances in which case this class tracks the number
+# of successful publishes relative to the total number of PubControlClient
+# instances. A failure to publish in any of the PubControlClient instances
+# will result in a failed result passed to the callback method and the error
+# from the first encountered failure.
 class PubControlClientCallbackHandler
+
+  # The initialize method accepts: a num_calls parameter which is an integer
+  # representing the number of PubControlClient instances, and a callback
+  # method to be executed after all publishing is complete.
   def initialize(num_calls, callback)
     @num_calls = num_calls
     @callback = callback
@@ -13,6 +25,12 @@ class PubControlClientCallbackHandler
     @first_error_message = nil
   end
 
+  # The handler method which is executed by PubControlClient when publishing
+  # is complete. This method tracks the number of publishes performed and 
+  # when all publishes are complete it will call the callback method
+  # originally specified by the consumer. If publishing failures are
+  # encountered only the first error is saved and reported to the callback
+  # method.
   def handler(success, message)
     if !success and @success
       @success = false
@@ -24,6 +42,7 @@ class PubControlClientCallbackHandler
     end
   end
 
+  # This method is used as a workaround to retrieve the handler method symbol.
   # TODO: how to get handler symbol without this method?
   def handler_method_symbol
     return method(:handler)

data/lib/pubcontrol.rb

@@ -10,7 +10,15 @@ require_relative 'item.rb'
 require_relative 'pubcontrolclient.rb'
 require_relative 'pcccbhandler.rb'
 
+# The PubControl class allows a consumer to manage a set of publishing
+# endpoints and to publish to all of those endpoints via a single publish
+# or publish_async method call. A PubControl instance can be configured
+# either using a hash or array of hashes containing configuration information
+# or by manually adding PubControlClient instances.
 class PubControl
+
+  # Initialize with or without a configuration. A configuration can be applied
+  # after initialization via the apply_config method.
   def initialize(config=nil)
     @clients = Array.new
     if !config.nil?
@@ -18,14 +26,21 @@ class PubControl
     end
   end
 
+  # Remove all of the configured PubControlClient instances.
   def remove_all_clients
     @clients = Array.new
   end
 
+  # Add the specified PubControlClient instance.
   def add_client(client)
     @clients.push(client)
   end
 
+  # Apply the specified configuration to this PubControl instance. The
+  # configuration object can either be a hash or an array of hashes where
+  # each hash corresponds to a single PubControlClient instance. Each hash
+  # will be parsed and a PubControlClient will be created either using just
+  # a URI or a URI and JWT authentication information.
   def apply_config(config)
     if !config.is_a?(Array)
       config = [config]
@@ -39,18 +54,29 @@ class PubControl
     end
   end
 
+  # The finish method is a blocking method that ensures that all asynchronous
+  # publishing is complete for all of the configured PubControlClient
+  # instances prior to returning and allowing the consumer to proceed.
   def finish
     @clients.each do |pub|
       pub.finish
     end
   end
 
+  # The synchronous publish method for publishing the specified item to the
+  # specified channel for all of the configured PubControlClient instances.
   def publish(channel, item)
     @clients.each do |pub|
       pub.publish(channel, item)
     end
   end
 
+  # The asynchronous publish method for publishing the specified item to the
+  # specified channel on the configured endpoint. The callback method is
+  # optional and will be passed the publishing results after publishing is
+  # complete. Note that a failure to publish in any of the configured
+  # PubControlClient instances will result in a failure result being passed
+  # to the callback method along with the first encountered error message.
   def publish_async(channel, item, callback=nil)
     cb = nil
     if !callback.nil?

data/lib/pubcontrolclient.rb

@@ -13,9 +13,16 @@ require 'json'
 require 'net/http'
 require_relative 'item.rb'
 
+# The PubControlClient class allows consumers to publish either synchronously 
+# or asynchronously to an endpoint of their choice. The consumer wraps a Format
+# class instance in an Item class instance and passes that to the publish
+# methods. The async publish method has an optional callback parameter that
+# is called after the publishing is complete to notify the consumer of the
+# result.
 class PubControlClient
   attr_accessor :req_queue
 
+  # Initialize this class with a URL representing the publishing endpoint.
   def initialize(uri)
     @uri = uri
     @lock = Mutex.new
@@ -29,6 +36,8 @@ class PubControlClient
     @auth_jwt_key = nil
   end
 
+  # Call this method and pass a username and password to use basic
+  # authentication with the configured endpoint.
   def set_auth_basic(username, password)
     @lock.synchronize do
       @auth_basic_user = username
@@ -36,6 +45,8 @@ class PubControlClient
     end
   end
 
+  # Call this method and pass a claim and key to use JWT authentication
+  # with the configured endpoint.
   def set_auth_jwt(claim, key)
     @lock.synchronize do
       @auth_jwt_claim = claim
@@ -43,6 +54,8 @@ class PubControlClient
     end
   end
 
+  # The synchronous publish method for publishing the specified item to the
+  # specified channel on the configured endpoint.
   def publish(channel, item)
     export = item.export
     export['channel'] = channel
@@ -52,9 +65,13 @@ class PubControlClient
       uri = @uri
       auth = gen_auth_header
     end
-    PubControlClient.pubcall(uri, auth, [export])
+    pubcall(uri, auth, [export])
   end
 
+  # The asynchronous publish method for publishing the specified item to the
+  # specified channel on the configured endpoint. The callback method is
+  # optional and will be passed the publishing results after publishing is
+  # complete.
   def publish_async(channel, item, callback=nil)
     export = item.export
     export['channel'] = channel
@@ -68,6 +85,9 @@ class PubControlClient
     queue_req(['pub', uri, auth, export, callback])
   end
 
+  # The finish method is a blocking method that ensures that all asynchronous
+  # publishing is complete prior to returning and allowing the consumer to 
+  # proceed.
   def finish
     @lock.synchronize do
       if !@thread.nil?
@@ -78,7 +98,17 @@ class PubControlClient
     end
   end
 
-  def self.pubcall(uri, auth_header, items)
+  # A helper method for returning the current UNIX UTC timestamp.
+  def self.timestamp_utcnow
+    return Time.now.utc.to_i
+  end
+
+  private
+
+  # An internal method for preparing the HTTP POST request for publishing
+  # data to the endpoint. This method accepts the URI endpoint, authorization
+  # header, and a list of items to publish.
+  def pubcall(uri, auth_header, items)
     uri = URI(uri + '/publish/')
     content = Hash.new
     content['items'] = items
@@ -89,16 +119,30 @@ class PubControlClient
     end
     request['Content-Type'] = 'application/json'
     use_ssl = uri.scheme == 'https'
-    response = Net::HTTP.start(uri.host, uri.port, use_ssl: use_ssl) do |http|
-      http.request(request)
-    end
+    response = make_http_request(uri, use_ssl, request)
     if !response.kind_of? Net::HTTPSuccess
       raise 'failed to publish: ' + response.class.to_s + ' ' +
           response.message
     end
   end
 
-  def self.pubbatch(reqs)
+  # An internal method for making the specified HTTP request to the
+  # specified URI with an option that determines whether to use
+  # SSL.
+  def make_http_request(uri, use_ssl, request)
+    response = Net::HTTP.start(uri.host, uri.port, use_ssl: use_ssl) do |http|
+      http.request(request)
+    end
+    return response
+  end
+
+  # An internal method for publishing a batch of requests. The requests are
+  # parsed for the URI, authorization header, and each request is published
+  # to the endpoint. After all publishing is complete, each callback
+  # corresponding to each request is called (if a callback was originally
+  # provided for that request) and passed a result indicating whether that
+  # request was successfully published.
+  def pubbatch(reqs)
     raise 'reqs length == 0' unless reqs.length > 0
     uri = reqs[0][0]
     auth_header = reqs[0][1]
@@ -109,7 +153,7 @@ class PubControlClient
       callbacks.push(req[3])
     end
     begin
-      PubControlClient.pubcall(uri, auth_header, items)
+      pubcall(uri, auth_header, items)
       result = [true, '']
     rescue => e
       result = [false, e.message]
@@ -121,12 +165,11 @@ class PubControlClient
     end
   end
 
-  def self.timestamp_utcnow
-    return Time.now.utc.to_i
-  end
-
-  private
-
+  # An internal method that is meant to run as a separate thread and process
+  # asynchronous publishing requests. The method runs continously and
+  # publishes requests in batches containing a maximum of 10 requests. The
+  # method completes and the thread is terminated only when a 'stop' command
+  # is provided in the request queue.
   def pubworker
     quit = false
     while !quit do
@@ -149,15 +192,19 @@ class PubControlClient
       end
       @thread_mutex.unlock
       if reqs.length > 0
-        PubControlClient.pubbatch(reqs)
+        pubbatch(reqs)
       end
     end
   end
 
+  # An internal method used to generate an authorization header. The
+  # authorization header is generated based on whether basic or JWT
+  # authorization information was provided via the publicly accessible
+  # 'set_*_auth' methods defined above.
   def gen_auth_header
     if !@auth_basic_user.nil?
       return 'Basic ' + Base64.encode64(
-          '#{@auth_basic_user}:#{@auth_basic_pass}')
+          "#{@auth_basic_user}:#{@auth_basic_pass}")
     elsif !@auth_jwt_claim.nil?
       if !@auth_jwt_claim.key?('exp')
         claim = @auth_jwt_claim.clone
@@ -171,6 +218,10 @@ class PubControlClient
     end
   end
 
+  # An internal method that ensures that asynchronous publish calls are
+  # properly processed. This method initializes the required class fields,
+  # starts the pubworker worker thread, and is meant to execute only when
+  # the consumer makes an asynchronous publish call.
   def ensure_thread
     if @thread.nil?
       @thread_cond = ConditionVariable.new
@@ -179,6 +230,10 @@ class PubControlClient
     end
   end
 
+  # An internal method for adding an asynchronous publish request to the 
+  # publishing queue. This method will also activate the pubworker worker
+  # thread to make sure that it process any and all requests added to
+  # the queue.
   def queue_req(req)
     @thread_mutex.lock
     @req_queue.push_back(req)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pubcontrol
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Konstantin Bokarius
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-01 00:00:00.000000000 Z
+date: 2015-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: algorithms