kerbi 0.0.1 → 0.0.2

data/lib/main/errors.rb

@@ -0,0 +1,109 @@
+module Kerbi
+  class Error < ::StandardError
+  end
+
+  class StateBackendNotReadyError < Error
+    MSG = "State-keeping backend not ready. Run 'kerbi state status' for more."
+
+    def initialize(msg = MSG)
+      super
+    end
+  end
+
+  class IllegalEntryTag < Error
+    def initialize(msg = "State entry tag cannot be 'latest'")
+      super
+    end
+  end
+
+  class IllegalConfigWrite < Error
+    LEGAL = Kerbi::Consts::OptionKeys::LEGAL_CONFIG_FILE_KEYS
+    def initialize(key)
+      super("Illegal config assignment. '#{key}' not in #{LEGAL}")
+    end
+  end
+
+  class BadEntryQueryForWrite < Error
+    MSG = "write-state needs an existing entry id/tag, 'candidate', or 'latest'"
+    def initialize(msg = MSG)
+      super
+    end
+  end
+
+  class IllegalWriteStateTagWordError < Error
+    MSG = "Tag names for writing cannot contain special words exclusive to tag "
+    def initialize(msg = MSG)
+      super
+    end
+  end
+
+  class StateNotFoundError < Error
+    def initialize(tag='')
+      super("State given by tag #{tag} not found")
+    end
+  end
+
+  class StateNotPromotable < Error
+    MSG = "Non-candidate states cannot be promoted"
+    def initialize(msg = MSG)
+      super
+    end
+  end
+
+  class StateNotDemotable < Error
+    MSG = "Candidate states cannot be demoted"
+    def initialize(msg = MSG)
+      super
+    end
+  end
+
+  class NoSuchStateAttrName < Error
+    MSG = "This attribute does not exist or is not writeable"
+    def initialize(msg = MSG)
+      super(MSG)
+    end
+  end
+
+  class ValuesFileNotFoundError < Error
+    def initialize(fname_expr: , root: )
+      msg = "Could not resolve values file '#{fname_expr}' in #{root}"
+      super(msg)
+    end
+  end
+
+  class KerbifileNotFoundError < Error
+    def initialize(root: )
+      msg = "Could not resolve kerbifile in #{root}"
+      super(msg)
+    end
+  end
+
+  class EntryValidationError < Error
+    MSG = "Cannot write state because of validation errors: "
+
+    # @param [Hash] errors
+    def initialize(errors)
+      message = self.class.build_message(errors)
+      super(message)
+    end
+
+    # @param [Hash] errors
+    def self.error_line(error)
+      "#{error[:attr]}['#{error[:value]}']: #{error[:msg]}".indent(1)
+    end
+
+    # @param [String] tag
+    # @param [Array<Hash>] errors
+    def self.entry_line(tag, error_dicts)
+      per_tag_parts = error_dicts.map{ |d| error_line(d) }
+      "Entry['#{tag}'] \n #{per_tag_parts.join("\n")}".indent(1)
+    end
+
+    # @param [Hash] errors
+    def self.build_message(errors)
+      parts = errors.map { |h| entry_line(h[0], h[1]) }
+      "#{MSG} \n#{parts.join("\n")}"
+    end
+  end
+
+end

data/lib/main/mixer.rb

@@ -45,7 +45,7 @@ module Kerbi
     def run
       begin
         self.mix
-      rescue Exception => e
+      rescue Error => e
         puts "Exception below caused by mixer #{self.class.name}"
         raise e
       end
@@ -202,15 +202,19 @@ module Kerbi
         subtree.freeze
       end
 
-      def resolve_file_name(fname)
+      ## Resolves a user-given short name for a file to interpolate,
+      # like 'pod', 'pod.yaml', into an absolute file path.
+      # @param [String] fname_expr e.g 'pod', 'pod.yaml'
+      # @return [?String]
+      def resolve_file_name(fname_expr)
         dir = self.pwd
         Kerbi::Utils::Misc.real_files_for(
-          fname,
-          "#{fname}.yaml",
-          "#{fname}.yaml.erb",
-          "#{dir}/#{fname}",
-          "#{dir}/#{fname}.yaml",
-          "#{dir}/#{fname}.yaml.erb"
+          fname_expr,
+          "#{fname_expr}.yaml",
+          "#{fname_expr}.yaml.erb",
+          "#{dir}/#{fname_expr}",
+          "#{dir}/#{fname_expr}.yaml",
+          "#{dir}/#{fname_expr}.yaml.erb"
         ).first
       end
 

data/lib/mixins/cli_state_helpers.rb

@@ -0,0 +1,136 @@
+module Kerbi
+  module Mixins
+    module CliStateHelpers
+
+      protected
+
+      ##
+      # Convenience method that returns the state backend's entry set.
+      # @return [Kerbi::State::EntrySet]
+      def entry_set
+        state_backend.entry_set
+      end
+
+      ##
+      # For commands that need a working state backend,
+      # ask the backend if it is operational, and raise otherwise.
+      def raise_unless_backend_ready
+        unless state_backend.read_write_ready?
+          raise Kerbi::StateBackendNotReadyError
+        end
+      end
+
+      ##
+      # Convenience method for invoking #find_entry_for_read
+      # on the state backend's entry-set.
+      # @return [Kerbi::State::Entry]
+      def find_readable_entry(tag_expr)
+        entry_set.find_entry_for_read(tag_expr)
+      end
+
+      ##
+      # Convenience method for updating a state entry's created_at
+      # and then persisting the new list of entries via the state backend.
+      # Also optionally pretty prints changes.
+      # @param [Kerbi::State::Entry] entry
+      def touch_and_save_entry(entry, changes={})
+        entry.created_at = Time.now
+        state_backend.save
+        if changes && (change = changes.first)
+          key, old_value = change
+          new_value = entry.send(key) rescue "ERR"
+          name = "state[#{entry.tag}].#{key}"
+          change_str = "from #{old_value} => #{new_value}"
+          echo "Updated #{name} #{change_str}".colorize(:green)
+        end
+      end
+
+      ##
+      # Given a tag by read-state [TAG], find the corresponding
+      # state entry and return its values dict.
+      #
+      # If the state entry is NOT found, an empty dict is returned,
+      # unless the strict-read option is also passed, in which
+      # case it raises a fatal exception.
+      # @return [Hash{Symbol->String}]
+      def read_state_values
+        if run_opts.reads_state?
+          expr = run_opts.read_state_from
+          begin
+            entry = entry_set.find_entry_for_read(expr)
+            entry.values.deep_dup.deep_symbolize_keys
+          rescue Kerbi::StateNotFoundError => e
+            raise e if run_opts.reads_state_strictly?
+            {}
+          end
+        else
+          {}
+        end
+      end
+
+      ##
+      # Given a tag by write-state [TAG], find or create a state entry
+      # and assign its values and default_values to the respective
+      # just values and default_values just compiled.
+      def persist_compiled_values
+        if run_opts.writes_state?
+          raise_unless_backend_ready
+          expr = run_opts.write_state_to
+          entry = entry_set.find_or_init_entry_for_write(expr)
+
+          entry.values = compile_values.deep_dup
+          entry.default_values = compile_default_values.deep_dup
+          entry.created_at = Time.now
+
+          state_backend.save
+        end
+      end
+
+      ##
+      # Given the state-backend parameter or config value,
+      # generate an instance of the corresponding backend
+      # class.
+      # @return [Kerbi::State::Backend]
+      def generate_state_backend(namespace=nil)
+        if run_opts.state_backend_type == 'configmap'
+          auth_bundle = make_k8s_auth_bundle
+          Kerbi::State::ConfigMapBackend.new(
+            auth_bundle,
+            namespace || run_opts.cluster_namespace
+          )
+        end
+      end
+
+      ##
+      # Given the various Kubernetes authentication options and
+      # configs, generates a Hash with the necessary data/schema
+      # to pass onto the internal k8s authentication logic.
+      #
+      # This method only delegates. Actual work done is done here at:
+      # Kerbi::Utils::K8sAuth.
+      # @return [Hash] auth bundle for the k8s authentication logic.
+      def make_k8s_auth_bundle
+        case run_opts.k8s_auth_type
+        when "kube-config"
+          Kerbi::Utils::K8sAuth.kube_config_bundle(
+            path: run_opts.kube_config_path,
+            name: run_opts.kube_context_name
+          )
+        when "basic"
+          Kerbi::Utils::K8sAuth.basic_auth_bundle(
+            username: run_opts.k8s_auth_username,
+            password: run_opts.k8s_auth_password
+          )
+        when "token"
+          Kerbi::Utils::K8sAuth.token_auth_bundle(
+            bearer_token: run_opts.k8s_auth_token,
+            )
+        when "in-cluster"
+          Kerbi::Utils::K8sAuth.in_cluster_auth_bundle
+        else
+          raise "Bad k8s connect type '#{run_opts.k8s_auth_type}'"
+        end
+      end
+    end
+  end
+end

data/lib/mixins/cm_backend_testing.rb

@@ -0,0 +1,95 @@
+module Kerbi
+  module Mixins
+    module CmBackendTesting
+
+      # @return [TrueClass, FalseClass]
+      def namespace_exists?
+        begin
+          !!client("v1").get_namespace(namespace)
+        rescue Kubeclient::ResourceNotFoundError
+          false
+        end
+      end
+
+      def resource_exists?
+        begin
+          !!resource
+        rescue Kubeclient::ResourceNotFoundError
+          false
+        end
+      end
+
+      def read_write_ready?
+        namespace_exists? && resource_exists?
+      end
+
+      def test_connection(options={})
+        res_name = Kerbi::State::Consts::RESOURCE_NAME
+        exceptions = []
+
+        schema = [
+          {
+            method: :client,
+            message: "1. Create Kubernetes client"
+          },
+          {
+            method: :test_list_namespaces,
+            message: "2. List cluster namespaces"
+          },
+          {
+            method: :test_target_ns_exists,
+            message: "3. Target namespace #{namespace} exists"
+          },
+          {
+            method: :load_resource,
+            message: "4. Resource #{namespace}/cm/#{res_name} exists"
+          }
+        ]
+
+        schema.each do |spec|
+          begin
+            self.send(spec[:method])
+            puts_outcome(spec[:message], true)
+          rescue StandardError => e
+            puts_outcome(spec[:message], false)
+            exceptions << { exception: e, test: spec[:message] }
+          end
+        end
+
+        if exceptions.any? && options[:verbose]
+          puts "\n---EXCEPTIONS---\n".colorize(:red).bold
+          exceptions.each do |exc|
+            puts "[#{exc[:test]}] #{exc[:exception]}".to_s.colorize(:red).bold
+            puts exc[:exception].backtrace
+            puts "\n\n"
+          end
+        end
+      end
+
+      def test_list_namespaces
+        client("v1").get_namespaces.any?
+      end
+
+      def test_target_ns_exists
+        client.get_namespace namespace
+      end
+
+      #noinspection RubyResolve
+      def puts_outcome(msg, result)
+        outcome_str = result.present? ? "Success" : "Failure"
+        color = result.present? ? :green : :red
+        outcome_str = outcome_str.colorize(color)
+        puts "#{msg}: #{outcome_str}".bold
+      end
+
+      def echo_init(msg, result, options={})
+        unless options[:quiet].present?
+          outcome_str = result.present? ? "Already existed" : "Created"
+          color = result.present? ? :green : :blue
+          outcome_str = outcome_str.colorize(color)
+          puts "#{msg}: #{outcome_str}".bold
+        end
+      end
+    end
+  end
+end

data/lib/mixins/entry_tag_logic.rb

@@ -0,0 +1,183 @@
+module Kerbi
+  module Mixins
+
+    ##
+    # Mixin for handling mission critical state entry tag logic. The logic
+    # is most comprised name resolution, i.e turning special words that users
+    # pass in place of literal tags, into literal tags.
+    module EntryTagLogic
+      extend ActiveSupport::Concern
+
+      SPECIAL_CHAR = "@"
+
+      CANDIDATE_WORD = "candidate"
+      NEW_CANDIDATE_WORD = "new-candidate"
+      LATEST_WORD = "latest"
+      OLDEST_WORD = "oldest"
+      RANDOM_WORD = "random"
+
+      SPECIAL_READ_WORDS = [
+        CANDIDATE_WORD,
+        LATEST_WORD,
+        OLDEST_WORD
+      ]
+
+      SPECIAL_WRITE_WORDS = [
+        LATEST_WORD,
+        OLDEST_WORD,
+        CANDIDATE_WORD,
+        NEW_CANDIDATE_WORD,
+        RANDOM_WORD
+      ]
+
+      ##
+      # Calls #do_resolve_tag_expr with verb=write in order to turn
+      # an entry tag expression like @candidate-new into [cand]purple-forest-new.
+      #
+      # See documentation for #resolve_word for information on how resolution
+      # works at the word level.
+      # @param [String] tag_expr
+      # @return [String]
+      def resolve_write_tag_expr(tag_expr)
+        do_resolve_tag_expr(tag_expr, "write")
+      end
+
+      ##
+      # Calls #do_resolve_tag_expr with verb=read in order to turn
+      # an entry tag expression like @latest into 2.1.1
+      #
+      # See documentation for #resolve_word for information on how resolution
+      # works at the word level.
+      # @param [String] tag_expr
+      # @return [String]
+      def resolve_read_tag_expr(tag_expr)
+        do_resolve_tag_expr(tag_expr, "read")
+      end
+
+      ## Main logic to template state entry tag expressions (that users use
+      # to identify state entries with) into a final, usable tag.
+      #
+      # The method finds special words in the tag expression, which start with
+      # the SPECIAL_CHAR '@', and substitutes them one at a time with a computed
+      # value. For instance, @latest will become the actual tag of the latest state
+      # entry, and @random will become a random string.
+      #
+      # Depending on whether the user's request is for reading or writing an entry,
+      # different substitutions are available.
+      # @return [String]
+      # @param [String] tag_expr
+      # @param [String] verb
+      def do_resolve_tag_expr(tag_expr, verb)
+        raise "Internal error" unless %w[read write].include?(verb)
+        words = verb == 'read' ? SPECIAL_READ_WORDS : SPECIAL_WRITE_WORDS
+
+        resolved_tag = tag_expr
+        words.each do |special_word|
+          part = "#{SPECIAL_CHAR}#{special_word}"
+          if tag_expr.include?(part)
+            resolved_word = resolve_word(special_word, verb)
+            resolved_tag = resolved_tag.gsub(part, resolved_word)
+          end
+        end
+        resolved_tag
+      end
+
+      ##
+      # Performs a special word substitution for an individual special word,
+      # like 'latest', 'random', or 'candidate'. Works by looking for a
+      # corresponding the word-resolver method in self.
+      #
+      # E.g if you pass 'random', it expects the method resolve_random_word to
+      # exist.
+      #
+      # Because the same special word can have different interpretations
+      # depending on whether the mode (read or write), this method will
+      # first look for the mode-specialized version of the word-resolver function,
+      # e.g if passed 'candidate' in 'read' mode, it will first look out for
+      # the a word-resolver method called 'resolve_candidate_read_word' and call it
+      # instead of the less specialized 'resolve_candidate_word' method.
+      #
+      # @param [String] word a special word ('latest', 'random', 'candidate')
+      # @param [Object] verb whether this is a read or write operation
+      def resolve_word(word, verb)
+        word = word.gsub("-", "_")
+        if respond_to?((method = "resolve_#{word}_#{verb}_word"))
+          send(method)
+        elsif respond_to?((method = "resolve_#{word}_word"))
+          send(method)
+        else
+          raise "What is #{word}??"
+        end
+      end
+
+      ##
+      # Single word resolver. Looks for the latest candidate state entry
+      # and returns its tag or an empty string if there is no
+      # latest candidate state.
+      # @return [String]
+      def resolve_candidate_read_word
+        latest_candidate&.tag || ""
+      end
+
+      ##
+      # Single word resolver. Outputs a non-taken random tag (given by
+      # #generate_random_tag) prefixed with candidate flag prefix [cand]-.
+      # @return [String]
+      def resolve_candidate_write_word
+        resolve_candidate_read_word || resolve_new_candidate_word
+      end
+
+      def resolve_new_candidate_word
+        prefix = Kerbi::State::Entry::CANDIDATE_PREFIX
+        begin
+          tag = "#{prefix}#{self.class.generate_random_tag}"
+        end while candidates.find{ |e| e.tag == tag }
+        tag
+      end
+
+      ##
+      # Single word resolver. Looks for the latest committed state entry
+      # and returns its tag or an empty string if there is no
+      # latest committed state.
+      # @return [String]
+      def resolve_latest_word
+        latest&.tag || ""
+      end
+
+      ##
+      # Single word resolver. Looks for the latest committed state entry
+      # and returns its tag or an empty string if there is no
+      # latest committed state.
+      # @return [String]
+      def resolve_oldest_word
+        oldest&.tag || ""
+      end
+
+      ##
+      # Single word resolver. Outputs a non-taken random tag (given by
+      # #generate_random_tag).
+      # @return [String]
+      def resolve_random_word
+        begin
+          tag = self.class.generate_random_tag
+        end while entries.find{ |e|e.tag == tag }
+        tag
+      end
+
+      # private :do_resolve_tag_expr
+      # private :resolve_candidate_read_word
+
+      module ClassMethods
+        ##
+        # Uses the Spicy::Proton gem to generate a convenient,
+        # human-readable random tag for a state entry.
+        # @return [String]
+        def generate_random_tag
+          gen = Spicy::Proton.new
+          "#{gen.adjective(max: 5)}-#{gen.noun(max: 5)}"
+        end
+      end
+
+    end
+  end
+end

data/lib/state/base_backend.rb

@@ -0,0 +1,59 @@
+module Kerbi
+  module State
+    class BaseBackend
+
+      def initialize(options={})
+      end
+
+      # @return [Kerbi::State::EntrySet]
+      def entry_set
+        @_entry_set ||= EntrySet.new(read_entries)
+      end
+
+      # @return [Array<Kerbi::State::Entry>]
+      def entries
+        entry_set.entries
+      end
+
+      # @param [Kerbi::State::Entry] entry
+      def delete_entry(entry)
+        entries.reject! { |e| e.tag == entry.tag }
+        save
+        @_entry_set = nil
+        @_resource = nil
+      end
+
+      def save
+        entry_set.validate!
+        update_resource
+        @_entry_set = nil
+        @_resource = nil
+      end
+
+      protected
+
+      def resource
+        @_resource ||= load_resource
+      end
+
+      def update_resource
+        raise NotImplementedError
+      end
+
+      # @return [Array<Hash>]
+      def read_entries
+        raise NotImplementedError
+      end
+
+      def load_resource
+        raise NotImplementedError
+      end
+
+      private
+
+      def utils
+        Kerbi::Utils
+      end
+    end
+  end
+end