cloud_powers 0.2.7 → 0.2.7.1

data/lib/cloud_powers/synapse/pipe/pipe.rb

@@ -8,11 +8,14 @@ module Smash
 
         # Create a Kinesis stream or wait until the stream with the given name is
         # through being created.
-        # === @params: name String
-        # === @returns: Boolean or nil
-        #     * returns true or false if the request was successful or not
-        #     * returns true if the stream has already been created
-        #     * returns false if the stream was not created
+        #
+        # Parameters
+        # * name +String+
+        #
+        # Returns Boolean or nil
+        # * returns true or false if the request was successful or not
+        # * returns true if the stream has already been created
+        # * returns false if the stream was not created
         def create_stream(name)
           begin
             config = stream_config(stream_name: name)
@@ -35,11 +38,25 @@ module Smash
         end
 
         # Use the KCL and LangDaemon to read from a stream
-        # === @params: stream String
+        # Parameters stream String
+        #
+        # Notes
+        # This method is not implemented yet (V 0.2.7)
         def flow_from_pipe(stream)
           throw NotImplementedError
         end
 
+        # Sends data through a Pipe.  This method is used for lower throughput
+        # applications, e.g. logging, status updates
+        #
+        # Parameters
+        # * stream +String+
+        #
+        # Returns
+        # @last_sequence_number +String+
+        #
+        # Notes
+        # This method is not implemented yet (V 0.2.7)
         def flow_to_pipe(stream)
           throw NotImplementedError
           create_stream(stream) unless stream_exists? stream
@@ -53,25 +70,41 @@ module Smash
         end
 
         # Read messages from the Pipe without using the KCL
-        # === @params: stream String
+        # Parameters stream String
+        #
+        # Notes
+        # This method is not implemented yet (V 0.2.7)
         def from_pipe(stream)
           # implement get_records and/or other consuming app stuff
           throw NotImplementedError
         end
 
+        # This message will prepare a set of collections to be sent through the Pipe
+        #
+        # Parameters
+        # * records
+        #
+        # Notes
+        # This method is not implemented yet (V 0.2.7)
         def message_body_collection(records)
           throw NotImplementedError
         end
 
         # Default message package.  This method yields the basic configuration
         # and message body for a stream and all options can be changed.
-        # === @params: opts Hash (optional)
-        #     * stream_name:    String name of the stream to pipe to
-        #     * data:           String message to send
-        #     * partition_key:  String defaults to  @instance_id
-        # === @returns: Hash
-        # === Notes:
-        #     See #instance_id()
+        #
+        # Parameters opts Hash (optional)
+        # * stream_name:    String name of the stream to pipe to
+        # * data:           String message to send
+        # * partition_key:  String defaults to  @instance_id
+        #
+        # Returns
+        # +Hash+
+        #
+        # Notes:
+        # * See +#zfind()+
+        # * See +#instance_id()+
+        # * See +#update_message_body()+
         def pipe_message_body(opts = {})
           {
             stream_name:      zfind(opts[:stream_name]) || zfind('status_stream'),
@@ -82,16 +115,19 @@ module Smash
 
         # Use Kinesis streams to send a message.  The message is given to the method
         # through a block that gets passed to the method.
-        # === @params: stream String
-        # === block: a block that generates a string that will be used in the message body
-        # === @returns: the sequence_number from the sent message.
-        # === Example use
-        #     ```Ruby
-        #     pipe_to(:status_stream) do
-        #       # the return from the inner method is what is sent
-        #       do_some_stuff_to_generate_a_message()
-        #     end
-        #     ```
+        #
+        # Parameters
+        # * stream +String+
+        # * block - a block that generates a string that will be used in the message body
+        #
+        # Returns
+        # the sequence_number from the sent message.
+        #
+        # Example use
+        #   pipe_to(:status_stream) do
+        #     # the return from the inner method is what is sent
+        #     do_some_stuff_to_generate_a_message()
+        #   end
         def pipe_to(stream)
           message = ''
           create_stream(stream) unless stream_exists? stream
@@ -103,8 +139,11 @@ module Smash
         end
 
         # New stream config with sensible defaults
-        # === @params: opts Hash
-        #     * stream_name:
+        #
+        # Parameters
+        # * opts +Hash+ (optional)
+        # * * stream_name - the name to give the stream
+        # * * shard_count - the number of shards to create
         def stream_config(opts = {})
           config = {
             stream_name: opts[:stream_name] || zfind(:status_stream),
@@ -113,8 +152,12 @@ module Smash
         end
 
         # Find out if the stream already exists.
-        # === @params: name String
-        # === @returns: Boolean
+        #
+        # Parameters
+        # * name +String+
+        #
+        # Returns
+        # +Boolean+
         def stream_exists?(name)
           begin
             kinesis.describe_stream(stream_name: name)
@@ -125,9 +168,12 @@ module Smash
         end
 
         # Get the status name for this stream
-        # === @params: name String
-        # === @returns: stream status, one of:
-        #       CREATING, DELETING, ACTIVE, UPDATING
+        #
+        # Parameters
+        # *name +String+
+        #
+        # Returns stream status, one of:
+        # CREATING, DELETING, ACTIVE, UPDATING
         def stream_status(name)
           kinesis.describe_stream(stream_name: name).stream_description.stream_status
         end

data/lib/cloud_powers/synapse/queue/board.rb

@@ -12,34 +12,37 @@ module Smash
 
           attr_accessor :address, :name, :poller, :sqs
 
-          # Takes a `name` and creates a Board object.
-          # The #new method is wrapped in #build() and #create!() but isn't labeled private so
-          # #new can be used instead of build.
+          # Creates a Board object.
+          # The +#new()+ method is wrapped in +#build()+ and +#create!()+ but isn't private so
+          # +#new()+ can be used instead of build.
           # The Board doesn't create Queue(s) or any other API calls until it is instructed to.
-          # @params: name <String>: the name of the board can be used to find its arn/url etc
-          # @returns: Queue::Board
-          # not `#new()`
+          #
+          # Parameters
+          # * name +String+ - the name of the board can be used to find its arn/url etc
+          #
+          # Returns
+          # +Queue::Board+
           def initialize(name, this_sqs)# = sqs)
             @sqs = this_sqs
             @name = name
           end
 
           # Gives back a string representation of the instance variable for this board.
-          # === @returns: String
-          #   *the instance variable for this Board in string format
-          # === Example:
-          #   ```Ruby
+          #
+          # Returns +String+ - the instance variable for this Board in string format
+          #
+          # Example
           #   board = Board.new(:backlog)
           #   Smash.instance_variable_get(board.i_var)
-          #   #=> Board <name: :backlog ...>
-          #   ```
+          #   #=> Board <name: :backlog, ...>
           def i_var
             "@#{@name}"
           end
 
           # Gives the Queue address (URL).  First the environment is searched, using Zenv and if nothing is
           # found, the best guess attempt at the correct address is used.
-          # === @returns:
+          #
+          # Returns
           #   * queue address <String>
           def address
             zfind(@name) ||  best_guess_address
@@ -49,28 +52,48 @@ module Smash
           # to build a standard URL for SQS.  The only problem with using this last resort is you may need
           # to use a Queue from a different region, account or name but it can be a handy catch-all for the URLs
           # for most cases.
-          # === @returns String
-          #     * exp. "https://sqs.us-west-2.amazonaws.com/12345678/fooBar"
+          #
+          # Returns String
+          # * exp. "https://sqs.us-west-2.amazonaws.com/12345678/fooBar"
           def best_guess_address
             "https://sqs.#{zfind(:aws_region)}.amazonaws.com/#{zfind(:account_number)}/#{@name}"
           end
 
-          # Builds a Queue::Board object and returns it.  No API calls are sent using this method
-          # === @params: name <String>
-          # === @returns: Queue::Board
-          def self.build(name, this_sqs)#)
+          # Builds a Queue::Board object and returns it.  No API calls are sent using this method. This is
+          # handy if you need to use a Queue but you don't want to create any resources in AWS.
+          #
+          # Parameters name +String+
+          #
+          # Returns Queue::Board
+          #
+          # Example
+          #   exp_board = Board.build('exampleBoard')
+          #   puts exp_board.best_guess_address
+          #   # => 'https://sqs.us-west-2.amaz.....'
+          def self.build(name, this_sqs = nil)
             new(name, this_sqs)
           end
 
           # Builds then Creates the Object and makes the API call to SQS to create the queue
-          # === @params: name <String>
-          # === @returns: Queue::Board with an actual queue in SQS
-          def self.create!(name, this_sqs)# = nil)
+          #
+          # Parameters
+          # * name <String>
+          #
+          # Returns
+          # +Queue::Board+ with an actual Queue in SQS
+          #
+          # Example
+          #   exp_board = Board.create!('exampleBoard')
+          #   queue_search(exp_board.name)
+          #   # => ['https://sqs.us-west-2.amazonaws.com/81234567890/exampleBoard']
+          def self.create!(name, this_sqs = nil)
             build(name, this_sqs).create_queue!
           end
 
-          # Creates an actual Queue in SQS using the standard format for a queue name (camel case)
-          # === @returns: Queue::Board
+          # Creates an actual Queue in SQS using the standard format for <b><i>this</i></b> queue name (camel case)
+          #
+          # Returns
+          # +Queue::Board+
           def create_queue!
             begin
               sqs.create_queue(queue_name: to_camel(@name))
@@ -87,20 +110,35 @@ module Smash
           end
 
           # Predicate method to query SQS for the queue
+          #
+          # Example
+          #   board = Board.build('example')
+          #   board.exists?
+          #   # => false
+          #   board.save!
+          #   board.exists?
+          #   # => true
           def exists?
             queue_exists?(@name)
           end
 
           # Gets the approximate message count for a Queue using the 'ApproximateMessageCount' attribute
+          #
+          # Returns
+          # +Integer+
           def message_count
             get_queue_message_count(address)
           end
 
-          # Gets a QueuePoller for the Queue attached to this Board instance
-          # === @returns Aws::SQS::QueuePoller
+          # Gets a QueuePoller for the Queue attached to this Board instance.
+          #
+          # Returns
+          # +Aws::SQS::QueuePoller+
+          #
+          # Notes
+          # * Provide an existing SQS Client if one exists.  This is used to sort out development
+          # production work.
           def poller
-            # Provide an existing SQS Client if one exists.
-            # This sets up stubbing and other stuff for later
             args = @sqs.nil? ? address : [address, { client: sqs }]
             @poller ||= Aws::SQS::QueuePoller.new(*args)
           end
@@ -113,17 +151,25 @@ module Smash
           # This method creates the queue in SQS for the given Board instance
           # It can be coupled with the #build() method in order to use a queue without
           # making the call to create it on AWS
+          #
+          # Example
+          #   board = Board.build('example')
+          #   board.exists?
+          #   # => false
+          #   board.save!
+          #   board.exists?
+          #   # => true
           def save!
             create_queue!
           end
 
           # Sends the given message to the queue
-          # === @params: message, which is either used as JSON or converted into it
+          #
+          # Parameters
+          # * message - used as JSON or converted into it
           def send_message(message)
             send_queue_message(
-              address,
-              (valid_json?(message) ? message : message.to_json),
-              sqs
+              address, (valid_json?(message) ? message : message.to_json), sqs
             )
           end
         end

data/lib/cloud_powers/synapse/queue/queue.rb

@@ -8,12 +8,29 @@ module Smash
         include Smash::CloudPowers::AwsResources
         include Smash::CloudPowers::Helper
 
-        # A simpl Struct that acts as a Name to URL map
+        # A simple Struct that acts as a Name to URL map
+        #
+        # Parameters
+        # * <tt>:set_name</tt> - name of the Queue +String+
+        # * <tt>:set_url</tt> - the url for the Queue +String+
+        #
+        # Example
+        #  name_url_map = NUMap.new(nil, 'https://sqs.us-west-53.amazonaws.com/001101010010/fooBar')
+        #  name_url_map.name
+        #  # => 'fooBar'
         NUMap = Struct.new(:set_name, :set_url) do
+          # Gives you back the name, even if it hasn't been set
+          #
+          # Returns
+          # +String+
           def name
             set_name || url.split('/').last # Queue names are last in the URL path
           end
 
+          # Gives you back the URL, even if it hasn't been set
+          #
+          # Returns
+          # +String+
           def url
             set_url || Smash::CloudPowers::Queue::Board.new(name).best_guess_address
           end
@@ -21,29 +38,49 @@ module Smash
 
         # This method can be used to parse a queue name from its address.  It can be handy if you need the name
         # of a queue but you don't want the overhead of creating a Board object.
-        # === @params: url String
-        # === @returns: String
-        # === Example:
-        #     ```Ruby
-        #      board_name('https://sqs.us-west-53.amazonaws.com/001101010010/fooBar')
-        #      => fooBar
-        #     ```
+        #
+        # Parameters
+        # * url +String+
+        #
+        # Returns
+        # +String+
+        #
+        # Example
+        #   board_name('https://sqs.us-west-53.amazonaws.com/001101010010/fooBar')
+        #   => fooBar
         def board_name(url)
           url.to_s.split('/').last
         end
 
         # This method builds a Queue::Board object for you to use but doesn't
-        # invoke the #create! method, so no API call is made to create the queue
-        # on SQS.  This can be used if the board already exists.
-        # === @params: name <String>: name of the queue you want to interact with
-        # === @returns: Queue::Board
+        # invoke the <tt>#create!()</tt> method, so no API call is made to create the Queue
+        # on SQS.  This can be used if the Board and/or Queue already exists.
+        #
+        # Parameters
+        # * name +String+ - name of the Queue you want to interact with
+        #
+        # Returns
+        # Queue::Board
+        #
+        # Example
+        #   queue_object = build_queue('exampleQueue')
+        #   queue_object.address
+        #   => https://sqs.us-west-2.amazonaws.com/81234567/exampleQueue
         def build_queue(name)
           Smash::CloudPowers::Queue::Board.build(to_camel(name), sqs)
         end
 
         # This method allows you to create a queue on SQS without explicitly creating a Board object
-        # === @params: name <String>: The name of the queue to be created
-        # === @returns: Queue::Board
+        #
+        # Parameters
+        # * name +String+ - The name of the Queue to be created
+        #
+        # Returns
+        # Queue::Board
+        #
+        # Example
+        #   create_queue('exampleQueue')
+        #   get_queue_message_count
         def create_queue!(name)
           begin
             Smash::CloudPowers::Queue::Board.create!(to_camel(name), sqs)
@@ -56,9 +93,20 @@ module Smash
         # Deletes a queue message without caring about reading/interacting with the message.
         # This is usually used for progress tracking, ie; a Neuron takes a message from the Backlog, moves it to
         # WIP and deletes it from Backlog.  Then repeats these steps for the remaining States in the Workflow
-        # === @params: queue <String>[, opts <Hash>]
-        #   queue is the name of the queue to interact with
-        #   opts is a configuration hash for the SQS::QueuePoller
+        #
+        # Parameters
+        # * queue +String+ - queue is the name of the +Queue+ to interact with
+        # * opts +Hash+ (optional) - a configuration +Hash+ for the +SQS::QueuePoller+
+        #
+        # Notes
+        # * throws :stop_polling after the message is deleted
+        #
+        # Example
+        #   get_queue_message_count('exampleQueue')
+        #   # => n
+        #   delete_queue_message('exampleQueue')
+        #   get_queue_message_count('exampleQueue')
+        #   # => n-1
         def delete_queue_message(queue, opts = {})
           poll(queue, opts) do |msg, stats|
             poller(queue).delete_message(msg)
@@ -66,9 +114,20 @@ module Smash
           end
         end
 
-        # This method is used to gain the approximate count of messages in a given queue
-        # === @params: board_url <String>: The URL for the board you need to get a count from
-        # === @returns: float representation of the count
+        # This method is used to get the approximate count of messages in a given queue
+        #
+        # Parameters
+        # * board_url +String+ - the URL for the board you need to get a count from
+        #
+        # Returns
+        # +Float+
+        #
+        # Example
+        #   get_queue_message_count('exampleQueue')
+        #   # => n
+        #   delete_queue_message('exampleQueue')
+        #   get_queue_message_count('exampleQueue')
+        #   # => n-1
         def get_queue_message_count(board_url)
           sqs.get_queue_attributes(
             queue_url: board_url,
@@ -76,8 +135,23 @@ module Smash
           ).attributes['ApproximateNumberOfMessages'].to_f
         end
 
-        # === @params: board<String|symbol>: The name of the board
-        # === @returns a message and deletes it from its origin
+        # Get a message from a Queue
+        #
+        # Parameters
+        # * board<String|symbol>: The name of the board
+        #
+        # Returns
+        # * +String+ if +msg.body+ is not valid JSON
+        # * +Hash+ if +msg.body+ is valid JSON
+        #
+        # Example
+        #   # msg.body == 'Hey' # +String+
+        #   pluck_queue_message('exampleQueue')
+        #   # => 'Hey' # +String+
+        #
+        #   # msg.body == "\{"tally":"ho"\}" # +JSON+
+        #   pluck_queue_message('exampleQueue')
+        #   # => { 'tally' => 'ho' } # +Hash+
         def pluck_queue_message(board)
           poll(board) do |msg, poller|
             poller.delete_message(msg)
@@ -87,11 +161,23 @@ module Smash
 
         # Polls the given board with the given options hash and a block that interacts with
         # the message that is retrieved from the queue
-        # === @params: board <String>[, opts <Hash>]
-        #   * `board` is the name of the queue you want to poll
-        #   * `opts` can have any AWS::SQS polling option
-        #   * `&block` is the block that is used to interact with the message that was retrieved
-        # === @returns the results from the `message` and the `block` that interacts with the message(s)
+        #
+        # Parameters
+        # * +board+ +String+ - the name of the queue you want to poll
+        # * +opts+ +Hash+ - costomizes the Aws::SQS::QueuePoller's <tt>#poll(<b>opts</b>)</tt> method
+        # and can have any +AWS::SQS:QueuePoller+ polling configuration option(s)
+        # * +block+ is the block that is used to interact with the message that was retrieved
+        #
+        # Returns
+        # the results from the +message+ and the +block+ that interacts with the +message(s)+
+        #
+        # Example
+        #   # continuously run jobs from messages in the Queue and leaves the message in the queue
+        #   # using the +:skip_delete+ parameter
+        #   poll(:backlog, :skip_delete) do |msg|
+        #     demo_job = Job.new(msg.body)
+        #     demo_job.run
+        #   end
         def poll(board_name, opts = {})
           this_poller = queue_poller(board_name)
           results = nil
@@ -106,8 +192,23 @@ module Smash
         # This method can be used to gain a SQS::QueuePoller.  It creates a Board object,
         # the Board then sends the API call to SQS to create the queue and sets an instance
         # variable, using the board's name, to the Board object itself
-        # === @params: board_name <String>: name of the Queue you want to gain a QueuePoller for
-        # === @returns: @<board_name:Queue::Board>
+        #
+        # Parameters
+        # * board_name +String+ - name of the Queue you want to gain a QueuePoller for
+        #
+        # Returns
+        # <tt>board_name:Queue::Board</tt>
+        #
+        # Notes
+        # * An instance variable is set with this method, if one doesn't exist for the board
+        # The instance variable that is created/used is named the same name that was given as
+        # a parameter.
+        #
+        # Example
+        #   # these are equivalent after @exp_queue_poller is set but before it is set,
+        #   # exp_queue_poller
+        #   queue_poller('exampleQueue').poll { |msg| Job.new(msg.body).run }
+        #   @example_queue.poll { |msg| Job.new(msg.body).run }
         def queue_poller(board_name)
           board = Smash::CloudPowers::Queue::Board.create!(board_name, sqs)
 
@@ -117,25 +218,50 @@ module Smash
           instance_variable_get(board.i_var).poller
         end
 
-        # Checks SQS for the existence of this queue using the #queue_search() method
-        # === @params: name String
-        # === @returns: Boolean
-        # === Notes:
-        #     * see #queue_search()
+        # Checks SQS for the existence of this queue using the <tt>#queue_search()</tt> method
+        #
+        # Parameters
+        # * name +String+
+        #
+        # Returns
+        # Boolean
+        #
+        # Notes:
+        #   * see <tt>#queue_search()</tt>
         def queue_exists?(name)
           !queue_search(name).empty?
         end
 
         # Searches for a queue based on the name
-        # === @params: name String
-        # === @returns: queue_urls [String]
+        #
+        # Parameters
+        # name +String+
+        #
+        # Returns
+        # queue_urls +String+
+        #
+        # Example
+        #   results = queue_search('exampleQueue') # returns related URLs
+        #   results.first =~ /exampleQueue/ # regex match against the URL
         def queue_search(name)
           sqs.list_queues(queue_name_prefix: name).queue_urls
         end
 
         # Sends a given message to a given queue
-        # === @params: address <String>: address of the queue you want to interact with
-        # === @returns: queue_urls <Array<String>> # TODO: verify this.  maybe it was late...
+        #
+        # Parameters
+        # * address +String+ - address of the Queue you want to interact with
+        # * message +String+ - message to be sent
+        #
+        # Returns
+        # <tt>Array<String></tt> - Array of URLs
+        #
+        # Example
+        #   legit_address = 'https://sqs.us-west-2.amazonaws.com/12345678/exampleQueue'
+        #   random_message = 'Wowza, this is pretty easy.'
+        #   resp = send_queue_message(legit_address, random_message))
+        #   resp.message_id
+        #   => 'some message id'
         def send_queue_message(address, message, this_sqs = sqs)
           this_sqs.send_message(queue_url: address, message_body: message)
         end

data/lib/cloud_powers/synapse/synapse.rb

@@ -8,17 +8,18 @@ require_relative './websocket/websocclient'
 module Smash
   module CloudPowers
     # The Synapse module provides all communications functionality
-    # - Broadcast is a module that is useful for sending 1 message to multiple recipients
-    # - Pipe is a module that is useful for sending large result sets, data to be processed
-    #     or loaded, logging info and any other high-throughput/data-centric application with
-    # - Queue is a module that is primarily used for asynchronous communications between a sender
-    #     and any number of users or apps that _might_ need to use it
-    # - WebSocServer ..._Faisal's turn_...
     module Synapse
+      # Broadcast is a module that is useful for sending 1 message to multiple recipients
       include Smash::CloudPowers::Synapse::Broadcast
+      # Pipe is a module that is useful for sending large result sets, data to be processed
+      # or loaded, logging info and any other high-throughput/data-centric application with
       include Smash::CloudPowers::Synapse::Pipe
+      # Queue is a module that is primarily used for asynchronous communications between a sender
+      # and any number of users or apps that _might_ need to use it
       include Smash::CloudPowers::Synapse::Queue
+      # WebSocClient ..._Faisal's turn_...
       include Smash::CloudPowers::Synapse::WebSocClient
+      # WebSocServer ..._Faisal's turn_...
       include Smash::CloudPowers::Synapse::WebSocServer
     end
   end

data/lib/cloud_powers/version.rb

@@ -1,3 +1,3 @@
 module CloudPowers
-  VERSION = "0.2.7"
+  VERSION = "0.2.7.1"
 end