cloudformula 1.1.2

data/lib/cloudformula/help/top.txt

@@ -0,0 +1,20 @@
+NAME
+  cloudformula
+  https://github.com/Kabam/cloudformula
+
+DESCRIPTION
+  Dynamically generates AWS CloudFormation templates, creates, and updates
+  CloudFormation stacks.
+
+USAGE
+  cloudformula <command> <options>
+
+AVAILABLE COMMANDS
+  'cloudformula <command> --help' provides more detailed information for each
+  command.
+
+  generate :: Generate a template
+  create   :: Generate a template and create a new CloudFormation stack
+  update   :: Generate a template and update an existing CloudFormation stack
+
+OPTIONS

data/lib/cloudformula/help/update.txt

@@ -0,0 +1,12 @@
+NAME
+  cloudformula update
+
+DESCRIPTION
+  Dynamically generates an AWS CloudFormation template and uses it to update an
+  existing CloudFormation stack.
+
+USAGE
+  cloudformula update --stack-name '<stackname>' --template '<template>' \\
+    --parameters '<params>' [--region '<region>']
+
+OPTIONS

data/lib/cloudformula/json_erb.rb

@@ -0,0 +1,42 @@
+require 'erb'
+
+module CloudFormula
+  # Custom ERB compiler which causes variable interpolation inside <%= %> to be json encoded.
+  # Inside regular <% %>, the variables are used without json encoding.
+  #
+  # CloudFormation stack options defaults can be set directly within a template by setting @stack_options.
+  # See README.md "CloudFormation stack options" for details.
+  #
+  # Basic validation functionality is possible by setting @validations.
+  # See README.md "Validations" for details
+  #
+  class JsonErb < ::ERB
+    class CompilerWithBlock < ::ERB::Compiler
+      def add_insert_cmd(out, content)
+        out.push "#{@insert_cmd}((#{content}).to_s.try_to_json)"
+      end
+    end
+
+    def make_compiler(*args)
+      CompilerWithBlock.new *args
+    end
+
+    # Returns the @stack_options value set within the template.
+    #
+    # @param [Binding] b accepts a Binding or Proc object which is used to set the context of code evaluation.
+    # @return [Hash] The stack options set by the template or an empty Hash if none are set.
+    def stack_options(b = new_toplevel)
+      result(b)
+      b.eval('@stack_options') || {}
+    end
+
+    # Returns the @validations value set within the template.
+    #
+    # @param [Binding] b accepts a Binding or Proc object which is used to set the context of code evaluation.
+    # @return [Hash] The stack options set by the template or an empty Hash if none are set.
+    def validations(b = new_toplevel)
+      result(b)
+      b.eval('@validations') || {}
+    end
+  end
+end

data/lib/cloudformula/string.rb

@@ -0,0 +1,11 @@
+require 'json'
+
+class String
+  # Returns the string JSON-escaped.
+  # If the cloudformula_raw flag is set, returns the string as-is.
+  # @return [String]
+  def try_to_json
+    return self if instance_variable_get :@cloudformula_raw
+    self.to_json
+  end
+end

data/lib/cloudformula/template.rb

@@ -0,0 +1,99 @@
+require 'json'
+
+module CloudFormula
+  # Defines a CloudFormula/CloudFormation template
+  class Template
+    attr :parameters, :source
+
+    # @param [String] source Path to source template
+    # @param [Hash] parameters Parameter names and values to use in the template
+    def initialize(source = '', parameters = {})
+      @source = source
+      @parameters = parameters
+    end
+
+    # Evaluates and returns the @source template populated with values from @parameters
+    # @return [String]
+    def generate
+      init_parameters @parameters
+      raise "Parameter validation failed.\n\nErrors:\n  #{errors.join("\n")}" if invalid?
+      JsonErb.new(File.read(@source)).result(binding)
+    end
+
+    # Evalutes and returns the @source template populated with values from @parameters
+    # @return [Hash]
+    def generate_hash
+      JSON.parse(generate)
+    end
+
+    # Causes the given string value to be output without escape characters
+    # @param [String] value
+    # @return [String]
+    def raw(value)
+      value.instance_variable_set :@cloudformula_raw, true
+      value
+    end
+
+    # @param [String] source Path to source template
+    # @param [Hash] parameters Parameter names and values to use in the template
+    # @return [String] The result of generating the template
+    def render(source, parameters = {})
+      raw CloudFormula::Template.new(source, parameters).generate
+    end
+
+    # Returns the CloudFormation stack options defined by the template.
+    def stack_options
+      init_parameters @parameters
+      JsonErb.new(File.read(@source), 0).stack_options(binding) rescue {}
+    end
+
+    # Returns the validations defined by the template.
+    def validations
+      init_parameters @parameters
+      JsonErb.new(File.read(@source), 0).validations(binding) rescue {}
+    end
+
+    # Returns the merged options Hash for use by AWS::CloudFormation::StackCollection#create and
+    # AWS::CloudFormation::Stack#update
+    #
+    # @param [Hash] override_options Optional. Stack options to override. See README.md "CloudFormation stack options" for details
+    # @param [Hash] parameters Parameters to supply to the template. Required if the template contains any required parameters without a default value
+    def aws_options(override_options = {}, parameters = {})
+      stack_options.merge(override_options.merge({ :parameters => parameters }))
+    end
+
+    # Similar to Active Record Validations errors[] object
+    # @see http://guides.rubyonrails.org/v3.2.13/active_record_validations_callbacks.html#validations_overview-errors
+    def errors
+      validate
+    end
+
+    def valid?
+      errors.length == 0
+    end
+
+    def invalid?
+      !valid?
+    end
+
+    private
+
+    # Sets the given Hash as instance variables for use in the ERB template
+    # @param [Hash] values
+    def init_parameters(values = {})
+      values.each { |key, value| instance_variable_set("@#{key}", value) }
+    end
+
+    def validate
+      errors = []
+      validations.each do |parameter_name, parameter_validations|
+        validator = CloudFormula::Validator.new(parameter_name, parameter_validations)
+        validate_result = validator.validate(@parameters[parameter_name.to_sym])
+        errors += validate_result
+      end
+      #puts errors.inspect
+      errors
+    end
+
+  end
+end

data/lib/cloudformula/validator.rb

@@ -0,0 +1,172 @@
+require 'json'
+
+module CloudFormula
+  # Contains logic to perform basic validation of parameters defined in a JsonErb template.
+  #
+  # Available validations:
+  #   :exclusion => ['val1'] Ensures a value is not in the exclusion list
+  #   :inclusion => ['val1', 'val2'] Ensures a value is in the inclusion list
+  #   :length => { Ensures value length
+  #     :minimum => n,
+  #     :maximum => n,
+  #     :in|:within => x..y,
+  #     :is => n
+  #   }
+  #   :format => /regex/ Ensures a value matches the regex
+  #   :presence => true|false Ensures a value exists and has a length greater than 0
+  #
+  class Validator
+    class Rule
+      attr_accessor :name, :value
+      def initialize(name, value)
+        @name = name
+        @value = value
+      end
+    end
+
+    attr_accessor :parameter_name, :validations
+
+    # @param [Hash] validations The rules defined for the given parameter_name
+    def initialize(parameter_name, validations)
+      @parameter_name = parameter_name
+      @validations = validations
+    end
+
+    # @param [Object] value The value to check against
+    # @return [Array] An Array of Strings describing the failure(s) if any checks fail, or an empty Array otherwise
+    def validate(value)
+      errors = []
+      @validations.each do |rule_name, rule_value|
+        rule_result = check_rule Rule.new(rule_name, rule_value), value
+        errors += rule_result
+      end
+      errors
+    end
+
+    private
+
+    # @param [Rule] rule The rule to check
+    # @param [Object] parameter_value The value to check against
+    # @return [Array] A string describing the failure will be returned if the check fails, or an empty Array otherwise
+    def check_rule(rule, parameter_value)
+      case rule.name
+        when :exclusion, :inclusion, :length, :numericality, :format, :presence
+          self.send("check_#{rule.name}", rule.value, @parameter_name, parameter_value)
+        else
+          raise "Unknown rule name #{rule.name} found in ERB template."
+      end || []
+    end
+
+    def check_exclusion(constraint, parameter_name, value)
+      unless value.nil?
+        if constraint.include? value
+          ["Value '#{value}' for parameter '#{parameter_name}' must not be one of [#{constraint.join(', ')}]"]
+        end
+      end
+    end
+
+    def check_inclusion(constraint, parameter_name, value)
+      unless value.nil?
+        unless constraint.include? value
+          ["Value '#{value}' for parameter '#{parameter_name}' must be one of [#{constraint.join(', ')}]"]
+        end
+      end
+    end
+
+    def check_length(constraint, parameter_name, value)
+      errors = []
+      unless value.nil?
+        constraint.each do |length_rule, length_value|
+          case length_rule
+            when :maximum
+              if value.length > length_value
+                errors << "Parameter '#{parameter_name}' must have length less than or equal to #{length_value}"
+              end
+            when :minimum
+              if value.length < length_value
+                errors << "Parameter '#{parameter_name}' must have length greater than or equal to #{length_value}"
+              end
+            when :in, :within
+              unless length_value.cover? value.length
+                errors << "Parameter '#{parameter_name}' must have length in the range of #{length_value}"
+              end
+            when :is
+              if value.length != length_value
+                errors << "Parameter '#{parameter_name}' must have length #{length_value}"
+              end
+            else
+              raise "Unknown length rule attribute #{length_rule} found in ERB template."
+          end
+        end
+      end
+      errors
+    end
+
+    def check_numericality(constraint, parameter_name, value)
+      errors = []
+      unless value.nil?
+        constraint.each do |numericality_rule, numericality_constraint|
+          numeric_value = (/\./ =~ value.to_s ? value.to_f : value.to_i)
+          case numericality_rule
+            when :only_integer
+              if numericality_constraint
+                unless value.to_s =~ /\A[+-]?\d+\Z/
+                  errors << "Parameter '#{parameter_name}' must be an integer"
+                end
+              end
+            when :equal_to
+              unless numeric_value == numericality_constraint
+                errors << "Parameter '#{parameter_name}' must be equal to #{numericality_constraint}"
+              end
+            when :greater_than
+              unless numeric_value > numericality_constraint
+                errors << "Parameter '#{parameter_name}' must be greater than #{numericality_constraint}"
+              end
+            when :less_than
+              unless numeric_value < numericality_constraint
+                errors << "Parameter '#{parameter_name}' must be less than #{numericality_constraint}"
+              end
+            when :greater_than_or_equal_to
+              unless numeric_value >= numericality_constraint
+                errors << "Parameter '#{parameter_name}' must be greater than or equal to #{numericality_constraint}"
+              end
+            when :less_than_or_equal_to
+              unless numeric_value <= numericality_constraint
+                errors << "Parameter '#{parameter_name}' must be less than or equal to #{numericality_constraint}"
+              end
+            when :even
+              if numericality_constraint
+                unless numeric_value.respond_to?('even?') && numeric_value.even?
+                  errors << "Parameter '#{parameter_name}' must be even"
+                end
+              end
+            when :odd
+              if numericality_constraint
+                unless numeric_value.respond_to?('odd?') && numeric_value.odd?
+                  errors << "Parameter '#{parameter_name}' must be odd"
+                end
+              end
+            else
+              raise "Unknown numericality rule attribute #{numericality_rule} found in ERB template."
+          end
+        end
+      end
+      errors
+    end
+
+    def check_format(constraint, parameter_name, value)
+      unless value.nil?
+        unless constraint =~ value
+          ["Value '#{value}' for parameter '#{parameter_name}' must match regexp #{constraint.source}"]
+        end
+      end
+    end
+
+    def check_presence(constraint, parameter_name, value)
+      if constraint && (value.nil? || value.to_s == '')
+        ["Parameter '#{parameter_name}' must exist and have a length of at least 1"]
+      end
+    end
+
+  end
+end

data/lib/cloudformula/version.rb

@@ -0,0 +1,3 @@
+module CloudFormula
+  VERSION = '1.1.2'
+end

data/lib/cloudformula.rb

@@ -0,0 +1,23 @@
+Dir.glob("#{File.dirname(__FILE__)}/cloudformula/*.rb") { |file| require file }
+
+module CloudFormula
+  class << self # class methods
+    # Creates a new CloudFormula::Template object.
+    # @see CloudFormula::Template.initialize
+    def template(source = '', parameters = {})
+      Template.new(source, parameters)
+    end
+
+    # Creates a new AWS CloudFormation stack
+    # @see CloudFormula::CloudFormation.create_stack
+    def create_stack(region, stack_name, template, override_options = {}, parameters = {}, aws_access_key_id = nil, aws_secret_key = nil)
+      CloudFormation.create_stack(region, stack_name, template, override_options, parameters, aws_access_key_id, aws_secret_key)
+    end
+
+    # Updates an AWS CloudFormation stack
+    # @see CloudFormula::CloudFormation.update_stack
+    def update_stack(region, stack_name, template, parameters = {}, aws_access_key_id = nil, aws_secret_key = nil)
+      CloudFormation.update_stack(region, stack_name, template, parameters, aws_access_key_id, aws_secret_key)
+    end
+  end
+end

data/spec/cloud_formula_spec.rb

@@ -0,0 +1,18 @@
+describe CloudFormula do
+  it 'should have a version' do
+    expect(CloudFormula::VERSION).to_not be_nil
+    expect(CloudFormula::VERSION).to_not be_empty
+  end
+
+  it 'template method should return a new Template object' do
+    expect(CloudFormula.template).to be_an_instance_of(CloudFormula::Template)
+  end
+
+  it 'create_stack method' do
+    expect(CloudFormula).to respond_to(:create_stack)
+  end
+
+  it 'update_stack method' do
+    expect(CloudFormula).to respond_to(:update_stack)
+  end
+end

data/spec/cloudformula/cloud_formation_spec.rb

@@ -0,0 +1,55 @@
+require 'spec_helper'
+
+module CloudFormula
+  describe CloudFormation do
+    describe 'create_stack method' do
+      it 'should exist' do
+        expect(CloudFormula::CloudFormation).to respond_to(:create_stack)
+      end
+    end
+
+    describe 'update_stack method' do
+      it 'should exist' do
+        expect(CloudFormula::CloudFormation).to respond_to(:update_stack)
+      end
+    end
+
+    describe 'private get_cloud_formation method' do
+      it 'should raise an error with invalid credentials explicitly passed to it' do
+        stub_aws_env
+        CloudFormula::CloudFormation.instance_eval do
+          def test_cf
+            get_cloud_formation('us-east-1', 'foo', 'bar')
+          end
+        end
+        expect(CloudFormula::CloudFormation.test_cf).to be_a(AWS::CloudFormation)
+        expect { CloudFormula::CloudFormation.test_cf.stacks.each }.to raise_error
+      end
+
+      it 'should work with credentials from ENV' do
+        # This test requires AWS credentials in ENV. Unfortunately it cannot be faked.
+        CloudFormula::CloudFormation.instance_eval do
+          def test_cf
+            get_cloud_formation('us-east-1')
+          end
+        end
+        expect(CloudFormula::CloudFormation.test_cf).to be_a(AWS::CloudFormation)
+        expect { CloudFormula::CloudFormation.test_cf.stacks.each }.to_not raise_error
+      end
+
+    end
+  end
+end
+
+def stub_aws_env
+  ENV.stub(:[]).with('AWS_ACCESS_KEY_ID').and_return(nil)
+  ENV.stub(:[]).with('AWS_SECRET_ACCESS_KEY').and_return(nil)
+  ENV.stub(:[]).with('AWS_SESSION_TOKEN').and_return(nil)
+  ENV.stub(:[]).with('AWS_CREDENTIAL_FILE').and_return(nil)
+  ENV.stub(:[]).with('http_proxy').and_return(nil)
+  ENV.stub(:[]).with('HTTP_PROXY').and_return(nil)
+  ENV.stub(:[]).with('AMAZON_ACCESS_KEY_ID').and_return(nil)
+  ENV.stub(:[]).with('AMAZON_SECRET_ACCESS_KEY').and_return(nil)
+  ENV.stub(:[]).with('AMAZON_SESSION_TOKEN').and_return(nil)
+  ENV.stub(:[]).with('AMAZON_CREDENTIAL_FILE').and_return(nil)
+end