cloud_powers 0.2.7 → 0.2.7.1

data/lib/cloud_powers/zenv.rb

@@ -10,8 +10,8 @@ module Smash
 
       # Attempts to find a file by searching the current directory for the file
       # then walking up the file tree and searching at each stop
-      # @param: name <String>: name of the file or directory to find
-      # @return: Pathname: path to the file or directory given as the `name` param
+      # Parameters name <String>: name of the file or directory to find
+      # Returns Pathname: path to the file or directory given as the `name` param
       def file_tree_search(name)
         next_dir = Pathname.new(`pwd`.strip).parent
         current_dir = Pathname.new(`pwd`.strip)
@@ -33,8 +33,8 @@ module Smash
 
       # Search through the instance variables for a key or if no key is given,
       # return all the i-vars and their values
-      # @params: [key <String]:  The key to search for
-      # @return:
+      # Parameters [key <String]:  The key to search for
+      # Returns
       def i_vars(key = '')
         if key.empty?
           return self.instance_variables.inject({}) do |r,v|
@@ -47,7 +47,7 @@ module Smash
       # PROJECT_ROOT should be set as early as possible in this Node's initilize
       # method.  This method tries to search for it, using #zfind() and if a `nil`
       # result is returned from that search, `pwd` is used as the PROJECT_ROOT.
-      # @return: Path to the project root or where ever `pwd` resolves to <Pathname>
+      # Returns Path to the project root or where ever `pwd` resolves to <Pathname>
       # TODO: improve this...it needs to find the gem's method's caller's project
       # root or at least the gem's method's caller's file's location.
       def project_root
@@ -61,16 +61,16 @@ module Smash
       end
 
       # Manually set the `@project_root` i-var as a `Pathname` object.
-      # @param: New path to the project root <String|Pathname>
-      # @return: @project_root <Pathname>
+      # Parameters New path to the project root <String|Pathname>
+      # Returns @project_root <Pathname>
       def project_root=(var)
         @project_root = Pathname.new(var)
       end
 
       # Search through the system environment variables for a key or if no key
       # is given, return all the system-env-vars and their values
-      # @params: [key <String>]:  The key to search for
-      # @return: Value <String> for the given key or if no key was given, a
+      # Parameters [key <String>]:  The key to search for
+      # Returns Value <String> for the given key or if no key was given, a
       # Hash with { key => value, ... } is returned for all keys with a value.
       # Keys with no value are ommitted from the result.
       def system_vars(key = '')
@@ -98,8 +98,8 @@ module Smash
       #     it's important
       #   * System Env[@] variables are up next.  Hopefully by this time we've found
       #     our information but if not, it should "search" through the system env too.
-      # @params: key <String>: The key to search for
-      # @return: <String>
+      # Parameters key <String>: The key to search for
+      # Returns <String>
       #   TODO: implement a search for all 3 that can find close matches
       def zfind(key)
         project_root if @project_root.nil?

data/lib/cloud_powers.rb

@@ -9,15 +9,25 @@ require 'cloud_powers/storage'
 require 'cloud_powers/version'
 require 'cloud_powers/workflow'
 
+# The Smash module allows us to use CloudPowers under a shared name space with other projects.
 module Smash
+  # The CloudPowers module contains all the other modules and classes that creates the <i>CloudPowers</i> gem.
   module CloudPowers
+    # Authentication mixin
     extend Smash::CloudPowers::Auth
+    # Dynamic Resource creation and delegation
     extend Smash::CloudPowers::Delegator
+    # Aws clients, like EC2 and S3
     include Smash::CloudPowers::AwsResources
+    # Various helper methods
     include Smash::CloudPowers::Helper
+    # Gathers data about an instance, itself
     include Smash::CloudPowers::SelfAwareness
+    # Store files
     include Smash::CloudPowers::Storage
+    # Communication modules
     include Smash::CloudPowers::Synapse
+    # CRUD on Nodes, which are individual instances
     include Smash::CloudPowers::Node
   end
 end

data/lib/stubs/aws_stubs.rb

@@ -1,11 +1,9 @@
-require 'spec_helper'
-
-require 'spec_helper'
-
 module Smash
   module CloudPowers
+    # Provides stubbing for development work in CloudPowers or in a project that uses is
     module AwsStubs
 
+      # Stub metadata for EC2 instance
       INSTANCE_METADATA_STUB = {
         'ami-id' => 'ami-1234',
         'ami-launch-index' => '1',
@@ -29,6 +27,35 @@ module Smash
         'services/' => ''
       }
 
+      # Get or create an EC2 client and cache that client so that a Context is more well tied together
+      #
+      # Parameters
+      # * opts +Hash+ (optional)
+      # * * stub_responses - defaulted to +false+ but it can be overriden with the desired responses for local testing
+      # * * region - defaulted to use the <tt>#region()</tt> method
+      # * * AWS::Credentials object, which will also scour the context and environment for your keys
+      #
+      # === Returns
+      # <tt>AWS::EC2::Client</tt>
+      # === Sample Usage
+      #   config = stub_responses: {
+      #     run_instances: {
+      #       instances: [{ instance_id: 'asd-1234', launch_time: Time.now, state: { name: 'running' }]
+      #     },
+      #     describe_instances: {
+      #       reservations: [
+      #         { instances: [{ instance_id: 'asd-1234', state: { code: 200, name: 'running' } }] }
+      #     ] },
+      #     describe_images: {
+      #       images: [{ image_id: 'asdf', state: 'available' }]
+      #     }
+      #   }
+      #
+      #   ec2(config) # sets and gets an <tt>EC2::Client</tt> that is stubbed with the return data in the config <tt>Hash</tt>
+      #
+      #   images = ec2.describe_images
+      #   images.first[:image_id]
+      #   # => 'asdf'
       def self.node_stub(opts = {})
         {
           stub_responses: {
@@ -63,6 +90,31 @@ module Smash
         }
       end
 
+      # Stub data for a SNS client
+      # Parameters
+      # * opts +Hash+
+      # * * stub_responses: defaulted to false but it can be overriden with the desired responses for local testing
+      # * * region: defaulted to use the `#region()` method
+      # * * AWS::Credentials object, which will also scour the context and environment for your keys
+      #
+      # === Returns
+      # AWS::SNS client
+      #
+      # === Example
+      #   config = {
+      #     stub_responses: {
+      #       create_topic: {},
+      #       delete_topic: {},
+      #       list_topics: [],
+      #       publish: {},
+      #       subscribe: {}
+      #     }
+      #   }
+      #
+      #   sns(config) # sets and gets an Kinesis client
+      #
+      #   create_channel!('testBroadcast')
+      #   # => true
       def self.broadcast_stub(opts = {})
         arn = "arn:aws:sns:us-west-2:8123456789:#{opts[:name] || 'testChannel'}"
        stub = {
@@ -77,6 +129,39 @@ module Smash
         stub.merge(opts.select { |k,v| stub.key? k })
       end
 
+      # Get or create an Kinesis client and cache that client so that a Context is more well tied together
+      # Parameters
+      # * opts <tt>Hash</tt>
+      # * * stub_responses: defaulted to false but it can be overriden with the desired responses for local testing
+      # * * region: defaulted to use the `#region()` method
+      # * * AWS::Credentials object, which will also scour the context and environment for your keys
+      #
+      # === Returns
+      # AWS::Kinesis client
+      #
+      # === Example
+      #   config = {
+      #     stub_responses: {
+      #       create_stream: {},
+      #         put_record: {
+      #           shard_id: opts[:shard_id] || 'idididididididid',
+      #           sequence_number: opts[:sequence_number] || Time.now.to_i.to_s
+      #         },
+      #         describe_stream: {
+      #           stream_description: {
+      #             stream_name: opts[:name] || 'somePipe',
+      #             stream_arn:  'arnarnarnarnar',
+      #             stream_status: 'ACTIVE',
+      #           }
+      #         }
+      #       }
+      #     }
+      #   }
+      #
+      #   kinesis(config) # sets and gets an Kinesis client
+      #
+      #   pipe_to('somePipe') { update_body(status: 'waHoo') }
+      #   # => sequence_number: '1676151970'
       def self.pipe_stub(opts = {})
         stub = {
           stub_responses: {
@@ -112,6 +197,49 @@ module Smash
         stub.merge(opts.select { |k| stub.key?(k) })
       end
 
+      # Get or create an S3 client and cache that client so that a Context is more well tied together
+      #
+      # Parameters
+      # * opts <tt>Hash</tt>
+      # * * stub_responses: defaulted to false but it can be overriden with the desired responses for local testing
+      # * * region: defaulted to use the `#region()` method
+      # * * AWS::Credentials object, which will also scour the context and environment for your keys
+      #
+      # === Returns
+      # AWS::S3 client
+      #
+      # === Example
+      #   config = {
+      #     stub_responses: {
+      #       head_bucket: {}
+      #     }
+      #   }
+      #
+      #   s3(config)
+      #   expect(s3.head_bucket).to be_empty
+      #   # passing expectation
+      def self.storage_stub(opts = {})
+        {
+          stub_responses: {
+            head_bucket: {}
+          }
+        }
+      end
+
+      # Stub data for an SQS client
+      #
+      # Parameters
+      # * opts <tt>Hash</tt>
+      # * * stub_responses: defaulted to false but it can be overriden with the desired responses for local testing
+      # * * region: defaulted to use the `#region()` method
+      # * * AWS::Credentials object, which will also scour the context and environment for your keys
+      #
+      # === Returns
+      # AWS::SQS client
+      #
+      # === Example
+      #   create_queue('someQueue') # uses AWS::SQS
+      #   some_queue_url = queue_search('someQueue').first # uses AWS::SQS
       def self.queue_stub(opts = {})
         {
           stub_responses: {

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cloud_powers
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.7.1
 platform: ruby
 authors:
 - Adam Phillipps
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-10-11 00:00:00.000000000 Z
+date: 2016-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport-core-ext
@@ -184,7 +184,7 @@ description: |2
       It was developed specifically for the Brain project but hopefully can be used
       in any other ruby project that needs to use cloud service providers' resources.
 
-      Version 0.2.7 has a little EC2, S3, SQS, SNS, Kinesis, websockets and a few other
+      Version 0.2.8 has a little EC2, S3, SQS, SNS, Kinesis, websockets and a few other
       features you can find in the docs.  There is also limitted support for stubbing
       AWS RESTful API calls.  That can come in handy for local testing and extra setup on
       AWS resource clients.
@@ -212,6 +212,7 @@ files:
 - Gemfile.lock_b
 - LICENSE.txt
 - README.md
+- README.rdoc.mdown
 - Rakefile
 - bin/console
 - bin/setup