aws-cft-tools 0.1.0

data/lib/aws_cft_tools/template/properties.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  class Template
+    ##
+    # Simple properties of templates.
+    #
+    module Properties
+      ##
+      # Returns the list of environments allowed for the +Environment+ parameter.
+      #
+      # @return [Array<String>]
+      #
+      def allowed_environments
+        template.dig('Parameters', 'Environment', 'AllowedValues') || []
+      end
+
+      def environment?(value)
+        allowed_environments.include?(value)
+      end
+
+      ##
+      # Returns the parameter defaults for the template.
+      #
+      def default_parameters
+        (template['Parameters'] || []).each_with_object({}) do |param, hash|
+          hash[param.first] = param.last['Default']
+        end
+      end
+
+      ##
+      # Returns the role of the template as specified in the template metadata.
+      #
+      # @return [String]
+      #
+      def role
+        template.dig('Metadata', 'Role')
+      end
+
+      def role?(value)
+        !value || role == value
+      end
+
+      ##
+      # Returns the list of regions in which the template is allowed.
+      #
+      # @note The region in which a template is deployed is available as the +AWS::Region+ pseudo-parameter.
+      #
+      # @return [Array<String>]
+      #
+      def allowed_regions
+        template.dig('Metadata', 'Region') || []
+      end
+
+      def region?(region)
+        !region || allowed_regions.empty? || allowed_regions.include?(region)
+      end
+
+      ##
+      # Returns any templates on which this template has an explicit dependency.
+      #
+      # These explicit dependencies are combined with any dependencies implied by imported values.
+      #
+      def template_dependencies
+        template.dig('Metadata', 'DependsOn', 'Templates') || []
+      end
+
+      ##
+      # lists the exported values from the template
+      #
+      # Note that this does substitutions of any references to template parameters.
+      #
+      # @return [Array<String>]
+      #
+      def outputs
+        (template['Outputs'] || []).map do |_, output|
+          with_substitutions(output_name(output.dig('Export', 'Name')))
+        end
+      end
+
+      ##
+      # lists the imports expected by the template
+      #
+      # Note that this does substitutions of any references to template parameters.
+      #
+      # @return [Array<String>]
+      #
+      def inputs
+        (template['Resources'] || {})
+          .values
+          .flat_map { |resource| pull_imports(resource['Properties'] || {}) }
+          .uniq
+          .map(&method(:with_substitutions))
+      end
+
+      private
+
+      def output_name(name)
+        if name.is_a?(Hash)
+          name['Sub'] || name['Fn::Sub']
+        else
+          name
+        end
+      end
+
+      def substitutions
+        @substitutions ||= begin
+          defaults = Hash.new { |hash, key| hash[key] = "${#{key}}" }
+          # need to get the default values of parameters from the template and populate those
+
+          [default_parameters, parameters].flat_map(&:to_a).each do |key, value|
+            defaults["${#{key}}"] = value
+          end
+
+          defaults
+        end
+      end
+
+      ## expands ${param} when ${param} is defined in the parameters
+      ## but only works with "${param}" and not [ "${param}", {param: value}]
+      ## only substitutes when a value is provided as a parameter - otherwise, leaves it unsubsituted
+      def with_substitutions(string)
+        return string if string.is_a?(Array)
+
+        string.gsub(/(\${[^}]*})/, substitutions)
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/template_set.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  ##
+  # Management of a set of template sources.
+  #
+  class TemplateSet < ::Array
+    extend Forwardable
+
+    attr_reader :known_exports
+    attr_reader :dependency_tree
+
+    require_relative 'template_set/array_methods'
+    require_relative 'template_set/closure'
+    require_relative 'template_set/dependencies'
+
+    include ArrayMethods
+
+    # @!method closure
+    #   @see AwsCftTools::TemplateSet::Closure
+    # @!method closed_subset
+    #   @see AwsCftTools::TemplateSet::Closure
+    include Closure
+
+    include Dependencies
+
+    # @!method undefined_variables
+    #   @see AwsCftTools::DependencyTree#undefined_variables
+    # @!method defined_variables
+    #   @see AwsCftTools::DependencyTree#defined_variables
+    def_delegators :dependency_tree, :undefined_variables, :defined_variables
+
+    ##
+    # @param list [Array<AwsCftTools::Template>] the templates in the set
+    #
+    def initialize(list = [])
+      @dependency_tree = AwsCftTools::DependencyTree.new
+      @sorted_names = []
+      @known_exports = []
+      super(list)
+
+      list.each { |template| process_template_addition(template) }
+    end
+
+    # @!visibility private
+    def initialize_clone(other)
+      initialize_copy(other)
+    end
+
+    # @!visibility private
+    def initialize_copy(other)
+      super(other)
+      @dependency_tree = other.dependency_tree.clone
+    end
+
+    ##
+    # Set the list of known exported values in CloudFormation
+    #
+    # @param list [Array<String>]
+    #
+    def known_exports=(list)
+      @known_exports |= list
+      list.each do |name|
+        @dependency_tree.exported(name)
+      end
+    end
+
+    ##
+    # @param filenames [Array<String>]
+    # @return [AwsCftTools::TemplateSet] set of templates with the given filenames
+    #
+    def templates_for(filenames)
+      select { |template| filenames.include?(template.filename.to_s) }
+    end
+
+    ##
+    # @param template [AwsCftTools::Template]
+    # @return [AwsCftTools::TemplateSet] set of templates on which the given template depends
+    #
+    def dependencies_for(template)
+      templates_for(@dependency_tree.dependencies_for(template.filename.to_s))
+    end
+
+    ##
+    # @param template [AwsCftTools::Template]
+    # @return [AwsCftTools::TemplateSet] set of templates that depend on the given template
+    #
+    def dependents_for(template)
+      templates_for(@dependency_tree.dependents_for(template.filename.to_s))
+    end
+
+    private
+
+    def resort_templates
+      @sorted_names = @dependency_tree.sort
+      sort_by! { |template| @sorted_names.index(template.filename.to_s) || -1 }
+    end
+
+    def process_template_outputs(template)
+      template.outputs.each { |name| provided(template, name) }
+    end
+
+    def process_template_inputs(template)
+      template.inputs.each { |name| required(template, name) }
+    end
+
+    def process_template_dependencies(template)
+      templates_for(template.template_dependencies).each { |other| linked(other, template) }
+    end
+
+    def process_template_addition(template)
+      process_template_inputs(template)
+      process_template_outputs(template)
+      process_template_dependencies(template)
+
+      resort_templates
+      self
+    end
+  end
+end

data/lib/aws_cft_tools/template_set/array_methods.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  class TemplateSet
+    ##
+    # Array methods that need to be overridden to work well with template sets.
+    #
+    module ArrayMethods
+      ##
+      # create a new template set holding templates in either set without duplicates
+      #
+      # Note that this is identical to `|`.
+      #
+      # @param other [AwsCftTools::TemplateSet]
+      # @return [AwsCftTools::TemplateSet]
+      #
+      def +(other)
+        self.class.new(super(other).uniq(&:name)).tap do |union|
+          union.known_exports = @known_exports
+        end
+      end
+
+      ##
+      # create a new template set holding templates in either set without duplicates
+      #
+      # @param other [AwsCftTools::TemplateSet]
+      # @return [AwsCftTools::TemplateSet]
+      #
+      def |(other)
+        self + other
+      end
+
+      ##
+      # create a new template set holding templates in the first set not in the second
+      #
+      # @param other [AwsCftTools::TemplateSet]
+      # @return [AwsCftTools::TemplateSet]
+      #
+      def -(other)
+        forbidden_names = other.map(&:name)
+        clone.replace_list(
+          reject { |template| forbidden_names.include?(template.name) }
+        )
+      end
+
+      ##
+      # @return [AwsCftTools::TemplateSet]
+      # @yield [AwsCftTools::Template]
+      #
+      def select
+        return unless block_given?
+        clone.replace_list(super)
+      end
+
+      protected
+
+      def replace_list(new_list)
+        self[0..size - 1] = new_list
+        self
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/template_set/closure.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  class TemplateSet
+    ##
+    # Closure-related functions for a TemplateSet.
+    #
+    module Closure
+      ##
+      # Provides the given templates and any from the set that those templates depend on.
+      #
+      # @param templates [Array<AwsCftTools::Template>]
+      # @return [AwsCftTools::TemplateSet]
+      #
+      def closure(templates)
+        templates_for(
+          calculate_closure(templates.filenames) { |template| @dependency_tree.dependencies_for(template) }
+        )
+      end
+
+      ##
+      # Provides a list of filenames holding the source for the templates in a set.
+      #
+      # @return [Array<String>]
+      #
+      def filenames
+        map(&:filename).map(&:to_s)
+      end
+
+      ##
+      # Provides the subset of the given templates that have no dependent templates outside the set.
+      #
+      # @param templates [AwsCftTools::TemplateSet]
+      # @return [AwsCftTools::TemplateSet]
+      #
+      def closed_subset(templates)
+        templates_for(@dependency_tree.closed_subset(templates.filenames))
+      end
+
+      ##
+      # @param folders [Array<String>]
+      # @return [AwsCftTools::TemplateSet]
+      #
+      def in_folder_order(folders)
+        proper_ordered_set, set = folders.reduce([clone, []]) do |memo, folder|
+          set, proper_ordered_set = memo
+          selected = closure(templates_in_folder(set, folder)) - proper_ordered_set
+          [set - selected, proper_ordered_set | selected]
+        end
+
+        proper_ordered_set | set
+      end
+
+      private
+
+      def templates_in_folder(set, folder)
+        set.select { |template| template.filename.to_s.start_with?(folder + '/') }
+      end
+
+      def calculate_closure(set, &block)
+        stack = set.clone
+
+        stack += closure_step(stack.shift, set, &block) while stack.any?
+        set
+      end
+
+      def closure_step(template, set)
+        [].tap do |stack|
+          (yield(template) - set).each do |depedency|
+            stack << depedency
+            set.unshift(depedency)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/template_set/dependencies.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'each_slice_state'
+
+module AwsCftTools
+  class TemplateSet
+    ##
+    # Simple derived information about templates.
+    #
+    module Dependencies
+      ##
+      # @param template [AwsCftTools::Template]
+      # @param variable [#to_s]
+      def provided(template, variable)
+        @dependency_tree.provided(template.filename.to_s, variable.to_s)
+      end
+
+      ##
+      # @param template [AwsCftTools::Template]
+      # @param variable [#to_s]
+      def required(template, variable)
+        @dependency_tree.required(template.filename.to_s, variable.to_s)
+      end
+
+      ##
+      # @param from [AwsCftTools::Template]
+      # @param to [AwsCftTools::Template]
+      #
+      def linked(from, to)
+        @dependency_tree.linked(from.filename.to_s, to.filename.to_s)
+      end
+
+      ##
+      # Iterates through the sorted list and yields an array of templates with no unsatisfied dependencies,
+      # up to the maximum slice size.
+      #
+      # @param maximum_slice_size [Integer]
+      # @yield [Array<AwsCftTools::Template>] up to +maximum_slice_size+ templates with no unsatisfied
+      #   dependencies
+      #
+      def each_slice(maximum_slice_size, &block)
+        return unless block_given?
+        # we want to start at the beginning and get up to <n> items for which all prior dependencies have
+        # already been returned in a prior call
+        state = EachSliceState.new(maximum_slice_size, &block)
+
+        each do |template|
+          state.add_template(template, @dependency_tree.dependencies_for(template.filename.to_s))
+        end
+        # catch the last templates
+        state.process_slice
+      end
+    end
+  end
+end

data/lib/aws_cft_tools/template_set/each_slice_state.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module AwsCftTools
+  class TemplateSet
+    ##
+    # Keeps track of state for the .each_slice(n) method.
+    #
+    class EachSliceState
+      ##
+      # @param slice_size [Integer] maximum number of templates to yield at once
+      # @yield [Array<AwsCftTools::Template>]
+      #
+      def initialize(slice_size, &block)
+        @seen = []
+        @size = slice_size
+        @slice = []
+        @block = block
+      end
+
+      ##
+      # Have all of the listed dependencies been seen in prior yields?
+      #
+      # @param deps [Array<String>]
+      # @return [Boolean]
+      #
+      def fulfilled?(deps)
+        (deps - @seen).empty?
+      end
+
+      ###
+      # Add the template to the current slice and process the slice if it reaches the maximum slice size.
+      #
+      # @param template [AwsCftTools::Template]
+      #
+      def add_template(template, dependencies = [])
+        process_slice unless fulfilled?(dependencies)
+        unless fulfilled?(dependencies)
+          raise AwsCftTools::UnsatisfiedDependencyError, "Unable to process #{template.filename}"
+        end
+
+        @slice << template
+
+        process_slice if @slice.count == @size
+      end
+
+      ###
+      # Pass the current slice through the block and reset for the next slice.
+      #
+      # @return [Integer] number of templates processed in this batch
+      #
+      def process_slice
+        @block.call(@slice) if @slice.any?
+        @seen |= @slice.map(&:filename).map(&:to_s)
+        @slice = []
+      end
+    end
+  end
+end