cloud-templates 0.1.0

data/lib/aws/templates/artifact.rb

@@ -0,0 +1,140 @@
+require 'aws/templates/utils/parametrized'
+require 'aws/templates/utils/parametrized/getters'
+require 'aws/templates/utils/parametrized/constraints'
+require 'aws/templates/utils/default'
+require 'aws/templates/utils/options'
+require 'aws/templates/utils/dependent'
+
+module Aws
+  module Templates
+    ##
+    # Basic artifact
+    #
+    # "Artifact" in the terminology of the framework is an entity which
+    # can represent any parametrizable object type from any problem domain
+    # possible. For instance, for CloudFormation, artifacts are resources
+    # in a CFN template, the template itself
+    #
+    # If your target domain is infrastructure orchestration, artifact is
+    # usually a single entity such as S3 volume, ASG, DynamoDB table, etc.
+    # However, the notion of artifact is not particularly fixed since the
+    # framework can be used for different purposes including documents
+    # generation and general templating tasks. Basically, artifact is a
+    # single parametrizable entity or a step in input hash
+    # transformations.
+    #
+    # Artifact classes work together with meta-programming mechanisms in
+    # Ruby language enabling artifacts inheritance in the natural way
+    # using simple Ruby classes. The feature is useful when you have a
+    # group of artifacts which share the same basic parameters but differ
+    # in details.
+    #
+    # The central part in the framework is played by processed hash. All
+    # mechanisms are based on simple ad-hoc merging rules which are
+    # described at merge method but basis can be described as following:
+    # each superclass initializer accepts children class processed hash
+    # as input hash and the hash is processed recursively through
+    # class hierarchy. Old values are newer removed by default so the
+    # whole process is no more than continuous hash expansion.
+    #
+    #    class Piece < Artifact
+    #      default { { output: options[:param] } }
+    #    end
+    #
+    #    class ConcretePiece < Piece
+    #      default param: 'Came from child'
+    #    end
+    #
+    #    Piece.new(a: 1, b: 2).options.to_hash # => { a: 1, b: 2, output: nil }
+    #    ConcretePiece.new(a: 1, b: 2).options.to_hash
+    #    # => { a: 1, b: 2, output: 'Came from child', param: 'Came from child' }
+    #
+    # Also, as one of the peculiarities of the framework, you can override
+    # any auto-generated parameter with input hash if they have the same
+    # name/path.
+    class Artifact
+      include Utils::Default
+      include Utils::Parametrized
+      include Utils::Dependent
+
+      attr_accessor :options
+
+      def self.getter
+        as_is
+      end
+
+      def self.to_s
+        return super unless name.nil?
+        "<Subclass of (#{superclass}) with features #{features}>"
+      end
+
+      def self.features
+        @features ||= ancestors.take_while { |mod| mod != superclass }
+      end
+
+      # Create new child class with mixins
+      #
+      # The class method is useful when you want to mix-in some behavior adjustments
+      # without creating a new named class. For instance when you want to mix-in
+      # some defaults into class and instantiate a few instances out of that.
+      def self.featuring(*modules)
+        return self if modules.empty?
+
+        modules.inject(Class.new(self)) do |klass, mod|
+          klass.send(:include, mod)
+        end
+      end
+
+      ##
+      # Artifact's label
+      #
+      # All artifacts have labels assigned to them to simplify reverse
+      # look-up while linking dependencies. Interpretation of this field is purely
+      # application-specific.
+      default label: proc { object_id }
+
+      parameter :label, description: 'Artifact\'s label', constraint: not_nil
+
+      ##
+      # Artifact's root
+      #
+      # A root is an object which bundles artifacts into common rendering group helping to find
+      # disconnected pieces of dependency graph. If two artifacts have different roots they
+      # definitelly belong to different graphs.
+      default root: proc { object_id }
+
+      def root
+        options[:root]
+      end
+
+      ##
+      # Artifact's parent
+      #
+      # Artifacts can be organized into a hierarchy of composition. This field points back to the
+      # artifact's parent.
+      parameter :parent, description: 'Artifact parent'
+
+      ##
+      # Create a new artifact
+      #
+      # Artifact constructor. If you want to override it you might probably
+      # want to look into default first. All default values specified in the
+      # class definition and all its ancestors are processed and merged with
+      # options so it contains fully-processed hash.
+      #
+      # The algorithm of the processing is the following:
+      # * merge defaults hash with passed options; options take precedence
+      # * merge the hash with default calculations return results; calculations output
+      #   takes preference
+      # * pass resulting hash to superclass initializer
+      # * merge resulting hash with options; options take preference
+      #
+      # * +params+ - input parameters hash to be used during following
+      #              hash transformations and expansions.
+      def initialize(params)
+        @options = Utils::Options.new(params)
+        process_options(params)
+      end
+    end
+  end
+end

data/lib/aws/templates/composite.rb

@@ -0,0 +1,178 @@
+require 'aws/templates/artifact'
+require 'aws/templates/utils/artifact_storage'
+require 'aws/templates/utils/contextualized'
+require 'aws/templates/utils/dependency'
+
+module Aws
+  module Templates
+    ##
+    # Composite
+    #
+    # Composite is an artifact which contain other artifacts and provide
+    # DSL syntax sugar to define it
+    #
+    # A composite can represent complex entities as CloudFormation
+    # stacks which can contain settings and infrastructure artifacts inside it.
+    # However, it's still a single entity which may be versioned as a
+    # whole and can represent the current state of deployed application.
+    #
+    # Composite is still an artifact and has all methods inherited so
+    # besides grouping different artifacts alltogether you can process
+    # input parameters too.
+    #
+    # Composite is a recursive structure as a result of being an artifact
+    # so you can construct arbitrary deep hierarchies of objects. Also it
+    # supports inheritance as artifact does. So every component defined in
+    # the parent class will be initialized properly in all children too.
+    class Composite < Artifact
+      include Aws::Templates::Utils::Contextualized
+
+      # propagate root to the components and set itself as the parent
+      contextualize filter(:add, :root) & (filter(:override) { { parent: self } })
+
+      ##
+      # Dictionary of artifacts and their labels the composite is
+      # consisting of
+      #
+      # Accessor returning dictionary of artifacts currently residing in
+      # composite instance with labels as keys
+      def artifacts
+        @artifacts ||= Utils::ArtifactStorage.new
+      end
+
+      ##
+      # Shortcut for accessing artifacts by their labels
+      #
+      # The method returns either stored artifact object or throws a
+      # descriptive exception.
+      def [](artifact_label)
+        unless artifacts.key?(artifact_label)
+          raise "There is no artifact #{artifact_label}" \
+            " in composite #{label}"
+        end
+
+        artifacts[artifact_label].as_a_dependency.to_self
+      end
+
+      def []=(artifact_label, artifact_object)
+        if artifacts.key?(artifact_label)
+          if artifacts[artifact_label] != artifact_object.object
+            raise "Artifact #{artifact_label} is already present " \
+              "in composite #{label}"
+          end
+        else
+          artifacts[artifact_label] = artifact_object.object
+        end
+
+        artifact_object.as_a_dependency.to_self
+      end
+
+      ##
+      # Artifacts definition block for DSL
+      #
+      # An element of the framework DSL. Allows you to define
+      # composite's artifacts declaratively with using standard language
+      # features.
+      def self.components(*args, &blk)
+        define_method(:create_components) do
+          super()
+          instance_exec(*args, &blk)
+        end
+
+        self
+      end
+
+      ##
+      # Add components into the composite's instance
+      #
+      # Analog of class-level "components" method to add components after
+      # artifact creation when using class-level definitions are not
+      # appropriate
+      def components(&blk)
+        instance_exec(&blk)
+        self
+      end
+
+      ##
+      # Syntax sugar to create composite classes on spot
+      #
+      # Create a new child class of the current class and executes a
+      # block in the context of the class object optionally passing a list
+      # of arguments to it.
+      def self.for(*args, &blk)
+        klass = Class.new(self)
+        klass.instance_eval(*args, &blk) unless blk.nil?
+        klass
+      end
+
+      ##
+      # Artifact definition constructor in DSL
+      #
+      # Defines a single artifact in composite's definition block. This
+      # method was designed to be used inside of composite block but you
+      # can use it elsewhere else applied on a class instance.
+      #
+      # * +type+ - artifact type (class)
+      # * +params+ - optional map of artifact options
+      # * +blk+ - a block which will be passed to artifacts constructor;
+      #           applications may vary but particular one is adding
+      #           artifacts into composite during instantiation
+      def artifact(type, params = nil, &blk)
+        artifact_object = create_artifact_object(type, params, &blk)
+        self[artifact_object.label] = artifact_object
+        artifact_object.as_a_dependency.to_self
+      end
+
+      ##
+      # Put labels on the artifact
+      #
+      # Put the artifact into the artifact storage under arbitrary aliases.
+      #
+      # * +artifact_object+ - artifact object to put
+      # * +labels+ - labels to assign to the artifact
+      def label_as(artifact_object, *labels)
+        labels.flatten.each do |artifact_label|
+          self[artifact_label] = artifact_object
+        end
+
+        artifact_object
+      end
+
+      ##
+      # Provisions parameters and initializes nested artifacts
+      def initialize(*params, &blk)
+        super(*params)
+        create_components
+        instance_exec(&blk) if blk
+      end
+
+      ##
+      # Find artifacts by criteria
+      #
+      # The method allows flexible introspection of the artifacts
+      # enclosed into the composite's storage. The method is just a proxy
+      # for the storage method with the same name
+      #
+      # * +search_params+ - map of search parameters:
+      # ** +recursive+ - if true, search will be performed recusrsively
+      #                  in nested composites
+      # ** +label+ - search for artifacts which have the label
+      # ** +parameters+ - search for artifacts which have specified
+      #                   parameters values; it's a multi-level map so
+      #                   you can check for nested values also
+      def search(search_params = {})
+        artifacts.search(search_params)
+      end
+
+      protected
+
+      def create_components; end
+
+      private
+
+      def create_artifact_object(type, params, &blk)
+        type.new(options.filter(&contextualize(params.to_filter)), &blk)
+      end
+    end
+  end
+end

data/lib/aws/templates/exceptions.rb

@@ -0,0 +1,221 @@
+module Aws
+  module Templates
+    ##
+    # Parameter definition exception
+    #
+    # Meta-programming exception related to Parametrized DSL
+    class ParametrizedDSLError < StandardError
+    end
+
+    ##
+    # Parameter already exists
+    #
+    # If you're trying to define a parameter in a parametrized artifact
+    # and this parameter either already defined for the class or defined
+    # in an ancestor.
+    class ParameterAlreadyExist < ParametrizedDSLError
+      # Parameter object of the conflicting parameter
+      attr_reader :parameter
+
+      def initialize(target_parameter)
+        @parameter = target_parameter
+        super(
+          "Parameter #{target_parameter.name} already in " \
+          "#{target_parameter.klass}."
+        )
+      end
+    end
+
+    ##
+    # Invalid parameter specification hash
+    #
+    # If unknown option is passed in a parameter description block
+    class ParameterSpecificationIsInvalid < ParametrizedDSLError
+      # Parameter object faulty options were specified for
+      attr_reader :parameter
+
+      # Options unknown to Parametrized
+      attr_reader :options
+
+      def initialize(target_parameter, opts)
+        @parameter = target_parameter
+        @options = opts
+
+        super(
+          'Unsupported options are in specification for ' \
+          "parameter #{target_parameter.name} in class " \
+          "#{target_parameter.klass} : #{opts}"
+        )
+      end
+    end
+
+    ##
+    # A regular method and a parameter have the same name in a class
+    #
+    # A parameter was specified with the same name as exsiting method
+    # in the class or in an ancestor of the class.
+    class ParameterMethodNameConflict < ParametrizedDSLError
+      # Method object of the method specified
+      attr_reader :method_object
+
+      def initialize(target_method)
+        @method_object = target_method
+
+        super(
+          "Parameter name #{target_method.name} clashes with a method name in " \
+          "#{target_method.owner.name}"
+        )
+      end
+    end
+
+    ##
+    # View was not found for the object
+    #
+    # View map was checked and there is no appropriate view class
+    # for the object class found in the registry.
+    class ViewNotFound < RuntimeError
+      # Instance of the object class render lookup was performed for
+      attr_reader :instance
+
+      def message
+        "Can't find any view for #{instance} of class #{instance.class}"
+      end
+
+      def initialize(target_instance)
+        super()
+        @instance = target_instance
+      end
+    end
+
+    ##
+    # Parameter exception
+    #
+    # Happens during runtime if an error happens during parameter
+    # evaluation
+    class ParameterException < RuntimeError
+      # Parameter object
+      attr_reader :parameter
+
+      def message
+        cause.nil? ? super : "#{super} : #{cause.message}"
+      end
+
+      def initialize(target_parameter, custom_message)
+        @parameter = target_parameter
+        super(custom_message)
+      end
+    end
+
+    ##
+    # If something happens during parameter calculation
+    class NestedParameterException < ParameterException
+      def initialize(target_parameter)
+        super(
+          target_parameter,
+          'Exception was thrown by nested parameter while calculating ' \
+            "#{target_parameter.name} (#{target_parameter.description})"
+        )
+      end
+    end
+
+    ##
+    # A value failed constraints
+    class ParameterValueInvalid < ParameterException
+      attr_reader :value
+      attr_reader :object
+
+      def initialize(target_parameter, target_object, target_value)
+        @value = target_value
+        @object = target_object
+        super(
+          target_parameter,
+          message_text(target_parameter, target_object, target_value)
+        )
+      end
+
+      private
+
+      def message_text(target_parameter, target_object, target_value)
+        message = "Value '(#{target_value.inspect})' violates constraints specified for " \
+          "#{target_parameter.name} (#{target_parameter.description}) in " \
+          "#{target_parameter.klass}"
+
+        unless target_object.class == target_parameter.klass
+          message += " and inherited by #{target_object.class}"
+        end
+
+        message
+      end
+    end
+
+    ##
+    # Getter is not specified
+    #
+    # Getter wasn't specified neither for the individual parameter nor for the mixing instance nor
+    # for its class.
+    class ParameterGetterIsNotDefined < ParameterException
+      def initialize(target_parameter)
+        super(
+          target_parameter,
+          "Can't find getter for #{target_parameter.name} (#{target_parameter.description}): " \
+            'a getter should be attached either to the parameter or the instance ' \
+            'or the instance class'
+        )
+      end
+    end
+
+    ##
+    # Options exception
+    #
+    # The parent of all exceptions Options method can throw
+    class OptionError < ArgumentError
+    end
+
+    ##
+    # Recursive value is expected
+    #
+    # Value passed doesn't not support "recursive" contract. See Utils.recursive?
+    class OptionShouldBeRecursive < OptionError
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+        super("Value #{value} is not a recursive data structure")
+      end
+    end
+
+    ##
+    # Deleted branch detected
+    #
+    # While traversing Options layers for a value, deleted branch marker was discovered.
+    class OptionValueDeleted < OptionError
+      attr_reader :path
+
+      def initialize(path)
+        @path = path
+        super(
+          "Deleted value was detected while traversing path. The path left untraversed: #{path}"
+        )
+      end
+    end
+
+    ##
+    # Scalar is met while traversing Options path
+    #
+    # Path is not empty yet but we can't traverse deeper because the current value is a scalar
+    class OptionScalarOnTheWay < OptionError
+      attr_reader :value
+      attr_reader :path
+
+      def initialize(value, path)
+        @value = value
+        @path = path
+
+        super(
+          "Value #{value} is not a recursive data structure and we have still #{path} keys " \
+            'to look-up'
+        )
+      end
+    end
+  end
+end

data/lib/aws/templates/render/registry.rb

@@ -0,0 +1,60 @@
+require 'aws/templates/exceptions'
+
+module Aws
+  module Templates
+    module Render
+      ##
+      # View registry
+      #
+      # View registries encapsulate differerent ways of transforming
+      # your artifacts into a domain-specific output.
+      # In nutshell, they are registries of View classes which are able
+      # to lookup proper View for object instance passed to it.
+      class Registry
+        # View registry accessor
+        def registry
+          @registry ||= {}
+        end
+
+        ##
+        # Register pair artifact-view
+        #
+        # Invoked from inside of a View class at definition of the link
+        # between the view class and an artifact
+        # * +artifact+ - artifact class the view claims to be able to render
+        # * +render+ - view class
+        def register(artifact, view)
+          registry[artifact] = view
+        end
+
+        ##
+        # Can object be rendered
+        #
+        # Returns true if the object passed can be rendered by one of the views in the registry
+        def can_render?(instance)
+          instance.class.ancestors.any? { |ancestor| registry.include?(ancestor) }
+        end
+
+        ##
+        # Lookup a view for the artifact
+        #
+        # Searches registry for artifact's class and all its ancestors
+        # in the registry and returns the closest matching view
+        # * +instance+ - artifact instance to render
+        # * +params+ - assigned parameters; it can be arbitrary value;
+        #              it is propagated to selected render
+        def view_for(instance, params = nil)
+          return instance if instance.respond_to?(:to_rendered)
+
+          mod = instance.class.ancestors.find do |ancestor|
+            registry.include?(ancestor)
+          end
+
+          raise ViewNotFound.new(instance) unless mod
+
+          registry[mod].new(instance, params)
+        end
+      end
+    end
+  end
+end