stackup 0.1.0 → 0.2.0

data/lib/stackup/error_mapping_proxy.rb

@@ -0,0 +1,37 @@
+require "stackup/errors"
+
+module Stackup
+
+  # An error-mapping proxy for Aws::CloudFormation models.
+  #
+  # It exists to convert certain types of `ValidationError`, where useful
+  # information is hidden inside the "message", to Stackup exceptions.
+  #
+  class ErrorMappingProxy
+
+    def initialize(delegate)
+      @delegate = delegate
+    end
+
+    def method_missing(*args)
+      @delegate.send(*args)
+    rescue Aws::CloudFormation::Errors::ValidationError => e
+      case e.message
+      when "No updates are to be performed."
+        raise NoUpdateRequired, "no updates are required"
+      when /Stack .* does not exist$/
+        raise NoSuchStack, "no such stack"
+      when / can ?not be /
+        raise InvalidStateError, e.message
+      else
+        raise e
+      end
+    end
+
+    def respond_to?(method)
+      @delegate.respond_to?(method)
+    end
+
+  end
+
+end

data/lib/stackup/errors.rb

@@ -1,15 +1,18 @@
 module Stackup
 
   # Base Stackup Exception class
-  class ServiceError < StandardError
-  end
+  class ServiceError < StandardError; end
 
   # Raised when the specified stack does not exist
-  class NoSuchStack < ServiceError
-  end
+  class NoSuchStack < ServiceError; end
 
   # Raised to indicate a problem updating a stack
-  class StackUpdateError < ServiceError
-  end
+  class StackUpdateError < ServiceError; end
+
+  # Raised if we can't perform that operation now
+  class InvalidStateError < ServiceError; end
+
+  # Raised when a stack is already up-to-date
+  class NoUpdateRequired < StandardError; end
 
 end

data/lib/stackup/service.rb

@@ -0,0 +1,39 @@
+require "aws-sdk-core"
+require "stackup/stack"
+
+module Stackup
+
+  # A handle to CloudFormation.
+  #
+  class Service
+
+    def initialize(cf_client = {})
+      cf_client = Aws::CloudFormation::Client.new(cf_client) if cf_client.is_a?(Hash)
+      @cf_client = cf_client
+    end
+
+    # @return [Stackup::Stack] the named stack
+    #
+    def stack(name, options = {})
+      Stack.new(name, cf_client, options)
+    end
+
+    # @return [Enumeration<String>] names of existing stacks
+    #
+    def stack_names
+      Enumerator.new do |y|
+        cf_client.describe_stacks.each do |response|
+          response.stacks.each do |stack|
+            y << stack.stack_name
+          end
+        end
+      end
+    end
+
+    private
+
+    attr_reader :cf_client
+
+  end
+
+end

data/lib/stackup/stack.rb

@@ -1,6 +1,6 @@
 require "aws-sdk-resources"
 require "logger"
-require "stackup/errors"
+require "stackup/error_mapping_proxy"
 require "stackup/stack_watcher"
 
 module Stackup
@@ -13,7 +13,6 @@ module Stackup
       client = Aws::CloudFormation::Client.new(client) if client.is_a?(Hash)
       @name = name
       @cf_client = client
-      @watcher = Stackup::StackWatcher.new(cf_stack)
       options.each do |key, value|
         public_send("#{key}=", value)
       end
@@ -35,8 +34,6 @@ module Stackup
     #
     def status
       cf_stack.stack_status
-    rescue Aws::CloudFormation::Errors::ValidationError => e
-      handle_validation_error(e)
     end
 
     # @return [boolean] true iff the stack exists
@@ -50,16 +47,20 @@ module Stackup
 
     # Create or update the stack.
     #
-    # @param [String] template template JSON
-    # @param [Array<Hash>] parameters template parameters
+    # @param [Hash] options create/update options
+    #   accepts a superset of the options supported by
+    #   +Aws::CloudFormation::Stack#update+
+    #   (see http://docs.aws.amazon.com/sdkforruby/api/Aws/CloudFormation/Stack.html#update-instance_method)
     # @return [Symbol] `:created` or `:updated` if successful
     # @raise [Stackup::StackUpdateError] if operation fails
     #
-    def create_or_update(template, parameters = [])
+    def create_or_update(options)
+      options = options.dup
+      options[:capabilities] ||= ["CAPABILITY_IAM"]
       delete if ALMOST_DEAD_STATUSES.include?(status)
-      update(template, parameters)
+      update(options)
     rescue NoSuchStack
-      create(template, parameters)
+      create(options)
     end
 
     alias_method :up, :create_or_update
@@ -74,17 +75,37 @@ module Stackup
     # @raise [Stackup::StackUpdateError] if operation fails
     #
     def delete
-      return nil unless exists?
+      begin
+        @stack_id = cf_stack.stack_id
+      rescue NoSuchStack
+        return nil
+      end
       status = modify_stack do
-        cf_client.delete_stack(:stack_name => name)
+        cf_stack.delete
       end
-      fail StackUpdateError, "stack delete failed" unless status.nil?
-    rescue NoSuchStack
+      fail StackUpdateError, "stack delete failed" unless status == "DELETE_COMPLETE"
       :deleted
+    ensure
+      @stack_id = nil
     end
 
     alias_method :down, :delete
 
+    # Cancel update in-progress.
+    #
+    # @return [Symbol] `:update_cancelled` if successful
+    # @raise [Stackup::StackUpdateError] if operation fails
+    #
+    def cancel_update
+      status = modify_stack do
+        cf_stack.cancel_update
+      end
+      fail StackUpdateError, "update cancel failed" unless status =~ /_COMPLETE$/
+      :update_cancelled
+    rescue InvalidStateError
+      nil
+    end
+
     # Get stack outputs.
     #
     # @return [Hash<String, String>]
@@ -97,28 +118,23 @@ module Stackup
           h[output.output_key] = output.output_value
         end
       end
-    rescue Aws::CloudFormation::Errors::ValidationError => e
-      handle_validation_error(e)
     end
 
     private
 
-    def create(template, parameters)
+    def create(options)
+      options[:stack_name] = name
       status = modify_stack do
-        cf_client.create_stack(
-          :stack_name => name,
-          :template_body => template,
-          :capabilities => ["CAPABILITY_IAM"],
-          :parameters => parameters
-        )
+        ErrorMappingProxy.new(cf).create_stack(options)
       end
       fail StackUpdateError, "stack creation failed" unless status == "CREATE_COMPLETE"
       :created
     end
 
-    def update(template, parameters)
+    def update(options)
+      options.delete(:disable_rollback)
       status = modify_stack do
-        cf_client.update_stack(:stack_name => name, :template_body => template, :parameters => parameters, :capabilities => ["CAPABILITY_IAM"])
+        cf_stack.update(options)
       end
       fail StackUpdateError, "stack update failed" unless status == "UPDATE_COMPLETE"
       :updated
@@ -127,11 +143,17 @@ module Stackup
     end
 
     def logger
-      @logger ||= (cf_client.config[:logger] || Logger.new($stdout))
+      @logger ||= cf_client.config[:logger]
+      @logger ||= Logger.new($stdout).tap { |l| l.level = Logger::INFO }
+    end
+
+    def cf
+      Aws::CloudFormation::Resource.new(:client => cf_client)
     end
 
     def cf_stack
-      Aws::CloudFormation::Stack.new(:name => name, :client => cf_client)
+      id_or_name = @stack_id || name
+      ErrorMappingProxy.new(cf.stack(id_or_name))
     end
 
     def event_handler
@@ -146,47 +168,18 @@ module Stackup
     # @return the final stack status
     #
     def modify_stack
+      watcher = Stackup::StackWatcher.new(cf_stack)
       watcher.zero
       yield
-      wait_until_stable
-    rescue Aws::CloudFormation::Errors::ValidationError => e
-      handle_validation_error(e)
-    end
-
-    # Wait (displaying stack events) until the stack reaches a stable state.
-    #
-    # @return the final stack status
-    #
-    def wait_until_stable
       loop do
-        report_new_events
-        cf_stack.reload
+        watcher.each_new_event(&event_handler)
+        status = self.status
+        logger.debug("stack_status=#{status}")
         return status if status.nil? || status =~ /_(COMPLETE|FAILED)$/
         sleep(5)
       end
     end
 
-    def report_new_events
-      watcher.new_events.each do |e|
-        event_handler.call(e)
-      end
-    end
-
-    def handle_validation_error(e)
-      case e.message
-      when "No updates are to be performed."
-        fail NoUpdateRequired, "no updates are required"
-      when / does not exist$/
-        fail NoSuchStack, "no such stack: #{name}"
-      else
-        raise e
-      end
-    end
-
-    # Raised when a stack is already up-to-date
-    class NoUpdateRequired < StandardError
-    end
-
   end
 
 end

data/lib/stackup/stack_watcher.rb

@@ -2,6 +2,10 @@ require "aws-sdk-core"
 
 module Stackup
 
+  # A stack event observer.
+  #
+  # Keeps track of previously processed events, and yields the new ones.
+  #
   class StackWatcher
 
     def initialize(stack)
@@ -13,22 +17,24 @@ module Stackup
 
     # Yield all events since the last call
     #
-    def new_events
-      [].tap do |events|
-        stack.events.each do |event|
-          break if @processed_event_ids.include?(event.event_id)
-          events.unshift(event)
-          @processed_event_ids.add(event.event_id)
-        end
+    def each_new_event
+      buffer = []
+      stack.events.each do |event|
+        break if @processed_event_ids.include?(event.event_id)
+        buffer.unshift(event)
       end
-    rescue ::Aws::CloudFormation::Errors::ValidationError
-      []
+      buffer.each do |event|
+        yield event if block_given?
+        @processed_event_ids.add(event.event_id)
+      end
+    rescue Aws::CloudFormation::Errors::ValidationError
+      # okay
     end
 
     # Consume all new events
     #
     def zero
-      new_events
+      each_new_event
       nil
     end
 

data/lib/stackup.rb

@@ -1 +1,27 @@
+require "forwardable"
+require "stackup/service"
 require "stackup/stack"
+
+# Allow use of `Stackup.stacks` rather than `Stackup().stacks`
+#
+module Stackup
+
+  class << self
+
+    def service(client = {})
+      Stackup::Service.new(client)
+    end
+
+    extend Forwardable
+
+    def_delegators :service, :stack, :stack_names
+
+  end
+
+end
+
+# rubocop:disable Style/MethodName
+
+def Stackup(*args)
+  Stackup.service(*args)
+end

data/spec/spec_helper.rb

@@ -1,5 +1,19 @@
-require File.expand_path("../../lib/stackup", __FILE__)
+require "console_logger"
+
+module CfStubbing
+
+  def stub_cf_client
+    client_options = { :stub_responses => true }
+    if ENV.key?("AWS_DEBUG")
+      client_options[:logger] = ConsoleLogger.new(STDOUT, true)
+      client_options[:log_level] = :debug
+    end
+    Aws::CloudFormation::Client.new(client_options)
+  end
+
+end
 
 RSpec.configure do |c|
   c.mock_with :rspec
+  c.include CfStubbing
 end

data/spec/stackup/stack_spec.rb

@@ -1,15 +1,10 @@
 require "spec_helper"
 
+require "stackup/stack"
+
 describe Stackup::Stack do
 
-  let(:cf_client) do
-    client_options = { :stub_responses => true }
-    if ENV.key?("AWS_DEBUG")
-      client_options[:logger] = Logger.new(STDOUT)
-      client_options[:log_level] = :debug
-    end
-    Aws::CloudFormation::Client.new(client_options)
-  end
+  let(:cf_client) { stub_cf_client }
 
   let(:stack_name) { "stack_name" }
   let(:unique_stack_id) { "ID:#{stack_name}" }
@@ -23,24 +18,21 @@ describe Stackup::Stack do
     allow(cf_client).to receive(:create_stack).and_call_original
     allow(cf_client).to receive(:delete_stack).and_call_original
     allow(cf_client).to receive(:update_stack).and_call_original
+    allow(cf_client).to receive(:cancel_update_stack).and_call_original
   end
 
-  def service_error(code, message)
+  def validation_error(message)
     {
       :status_code => 400,
       :headers => {},
-      :body => "<ErrorResponse><Error><Code>#{code}</Code><Message>#{message}</Message></Error></ErrorResponse>"
+      :body => [
+        "<ErrorResponse><Error><Code>ValidationError</Code><Message>",
+        message,
+        "</Message></Error></ErrorResponse>"
+      ].join
     }
   end
 
-  def stack_does_not_exist
-    service_error("ValidationError", "Stack with id #{stack_name} does not exist")
-  end
-
-  def no_update_required
-    service_error("ValidationError", "No updates are to be performed.")
-  end
-
   def stack_description(stack_status)
     {
       :stacks => [
@@ -58,7 +50,7 @@ describe Stackup::Stack do
 
     let(:describe_stacks_responses) do
       [
-        stack_does_not_exist
+        validation_error("Stack with id #{stack_name} does not exist")
       ]
     end
 
@@ -85,7 +77,7 @@ describe Stackup::Stack do
       let(:template) { "stack template" }
 
       def create_or_update
-        stack.create_or_update(template)
+        stack.create_or_update(:template_body => template)
       end
 
       context "successful" do
@@ -162,14 +154,14 @@ describe Stackup::Stack do
         let(:describe_stacks_responses) do
           super() + [
             stack_description("DELETE_IN_PROGRESS"),
-            stack_does_not_exist
+            stack_description("DELETE_COMPLETE")
           ]
         end
 
         it "calls delete_stack" do
           stack.delete
           expect(cf_client).to have_received(:delete_stack)
-            .with(hash_including(:stack_name => stack_name))
+            .with(hash_including(:stack_name => unique_stack_id))
         end
 
         it "returns :deleted" do
@@ -199,28 +191,36 @@ describe Stackup::Stack do
 
       let(:template) { "stack template" }
 
+      let(:options) do
+        { :template_body => template }
+      end
+
       def create_or_update
-        stack.create_or_update(template)
+        stack.create_or_update(options)
       end
 
-      context "successful" do
+      let(:describe_stacks_responses) do
+        super() + [
+          stack_description("UPDATE_IN_PROGRESS"),
+          final_describe_stacks_response
+        ]
+      end
 
-        let(:describe_stacks_responses) do
-          super() + [
-            stack_description("UPDATE_IN_PROGRESS"),
-            stack_description("UPDATE_COMPLETE")
-          ]
-        end
+      let(:final_describe_stacks_response) do
+        stack_description("UPDATE_COMPLETE")
+      end
 
-        it "calls :update_stack" do
-          expected_args = {
-            :stack_name => stack_name,
-            :template_body => template
-          }
-          create_or_update
-          expect(cf_client).to have_received(:update_stack)
-            .with(hash_including(expected_args))
-        end
+      it "calls :update_stack" do
+        expected_args = {
+          :stack_name => stack_name,
+          :template_body => template
+        }
+        create_or_update
+        expect(cf_client).to have_received(:update_stack)
+          .with(hash_including(expected_args))
+      end
+
+      context "successful" do
 
         it "returns :updated" do
           expect(create_or_update).to eq(:updated)
@@ -229,7 +229,10 @@ describe Stackup::Stack do
         context "if no updates are required" do
 
           before do
-            cf_client.stub_responses(:update_stack, no_update_required)
+            cf_client.stub_responses(
+              :update_stack,
+              validation_error("No updates are to be performed.")
+            )
           end
 
           it "returns nil" do
@@ -242,11 +245,8 @@ describe Stackup::Stack do
 
       context "unsuccessful" do
 
-        let(:describe_stacks_responses) do
-          super() + [
-            stack_description("UPDATE_IN_PROGRESS"),
-            stack_description("UPDATE_ROLLBACK_COMPLETE")
-          ]
+        let(:final_describe_stacks_response) do
+          stack_description("UPDATE_ROLLBACK_COMPLETE")
         end
 
         it "raises a StackUpdateError" do
@@ -255,6 +255,20 @@ describe Stackup::Stack do
 
       end
 
+      context "with :disable_rollback" do
+
+        before do
+          options[:disable_rollback] = true
+        end
+
+        it "calls :update_stack" do
+          create_or_update
+          expect(cf_client).to have_received(:update_stack)
+            .with(hash_not_including(:disable_rollback))
+        end
+
+      end
+
     end
 
     %w(CREATE_FAILED ROLLBACK_COMPLETE).each do |initial_status|
@@ -267,20 +281,23 @@ describe Stackup::Stack do
           let(:template) { "stack template" }
 
           def create_or_update
-            stack.create_or_update(template)
+            stack.create_or_update(:template_body => template)
           end
 
           let(:describe_stacks_responses) do
             super() + [
               stack_description("DELETE_IN_PROGRESS"),
-              stack_does_not_exist,
+              validation_error("Stack with id #{stack_name} does not exist"),
               stack_description("CREATE_IN_PROGRESS"),
               stack_description("CREATE_COMPLETE")
             ]
           end
 
           before do
-            cf_client.stub_responses(:update_stack, stack_does_not_exist)
+            cf_client.stub_responses(
+              :update_stack,
+              validation_error("Stack [woollyams-test] does not exist")
+            )
           end
 
           it "calls :delete_stack, then :create_stack first" do
@@ -294,6 +311,55 @@ describe Stackup::Stack do
       end
     end
 
+    context "when status is stable" do
+
+      before do
+        cf_client.stub_responses(
+          :cancel_update_stack,
+          validation_error("that cannot be called from current stack status")
+        )
+      end
+
+      describe "#cancel_update" do
+
+        it "returns nil" do
+          expect(stack.cancel_update).to be_nil
+        end
+
+      end
+
+    end
+
+    context "when status is UPDATE_IN_PROGRESS" do
+
+      let(:stack_status) { "UPDATE_IN_PROGRESS" }
+
+      describe "#cancel_update" do
+
+        let(:describe_stacks_responses) do
+          super() + [
+            stack_description("UPDATE_ROLLBACK_IN_PROGRESS"),
+            stack_description("UPDATE_ROLLBACK_COMPLETE")
+          ]
+        end
+
+        it "calls :cancel_update_stack" do
+          expected_args = {
+            :stack_name => stack_name
+          }
+          stack.cancel_update
+          expect(cf_client).to have_received(:cancel_update_stack)
+            .with(hash_including(expected_args))
+        end
+
+        it "returns :update_cancelled" do
+          expect(stack.cancel_update).to eq(:update_cancelled)
+        end
+
+      end
+
+    end
+
   end
 
 end