esse 0.0.2

data/lib/esse/cli/generate.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'thor'
+require 'ostruct'
+require_relative 'base'
+
+module Esse
+  module CLI
+    class Generate < Base
+      NAMESPACE_PATTERN_RE = %r{\:|/|\\}i.freeze
+
+      def self.source_root
+        File.dirname(__FILE__)
+      end
+
+      desc 'index NAME *TYPES', 'Creates a new index'
+      def index(name, *types)
+        ns_path = name.split(NAMESPACE_PATTERN_RE).tap(&:pop)
+        @index_name = Hstring.new(name.to_s).modulize.sub(/Index$/, '') + 'Index'
+        @types = types.map { |type| Hstring.new(type) }
+        @base_class = base_index_class(*ns_path)
+
+        base_dir = Esse.config.indices_directory.join(*ns_path)
+        index_name = Hstring.new(@index_name).demodulize.underscore.to_s
+        template(
+          'templates/index.rb.erb',
+          base_dir.join("#{index_name}.rb"),
+        )
+        @types.each do |type|
+          @type = Hstring.new(type).underscore
+          copy_file(
+            'templates/mappings.json',
+            base_dir.join(index_name, 'templates', "#{@type}_mapping.json"),
+          )
+          template(
+            'templates/serializer.rb.erb',
+            base_dir.join(index_name, 'serializers', "#{@type}_serializer.rb"),
+          )
+        end
+      end
+
+      protected
+
+      def base_index_class(*ns)
+        return 'ApplicationIndex' if Esse.config.indices_directory.join(*ns, 'application_index.rb').exist?
+
+        'Esse::Index'
+      end
+    end
+  end
+end

data/lib/esse/cli/index.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'thor'
+require_relative 'base'
+module Esse
+  module CLI
+    class Index < Base
+      desc 'create *INDEX_CLASSES', 'Creates a new index'
+      def create(*index_classes)
+        # Add action here
+      end
+    end
+  end
+end

data/lib/esse/cli/templates/index.rb.erb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+class <%= @index_name %> < <%= @base_class %>
+  # plugin :active_record
+  # plugin :sequel
+  <%- @types.each do |type| -%>
+
+  define_type :<%= type %> do
+    # Collection
+    # ==========
+    #
+    # Collection wraps the data into an array of items that should be serialized. The first argument that is
+    # yielded must extends Enumerable.
+    # Useful for eager loading data from database or any other repository. Below is an example of a rails like
+    # application could load using activerecord.
+    #
+    #   collection do |conditions|
+    #     context = {}
+    #     <%= type.camelize %>.where(conditions).find_in_batches(batch_size: 5000) do |batch|
+    #       yield batch, context, ...
+    #     end
+    #   end
+    #
+    #
+    # Serializer
+    # ==========
+    #
+    # The serializer can be any class that respond with the `as_json` class method.
+    # And the result of its as_json is a Hash.
+    #
+    # Here is an example of a simple serializer:
+    # app/serializers/<%= type %>_serializer.rb
+    #   class <%= type.camelize %>Serializer
+    #     def initialize(<%= type %>, _context)
+    #       @<%= type %> = <%= type %>
+    #     end
+    #
+    #     def as_json
+    #       { '_id' => @<%= type %>.id, 'name' => @<%= type %>.name }
+    #     end
+    #   end
+    #
+    # And here you specify your serializer classe.
+    #    serializer <%= @index_name %>::Serializers::<%= type.camelize %>Serializer
+    #
+    # You can also serialize the collection entry using a block:
+    #
+    #   serializer(<%= type %>, context = {}) do
+    #     hash = {
+    #       name: <%= type %>.name,
+    #     }
+    #     # Context is just an example here. But it's useful for eager loading data.
+    #     # I'll think a better example when implement this idea.
+    #     hash[:some_attribute] = <%= type %>.some_attribute if context[:include_some_attribute]
+    #     hash
+    #   end
+  end
+  <%- end -%>
+end

data/lib/esse/cli/templates/mappings.json

@@ -0,0 +1,6 @@
+{
+  "name": {
+    "type": "string",
+    "index": "analyzed"
+  }
+}

data/lib/esse/cli/templates/serializer.rb.erb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class <%= @index_name %>::Serializers::<%= @type.camelize %>Serializer
+  def initialize(<%= @type %>, *_other)
+    @entity = <%= @type %>
+  end
+
+  def as_json
+    {
+      id: @entity.id, # This field is required
+      name: @entity.name,
+    }
+  end
+end

data/lib/esse/cluster.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Esse
+  class Cluster
+    ATTRIBUTES = %i[index_prefix index_settings client].freeze
+
+    # The index prefix. For example an index named UsersIndex.
+    # With `index_prefix = 'app1'`. Final index/alias is: 'app1_users'
+    attr_accessor :index_prefix
+
+    # This settings will be passed through all indices during the mapping
+    attr_accessor :index_settings
+
+    attr_reader :id
+
+    def initialize(id:, **options)
+      @id = id.to_sym
+      @index_settings = {}
+      assign(options)
+    end
+
+    def assign(hash)
+      return unless hash.is_a?(Hash)
+
+      hash.each do |key, value|
+        method = (ATTRIBUTES & [key.to_s, key.to_sym]).first
+        next unless method
+
+        public_send(:"#{method}=", value)
+      end
+    end
+
+    def client
+      @client ||= Elasticsearch::Client.new
+    end
+
+    # Define the elasticsearch client connectio
+    # @param client [Elasticsearch::Client, Hash] an instance of elasticsearch/api client or an hash
+    #   with the settings that will be used to initialize Elasticsearch::Client
+    def client=(val)
+      @client = if val.is_a?(Hash)
+        settings = val.each_with_object({}) { |(k,v), r| r[k.to_sym] = v }
+        Elasticsearch::Client.new(settings)
+      else
+        val
+      end
+    end
+
+    def inspect
+      attrs = ([:id] + ATTRIBUTES - [:client]).map do |method|
+        value = public_send(method)
+        format('%<k>s=%<v>p', k: method, v: value) if value
+      end.compact
+      attrs << format('client=%p', @client)
+      format('#<Esse::Cluster %<attrs>s>', attrs: attrs.join(' '))
+    end
+  end
+end

data/lib/esse/config.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module Esse
+  # Provides all configurations
+  #
+  # Example
+  #   Esse.config do |conf|
+  #     conf.indices_directory = 'app/indices'
+  #   end
+  class Config
+    DEFAULT_CLUSTER_ID = :default
+    ATTRIBUTES = %i[indices_directory].freeze
+
+    # The location of the indices. Defaults to the `app/indices`
+    attr_reader :indices_directory
+
+    def initialize
+      self.indices_directory = 'app/indices'
+      @clusters = {}
+      clusters(DEFAULT_CLUSTER_ID) # initialize the :default client
+    end
+
+    def cluster_ids
+      @clusters.keys
+    end
+
+    def clusters(key = DEFAULT_CLUSTER_ID, **options)
+      return unless key
+
+      id = key.to_sym
+      (@clusters[id] ||= Cluster.new(id: id)).tap do |c|
+        c.assign(options) if options
+        yield c if block_given?
+      end
+    end
+
+    def indices_directory=(value)
+      @indices_directory = value.is_a?(Pathname) ? value : Pathname.new(value)
+    end
+
+    def load(arg)
+      case arg
+      when Hash
+        assign(arg)
+      when File, Pathname
+        # @TODO Load JSON or YAML
+      when String
+        # @TODO Load JSON or YAML if File.exist?(arg)
+      else
+        raise ArgumentError, printf('could not load configuration using: %p', val)
+      end
+    end
+
+    private
+
+    def assign(hash)
+      hash.each do |key, value|
+        method = (ATTRIBUTES & [key.to_s, key.to_sym]).first
+        next unless method
+
+        public_send("#{method}=", value)
+      end
+      if (connections = hash['clusters'] || hash[:clusters]).is_a?(Hash)
+        connections.each do |key, value|
+          clusters(key).assign(value) if value.is_a?(Hash)
+        end
+      end
+      true
+    end
+  end
+end

data/lib/esse/core.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'multi_json'
+require 'elasticsearch'
+
+module Esse
+  @single_threaded = false
+  # Mutex used to protect mutable data structures
+  @data_mutex = Mutex.new
+
+  # Block configurations
+  #   Esse.config do |conf|
+  #     conf.indices_directory = 'app/indices/directory'
+  #     conf.clusters(:v1) do |cluster|
+  #       cluster.index_prefix = 'backend'
+  #       cluster.client = Elasticsearch::Client.new
+  #       cluster.index_settings = {
+  #         number_of_shards: 2,
+  #         number_of_replicas: 0
+  #       }
+  #     end
+  #   end
+  #
+  # Inline configurations
+  #   Esse.config.indices_directory = 'app/indices/directory'
+  #   Esse.config.clusters(:v1).client = Elasticsearch::Client.new
+  def self.config
+    @config ||= Config.new
+    yield(@config) if block_given?
+    @config
+  end
+
+  # Unless in single threaded mode, protects access to any mutable
+  # global data structure in Esse.
+  # Uses a non-reentrant mutex, so calling code should be careful.
+  # In general, this should only be used around the minimal possible code
+  # such as Hash#[], Hash#[]=, Hash#delete, Array#<<, and Array#delete.
+  def self.synchronize(&block)
+    @single_threaded ? yield : @data_mutex.synchronize(&block)
+  end
+
+  # Generates an unique timestamp to be used as a index suffix.
+  # Time.now.to_i could also do the job. But I think this format
+  # is more readable for humans
+  def self.timestamp
+    Time.now.strftime('%Y%m%d%H%M%S')
+  end
+
+  # Simple helper used to fetch Hash value using Symbol and String keys.
+  #
+  # @param [Hash] the JSON document
+  # @option [Array] :delete Removes the hash key and return its value
+  # @option [Array] :keep Fetch the hash key and return its value
+  # @return [Array([Integer, String, nil], Hash)] return the key value and the modified hash
+  def self.doc_id!(hash, delete: %w[_id], keep: %w[id])
+    return unless hash.is_a?(Hash)
+
+    id = nil
+    modified = nil
+    Array(delete).each do |key|
+      k = key.to_s if hash.key?(key.to_s)
+      k ||= key.to_sym if hash.key?(key.to_sym)
+      next unless k
+
+      modified ||= hash.dup
+      id = modified.delete(k)
+      break if id
+    end
+    return [id, modified] if id
+
+    modified ||= hash
+    Array(keep).each do |key|
+      id = modified[key.to_s] || modified[key.to_sym]
+      break if id
+    end
+    [id, modified]
+  end
+
+  require_relative 'config'
+  require_relative 'cluster'
+  require_relative 'primitives'
+  require_relative 'index_type'
+  require_relative 'index_setting'
+  require_relative 'index_mapping'
+  require_relative 'template_loader'
+  require_relative 'backend/index'
+  require_relative 'backend/index_type'
+  require_relative 'version'
+end

data/lib/esse/index.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'core'
+
+module Esse
+  class Index
+    require_relative 'index/base'
+    require_relative 'index/inheritance'
+    require_relative 'index/actions'
+    require_relative 'index/naming'
+    require_relative 'index/type'
+    require_relative 'index/settings'
+    require_relative 'index/mappings'
+    require_relative 'index/descendants'
+    require_relative 'index/backend'
+
+    @cluster_id = nil
+
+    def_Index(::Esse)
+  end
+end

data/lib/esse/index/actions.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Esse
+  class Index
+    module ClassMethods
+    end
+
+    extend ClassMethods
+  end
+end

data/lib/esse/index/backend.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Esse
+  class Index
+    module ClassMethods
+      def backend
+        Esse::Backend::Index.new(self)
+      end
+    end
+
+    extend ClassMethods
+  end
+end

data/lib/esse/index/base.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Esse
+  class Index
+    module ClassMethods
+      attr_reader :cluster_id
+
+      # Define a Index method on the given module that calls the Index
+      # method on the receiver. This is how the Esse::Index() method is
+      # defined, and allows you to define Index() methods on other modules,
+      # making it easier to have custom index settings for all indexes under
+      # a namespace.  Example:
+      #
+      #   module V1
+      #     EsIndex = Class.new(Esse::Index)
+      #     EsIndex.def_Index(self)
+      #
+      #     class Bar < EsIndex
+      #       # Uses :default elasticsearch client connection
+      #     end
+      #
+      #     class Baz < EsIndex(:v1)
+      #       # Uses :v1 elasticsearch client connection
+      #     end
+      #   end
+      def def_Index(index_module) # rubocop:disable Naming/MethodName
+        tap do |model|
+          index_module.define_singleton_method(:Index) do |source|
+            model.Index(source)
+          end
+        end
+      end
+
+      # Lets you create a Index subclass with its elasticsearch cluster
+      #
+      # Example:
+      #   # Using a custom cluster
+      #   Esse.config.clusters(:v1).client = Elasticsearch::Client.new
+      #   class UsersIndex < Esse::Index(:v1)
+      #   end
+      #
+      #   # Using :default cluster
+      #   class UsersIndex < Esse::Index
+      #   end
+      def Index(source) # rubocop:disable Naming/MethodName
+        klass = Class.new(self)
+
+        valid_ids = Esse.config.cluster_ids
+        klass.cluster_id = \
+          case source
+          when Esse::Cluster
+            source.id
+          when String, Symbol
+            id = source.to_sym
+            id if valid_ids.include?(id)
+          end
+
+        msg = <<~MSG
+          We could not resolve the index cluster using the argument %<arg>p. \n
+          It must be previously defined in the `Esse.config' settings. \n
+          Here is the list of cluster ids we have configured: %<ids>s\n
+
+          You can ignore this cluster id entirely. That way the :default id will be used.\n
+          Example: \n
+            class UsersIndex < Esse::Index\n
+            end\n
+        MSG
+        unless klass.cluster_id
+          raise ArgumentError.new, format(msg, arg: source, ids: valid_ids.map(&:inspect).join(', '))
+        end
+
+        klass.type_hash = {}
+        klass
+      end
+
+      # Sets the client_id associated with the Index class.
+      # This can be used directly on Esse::Index to set the :default es cluster
+      # to be used by subclasses, or to override the es client used for specific indices:
+      #   Esse::Index.cluster_id = :v1
+      #   ArtistIndex = Class.new(Esse::Index)
+      #   ArtistIndex.cluster_id = :v2
+      def cluster_id=(cluster_id)
+        @cluster_id = cluster_id
+      end
+
+      # @return [Symbol] reads the @cluster_id instance variable or :default
+      def cluster_id
+        @cluster_id || Config::DEFAULT_CLUSTER_ID
+      end
+
+      # @return [Esse::Cluster] an instance of cluster based on its cluster_id
+      def cluster
+        unless Esse.config.cluster_ids.include?(cluster_id)
+          raise NotImplementedError, <<~MSG
+            There is no cluster configured for this index. Use `Esse.config.clusters(cluster_id) { ... }' define the elasticsearch
+            client connection.
+          MSG
+        end
+
+        Esse.synchronize { Esse.config.clusters(cluster_id) }
+      end
+
+      def inspect
+        if self == Index
+          super
+        elsif abstract_class?
+          "#{super}(abstract)"
+        elsif index_name?
+          "#{super}(Index: #{index_name})"
+        else
+          "#{super}(Index is not defined)"
+        end
+      end
+    end
+
+    extend ClassMethods
+  end
+end