cloud-templates 0.1.0

data/lib/aws/templates/utils/default.rb

@@ -0,0 +1,185 @@
+require 'aws/templates/utils'
+require 'aws/templates/utils/options'
+require 'aws/templates/utils/inheritable'
+
+module Aws
+  module Templates
+    module Utils
+      ##
+      # Default mixin.
+      #
+      # It implements class instance-based definitions of so-called
+      # defaults. Defaults are input hash alterations and transformations
+      # which are defined per-class basis and applied according to class
+      # hierarchy when invoked. The target mixing entity should be either
+      # Module or Class. In the former case it's possible to model set of
+      # object which have common traits organized as an arbitrary graph
+      # with many-to-many relationship.
+      module Default
+        include Inheritable
+
+        ##
+        # Hash wrapper
+        #
+        # The hash wrapper does intermediate calculations of nested lambdas in the specified
+        # context as they are encountered
+        class Definition
+          ##
+          # Defined hash keys
+          def keys
+            @hash.keys
+          end
+
+          ##
+          # Transform to hash
+          def to_hash
+            _recurse_into(@hash)
+          end
+
+          def dependency?
+            true
+          end
+
+          def dependencies
+            to_hash.dependencies
+          end
+
+          ##
+          # Index operator
+          #
+          # Performs intermediate transformation of value if needed (if value is a lambda) and
+          # returns it wrapping into Definition instance with the same context if needed
+          # (if value is a map)
+          def [](k)
+            result = _process_value(@hash[k])
+            result.respond_to?(:to_hash) ? self.class.new(result, @context) : result
+          end
+
+          ##
+          # Check if the key is present in the hash
+          def include?(k)
+            @hash.include?(k)
+          end
+
+          ##
+          # Create wrapper object
+          #
+          # Creates wrapper object with attached hash and context to evaluate lambdas in
+          def initialize(hsh, ctx)
+            @hash = hsh
+            @context = ctx
+          end
+
+          private
+
+          def _process_value(value)
+            if value.respond_to?(:to_hash)
+              value
+            elsif value.respond_to?(:to_proc)
+              @context.instance_eval(&value)
+            else
+              value
+            end
+          end
+
+          def _recurse_into(value)
+            value.each_with_object({}) do |(k, v), memo|
+              processed = _process_value(v)
+              processed = _recurse_into(processed.to_hash) if Utils.hashable?(processed)
+              memo[k] = processed
+            end
+          end
+        end
+
+        instance_scope do
+          ##
+          # Apply specified defaults to options
+          #
+          # It's a mixin method which depends on presence of options accessor
+          # methods in the consuming class. The options property should contain
+          # an object implementing to_hash method. The method is mutating for
+          # options. The algorithm is to walk down the hierarchy of the
+          # class and collect and merge all defaults from its ancestors
+          # prioritizing the ones made later in the class hierarchy. The method
+          # is working correctly with both parent classes and all Default
+          # mixins used in between.
+          def process_options(params = nil)
+            # iterating through all ancestors with defaults
+            ancestors_with_defaults.reverse_each do |mod|
+              # ... through all defaults of particular ancestor
+              mod.defaults.each do |defaults_definition|
+                # merge the default definition with options
+                options.merge!(Definition.new(defaults_definition, self))
+              end
+            end
+
+            # re-inforce caller-specified overrides
+            options.merge!(params) if params
+          end
+
+          private
+
+          def ancestors_with_defaults
+            self
+              .class
+              .ancestors
+              .select do |mod|
+                (mod != Default) && mod.ancestors.include?(Default)
+              end
+          end
+        end
+
+        ##
+        # Class-level mixins
+        #
+        # It's a DSL extension to declaratively define defaults
+        class_scope do
+          ##
+          # Defaults for the input hash
+          #
+          # Class-level accessor of a hash which will be merged into input
+          # parameters hash. The hash can't be changed directly or set to
+          # another value. Only incremental changes are allowed with
+          # default method which is a part of the framework DSL. The method
+          # returns only defaults for the current class without
+          # consideration of the class hierarchy.
+          def defaults
+            @defaults ||= []
+          end
+
+          ##
+          # Put an default/calculation for the input hash
+          #
+          # The class method is the main knob which is used to build
+          # hierarchical hash mutation pipeline using language-provided
+          # features such as class inheritance and introspection. You can
+          # specify either hash (or an object which has :to_hash method) or
+          # a lambda/Proc as a parameter.
+          #
+          # If you specify a hash then it will be merged with the current
+          # value of default where the hash passed will take preference
+          # during the merge.
+          #
+          # If you specify a lambda it will be added to calculations stack
+          #
+          # If the parameter you passed is neither a hash nor callable or
+          # no parameters are passed at all, ArgumentError will be thrown.
+          def default(defaults_hash = nil)
+            raise_defaults_is_nil unless defaults_hash
+            raise_default_type_mismatch(defaults_hash) unless defaults_hash.respond_to?(:to_hash)
+
+            defaults << defaults_hash.to_hash
+          end
+
+          def raise_defaults_is_nil
+            raise ArgumentError.new('Map should be specified')
+          end
+
+          def raise_default_type_mismatch(defaults_hash)
+            raise ArgumentError.new("#{defaults_hash.inspect} is not a hash")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/utils/dependency/enumerable.rb

@@ -0,0 +1,13 @@
+require 'set'
+
+##
+# Dependencies methods definitions for all collections
+module Enumerable
+  def dependencies
+    find_all(&:dependency?).inject(Set.new) { |acc, elem| acc.merge(elem.dependencies) }
+  end
+
+  def dependency?
+    true
+  end
+end

data/lib/aws/templates/utils/dependency/object.rb

@@ -0,0 +1,46 @@
+require 'set'
+require 'aws/templates/utils/dependency'
+
+##
+# Dependency method stubs
+#
+# To avoid checking classes directly to filter out dependencies and non-dependencies, we're
+# monkey-patching Object class with stubs for Dependency class.
+#
+# TODO: Devise a better approach and remove the extension
+class Object
+  EMPTY_SET = Set.new.freeze
+
+  # By default an object is not a dependency
+  def dependency?
+    false
+  end
+
+  # It returns self
+  def object
+    self
+  end
+
+  ##
+  # Object root
+  #
+  # It is used to gracefully process dependencies
+  def root; end
+
+  alias not_a_dependency object
+
+  # it returns a set containing a single dependency on itself
+  def dependencies
+    EMPTY_SET
+  end
+
+  # mark the object as dependency
+  def as_a_dependency
+    Aws::Templates::Utils::Dependency.new(object)
+  end
+
+  # mark the object as dependency of itself
+  def as_a_self_dependency
+    as_a_dependency.to_self
+  end
+end

data/lib/aws/templates/utils/dependency.rb

@@ -0,0 +1,121 @@
+require 'set'
+require 'aws/templates/utils/dependency/object'
+require 'aws/templates/utils/dependency/enumerable'
+
+module Aws
+  module Templates
+    module Utils
+      ##
+      # Dependency marker proxy
+      #
+      # Used internally in the framework to mark an object as potential dependency. There are other
+      # alternatives for doing the same like singleton class and reference object. There are a few
+      # advantages of the approach taken:
+      # * Dependency can be used whereever original object is expected
+      # * Dependecy can be applied case-by-case basis whereas singleton is attached to the object
+      #   itself
+      class Dependency < BasicObject
+        ##
+        # Equality
+        #
+        # Two Dependency objects are equal if it's the same object or if they are pointing to the
+        # same target.
+        def eql?(other)
+          equal?(other) || ((self.class == other.class) && (object == other.object))
+        end
+
+        ##
+        # Alias for #eql?
+        def ==(other)
+          eql?(other)
+        end
+
+        # Non-equality
+        def !=(other)
+          !eql?(other)
+        end
+
+        # BasicObject is so basic that this part is missing too
+        def class
+          Dependency
+        end
+
+        # It's a dependency
+        def dependency?
+          true
+        end
+
+        # mark the object as dependency
+        def as_dependency
+          self
+        end
+
+        attr_reader :object
+        attr_reader :dependencies
+
+        ##
+        # Redirect every method call to the proxied object if the object supports it
+        def method_missing(name, *args, &block)
+          object.respond_to?(name) ? object.send(name, *args, &block) : super
+        end
+
+        ##
+        # It supports every method proxied object supports
+        def respond_to_missing?(name, include_private = false)
+          object.respond_to?(name, include_private) || super(name, include_private)
+        end
+
+        ##
+        # Add dependency
+        #
+        # Add a link to the target to the current Dependency object
+        def to(target)
+          if target.dependency?
+            dependencies.merge(target.dependencies)
+          else
+            dependencies << target
+          end
+
+          self
+        end
+
+        ##
+        # Link the value to the source
+        #
+        # Links source or result of calculation of the block to the target object of the dependency.
+        # The mecahanism is a middle ground between extreme case of indefinite recursive dependency
+        # propagation and no propagation at all
+        #
+        #    some_artifact.as_a_dependency.with { some_attribute }
+        #    # => Dependency(@object = <some_attribute value>, <link to some_artifact>)
+        def with(source = nil, &source_calculation_block)
+          value = if source_calculation_block.nil?
+            source
+          else
+            object.instance_exec(value, &source_calculation_block)
+          end
+
+          value.as_a_dependency.to(self)
+        end
+
+        ##
+        # Set dependency to the target
+        def to_self
+          to(object)
+        end
+
+        ##
+        # Initialize the proxy
+        def initialize(source_object)
+          @object = source_object.object
+
+          @dependencies = if source_object.dependency?
+            source_object.dependencies.dup
+          else
+            ::Set.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/utils/dependent.rb

@@ -0,0 +1,28 @@
+require 'aws/templates/utils/dependency/object'
+require 'set'
+
+module Aws
+  module Templates
+    module Utils
+      ##
+      # Dependency node mixin
+      #
+      # Introduces methods needed to track dependencies of an object. The object needs to implement
+      # options method and root method.
+      module Dependent
+        ##
+        # Introduce dependencies manually
+        #
+        # Dependencies are calculated from "options" recursive structure by traversal and location
+        # of all dependencies automatically. If some dependency is not logical/parametrical but
+        # purely chronological, it can be introduced into the dependency list with this method.
+        def depends_on(*depends)
+          new_dependencies = depends.dependencies
+          new_dependencies.select! { |obj| obj.root == root } unless root.nil?
+          dependencies.merge(new_dependencies)
+          self
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/utils/inheritable.rb

@@ -0,0 +1,52 @@
+module Aws
+  module Templates
+    module Utils
+      ##
+      # Introduces class method inheritance through module hierarchy
+      module Inheritable
+        ##
+        # Core class-level mixins
+        #
+        # Contains core logic of the inheritance feature. This module is used as extention
+        # in every including module/class to expose appropriate module-level primitives for
+        # handling inheritance of class-scope methods.
+        module ClassMethods
+          DEFAULT_MODULE = Module.new.freeze
+
+          ##
+          # To add class methods also while including the module
+          def included(base)
+            super(base)
+            base.extend(Inheritable::ClassMethods)
+            base._merge_class_scope(class_scope || DEFAULT_MODULE)
+          end
+
+          def instance_scope(&blk)
+            module_eval(&blk)
+          end
+
+          def class_scope(&blk)
+            if blk
+              @class_scope.module_eval(&blk)
+              extend @class_scope
+            end
+
+            @class_scope
+          end
+
+          def _merge_class_scope(mod)
+            if @class_scope.nil?
+              @class_scope = mod.dup
+            else
+              @class_scope.include(mod)
+            end
+
+            extend @class_scope
+          end
+        end
+
+        extend ClassMethods
+      end
+    end
+  end
+end

data/lib/aws/templates/utils/late_bound.rb

@@ -0,0 +1,89 @@
+require 'aws/templates/utils/inheritable'
+
+module Aws
+  module Templates
+    module Utils
+      ##
+      # Late binding utilities
+      #
+      # Late binding is a technique of referencing values which don't exist at the template
+      # calculation stage. Examples could be Process ID, SQL record calculated ID or AWS object
+      # ARN you're creating through a script or CFN template.
+      #
+      # The module provides DSL for creating late binding points known as References.
+      module LateBound
+        include Inheritable
+
+        ##
+        # Reference
+        #
+        # Reference is a special placeholder object designed to point to the object reference was
+        # created for with optional path and args attached.
+        #
+        # References are used when the final value of an object property is unknown at the template
+        # calculation stage and can be extracted only when the final rendered view is submitted to
+        # the target system (late binding)
+        class Reference
+          attr_reader :instance
+          attr_reader :path
+          attr_reader :arguments
+
+          FAILURE_MESSAGES = {
+            to_s: 'string',
+            to_i: 'integer',
+            to_f: 'float',
+            to_a: 'array',
+            to_h: 'hash',
+            to_str: 'string',
+            to_int: 'integer',
+            to_ary: 'array',
+            to_hash: 'hash',
+            to_proc: 'proc'
+          }.freeze
+
+          FAILURE_MESSAGES.each_pair do |method_name, type_name|
+            define_method(method_name) do
+              raise(
+                "Reference can't be transformed to #{type_name} or paricipate in any operations" \
+                'References are placeholders for values which don\'t exist at the template ' \
+                'calculation stage (late binding)'
+              )
+            end
+          end
+
+          def initialize(target_instance, target_path = nil, args = nil)
+            @instance = target_instance
+            @path = target_path
+            @arguments = args
+          end
+        end
+
+        instance_scope do
+          ##
+          # Create reference
+          #
+          # Create and return Reference object attached to the current instance with specified path
+          # and arguments
+          def reference(path = nil, *args)
+            Reference.new(self, path, args)
+          end
+        end
+
+        ##
+        # Class-level DSL
+        class_scope do
+          ##
+          # Wrap reference for postponed instantiation
+          #
+          # References are instance-level objects so they can be attached only to an instance, not
+          # to a class. So, to be able to do that in "default" section in an artifact, for instance,
+          # you need to specify a proc/lambda object for the option. This method makes the wrappin
+          # unnecessary.
+          def reference(path = nil, *args)
+            -> { reference(path, *args) }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/utils/memoized.rb

@@ -0,0 +1,27 @@
+module Aws
+  module Templates
+    module Utils
+      ##
+      # Simple memoization facility
+      module Memoized
+        # Cancel all memoizations
+        def dirty!
+          @memoized = nil
+          self
+        end
+
+        ##
+        # Memoize block result
+        #
+        # Return memoized value with the ID. If slot is empty - call the block
+        def memoize(id)
+          memoized[id] ||= yield
+        end
+
+        def memoized
+          @memoized ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/aws/templates/utils/named.rb

@@ -0,0 +1,19 @@
+require 'aws/templates/utils/parametrized'
+require 'aws/templates/utils/parametrized/constraints'
+
+module Aws
+  module Templates
+    module Utils
+      ##
+      # Named parametrized object mixin
+      #
+      # Provides a simple utility to define artifacts/objects which have
+      # "name" parameter which should be present as :name in the input hash
+      module AsNamed
+        include Parametrized
+
+        parameter :name, description: 'Name of the object', constraint: not_nil
+      end
+    end
+  end
+end