Refactor configuration

docs/documentation/searches/filters/date.md

@@ -2,7 +2,8 @@
 title: Date
 ---
 
-For a date filter defined like this:
+Register a date filter like this:
+
 ```ruby
 class ArticleSearch < Caoutsearch::Search::Base
   ...
@@ -11,7 +12,8 @@ class ArticleSearch < Caoutsearch::Search::Base
 end
 ```
 
-You can now search the matching index with the `published_on` criterion:
+You can now search with the matching property:
+
 ```ruby
 Article.search(published_on: Date.today)
 ```
@@ -29,7 +31,27 @@ and the following query will be generated to send to elasticsearch:
 }
 ```
 
-The date filter accepts multiple types of arguments :
+Various formats for times & dates are accepted:
+```ruby
+"2022-10-11"
+Date.today
+Time.zone.now
+```
+
+It also supports [Elasticsearch Date Math](https://www.elastic.co/guide/en/elasticsearch/reference/current/common-options.html#date-math):
+```ruby
+"now-1h"
+"now+2w/d"
+```
+
+It also accepts ranges (closed or open) in various formats: `Range`, `Hash` or `Array`
+```ruby
+..Date.new(2022, 12, 25)
+{ less_than: "2022-12-25" }
+[["now-1w/d", "now/d"]]
+```
+
+Examples:
 
 ```ruby
 # Search for articles published on a date:
@@ -52,16 +74,3 @@ Article.search(published_on: { greater_than: "2022-12-25", less_than: "2023-12-2
 Article.search(published_on: Date.new(2022, 12, 25)..Date.new(2023, 12, 25))
 Article.search(published_on: [["now-1w/d", "now/d"]])
 ```
-
-Dates of various formats are handled:
-```ruby
-"2022-10-11"
-Date.today
-Time.zone.now
-```
-
-We also support elasticsearch's date math
-```ruby
-"now-1h"
-"now+2w/d"
-```

docs/getting_started.md

@@ -1,8 +1,8 @@
 ## Prerequisites
 
 Caoutsearch requires at least :
-* Ruby  2.7.x
-* Rails 6.x
+* Ruby  >= 2.7.x
+* Rails >= 6.x
 * Elasticsearch 8.x
 
 ## Installation
@@ -15,4 +15,66 @@ bundle add caoutsearch
 
 ## Configuration
 
-TODO
+Few options are available to configure Caoutsearch:
+
+```ruby
+Caoutsearch.configure do |config|
+  # Configure how to connect to Elasticsearch.
+  #
+  # `Elasticsearch::Client` is provided by the elasticsearch gem.
+  # See https://www.elastic.co/guide/en/elasticsearch/client/ruby-api/current/connecting.html
+  #
+  config.client = Elasticsearch::Client.new(
+    host:             "https://my-elasticsearch-host.example",
+    retry_on_failure: true,
+    request_timeout:  30
+  )
+
+  # Set defaults settings to apply to every indexes:
+  #
+  # See https://www.elastic.co/guide/en/elasticsearch/reference/current/index-modules.html#index-modules-settings
+  #
+  config.settings = {
+    number_of_shards:    5,
+    number_of_replicas:  2,
+    analysis: {
+      analyzer: {
+        words: { type: :custom, tokenizer: :standard, filter: %i[lowercase word_length] }
+      },
+      normalizer: {
+        lowercase:  { type: :custom, filter: %i[lowercase] },
+      },
+      filter: {
+        word_length: { type: :length, min: 1 },
+      }
+    }
+  }
+
+  # Instrument Elasticsearch requests into your Rails logs.
+  # There are three different output:
+  #   - 'full'          - Log the full request
+  #   - 'truncated'     - Log only the 200 first character of the request
+  #   - 'amazing_print' - Pretty print the request body.
+  #
+  # Instrumentation is not enabled by default.
+  # Without argument, 'full' format is used by default.
+  # You need to install the amazing_print gem to use the corresponding format.
+  #
+  config.instrument
+
+  # You can also define alternative configurations to indexes & searches:
+  #
+  config.index do |index|
+    config.instrument :truncated
+  end
+
+  config.search do |search|
+    search.client = Elasticsearch::Client.new(
+      host:            "https://my-elasticsearch-host.example",
+      request_timeout: 10
+    )
+
+    config.instrument :amazing_print
+  end
+end
+```

docs/index.md

@@ -25,18 +25,23 @@ Depending on your search scenarios, they may better suite your needs.
 Caoutsearch let you create `Index` and `Search` classes to manipulate your data :
 
 ```ruby
+class Article < ActiveRecord::Base
+  include Caoutsearch::Model
+
+  index_with ArticleIndex
+  search_with ArticleSearch
+end
+
 class ArticleIndex < Caoutsearch::Index::Base
   property :title
   property :published_on
   property :tags
 
   def tags
-    records.tags.public.map(&:to_s)
+    record.tags.public.map(&:to_s)
   end
 end
-```
 
-```ruby
 class ArticleSearch < Caoutsearch::Search::Base
   filter :title, as: :match
   filter :published_on, as: :date
@@ -53,14 +58,13 @@ class ArticleSearch < Caoutsearch::Search::Base
 end
 ```
 
-You can then index your records
+You can then index & search through your records:
 
 ```ruby
-ArticleIndex.reindex
+Article.reindex
 ```
-
-Or search through them:
-
 ```ruby
-ArticleSearch.search(published_on: [["now-1y", nil]]).aggregate(:popular_tags)
+Article.search(published_on: [["now-1y", nil]]).aggregate(:popular_tags)
 ```
+
+But that's just the beginning...

lib/caoutsearch.rb

@@ -16,28 +16,17 @@
 
 module Caoutsearch
   class << self
-    attr_writer :client
-
-    def client
-      @client ||= Elasticsearch::Client.new
-    end
-
-    def settings
-      @settings ||= Caoutsearch::Settings.new({})
-    end
-
-    def settings=(settings)
-      @settings = Caoutsearch::Settings.new(settings)
+    def config
+      @config ||= Configuration.new
     end
+    alias_method :configuration, :config
 
-    def instrument!(**options)
-      @instrumentation_options = options
-      Caoutsearch::Instrumentation::Index.attach_to :caoutsearch_index if options[:index]
-      Caoutsearch::Instrumentation::Search.attach_to :caoutsearch_search if options[:search]
+    def configure
+      yield(configuration)
     end
 
-    def instrumentation_options
-      @instrumentation_options ||= {}
+    def reset_config
+      @config = Configuration.new
     end
   end
 end

lib/caoutsearch/config/client.rb → lib/caoutsearch/concerns/client.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module Caoutsearch
-  module Config
+  module Concerns
     module Client
       extend ActiveSupport::Concern
 
       included do
-        class_attribute :client, default: Caoutsearch.client
+        class_attribute :client, default: Caoutsearch.config.client
       end
     end
   end

lib/caoutsearch/config/mappings.rb → lib/caoutsearch/concerns/mappings.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Caoutsearch
-  module Config
+  module Concerns
     module Mappings
       extend ActiveSupport::Concern
 

lib/caoutsearch/config/settings.rb → lib/caoutsearch/concerns/settings.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
 
 module Caoutsearch
-  module Config
+  module Concerns
     module Settings
       extend ActiveSupport::Concern
 
       included do
-        delegate :mappings, to: :class
+        delegate :settings, to: :class
       end
 
       class_methods do
@@ -21,7 +21,7 @@ def settings=(settings)
         protected
 
         def default_settings
-          Caoutsearch.settings.to_hash.dup
+          Caoutsearch.config.settings.to_hash.dup
         end
       end
     end

lib/caoutsearch/configuration.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Caoutsearch
+  class Configuration
+    DEFAULT_INSTRUMENTATION_FORMAT = "full"
+
+    attr_reader :client, :settings, :instrumentation_format
+
+    def initialize
+      self.client = Elasticsearch::Client.new
+      self.settings = {}
+    end
+
+    def client=(client)
+      @client = client
+
+      index.client = client
+      search.client = client
+    end
+
+    def settings=(settings)
+      settings = Caoutsearch::Settings.new(settings) if settings.is_a?(Hash)
+      @settings = settings
+    end
+
+    def instrument(format = DEFAULT_INSTRUMENTATION_FORMAT)
+      @instrumentation_format = format.to_s
+
+      index.instrument(format)
+      search.instrument(format)
+    end
+
+    def index
+      @index ||= IndexConfig.new
+      yield(@index) if block_given?
+      @index
+    end
+
+    def search
+      @search ||= SearchConfig.new
+      yield(@search) if block_given?
+      @search
+    end
+
+    class IndexConfig
+      attr_accessor :client
+      attr_reader :instrumentation_format
+
+      def instrument(format = DEFAULT_INSTRUMENTATION_FORMAT)
+        @instrumentation_format = format.to_s
+        Caoutsearch::Instrumentation::Index.attach_to :caoutsearch_index
+      end
+    end
+
+    class SearchConfig
+      attr_accessor :client
+      attr_reader :instrumentation_format
+
+      def instrument(format = DEFAULT_INSTRUMENTATION_FORMAT)
+        @instrumentation_format = format.to_s
+        Caoutsearch::Instrumentation::Search.attach_to :caoutsearch_search
+      end
+    end
+  end
+end

lib/caoutsearch/index/base.rb

@@ -3,9 +3,9 @@
 module Caoutsearch
   module Index
     class Base
-      include Caoutsearch::Config::Client
-      include Caoutsearch::Config::Mappings
-      include Caoutsearch::Config::Settings
+      include Caoutsearch::Concerns::Client
+      include Caoutsearch::Concerns::Mappings
+      include Caoutsearch::Concerns::Settings
 
       include Caoutsearch::Index::Document
       include Caoutsearch::Index::Indice

lib/caoutsearch/instrumentation/index.rb

@@ -50,7 +50,7 @@ def reindex(event)
       private
 
       def log_request_format
-        Caoutsearch.instrumentation_options[:index]
+        Caoutsearch.config.index.instrumentation_format
       end
     end
   end

lib/caoutsearch/instrumentation/search.rb

@@ -43,7 +43,7 @@ def delete(event)
       private
 
       def log_request_format
-        Caoutsearch.instrumentation_options[:search]
+        Caoutsearch.config.search.instrumentation_format
       end
     end
   end

lib/caoutsearch/search/base.rb

@@ -3,9 +3,9 @@
 module Caoutsearch
   module Search
     class Base
-      include Caoutsearch::Config::Client
-      include Caoutsearch::Config::Mappings
-      include Caoutsearch::Config::Settings
+      include Caoutsearch::Concerns::Client
+      include Caoutsearch::Concerns::Mappings
+      include Caoutsearch::Concerns::Settings
 
       include Caoutsearch::Search::BatchMethods
       include Caoutsearch::Search::Batch::Scroll