kerbi 0.0.1 → 0.0.5

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,93 @@
+module Kerbi
+  module State
+    class BaseBackend
+
+      attr_reader :is_working
+
+      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
+
+      def delete
+        delete_resource
+      end
+
+      def resource_signature
+        raise NotImplementedError
+      end
+
+      def prime
+        begin
+          resource
+          entries
+          @is_working = true
+        rescue
+          @is_working = false
+        end
+      end
+
+      # @return [TrueClass|FalseClass]
+      def working?
+        prime if @is_working.nil?
+        @is_working
+      end
+
+      def self.type_signature
+        raise NotImplementedError
+      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
+
+      def delete_resource
+        raise NotImplementedError
+      end
+
+      private
+
+      def utils
+        Kerbi::Utils
+      end
+    end
+  end
+end

data/lib/state/config_map_backend.rb

@@ -0,0 +1,173 @@
+module Kerbi
+  module State
+
+    ##
+    # Treats a Kubernetes configmap in a namespace as a
+    # persistent store for state entries. Reads and writes
+    # to the configmap.
+    class ConfigMapBackend < Kerbi::State::BaseBackend
+      include Kerbi::Mixins::CmBackendTesting
+
+      attr_reader :auth_bundle
+      attr_reader :release_name
+      attr_reader :namespace
+
+      # @param [Hash] auth_bundle generated by Kerbi::Utils::K8sAuth
+      # @param [String] release_name Kubernetes namespace where configmap lives
+      def initialize(auth_bundle, release_name, namespace)
+        @auth_bundle = auth_bundle.freeze
+        @release_name = release_name.freeze
+        @namespace = (namespace || @release_name).freeze
+      end
+
+      ##
+      # Checks for the namespace and configmap, creating along
+      # the way if missing. Does not raise if already exists.
+      # @param [Hash] opts for things like verbose
+      def provision_missing_resources(**opts)
+        create_namespace unless (ns_existed = namespace_exists?)
+        echo_init("namespaces/#{namespace}", ns_existed, opts)
+
+        create_resource unless (cm_existed = resource_exists?)
+        echo_init("#{namespace}/configmaps/#{cm_name}", cm_existed, opts)
+      end
+
+      ##
+      # Creates the configmap with 0 entries.
+      def create_resource
+        apply_resource(template_resource([]))
+      end
+
+      ##
+      # Creates the configmap given an exact dict representation
+      # of its contents. This method doesn't actually get used outside
+      # of rspec, but it's super useful there so keeping for time being.
+      # @param [Hash] resource_desc
+      def apply_resource(resource_desc, mode: 'create')
+        if mode == 'create'
+          #noinspection RubyResolve
+          client("v1").create_config_map(resource_desc)
+        elsif mode == 'update'
+          #noinspection RubyResolve
+          client("v1").update_config_map(resource_desc)
+        else
+          raise "What kind of sick mode is #{mode}?"
+        end
+      end
+
+      ##
+      # Outputs the dict representation of the configmap, templated
+      # with the given entries.
+      # @param [Array<Kerbi::State::Entry>] entries
+      # @return [Hash]
+      def template_resource(entries)
+        values = {
+          consts::ENTRIES_ATTR => entries.map(&:to_h),
+          namespace: namespace,
+          cm_name: cm_name
+        }
+        Kerbi::State::ConfigMapMixer.new(values).run.first
+      end
+
+      ##
+      # Creates the required namespace resource for this configmap
+      # in the cluster.
+      def create_namespace
+        values = { namespace: namespace }
+        dict = Kerbi::State::NamespaceMixer.new(values).run.first
+        #noinspection RubyResolve
+        client("v1").create_namespace(dict)
+      end
+
+      def resource_name
+        cm_name
+      end
+
+      def resource_signature
+        "configmaps/#{namespace}/#{resource_name}"
+      end
+
+      protected
+
+      ##
+      # Reads the configmap from Kubernetes, returns its dict representation.
+      def load_resource
+        #noinspection RubyResolve
+        client("v1").get_config_map(cm_name, namespace).to_h
+      end
+
+      ##
+      # Reads the configmap from Kubernetes, returns its dict representation.
+      def delete_resource
+        #noinspection RubyResolve
+        client("v1").delete_config_map(cm_name, namespace)
+      end
+
+      ##
+      # Templates the updated version of the configmap given the entries
+      # in memory, and uses the new dict to overwrite the last configmap
+      # in the cluster.
+      def update_resource
+        new_resource = template_resource(entries)
+        #noinspection RubyResolve
+        client("v1").update_config_map(new_resource)
+      end
+
+      ##
+      # Deserializes the list of entries in the configmap. Calls
+      # #resources, which is memoized, so may trigger a cluster read.
+      # @return [Array<Hash>] entries
+      def read_entries
+        str_entries = resource[:data][consts::ENTRIES_ATTR]
+        JSON.parse(str_entries)
+      end
+
+      ## Creates an instance of Kubeclient::Client given
+      # the auth_bundle in the state, and a Kubernetes API name
+      # like appsV1 (defaults to "v1" if not passed).
+      # @return [Kubeclient::Client]
+      def client(api_name="v1")
+        self.class.make_client(auth_bundle, api_name)
+      end
+
+      def consts
+        Kerbi::State::Consts
+      end
+
+      def cm_name
+        self.class.mk_cm_name(release_name)
+      end
+
+      def self.releases(auth_bundle)
+        client = make_client(auth_bundle, "v1")
+        res_dicts = client.get_config_maps.map(&:to_h).select do |res_dict|
+          name = res_dict.dig(:metadata, :name)
+          name =~ Kerbi::State::Consts::CM_REGEX
+        end
+
+        res_dicts.map do |res_dict|
+          name, namespace = res_dict[:metadata].values_at(:name, :namespace)
+          release = name.match(Kerbi::State::Consts::CM_REGEX)[1]
+          self.new(auth_bundle, release, namespace)
+        end
+      end
+
+      def self.mk_cm_name(release_name)
+        "kerbi-#{release_name}-db"
+      end
+
+      def self.make_client(auth_bundle, api_name)
+        Kubeclient::Client.new(
+          auth_bundle[:endpoint],
+          api_name,
+          **auth_bundle[:options]
+        )
+      end
+
+      def self.type_signature
+        "ConfigMap"
+      end
+
+    end
+  end
+end

data/lib/state/entry.rb

@@ -0,0 +1,173 @@
+module Kerbi
+  module State
+
+    ##
+    # Represents a single Kerbi state entry.
+    class Entry
+
+      CANDIDATE_PREFIX = "[cand]-"
+
+      ATTRS = %i[tag message values default_values created_at]
+      SETTABLE_ATTRS = %i[message created_at]
+
+      attr_accessor :set
+
+      attr_accessor :tag
+      attr_accessor :message
+      attr_accessor :default_values
+      attr_accessor :values
+      attr_accessor :created_at
+
+      attr_reader :validation_errors
+
+      def initialize(set, dict)
+        @set = set
+        ATTRS.each do |attr|
+          instance_variable_set("@#{attr}", dict[attr].freeze)
+        end
+        @_was_validated = false
+        @validation_errors = []
+      end
+
+      ## A state entry is a 'candidate' if its tag has the
+      # candidate signature - that is it starts with [cand]-.
+      # @return [TrueClass, FalseClass]
+      def candidate?
+        tag.start_with?(CANDIDATE_PREFIX)
+      end
+
+      ##
+      # Convenience method that returns the negation of #candidate?
+      # @return [TrueClass, FalseClass]
+      def committed?
+        !candidate?
+      end
+
+      ##
+      # Ghetto attribute validation. Pushes a attr => msg hash to the
+      # @validation_errors for every problem found. Does not raise on
+      # problems.
+      # @return [NilClass]
+      def validate
+        @validation_errors.push(
+          attr: 'tag',
+          msg: "Cannot be empty",
+          value: tag
+        ) unless tag.present?
+
+        @_was_validated = true
+      end
+
+      def valid?
+        raise "valid? called before #validate" unless @_was_validated
+        validation_errors.empty?
+      end
+
+      ##
+      # Computes a delta between this state's values and its
+      # default values.
+      # @return [Hash]
+      def overrides_delta
+        if values.is_a?(Hash) & default_values.is_a?(Hash)
+          Kerbi::Utils::Misc.deep_hash_diff(default_values, values)
+        else
+          nil
+        end
+      end
+
+      ##
+      # Dynamically assign as a user.
+      # @param [String|Symbol] attr_name
+      # @param [Object] new_value
+      # @return [String] the old value, for convenience
+      def assign_attr(attr_name, new_value)
+        if SETTABLE_ATTRS.include?(attr_name.to_sym)
+          old_value = send(attr_name)
+          send("#{attr_name}=", new_value)
+          old_value
+        else
+          raise Kerbi::NoSuchStateAttrName
+        end
+      end
+
+      ##
+      # Replace current tag with a new one, where the new
+      # one can contain special interpolatable words like
+      # @candidate.
+      # @param [String] new_tag_expr
+      # @return [String] the old tag, for convenience
+      def retag(new_tag_expr)
+        old_tag = tag
+        self.tag = set.resolve_write_tag_expr(new_tag_expr)
+        old_tag
+      end
+
+      ##
+      # Removes the [cand]- part of the tag, making this
+      # entry lose its candidate status.
+      #
+      # Raises an exception if this entry was not a candidate.
+      # @return [String] the old tag, for convenience
+      def promote
+        raise Kerbi::StateNotPromotable unless candidate?
+        old_tag = tag
+        self.tag = tag[CANDIDATE_PREFIX.length..]
+        old_tag
+      end
+
+      ##
+      # Adds the [cand]- flag to this entry's tag, making this
+      # entry gain candidate status.
+      #
+      # Raises an exception if this entry was already a candidate.
+      # @return [String] the old tag, for convenience
+      def demote
+        raise Kerbi::StateNotDemotable unless committed?
+        old_tag = tag
+        self.tag = "#{CANDIDATE_PREFIX}#{tag}"
+        old_tag
+      end
+
+      ##
+      # Convenience method to get all overridden keys between
+      # the values and default_values dicts.
+      # @return [Array<String>]
+      def overridden_keys
+        (delta = overrides_delta) ? delta.keys.map(&:to_s) : []
+      end
+
+      def to_h
+        special_ser = {
+          values: values || {},
+          default_values: default_values || {},
+          created_at: created_at.to_s
+        }
+        Hash[ATTRS.map{|k|[k, send(k)]}].merge(special_ser)
+      end
+      alias_method :serialize, :to_h
+
+      def to_json
+        JSON.dump(serialize)
+      end
+
+      # @param [Hash] dict
+      # @return [Kerbi::State::Entry]
+      def self.from_dict(set, dict={})
+        dict.deep_symbolize_keys!
+        dict.slice!(*ATTRS)
+
+        self.new(
+          set,
+          **dict,
+          values: dict[:values] || {},
+          default_values: dict[:default_values] || {},
+          created_at: (Time.parse(dict[:created_at]) rescue nil)
+        )
+      end
+
+      def self.versioned?(expr)
+        Gem::Version.correct?(expr)
+      end
+    end
+  end
+end