gripcontrol 1.2.1 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cae2f828396f43ecec0430ca4dec5ed6bb3781a6
-  data.tar.gz: b232a252079b157d246c9d33f409511a1d6d3bc4
+  metadata.gz: 58499f9d93b611ba458fbdeab01a6e124f22d944
+  data.tar.gz: a56f77a99c922f9399d4b926eccea80d7e108305
 SHA512:
-  metadata.gz: 82727271f42df23c2758106b287364d0522afa37eb8697dce5d9da997ee311fcda9b18d06192618be998ab25962ead3fd499eb4ecc930a017217ba4dbc02cdb5
-  data.tar.gz: 5f83386f017dd97bc2337176c0b596d3ee201dc5721ca8a7ebebfdd2956aa9dfa234b440fe45152ad12dbc410bc099c05759e36f1d0fab1937568f5d0ee5282b
+  metadata.gz: ee47b91038d0645aec69a8b41123737df2e18866f700dc8474217ed097738a22e3757ebc945812091a6db9caec1b927017f148e45a0bd48042b9ff5d9f318e8e
+  data.tar.gz: dc032e0a364295699fa43049edfe498a08b476812161ea8a314f3c507b4a21045b47b04131b7129ed25aa75fb547e60c77219765314cd1045bc31d617b842948

data/lib/channel.rb

@@ -5,10 +5,13 @@
 #    :copyright: (c) 2015 by Fanout, Inc.
 #    :license: MIT, see LICENSE for more details.
 
+# The Channel class is used to represent a channel in for a GRIP proxy and
+# tracks the previous ID of the last message.
 class Channel
   attr_accessor :name
   attr_accessor :prev_id
 
+  # Initialize with the channel name and an optional previous ID.
   def initialize(name, prev_id=nil)
     @name = name
     @prev_id = prev_id

data/lib/gripcontrol.rb

@@ -17,55 +17,30 @@ require_relative 'websocketevent.rb'
 require_relative 'grippubcontrol.rb'
 require_relative 'response.rb'
 
+# The GripControl class provides functionality that is used in conjunction
+# with GRIP proxies. This includes facilitating the creation of hold
+# instructions for HTTP long-polling and HTTP streaming, parsing GRIP URIs
+# into config objects, validating the GRIP-SIG header coming from GRIP
+# proxies, creating GRIP channel headers, and also WebSocket-over-HTTP
+# features such as encoding/decoding web socket events and generating
+# control messages.
 class GripControl
+
+  # Create GRIP hold instructions for the specified mode, channels, response
+  # and optional timeout value. The channel parameter can be specified as
+  # either a string representing the channel name, a Channel instance or an
+  # array of Channel instances. The response parameter can be specified as
+  # either a string representing the response body or a Response instance.
   def self.create_hold(mode, channels, response, timeout=nil)
     hold = Hash.new
     hold['mode'] = mode
-    if channels.is_a?(Channel)
-      channels = [channels]
-    elsif channels.is_a?(String)
-      channels = [Channel.new(channels)]
-    end
-    raise 'channels.length equal to 0' unless channels.length > 0
-    ichannels = []
-    channels.each do |channel|
-      if channel.is_a?(String)
-        channel = Channel(channel)
-      end
-      ichannel = Hash.new
-      ichannel['name'] = channel.name
-      if !channel.prev_id.nil?
-        ichannel['prev-id'] = channel.prev_id
-      end
-      ichannels.push(ichannel)
-    end
+    channels = GripControl.parse_channels(channels)
+    ichannels = GripControl.get_hold_channels(channels)
     hold['channels'] = ichannels
     if !timeout.nil?
       hold['timeout'] = timeout
     end
-    iresponse = nil
-    if !response.nil?
-      if response.is_a?(String)
-        response = Response(nil, nil, nil, response)
-      end
-      iresponse = Hash.new
-      if !response.code.nil?
-        iresponse['code'] = response.code
-      end
-      if !response.reason.nil?
-        iresponse['reason'] = response.reason
-      end
-      if !response.headers.nil? and response.headers.length > 0
-        iresponse['headers'] = response.headers
-      end
-      if !response.body.nil?
-        if response.body.encoding.name == 'ASCII-8BIT'
-          iresponse['body-bin'] = Base64.encode64(response.body)
-        else
-          iresponse['body'] = response.body
-        end
-      end
-    end
+    iresponse = GripControl.get_hold_response(response)
     instruct = Hash.new
     instruct['hold'] = hold
     if !iresponse.nil?
@@ -74,9 +49,17 @@ class GripControl
     return instruct.to_json
   end
 
+  # Parse the specified GRIP URI into a config object that can then be passed
+  # to the GripPubControl class. The URI can include 'iss' and 'key' JWT
+  # authentication query parameters as well as any other required query string
+  # parameters. The JWT 'key' query parameter can be provided as-is or in base64
+  # encoded format.
   def self.parse_grip_uri(uri)
     uri = URI(uri)
-    params = CGI.parse(uri.query)
+    params = {}
+    if (uri.query)
+        params = CGI.parse(uri.query)
+    end
     iss = nil
     key = nil
     if params.key?('iss')
@@ -93,7 +76,7 @@ class GripControl
     qs = []
     params.map do |name,values|
       values.map do |value|
-        qs.push('#{CGI.escape name}=#{CGI.escape value}')
+        qs.push("#{CGI.escape name}=#{CGI.escape value}")
       end
     end
     qs = qs.join('&')
@@ -119,6 +102,9 @@ class GripControl
     return out
   end
 
+  # Validate the specified JWT token and key. This method is used to validate
+  # the GRIP-SIG header coming from GRIP proxies such as Pushpin or Fanout.io.
+  # Note that the token expiration is also verified.
   def self.validate_sig(token, key)
     token = token.encode('utf-8')
     begin
@@ -135,13 +121,13 @@ class GripControl
     return true
   end
 
+  # Create a GRIP channel header for the specified channels. The channels
+  # parameter can be specified as a string representing the channel name,
+  # a Channel instance, or an array of Channel instances. The returned GRIP
+  # channel header is used when sending instructions to GRIP proxies via
+  # HTTP headers.
   def self.create_grip_channel_header(channels)
-    if channels.is_a?(Channel)
-      channels = [channels]
-    elsif channels.is_a?(String)
-      channels = [Channel.new(channels)]
-    end
-    raise 'channels.length equal to 0' unless channels.length > 0
+    channels = parse_channels(channels)
     parts = []
     channels.each do |channel|
       s = channel.name
@@ -153,14 +139,23 @@ class GripControl
     return parts.join(', ')
   end
 
+  # A convenience method for creating GRIP hold response instructions for HTTP
+  # long-polling. This method simply passes the specified parameters to the
+  # create_hold method with 'response' as the hold mode.
   def self.create_hold_response(channels, response=nil, timeout=nil)
     return GripControl.create_hold('response', channels, response, timeout)
   end
 
+  # A convenience method for creating GRIP hold stream instructions for HTTP
+  # streaming. This method simply passes the specified parameters to the
+  # create_hold method with 'stream' as the hold mode.
   def self.create_hold_stream(channels, response=nil)
     return create_hold('stream', channels, response)
   end
 
+  # Decode the specified HTTP request body into an array of WebSocketEvent
+  # instances when using the WebSocket-over-HTTP protocol. A RuntimeError
+  # is raised if the format is invalid.
   def self.decode_websocket_events(body)
     out = []
     start = 0
@@ -187,6 +182,9 @@ class GripControl
     return out
   end
 
+  # Encode the specified array of WebSocketEvent instances. The returned string
+  # value should then be passed to a GRIP proxy in the body of an HTTP response
+  # when using the WebSocket-over-HTTP protocol.
   def self.encode_websocket_events(events)
     out = ''
     events.each do |event|
@@ -200,6 +198,10 @@ class GripControl
     return out
   end
 
+  # Generate a WebSocket control message with the specified type and optional
+  # arguments. WebSocket control messages are passed to GRIP proxies and
+  # example usage includes subscribing/unsubscribing a WebSocket connection
+  # to/from a channel.
   def self.websocket_control_message(type, args=nil)
     if !args.nil?
       out = Marshal.load(Marshal.dump(args))
@@ -209,4 +211,66 @@ class GripControl
     out['type'] = type
     return out.to_json
   end
+
+  private
+
+  # Parse the specified parameter into an array of Channel instances. The
+  # specified parameter can either be a string, a Channel instance, or
+  # an array of Channel instances.
+  def self.parse_channels(channels)
+    if channels.is_a?(Channel)
+      channels = [channels]
+    elsif channels.is_a?(String)
+      channels = [Channel.new(channels)]
+    end
+    raise 'channels.length equal to 0' unless channels.length > 0
+    return channels
+  end
+
+  # Get an array of hashes representing the specified channels parameter. The
+  # resulting array is used for creating GRIP proxy hold instructions.
+  def self.get_hold_channels(channels)
+    ichannels = []
+    channels.each do |channel|
+      if channel.is_a?(String)
+        channel = Channel(channel)
+      end
+      ichannel = Hash.new
+      ichannel['name'] = channel.name
+      if !channel.prev_id.nil?
+        ichannel['prev-id'] = channel.prev_id
+      end
+      ichannels.push(ichannel)
+    end
+    return ichannels
+  end
+
+  # Get a hash representing the specified response parameter. The
+  # resulting hash is used for creating GRIP proxy hold instructions.
+  def self.get_hold_response(response)
+    iresponse = nil
+    if !response.nil?
+      if response.is_a?(String)
+        response = Response.new(nil, nil, nil, response)
+      end
+      iresponse = Hash.new
+      if !response.code.nil?
+        iresponse['code'] = response.code
+      end
+      if !response.reason.nil?
+        iresponse['reason'] = response.reason
+      end
+      if !response.headers.nil? and response.headers.length > 0
+        iresponse['headers'] = response.headers
+      end
+      if !response.body.nil?
+        if response.body.clone.force_encoding("UTF-8").valid_encoding?
+          iresponse['body'] = response.body
+        else  
+          iresponse['body-bin'] = Base64.encode64(response.body)
+        end
+      end
+    end
+    return iresponse
+  end
 end

data/lib/grippubcontrol.rb

@@ -7,11 +7,19 @@
 
 require 'pubcontrol'
 
+# The GripPubControl class allows consumers to easily publish HTTP response
+# and HTTP stream format messages to GRIP proxies. Configuring GripPubControl
+# is slightly different from configuring PubControl in that the 'uri' and
+# 'iss' keys in each config entry should have a 'control_' prefix.
+# GripPubControl inherits from PubControl and therefore also provides all
+# of the same functionality.
 class GripPubControl < PubControl
   alias super_add_client add_client
   alias super_publish publish
   alias super_publish_async publish_async
 
+  # Initialize with or without a configuration. A configuration can be applied
+  # after initialization via the apply_grip_config method.
   def initialize(config=nil)
     @clients = Array.new
     if !config.nil?
@@ -19,6 +27,11 @@ class GripPubControl < PubControl
     end
   end
 
+  # Apply the specified configuration to this GripPubControl 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_grip_config(config)
     if !config.is_a?(Array)
       config = [config]
@@ -35,6 +48,12 @@ class GripPubControl < PubControl
     end
   end
 
+  # Synchronously publish an HTTP response format message to all of the
+  # configured PubControlClients with a specified channel, message, and
+  # optional ID and previous ID. Note that the 'http_response' parameter can
+  # be provided as either an HttpResponseFormat instance or a string (in which
+  # case an HttpResponseFormat instance will automatically be created and
+  # have the 'body' field set to the specified string).
   def publish_http_response(channel, http_response, id=nil, prev_id=nil)
     if http_response.is_a?(String)
       http_response = HttpResponseFormat.new(nil, nil, nil, http_response)
@@ -43,6 +62,14 @@ class GripPubControl < PubControl
     super_publish(channel, item)
   end
 
+  # Asynchronously publish an HTTP response format message to all of the
+  # configured PubControlClients with a specified channel, message, and
+  # optional ID, previous ID, and callback. Note that the 'http_response'
+  # parameter can be provided as either an HttpResponseFormat instance or
+  # a string (in which case an HttpResponseFormat instance will automatically
+  # be created and have the 'body' field set to the specified string). When
+  # specified, the callback method will be called after publishing is complete
+  # and passed a result and error message (if an error was encountered).
   def publish_http_response_async(channel, http_response, id=nil,
       prev_id=nil, callback=nil)
     if http_response.is_a?(String)
@@ -52,6 +79,12 @@ class GripPubControl < PubControl
     super_publish_async(channel, item, callback)
   end
 
+  # Synchronously publish an HTTP stream format message to all of the
+  # configured PubControlClients with a specified channel, message, and
+  # optional ID and previous ID. Note that the 'http_stream' parameter can
+  # be provided as either an HttpStreamFormat instance or a string (in which
+  # case an HttStreamFormat instance will automatically be created and
+  # have the 'content' field set to the specified string).
   def publish_http_stream(channel, http_stream, id=nil, prev_id=nil)
     if http_stream.is_a?(String)
       http_stream = HttpStreamFormat.new(http_stream)
@@ -60,6 +93,14 @@ class GripPubControl < PubControl
     super_publish(channel, item)
   end
 
+  # Asynchronously publish an HTTP stream format message to all of the
+  # configured PubControlClients with a specified channel, message, and
+  # optional ID, previous ID, and callback. Note that the 'http_stream'
+  # parameter can be provided as either an HttpStreamFormat instance or
+  # a string (in which case an HttpStreamFormat instance will automatically
+  # be created and have the 'content' field set to the specified string). When
+  # specified, the callback method will be called after publishing is complete
+  # and passed a result and error message (if an error was encountered).
   def publish_http_stream_async(channel, http_stream, id=nil,
       prev_id=nil, callback=nil)
     if http_stream.is_a?(String)

data/lib/httpresponseformat.rb

@@ -8,12 +8,16 @@
 require 'base64'
 require 'pubcontrol'
 
+# The HttpResponseFormat class is the format used to publish messages to
+# HTTP response clients connected to a GRIP proxy.
 class HttpResponseFormat < Format
   attr_accessor :code
   attr_accessor :reason
   attr_accessor :headers
   attr_accessor :body
 
+  # Initialize with the message code, reason, headers, and body to send
+  # to the client when the message is publishing.
   def initialize(code=nil, reason=nil, headers=nil, body=nil)
     @code = code
     @reason = reason
@@ -21,10 +25,14 @@ class HttpResponseFormat < Format
     @body = body
   end
 
+  # The name used when publishing this format.
   def name
     return 'http-response'
   end
 
+  # Export the message into the required format and include only the fields
+  # that are set. The body is exported as base64 if the text is encoded as
+  # binary.
   def export
     out = Hash.new
     if !@code.nil?
@@ -37,10 +45,10 @@ class HttpResponseFormat < Format
       out['headers'] = @headers
     end
     if !@body.nil?
-      if @body.encoding.name == 'ASCII-8BIT'
-        out['body-bin'] = Base64.encode64(@body)
-      else
+      if @body.clone.force_encoding("UTF-8").valid_encoding?   
         out['body'] = @body
+      else
+        out['body-bin'] = Base64.encode64(@body)
       end
     end
     return out

data/lib/httpstreamformat.rb

@@ -8,10 +8,15 @@
 require 'base64'
 require 'pubcontrol'
 
+# The HttpStreamFormat class is the format used to publish messages to
+# HTTP stream clients connected to a GRIP proxy.
 class HttpStreamFormat < Format
   attr_accessor :content
   attr_accessor :close
 
+  # Initialize with either the message content or a boolean indicating that
+  # the streaming connection should be closed. If neither the content nor
+  # the boolean flag is set then an error will be raised.
   def initialize(content=nil, close=false)
     @content = content
     @close = close
@@ -20,19 +25,23 @@ class HttpStreamFormat < Format
     end
   end
 
+  # The name used when publishing this format.
   def name
     return 'http-stream'
   end
 
+  # Exports the message in the required format depending on whether the
+  # message content is binary or not, or whether the connection should
+  # be closed.
   def export
     out = Hash.new
     if @close
       out['action'] = 'close'
     else
-      if @content.encoding.name == 'ASCII-8BIT'
-        out['content-bin'] = Base64.encode64(@content)
-      else
+      if @content.clone.force_encoding("UTF-8").valid_encoding?
         out['content'] = @content
+      else
+        out['content-bin'] = Base64.encode64(@content)
       end
     end
     return out

data/lib/response.rb

@@ -5,12 +5,18 @@
 #    :copyright: (c) 2015 by Fanout, Inc.
 #    :license: MIT, see LICENSE for more details.
 
+# The Response class is used to represent a set of HTTP response data.
+# Populated instances of this class are serialized to JSON and passed
+# to the GRIP proxy in the body. The GRIP proxy then parses the message
+# and deserialized the JSON into an HTTP response that is passed back 
+# to the client.
 class Response
   attr_accessor :code
   attr_accessor :reason
   attr_accessor :headers
   attr_accessor :body
 
+  # Initialize with an HTTP response code, reason, headers, and body.
   def initialize(code=nil, reason=nil, headers=nil, body=nil)
     @code = code
     @reason = reason

data/lib/websocketevent.rb

@@ -5,10 +5,14 @@
 #    :copyright: (c) 2015 by Fanout, Inc.
 #    :license: MIT, see LICENSE for more details.
 
+# The WebSocketEvent class represents WebSocket event information that is
+# used with the GRIP WebSocket-over-HTTP protocol. It includes information
+# about the type of event as well as an optional content field.
 class WebSocketEvent
   attr_accessor :type
   attr_accessor :content
 
+  # Initialize with a specified event type and optional content information.
   def initialize(type, content=nil)
     @type = type
     @content = content

data/lib/websocketmessageformat.rb

@@ -8,18 +8,25 @@
 require 'base64'
 require 'pubcontrol'
 
+# The WebSocketMessageFormat class is the format used to publish data to
+# WebSocket clients connected to GRIP proxies.
 class WebSocketMessageFormat < Format
   attr_accessor :content
 
+  # Initialize with the message content and a flag indicating whether the
+  # message content should be sent as base64-encoded binary data.
   def initialize(content, binary=false)
     @content = content
     @binary = binary
   end
 
+  # The name used when publishing this format.
   def name
     return 'ws-message'
   end
 
+  # Exports the message in the required format depending on whether the
+  # message content is binary or not.
   def export
     out = Hash.new
     if @binary

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gripcontrol
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.2.2
 platform: ruby
 authors:
 - Konstantin Bokarius
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-18 00:00:00.000000000 Z
+date: 2015-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pubcontrol