Add Chewy 7/ES 7 to Chewy 8/ES 8 migration guide (toptal#1010)

* Update Elasticsearch client references for v8 gem namespaces

The elasticsearch-ruby v8 gem reorganized its module hierarchy:
- The transport client moved from Elasticsearch::Transport::Client
  to Elasticsearch::Client
- Transport errors moved from Elasticsearch::Transport::Transport::Errors
  to Elastic::Transport::Transport::Errors

Update documentation and YARD annotations to reflect these changes.

* Add Chewy 7→8 / Elasticsearch 7→8 migration guide

The migration guide previously only covered up to the Chewy 6→7
upgrade path. This adds a comprehensive section for users upgrading
to Chewy 8 / Elasticsearch 8, covering:

- Minimum Ruby (3.2) and Rails (7.2) version requirements
- elasticsearch gem version bump (>= 8.14, < 9.0)
- Namespace changes from elasticsearch-transport to elastic-transport
- Transport logger/tracer configuration changes
- Chewy.massacre / delete_all restriction due to ES 8 defaults
- Elasticsearch 8 security-by-default considerations
- Recommended rolling upgrade procedure

Closes toptal#1004

* Update documented Ruby compatibility to include 4.0

PR toptal#1003 added Ruby 4.0 support but the README still listed
3.2-3.4. Bump the documented range to 3.2-4.0 to match.

---------

Co-authored-by: Alfonso Uceda <alfonso.uceda@toptal.com>

Author: mattmenefee

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Changes
 
+* [#1010](https://github.com/toptal/chewy/pull/1010): Add Chewy 7/ES 7 to Chewy 8/ES 8 migration guide and fix stale `Elasticsearch::Transport` namespace references in docs. ([@mattmenefee][])
 * [#1011](https://github.com/toptal/chewy/pull/1011): Replace deprecated `Sidekiq::Testing` API with new `Sidekiq 8.1+` testing API and silence Sidekiq logger during spec runs. ([@mattmenefee][], [@mjankowski][])
 * [#1013](https://github.com/toptal/chewy/pull/1013): Fix `drop_indices` test helper to use `format: 'json'` for ES version portability. If you define a custom `drop_indices` helper in your test suite, update it to use `Chewy.client.cat.indices(format: 'json')` instead of parsing the text-format response. ([@mattmenefee][])
 * [#1014](https://github.com/toptal/chewy/pull/1014): Improve contributing documentation with development setup instructions, PR workflow, and grammar fixes. ([@mattmenefee][])
@@ -881,7 +882,6 @@
 [@MarkMurphy]: https://github.com/MarkMurphy
 [@marshall]: https://github.com/marshall
 [@matchbookmac]: https://github.com/matchbookmac
-[@mattmenefee]: https://github.com/mattmenefee
 [@matthee]: https://github.com/matthee
 [@mattmenefee]: https://github.com/mattmenefee
 [@mattzollinhofer]: https://github.com/mattzollinhofer

README.md

@@ -45,7 +45,7 @@ Chewy aims to support all Ruby and Rails versions that are currently maintained
 
 ### Ruby
 
-Chewy is compatible with MRI 3.2-3.4.
+Chewy is compatible with MRI 3.2-4.0.
 
 ### Elasticsearch compatibility matrix
 

docs/configuration.md

@@ -25,7 +25,7 @@ development:
 
 > **Not using Rails?** You can skip `chewy.yml` entirely and configure Chewy with `Chewy.settings = {...}`. See the [Non-Rails Usage](non_rails.md) guide.
 
-The resulting config merges both hashes. Client options are passed as is to `Elasticsearch::Transport::Client` except for the `:prefix`, which is used internally by Chewy to create prefixed index names:
+The resulting config merges both hashes. Client options are passed as is to `Elasticsearch::Client` except for the `:prefix`, which is used internally by Chewy to create prefixed index names:
 
 ```ruby
   Chewy.settings = {prefix: 'test'}

docs/getting_started.md

@@ -285,7 +285,7 @@ class BooksController < ApplicationController
     @books = form.search
                  .load(scope: -> { includes(:author) })
                  .page(params[:page]).per(20)
-  rescue Elasticsearch::Transport::Transport::Errors::BadRequest
+  rescue Elastic::Transport::Transport::Errors::BadRequest
     # Malformed user query — fall back to empty results
     @books = Book.none.page(params[:page])
     flash.now[:alert] = 'Invalid search query.'

docs/querying.md

@@ -82,7 +82,7 @@ When building search UIs where users type free-text queries, malformed input
 ```ruby
 begin
   results = CitiesIndex.query(query_string: {query: user_input}).to_a
-rescue Elasticsearch::Transport::Transport::Errors::BadRequest => e
+rescue Elastic::Transport::Transport::Errors::BadRequest => e
   results = []
   # Log or display a user-friendly message
 end

lib/chewy/multi_search.rb

@@ -11,7 +11,7 @@ class MultiSearch
     # Instantiate a new MultiSearch instance.
     #
     # @param queries [Array<Chewy::Search::Request>]
-    # @option [Elasticsearch::Transport::Client] :client (Chewy.client)
+    # @option [Elasticsearch::Client] :client (Chewy.client)
     #   The Elasticsearch client that should be used for issuing requests.
     def initialize(queries, client: Chewy.client)
       @client = client

migration_guide.md

@@ -4,6 +4,32 @@ This document outlines the steps you need to take when migrating between major v
 Chewy and Elasticsearch. For simplicity's sake the guide will assume that you're using
 Chewy alongside a matching Elasticsearch version.
 
+## Chewy 7/Elasticsearch 7 to Chewy 8/Elasticsearch 8
+
+In order to upgrade Chewy 7/Elasticsearch 7 to Chewy 8/Elasticsearch 8 in the most seamless manner you have to:
+
+* Upgrade to the latest 7.x stable release (Chewy 7.6.0, Elasticsearch 7.17)
+* Study carefully [Breaking changes in 8.0](https://www.elastic.co/guide/en/elasticsearch/reference/8.17/migrating-8.0.html), make sure your application conforms
+* Upgrade Ruby to >= 3.2 and Rails/ActiveSupport to >= 7.2 — Chewy 8 drops support for older versions
+* Update the `elasticsearch` gem — Chewy 8 requires `>= 8.14, < 9.0`
+* Update error class references:
+  * The `elasticsearch-transport` gem was replaced by `elastic-transport`, moving all error classes from the `Elasticsearch::Transport` namespace to `Elastic::Transport`. Update any `rescue` clauses:
+    * `Elasticsearch::Transport::Transport::Errors::NotFound` → `Elastic::Transport::Transport::Errors::NotFound`
+    * `Elasticsearch::Transport::Transport::Errors::BadRequest` → `Elastic::Transport::Transport::Errors::BadRequest`
+* Update transport logger/tracer configuration:
+  * `Chewy.client.transport.transport.logger` → `Chewy.client.transport.logger`
+  * `Chewy.client.transport.transport.tracer` → `Chewy.client.transport.tracer`
+* Handle the new `Chewy.massacre` / `delete_all` restriction:
+  * Elasticsearch 8 disables wildcard index deletion by default (`action.destructive_requires_name`). `Chewy.massacre` now raises `Chewy::FeatureDisabled` unless explicitly enabled
+  * To continue using `Chewy.massacre`, add `Chewy.settings[:delete_all_enabled] = true` to your Chewy initializer (e.g. `config/initializers/chewy.rb`) **and** configure your ES cluster with `action.destructive_requires_name: false`
+  * In test suites, consider switching to targeted index deletion instead of `Chewy.massacre`
+* Configure Elasticsearch 8 security:
+  * ES 8 enables security features by default. Ensure your Chewy configuration includes proper authentication (username/password or API key) and SSL/TLS settings as needed.
+* Run your test suite on Chewy 8 / Elasticsearch 8
+* Run manual tests on Chewy 8 / Elasticsearch 8
+* Upgrade to Chewy 8
+* Perform a [rolling upgrade](https://www.elastic.co/guide/en/elasticsearch/reference/8.17/rolling-upgrades.html) of Elasticsearch
+
 ## Chewy 6/Elasticsearch 6 to Chewy 7/Elasticsearch 7
 
 In order to upgrade Chewy 6/Elasticsearch 6 to Chewy 7/Elasticsearch 7 in the most seamless manner you have to:
@@ -13,12 +39,12 @@ In order to upgrade Chewy 6/Elasticsearch 6 to Chewy 7/Elasticsearch 7 in the mo
 * Run your test suite on Chewy 7.0 / Elasticsearch 7
 * Run manual tests on Chewy 7.0 / Elasticsearch 7
 * Upgrade to Chewy 7.0
-  * The “total hits” counter is an integer for ES versions < 7 and an object (hash) for the versions starting from 7.0.0. Elasticsearch added a special option, `rest_total_hits_as_int`, to ease the upgrade, that could be appended to any request and results in the old “total hits” format. Unfortunately, this option is not recognized by ES versions prior to 7.0.0, which means that we have to check the version to decide if we need this option.
+  * The "total hits" counter is an integer for ES versions < 7 and an object (hash) for the versions starting from 7.0.0. Elasticsearch added a special option, `rest_total_hits_as_int`, to ease the upgrade, that could be appended to any request and results in the old "total hits" format. Unfortunately, this option is not recognized by ES versions prior to 7.0.0, which means that we have to check the version to decide if we need this option.
     Normally Chewy does memoization of the current ES version, but this might be inappropriate for the upgrade, as the version changes live.
-    To handle that we have 2 versions of Chewy for this stage of the upgrade: 7.0.0 and 7.0.1. Version 7.0.0 does the memoization and version 7.0.1 requests the current version on every search request. 
+    To handle that we have 2 versions of Chewy for this stage of the upgrade: 7.0.0 and 7.0.1. Version 7.0.0 does the memoization and version 7.0.1 requests the current version on every search request.
   * You can use the 7.0.0 version if it's fine for you to have an application restart immediately after ES cluster upgrade.
   * If you're using the 7.0.1 version you might be interested in keeping the timeframe between this step and updating to Chewy 7.1 as small as possible, as version 7.0.1 skips ES version memoization for search requests to help dynamically detect ES version. This leads to an extra version request on each search request, i.e. could affect the overall performance/latency of the search and a load of ES cluster.
-* Perform a [rolling upgrade](https://www.elastic.co/guide/en/elasticsearch/reference//rolling-upgrades.html) of Elasticsearch
+* Perform a [rolling upgrade](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/rolling-upgrades.html) of Elasticsearch
 * Run your test suite on Chewy 7.1 / Elasticsearch 7
 * Run manual tests on Chewy 7.1 / Elasticsearch 7
 * Upgrade to Chewy 7.1
@@ -48,7 +74,7 @@ In order to upgrade Chewy 5/Elasticsearch 5 to Chewy 6/Elasticsearch 6 in the mo
 * Handle deprecation of `string` type & `not_analyzed` value for the `index` mapping parameter:
   * replace fields with `{ type: 'string', index: 'not_analyzed'}` by `{type: 'keyword'}`
   * replace fields with `{ type: 'string', index: 'analyzed'}` by `{type: 'text'}`
-* `PathHierarchy` tokenizer' param `delimiter` now accepts only one argument, [others should be replaced by character filter ](https://discuss.elastic.co/t/multichar-delimiter-in-path-hierarchy-tokenizer/16203)
+* `PathHierarchy` tokenizer' param `delimiter` now accepts only one argument, [others should be replaced by character filter](https://discuss.elastic.co/t/multichar-delimiter-in-path-hierarchy-tokenizer/16203)
 * Make sure you don't use any other of the [deprecated Elasticsearch 5 features](https://www.elastic.co/guide/en/elasticsearch/reference/6.8/breaking-changes-6.0.html)
 * Run your test suite on Chewy 6 / Elasticsearch 6
 * Run manual tests on Chewy 6 / Elasticsearch 6