aws-cft-tools 0.1.0

data/lib/aws_cft_tools/client/templates.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module AwsCftTools
+  class Client
+    ##
+    # All of the business logic behind direct interaction with the AWS Template sources.
+    #
+    class Templates < Base
+      ##
+      # Default template directory in the project.
+      DEFAULT_TEMPLATE_DIR = 'cloudformation/templates/'
+
+      ##
+      # Default parameters directory in the project.
+      DEFAULT_PARAMETER_DIR = 'cloudformation/parameters/'
+
+      ##
+      # Default set of file extensions that might contain templates.
+      #
+      TEMPLATE_FILE_EXTENSIONS = %w[.yaml .yml .json .rb].freeze
+
+      ##
+      #
+      # @param options [Hash] client configuration
+      # @option options [String] :environment the operational environment in which to act
+      # @option options [String] :parameter_dir
+      # @option options [String] :region the AWS region in which to act
+      # @option options [Pathname] :root
+      # @option options [String] :template_dir
+      #
+      def initialize(options)
+        super({
+          template_dir: DEFAULT_TEMPLATE_DIR,
+          parameter_dir: DEFAULT_PARAMETER_DIR
+        }.merge(options))
+      end
+
+      ##
+      # Lists all templates.
+      #
+      # @return AwsCftTools::TemplateSet
+      #
+      def templates
+        template_file_root = (options[:root] + options[:template_dir]).cleanpath
+        filtered_by_region(
+          filtered_by_environment(
+            all_templates(
+              template_file_root
+            )
+          )
+        )
+      end
+
+      private
+
+      def filtered_by_environment(set)
+        set.select { |template| template.environment?(options[:environment]) }
+      end
+
+      def filtered_by_region(set)
+        set.select { |template| template.region?(options[:region]) }
+      end
+
+      def all_templates(root)
+        AwsCftTools::TemplateSet.new(glob_templates(root)).tap do |set|
+          set.known_exports = options[:client].exports.map(&:name)
+        end
+      end
+
+      def glob_templates(root)
+        Pathname.glob(root + '**/*')
+                .select { |file| TEMPLATE_FILE_EXTENSIONS.include?(file.extname) }
+                .map { |file| file_to_template(root, file) }
+                .select(&:template?)
+      end
+
+      def file_to_template(root, file)
+        AwsCftTools::Template.new(file.relative_path_from(root), options)
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/deletion_change.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  # Represents a change in a changeset.
+  class DeletionChange < Change
+    attr_reader :resource
+
+    ###
+    #
+    # @param resource
+    #
+    def initialize(resource)
+      @resource = resource
+    end
+
+    ###
+    # Return the action taken. For deletion, this is always +DELETE+.
+    #
+    # @return [String] +'DELETE'+ to indicate a deletion
+    #
+    def action
+      'DELETE'
+    end
+
+    ###
+    # Return the status of this change as a replacement. For deletion, this is always +nil+.
+    #
+    # @return [nil]
+    #
+    def replacement
+      nil
+    end
+
+    ###
+    # Return the scopes of the change. For deletions, this is always +Resource+.
+    #
+    # @return [String] +'Resource'+
+    #
+    def scopes
+      'Resource'
+    end
+  end
+end

data/lib/aws_cft_tools/dependency_tree.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  ##
+  # = Dependency Tree
+  #
+  # Manage dependencies between CloudFormation templates based on exported and imported variables.
+  #
+  class DependencyTree
+    extend Forwardable
+
+    require_relative 'dependency_tree/nodes'
+    require_relative 'dependency_tree/variables'
+
+    attr_reader :filenames, :nodes, :variables
+
+    def initialize
+      @nodes = Nodes.new
+      @variables = Variables.new
+      @filenames = []
+    end
+
+    # @!method undefined_variables
+    #   @see AwsCftTools::DependencyTree::Variables#undefined_variables
+    # @!method defined_variables
+    #   @see AwsCftTools::DependencyTree::Variables#defined_variables
+    def_delegators :variables, :undefined_variables, :defined_variables
+    # @!method exported
+    #   @see AwsCftTools::DependencyTree::Variables#defined
+    def_delegator :variables, :defined, :exported
+
+    # @!method dependencies_for
+    #   @see AwsCftTools::DependencyTree::Nodes#dependencies_for
+    # @!method dependents_for
+    #   @see AwsCftTools::DependencyTree::Nodes#dependents_for
+    def_delegators :nodes, :dependencies_for, :dependents_for
+
+    ##
+    # computes a topological sort and returns the filenames in that sort order
+    #
+    # @return [Array<String>]
+    #
+    def sort
+      nodes.tsort & filenames
+    end
+
+    ##
+    # notes that the given filename defines the given variable name
+    #
+    # @param filename [#to_s]
+    # @param variable [String]
+    #
+    def provided(filename, variable)
+      filename = filename.to_s
+      nodes.make_link(variable, filename)
+      @filenames |= [filename]
+      exported(variable)
+    end
+
+    ##
+    # notes that the given filename requires the given variable name to be defined before deployment
+    #
+    # @param filename [#to_s]
+    # @param variable [String]
+    #
+    def required(filename, variable)
+      filename = filename.to_s
+      nodes.make_link(filename, variable)
+      @filenames |= [filename]
+      variables.referenced(variable)
+    end
+
+    ##
+    # links two nodes in a directed fashion
+    #
+    # The template named by _from_ provides resources required by the template named by _to_.
+    #
+    # @param from [#to_s]
+    # @param to [#to_s]
+    #
+    def linked(from, to)
+      linker = "#{from}$$#{to}"
+      provided(from, linker)
+      required(to, linker)
+    end
+
+    ##
+    # finds a subset of the given set that has no dependencies outside the set
+    #
+    # @param set [Array<T>]
+    # @return [Array<T>]
+    #
+    def closed_subset(set)
+      # list all nodes that have no dependents outside the set
+      close_subset(set, &method(:dependents_for))
+    end
+
+    private
+
+    def close_subset(set, &block)
+      return [] unless block_given?
+      set - items_outside_subset(set, &block)
+    end
+
+    def items_outside_subset(set)
+      set.select { |node| (yield(node) - set).any? }
+    end
+  end
+end

data/lib/aws_cft_tools/dependency_tree/nodes.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  class DependencyTree
+    ##
+    # Manages a list of nodes or vertices. Edges pass from a filename node to a variable node or from
+    # a variable node to a filename node, but never from a filename node to a filename node or from
+    # a variable node to a variable node.
+    #
+    class Nodes
+      include TSort
+
+      def initialize
+        @nodes = default_hash
+        @inverse_nodes = default_hash
+      end
+
+      ##
+      # Computes the direct dependencies of a node that are of the same type as the node. If the node
+      # is a filename, then the returned nodes will be filenames. Likewise with variable names.
+      #
+      # @param node [String]
+      # @return [Array<String>]
+      #
+      def dependencies_for(node)
+        double_hop(@nodes, node.to_s)
+      end
+
+      ##
+      # Computes the things dependent on the given node. If the node is a filename, then the returned
+      # nodes will be filenames. Likewise with variable names.
+      #
+      # @param node [String]
+      # @return [Array<String>]
+      #
+      def dependents_for(node)
+        double_hop(@inverse_nodes, node.to_s)
+      end
+
+      ##
+      # Draws a directed link from +from+ to +to+.
+      #
+      # @param from [String]
+      # @param to [String]
+      def make_link(from, to)
+        @nodes[from] << to
+        @inverse_nodes[to] << from
+      end
+
+      private
+
+      def double_hop(set, node)
+        # we hop from a filename to a variable child to a filename child
+        #     or from a variable to a filename child to a variable child
+        set[node].flat_map { |neighbor| set[neighbor] }.uniq
+      end
+
+      def tsort_each_node(&block)
+        @nodes.each_key(&block)
+      end
+
+      def tsort_each_child(node, &block)
+        @nodes[node].each(&block) if @nodes.include?(node)
+      end
+
+      def default_hash
+        Hash.new { |hash, key| hash[key] = [] }
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/dependency_tree/variables.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  class DependencyTree
+    ##
+    # Manage list of defined/undefined variables
+    #
+    class Variables
+      attr_reader :undefined_variables, :defined_variables
+
+      def initialize
+        @undefined_variables = []
+        @defined_variables = []
+      end
+
+      ##
+      # Notes that the given variable name is provided either by the CloudFormation environment or by
+      # another template.
+      #
+      # @param name [String]
+      #
+      def defined(name)
+        @undefined_variables -= [name]
+        @defined_variables |= [name]
+      end
+
+      ##
+      # Notes that the given variable name is used as an input into a template.
+      #
+      # @param name [String]
+      #
+      def referenced(name)
+        @undefined_variables |= [name] unless @defined_variables.include?(name)
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/errors.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  ##
+  # Provides a root class for matching any internal exceptions.
+  #
+  class ToolingException < StandardError; end
+
+  ##
+  # Exception when a needed environment variable is not provided. Intended for use in
+  # parameter files.
+  class IncompleteEnvironmentError < ToolingException; end
+
+  ##
+  # Exception raised when the template or parameter source file can not be read and parsed.
+  class ParseException < ToolingException; end
+
+  ##
+  # Exception raised when the AWS SDK raises an error interacting with the AWS API.
+  class CloudFormationError < ToolingException; end
+
+  ##
+  # Exception raised when an expected resolvable template dependency can not be satisfied.
+  class UnsatisfiedDependencyError < ToolingException; end
+end

data/lib/aws_cft_tools/runbook.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  ##
+  # This is the base class for runbooks.
+  #
+  # A runbook is a command that can be accessed via the `aws-cft` script. A runbook is implemented as a
+  # subclass of this class.
+  #
+  # == Callbacks
+  # The AwsCftTools::CLI uses callbacks to manage runbook-specific options and behaviors.
+  #
+  # == Helpers
+  #
+  # The various helpers make managing logic flow much easier. Rather than having to be aware of how the
+  # different modes (+verbose+, +change+, +noop+) interplay and are configured, you can use the
+  # methods in this section to annotate the flow with your intent.
+  #
+  # @abstract Subclass and override {.default_options}, {.options}, and {#run} to implement
+  #   a custom Runbook class.
+  class Runbook
+    require_relative 'runbook/report'
+
+    ##
+    # The AwsCftTools::Client instance used by the runbook.
+    #
+    attr_reader :client
+
+    ##
+    # The configuration options passed in to the runbook.
+    #
+    attr_reader :options
+
+    ##
+    # Recognized configuration options depend on the runbook but include any options valid for
+    # AwsCftTools::Client.
+    #
+    # Modes are selected by various configuration options:
+    #
+    # +:verbose+:: provide more narrative as the runbook executes
+    # +:noop+:: do nothing that could modify state
+    # +:change+:: do nothing that could permanently modify state, though some modifications are permitted
+    #  in order to examine what might change if permanent changes were made
+    #
+    # @param configuration [Hash] Various options passed to the AwsCftTools::Client.
+    # @return AwsCftTools::Runbook
+    #
+    def initialize(configuration = {})
+      @options = configuration
+      @client = AwsCftTools::Client.new(options)
+    end
+
+    # @!group Callbacks
+
+    ##
+    # A callback to implement the runbook actions. Nothing is passed in or returned.
+    #
+    # @return void
+    #
+    def run; end
+
+    ##
+    # An internal wrapper around +#run+ to catch credential errors and print a useful message.
+    #
+    def _run
+      run
+    rescue Aws::Errors::MissingCredentialsError
+      puts 'Unable to access AWS without valid credentials. Either define a default credential' \
+      ' profile or use the -p option to specify an AWS credential profile.'
+    end
+
+    # @!group Helpers
+
+    ##
+    # @param description [String] an optional description of the operation
+    # @yield runs the block if not in +noop+ mode
+    # @return void
+    #
+    # Defines an operation that may or may not be narrated and that should not be run if in +noop+ mode.
+    #
+    # @example
+    #   operation("considering the change" ) do
+    #     checking("seeing what changes") { check_what_changes }
+    #     doing("committing the change") { make_the_change }
+    #   end
+    #
+    def operation(description = nil)
+      narrative(description)
+      return if options[:noop]
+
+      yield if block_given?
+    end
+
+    ##
+    # @param description [String] an optional description of the check
+    # @yield runs the block if in +check+ mode and not in +noop+ mode
+    # @return void
+    #
+    # Runs the given block when in +check+ mode and not in +noop+ mode. Outputs the description if the
+    # block is run.
+    #
+    # @example (see #operation)
+    #
+    def checking(description = nil)
+      return if options[:noop] || !options[:check]
+      output(description)
+      yield if block_given?
+    end
+
+    ##
+    # @param description [String] an optional description of the action
+    # @yield runs the block if not in +check+ or +noop+ mode
+    # @return void
+    #
+    # Runs the given block when not in +check+ or +noop+ mode. Outputs the description if the block is run.
+    #
+    # @example (see #operation)
+    #
+    def doing(description = nil)
+      return if options[:noop] || options[:check]
+      output(description)
+      yield if block_given?
+    end
+
+    ##
+    # @param description [String] an optional narrative string
+    # @return void
+    #
+    # Prints out the given description to stdout. If in +noop+ mode, +" (noop)"+ is appended.
+    #
+    def narrative(description = nil)
+      return unless description
+      if options[:noop]
+        puts "#{description} (noop)"
+      else
+        puts description
+      end
+    end
+
+    ##
+    # @param description [String] an optional verbose description
+    # @yield runs the block if in +verbose+ mode
+    # @return void
+    #
+    # Prints out the given description and runs the block if in +verbose+ mode. This is useful if the
+    # verbose narrative might be computationally expensive.
+    #
+    # @example
+    #    detail do
+    #      ... run some extensive processing to summarize stuff
+    #      puts "The results are #{interesting}."
+    #    end
+    #
+    def detail(description = nil)
+      return unless options[:verbose]
+      output(description)
+      yield if block_given?
+    end
+
+    private
+
+    def output(description)
+      puts description if description
+    end
+  end
+end