solr_cloud-connection 0.6.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da67e9a6312ae058259368a9933abe711d1c0554337c59c5f688cf2f17cee606
-  data.tar.gz: 36b815217b2f3e806d9b639d4839f093d61327ee496fee1c3d4774039c688e48
+  metadata.gz: 19bcfd12d8bc2169aad5f3a01163996e671c0e8b2594ad50197ee7127abf15a9
+  data.tar.gz: 9088cfcdf21b11fe5ac92fd35ea2d5ec66ea55471d9a0e3a16edf2304db22bf4
 SHA512:
-  metadata.gz: c828e6c7f7976cee46ac7b81c8955d2253253e3084e3841e26a502bf2d03808327578e69e63a47c0907dd7d38df3db27747a2383a6e8a6f9f4b1a73c69832340
-  data.tar.gz: 25548a6825b308a62ec376bf1b59d596a557c8508f9feeb56cabd5bc402907ecf4f7602658c5087483424844d1fffddf2c7673ecc2f16cefb3ad79f03696aba5
+  metadata.gz: 61d0a5ce50ec30182bc0e60c915a78b6cc492039291634b53e48efb5fd91124643c97ebafc9ad9043d690bf0f28dbd047c5d1688acfb927c5ca126320d9e00c7
+  data.tar.gz: 9771f4d1047ef1210eecd1fc78b376363c7d9d7cd34b4c72023eb9f502aa746c1247844de176d03c9c3db8aec9673fa9d65edd97eb06c7f4d9bb18ec7a70a217

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [1.0.0] - 2026-07-07
+
+### Major — Solr 8/9/10 Dual-Version Compatibility
+
+This release adds support for Solr 9 and 10 alongside the existing Solr 8 support.
+The internal API dispatch now detects the connected Solr major version and routes
+requests to the correct endpoint, since several Solr APIs changed paths or response
+envelopes between Solr 8 and Solr 9/10.
+
+- **Feature: Solr 8/9/10 compatibility**
+  - Use V1 `CLUSTERSTATUS` action for collection info instead of V2 `api/collections/{name}`
+    (the V2 response envelope changed between Solr 8 and Solr 9/10 — the `cluster` wrapper
+    key is absent in Solr 10)
+  - Use V1 `LISTALIASES` action with `|| {}` guard for nil aliases on Solr 10
+  - Use V1 `admin/configs` endpoint for configset upload (path differs between Solr 8 and 9+)
+  - Add `solr9_or_later?` predicate to the connection for external version-gating
+- **CI: Matrix testing** — run tests against Solr 8 & Solr 10 in parallel via GitHub Actions
+- **Infrastructure** — Docker Compose healthchecks, env setup for Solr 10 test container, curl-based wait loops
+
+### Chores
+- Replace `wait-for-it` / raw curl loops with Docker Compose healthcheck + `docker compose wait`
+- Add Solr 10 Docker image definition (`spec/data/solr10_docker/`)
+- Update README
+- Version bump to 1.0.0
+
+## [0.6.0] - 2025-05-29
+- Expose `username` and `password` getters on the connection
+- Update README with "Common Usage" section
+- Peg dependency versions in gemspec
+- General gemfile/spec cleanup
+
 ## [0.5.0] - 2025-03-24
 - Added some sugar for unifying aliases and collections
 - Update tests

data/LICENSE.md

@@ -0,0 +1,27 @@
+Copyright (c) 2026, The Regents of the University of Michigan.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+* Neither the name of the The University of Michigan nor the
+  names of its contributors may be used to endorse or promote products
+  derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE REGENTS OF THE UNIVERSITY OF MICHIGAN AND
+CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
+NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OF THE
+UNIVERSITY OF MICHIGAN BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO,PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/compose.yml

@@ -11,21 +11,56 @@ services:
       - .env
       - env.test
     command: "tail -f /dev/null"
+    depends_on:
+      solr:
+        condition: service_healthy
+      solr10:
+        condition: service_healthy
 
   solr:
     build: spec/data/solr_docker/.
     ports:
-      - "9090:8983"
+      - "6781:8983"
     environment:
       - ZK_HOST=zoo:2181
     depends_on:
       - zoo
     command: solr-foreground
+    healthcheck:
+      test: ["CMD-SHELL", "curl -sf -u solr:SolrRocks http://localhost:8983/solr/admin/info/system || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 30s
 
   zoo:
     image: zookeeper
     ports:
-      - 9091:2181
+      - 6782:2181
+    environment:
+      ZOO_MY_ID: 1
+      ZOO_SERVERS: server.1=0.0.0.0:2888:3888;2181
+
+  solr10:
+    build: spec/data/solr10_docker/.
+    ports:
+      - "6783:8983"
+    environment:
+      - ZK_HOST=zoo10:2181
+    depends_on:
+      - zoo10
+    command: solr-foreground
+    healthcheck:
+      test: ["CMD-SHELL", "curl -sf -u solr:SolrRocks http://localhost:8983/solr/admin/info/system || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 12
+      start_period: 30s
+
+  zoo10:
+    image: zookeeper
+    ports:
+      - 6784:2181
     environment:
       ZOO_MY_ID: 1
       ZOO_SERVERS: server.1=0.0.0.0:2888:3888;2181

data/env.test.solr10

@@ -0,0 +1,3 @@
+SOLR_URL="http://solr10:8983"
+SOLR_PASSWORD=SolrRocks
+SOLR_USER=solr

data/lib/solr_cloud/collection.rb

@@ -98,8 +98,15 @@ module SolrCloud
 
     # Access to the root info from the api. Mostly for internal use, but not labeled as such
     # 'cause users will almost certainly find a use for it.
+    #
+    # Uses the V1 +CLUSTERSTATUS+ action rather than the V2 +api/collections/{name}+
+    # endpoint because the V2 response envelope changed between Solr 8 and Solr 9/10
+    # (the +cluster+ wrapper key is absent in Solr 10). The V1 CLUSTERSTATUS response
+    # consistently returns +cluster.collections.{name}+ on all supported versions.
+    #
+    # @return [Hash] the collection status hash as returned by Solr
     def info
-      connection.get("api/collections/#{name}").body["cluster"]["collections"][name]
+      connection.get("solr/admin/collections", action: "CLUSTERSTATUS", collection: name).body["cluster"]["collections"][name]
     end
 
     # Reported as healthy?

data/lib/solr_cloud/connection/alias_admin.rb

@@ -74,10 +74,16 @@ module SolrCloud
         end
       end
 
-      # The "raw" alias map, which just maps alias names to collection names
-      # @return [Hash<String, String>]
+      # The "raw" alias map, which just maps alias names to collection names.
+      #
+      # The Solr +LISTALIASES+ action omits the +"aliases"+ key entirely (returning +null+
+      # or an absent key) when no aliases are defined. This is true on Solr 10 and can
+      # occur on earlier versions as well. The +|| {}+ guard ensures callers always receive
+      # a Hash rather than +nil+.
+      #
+      # @return [Hash<String, String>] map of alias name -> collection name, empty if none exist
       def raw_alias_map
-        connection.get("solr/admin/collections", action: "LISTALIASES").body["aliases"]
+        connection.get("solr/admin/collections", action: "LISTALIASES").body["aliases"] || {}
       end
     end
   end

data/lib/solr_cloud/connection/configset_admin.rb

@@ -4,15 +4,30 @@ require "zip"
 
 module SolrCloud
   class Connection
-    # methods having to do with configsets, to be included by the connection object.
+    # Methods having to do with configsets, to be included by the connection object.
     # These are split out only to make it easier to deal with them.
     module ConfigsetAdmin
       # Given the path to a solr configuration "conf" directory (i.e., the one with
       # solrconfig.xml in it), zip it up and send it to solr as a new configset.
+      #
+      # The upload API endpoint differs across major Solr versions:
+      #
+      # - *Solr 8*: uses the V2 API (+PUT /api/cluster/configs/<name>+), which was the
+      #   canonical configset path in Solr 8.
+      # - *Solr 9+*: uses the V2 API (+PUT /api/configsets/<name>+).
+      #   The V2 configset path moved from +/api/cluster/configs/<name>+ (Solr 8) to
+      #   +/api/configsets/<name>+ (Solr 9+). The new V2 PUT defaults to overwriting an
+      #   existing configset, which means in-use configsets can be replaced without
+      #   deleting them first.
+      #
+      # Dispatches via {Connection#solr9_or_later?}; see {#upload_configset_v9} and
+      # {#upload_configset_v8} for the version-specific implementations.
+      #
       # @param name [String] Name to give the new configset
       # @param confdir [String, Pathname] Path to the solr configuration "conf" directory
       # @param force [Boolean] Whether or not to overwrite an existing configset if there is one
-      # @raise [WontOverwriteError] if the configset already exists and "force" is false
+      # @raise [IllegalNameError] if +name+ is not a valid Solr identifier
+      # @raise [WontOverwriteError] if the configset already exists and +force+ is false
       # @return [Configset] the configset created
       def create_configset(name:, confdir:, force: false)
         config_set_name = name
@@ -23,36 +38,58 @@ module SolrCloud
         if has_configset?(config_set_name) && !force
           raise WontOverwriteError.new("Won't replace configset #{config_set_name} unless 'force: true' passed ")
         end
+
         zfile = "#{Dir.tmpdir}/solr_add_configset_#{name}_#{Time.now.hash}.zip"
-        z = ZipFileGenerator.new(confdir, zfile)
-        z.write
-        @connection.put("api/cluster/configs/#{config_set_name}") do |req|
-          req.body = File.binread(zfile)
+        ZipFileGenerator.new(confdir, zfile).write
+
+        if solr9_or_later?
+          upload_configset_v9(config_set_name, zfile)
+        else
+          upload_configset_v8(config_set_name, zfile)
         end
-        # TODO: Error check in here somewhere
-        FileUtils.rm(zfile, force: true)
+
         get_configset(name)
+      ensure
+        FileUtils.rm(zfile, force: true) if zfile
       end
 
-      # Get a list of the already-defined configSets
-      # @return [Array<Configset>] possibly empty list of configSets
+      # Get a list of the already-defined configsets.
+      # @return [Array<Configset>] possibly empty list of configsets
       def configsets
         configset_names.map { |cs| Configset.new(name: cs, connection: self) }
       end
 
+      # Get the names of all defined configsets.
+      #
+      # The API endpoint differs across major Solr versions:
+      #
+      # - *Solr 8*: uses the V2 API (+GET /api/cluster/configs+).
+      # - *Solr 9+*: uses the V1 API (+GET /solr/admin/configs?action=LIST+).
+      #   The V2 configset path changed between Solr 8 and Solr 9; V1 is used for
+      #   consistency on Solr 9 and later.
+      #
       # @return [Array<String>] the names of the config sets
       def configset_names
-        connection.get("api/cluster/configs").body["configSets"]
+        if solr9_or_later?
+          connection.get("solr/admin/configs", action: "LIST").body["configSets"]
+        else
+          connection.get("api/cluster/configs").body["configSets"]
+        end
       end
 
-      # Check to see if a configset is defined
-      # @param name [String] Name of the configSet
+      # Check to see if a configset with the given name is defined.
+      # @param name [String] Name of the configset
       # @return [Boolean] Whether a configset with that name exists
       def has_configset?(name)
         configset_names.include? name.to_s
       end
 
-      # Get an existing configset
+      # Get an existing configset by name.
+      #
+      # @note Does not verify that the configset actually exists; use {#has_configset?}
+      #   to check first if needed.
+      # @param name [String] Name of the configset
+      # @return [Configset]
       def get_configset(name)
         Configset.new(name: name, connection: self)
       end
@@ -63,12 +100,25 @@ module SolrCloud
       #
       # In general, prefer using {Configset#delete!} instead of running everything
       # through the connection object.
-      # @param [String] name The name of the configuration set
-      # @raise [InUseError] if the configset can't be deleted because it's in use by a live collection
+      #
+      # The delete API endpoint differs across major Solr versions:
+      #
+      # - *Solr 8*: uses the V2 API (+DELETE /api/cluster/configs/<name>+).
+      # - *Solr 9+*: uses the V1 API (+GET /solr/admin/configs?action=DELETE+).
+      #   The V2 configset path changed between Solr 8 and Solr 9; V1 is used for
+      #   consistency on Solr 9 and later.
+      #
+      # @param name [String] The name of the configuration set
+      # @raise [ConfigSetInUseError] if the configset can't be deleted because it's in use
+      #   by a live collection
       # @return [Connection] self
       def delete_configset(name)
-        if has_configset? name
-          connection.delete("api/cluster/configs/#{name}")
+        if has_configset?(name)
+          if solr9_or_later?
+            connection.get("solr/admin/configs", action: "DELETE", name: name)
+          else
+            connection.delete("api/cluster/configs/#{name}")
+          end
         end
         self
       rescue Faraday::BadRequestError => e
@@ -125,6 +175,43 @@ module SolrCloud
           zipfile.add(zipfile_path, disk_file_path)
         end
       end
+
+      private
+
+      # Upload a configset zip using the Solr 9+ V2 API.
+      #
+      # Sends a +PUT+ to +/api/configsets/<name>+ with the zip file as an
+      # octet-stream body. The V2 configset upload path moved from
+      # +/api/cluster/configs/<name>+ (Solr 8) to +/api/configsets/<name>+ (Solr 9+).
+      # The new V2 PUT defaults to overwriting any existing configset at that name,
+      # so in-use configsets can be replaced without deleting first.
+      #
+      # @param name [String] configset name
+      # @param zipfile_path [String] filesystem path to the zip archive to upload
+      # @return [void]
+      def upload_configset_v9(name, zipfile_path)
+        connection.put("api/configsets/#{name}") do |req|
+          req.headers["Content-Type"] = "application/octet-stream"
+          req.body = File.binread(zipfile_path)
+        end
+      end
+
+      # Upload a configset zip using the Solr 8 V2 API.
+      #
+      # Sends a +PUT+ to +/api/cluster/configs/<name>+ with the zip file as an
+      # octet-stream body. This was the canonical V2 configset upload path in Solr 8.
+      # The path changed to +/api/configsets/<name>+ in Solr 9; use {#upload_configset_v1}
+      # for Solr 9 and later.
+      #
+      # @param name [String] configset name
+      # @param zipfile_path [String] filesystem path to the zip archive to upload
+      # @return [void]
+      def upload_configset_v8(name, zipfile_path)
+        connection.put("api/cluster/configs/#{name}") do |req|
+          req.headers["Content-Type"] = "application/octet-stream"
+          req.body = File.binread(zipfile_path)
+        end
+      end
     end
   end
 end

data/lib/solr_cloud/connection/version.rb

@@ -2,6 +2,6 @@
 
 module SolrCloud
   class Connection
-    VERSION = "0.6.0"
+    VERSION = "1.0.0"
   end
 end

data/lib/solr_cloud/connection.rb

@@ -176,6 +176,17 @@ module SolrCloud
       _version_part_int(2)
     end
 
+    # Returns true if the connected Solr instance is version 9 or later (9, 10, 11, ...).
+    #
+    # Several Solr APIs changed paths between Solr 8 and Solr 9. This predicate is used
+    # internally to dispatch to the correct API endpoint when behavior differs across major
+    # versions. External callers may also use it to gate version-specific logic.
+    #
+    # @return [Boolean] true if the server reports major version >= 9
+    def solr9_or_later?
+      major_version >= 9
+    end
+
     # Check to see if the given string follows solr's rules for thing
     # Solr only allows ASCII letters and numbers, underscore, and dash,
     # and it can't start with an underscore.

data/solr10_compat_update_plan.md

@@ -0,0 +1,290 @@
+# Solr 8 / 9 / 10 Compatibility Update Plan
+
+## Overview
+
+Make `solr_cloud-connection` work correctly with Solr 8, 9, and 10 simultaneously. The approach:
+branch on `major_version` where APIs differ, and use V1 (legacy) APIs where they work uniformly
+across versions.
+
+Version detection is already in place in `connection.rb` via `major_version`, `minor_version`,
+and `patch_version` methods derived from `GET /solr/admin/info/system`.
+
+Source examined: `main` branch and `fix/solr-10-api-compatibility` branch.
+API docs source: Apache Solr Reference Guide 10.0 (live, fetched May 2026).
+
+---
+
+## Root Cause
+
+The main branch uses Solr 8-era V2 API paths for configset management
+(`api/cluster/configs/*`). These paths changed in Solr 9/10 to `api/configsets/*`.
+Additionally, the V1 `LISTALIASES` action returns `null` (not `{}`) in Solr 10 when
+no aliases exist, causing a `NoMethodError` on `nil.keys`.
+
+The `fix/solr-10-api-compatibility` branch already addresses this by switching configset
+operations wholesale to V1 APIs and adding a `|| {}` nil guard, but it does so without
+version branching. This plan implements proper version-based dispatch.
+
+---
+
+## API Compatibility Matrix
+
+| Method / File | Solr 8 (main branch) | Solr 9/10 compat? | Notes |
+|---|---|---|---|
+| `configset_admin#create_configset` | `PUT api/cluster/configs/{name}` (V2) | NO | V2 path changed |
+| `configset_admin#configset_names` | `GET api/cluster/configs` (V2) | NO | V2 path changed |
+| `configset_admin#delete_configset` | `DELETE api/cluster/configs/{name}` (V2) | NO | V2 path changed |
+| `alias_admin#raw_alias_map` | `GET solr/admin/collections?action=LISTALIASES` | PARTIAL | returns nil when empty |
+| `alias_admin#create_alias` | V1 CREATEALIAS | YES | V1 works in all versions |
+| `alias#delete!` | V1 DELETEALIAS | YES | V1 works in all versions |
+| `collection_admin#only_collections` | `GET api/collections` (V2) | YES | same response format |
+| `collection_admin#create_collection` | V1 CREATE | YES | V1 works in all versions |
+| `collection#delete!` | V1 DELETE | YES | V1 works in all versions |
+| `collection#info` | `GET api/collections/{name}` (V2) | UNKNOWN | needs testing; see below |
+
+---
+
+## Changes Required
+
+### 1. `connection.rb` -- add version-helper predicate
+
+Add a convenience predicate to avoid repeating `major_version >= 9` comparisons inline:
+
+```ruby
+# Returns true for Solr 9 and later (including 10, 11, ...)
+def solr9_or_later?
+  major_version >= 9
+end
+```
+
+Place it alongside the existing `major_version` / `minor_version` / `patch_version` methods.
+No changes to `bail_if_incompatible!`.
+
+---
+
+### 2. `connection/configset_admin.rb` -- version-branch all three methods
+
+The V2 configset paths changed between Solr 8 and Solr 9:
+
+| Operation | Solr 8 V2 path | Solr 9/10 V2 path | V1 path (all versions) |
+|---|---|---|---|
+| Upload | `PUT api/cluster/configs/{name}` | `PUT api/configsets/{name}` | `POST solr/admin/configs?action=UPLOAD&name={name}` |
+| List | `GET api/cluster/configs` -> `["configSets"]` | `GET api/configsets` -> `["configSets"]` | `GET solr/admin/configs?action=LIST` -> `["configSets"]` |
+| Delete | `DELETE api/cluster/configs/{name}` | `DELETE api/configsets/{name}` | `GET solr/admin/configs?action=DELETE&name={name}` |
+
+Strategy: use V1 for Solr 9+, keep existing V2 for Solr 8. V1 works in Solr 8 too, so
+an alternative is to use V1 for all versions and avoid branching entirely -- but the task
+requires explicit version dispatch.
+
+#### `create_configset`
+
+```ruby
+def create_configset(name:, confdir:, force: false)
+  raise WontOverwriteError.new("Configset '#{name}' already exists") if has_configset?(name) && !force
+  zipfile = zip_configset_dir(confdir)
+  if connection.solr9_or_later?
+    connection.post("solr/admin/configs?action=UPLOAD&name=#{name}") do |req|
+      req.headers["Content-Type"] = "application/octet-stream"
+      req.body = File.binread(zipfile)
+    end
+  else
+    connection.put("api/cluster/configs/#{name}") do |req|
+      req.headers["Content-Type"] = "application/octet-stream"
+      req.body = File.binread(zipfile)
+    end
+  end
+  get_configset(name)
+ensure
+  FileUtils.rm_f(zipfile) if zipfile
+end
+```
+
+Note: the `fix` branch uses `connection.post("solr/admin/configs", action: "UPLOAD",
+name: name)` but that places action/name as query params on a POST. The Solr V1 API
+docs specify these as query string parameters for the UPLOAD action, so either form works.
+Verify with integration tests.
+
+#### `configset_names`
+
+```ruby
+def configset_names
+  if connection.solr9_or_later?
+    connection.get("solr/admin/configs", action: "LIST").body["configSets"]
+  else
+    connection.get("api/cluster/configs").body["configSets"]
+  end
+end
+```
+
+#### `delete_configset`
+
+```ruby
+def delete_configset(name:)
+  return unless has_configset?(name)
+  if connection.solr9_or_later?
+    connection.get("solr/admin/configs", action: "DELETE", name: name)
+  else
+    connection.delete("api/cluster/configs/#{name}")
+  end
+end
+```
+
+---
+
+### 3. `connection/alias_admin.rb` -- nil guard (bug fix, not version-specific)
+
+`raw_alias_map` crashes with `NoMethodError` when no aliases exist because the Solr
+`LISTALIASES` response omits the `aliases` key entirely (returns `null` or simply absent).
+This is confirmed on Solr 10 and the fix is straightforward:
+
+```ruby
+def raw_alias_map
+  connection.get("solr/admin/collections", action: "LISTALIASES").body["aliases"] || {}
+end
+```
+
+This fix is already present in `fix/solr-10-api-compatibility`. It is not version-specific --
+apply it unconditionally, as it is defensive coding.
+
+---
+
+### 4. `lib/solr_cloud/collection.rb` -- verify `info` endpoint (needs testing)
+
+`Collection#info` calls:
+
+```ruby
+connection.get("api/collections/#{name}").body["cluster"]["collections"][name]
+```
+
+The response path `body["cluster"]["collections"][name]` matches the structure returned by
+the V1 `CLUSTERSTATUS` API and the V2 `GET /api/cluster` endpoint. Whether
+`GET /api/collections/{name}` returns this same nested structure in Solr 9/10 is not
+confirmed from docs alone.
+
+**Action required:**
+- Run integration tests against Solr 9 and Solr 10 containers with the existing code
+- If `api/collections/{name}` returns a different response structure in Solr 9/10,
+  add version branching:
+
+  ```ruby
+  def info
+    if connection.solr9_or_later?
+      # Fallback to V1 CLUSTERSTATUS filtered to this collection
+      connection.get("solr/admin/collections",
+        action: "CLUSTERSTATUS",
+        collection: name
+      ).body["cluster"]["collections"][name]
+    else
+      connection.get("api/collections/#{name}").body["cluster"]["collections"][name]
+    end
+  end
+  ```
+
+  V1 `CLUSTERSTATUS` with `collection` param is confirmed to work in both Solr 8 and 10
+  and returns the exact same `cluster.collections.{name}` structure.
+
+---
+
+### 5. No changes needed
+
+The following use V1 APIs or V2 APIs that are stable across Solr 8, 9, and 10:
+
+- `alias_admin#create_alias` -- V1 `CREATEALIAS`
+- `alias#delete!` -- V1 `DELETEALIAS`
+- `collection_admin#create_collection` -- V1 `CREATE`
+- `collection_admin#only_collections` -- `GET api/collections` response format confirmed
+  unchanged in Solr 10 (`{"collections": [...]}`)
+- `collection#delete!` -- V1 `DELETE`
+- `connection#system` / `version_string` / `major_version` etc. -- `/solr/admin/info/system`
+  unchanged
+
+---
+
+## Implementation Pattern
+
+Use private dispatch methods to keep the public interface clean:
+
+```ruby
+# In ConfigsetAdmin module:
+
+def create_configset(name:, confdir:, force: false)
+  raise WontOverwriteError.new(...) if has_configset?(name) && !force
+  zipfile = zip_configset_dir(confdir)
+  solr9_or_later? ? upload_configset_v1(name, zipfile) : upload_configset_v8(name, zipfile)
+  get_configset(name)
+ensure
+  FileUtils.rm_f(zipfile) if zipfile
+end
+
+private
+
+def upload_configset_v1(name, zipfile)
+  connection.post("solr/admin/configs?action=UPLOAD&name=#{name}") do |req|
+    req.headers["Content-Type"] = "application/octet-stream"
+    req.body = File.binread(zipfile)
+  end
+end
+
+def upload_configset_v8(name, zipfile)
+  connection.put("api/cluster/configs/#{name}") do |req|
+    req.headers["Content-Type"] = "application/octet-stream"
+    req.body = File.binread(zipfile)
+  end
+end
+```
+
+Where the dispatch is simple (one line each branch), inline `if/else` is acceptable.
+Prefer private methods when the per-version logic is more than 2 lines.
+
+---
+
+## Test Infrastructure
+
+The existing spec infrastructure uses Docker Compose in `spec/data/solr_docker/`.
+
+Add a Solr 10 service (and optionally Solr 9) alongside the existing Solr 8 service:
+
+```yaml
+# In spec/data/solr_docker/docker-compose.yml (new service):
+solr10:
+  image: solr:10-slim
+  ports:
+    - "18984:8983"
+  command: solr-demo
+  # or whatever start command the existing solr8 service uses
+```
+
+Update the integration test runner (likely a Rake task or script) to run the full spec
+suite twice: once against Solr 8 and once against Solr 10 (passing the base URL as an
+environment variable).
+
+If the test suite already accepts a `SOLR_URL` environment variable, this is straightforward.
+If it hardcodes a port, parameterize it.
+
+---
+
+## Implementation Order
+
+1. Add `solr9_or_later?` to `connection.rb`
+2. Apply `|| {}` nil guard to `alias_admin.rb#raw_alias_map` (already in fix branch --
+   cherry-pick or re-apply)
+3. Version-branch `configset_admin.rb`: `configset_names`, `delete_configset`,
+   `create_configset` (in that order -- names and delete first so tests can verify the
+   cycle without broken upload)
+4. Add Solr 10 container to Docker Compose test setup
+5. Run integration tests against both Solr 8 and Solr 10
+6. If `Collection#info` fails against Solr 10, add version-branch (step 4 above)
+7. Update gem version (patch or minor, depending on whether the nil-guard fix is considered
+   a breaking change)
+
+---
+
+## Notes on the fix/solr-10-api-compatibility Branch
+
+That branch's approach (switch all configset ops to V1 unconditionally) is functionally
+correct and simpler. If backward compatibility with the V2 Solr 8 behavior is not a concern,
+that approach is acceptable and lower-risk than version branching. The user has explicitly
+requested version-based dispatch, which this plan implements.
+
+If Solr 8 V2 API support is dropped in a future major version of the gem, the branches
+can be collapsed to use V1 everywhere.

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: solr_cloud-connection
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Bill Dueber
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-18 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -154,7 +153,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description:
 email:
 - bill@dueber.com
 executables: []
@@ -166,11 +164,13 @@ files:
 - ".standard.yml"
 - CHANGELOG.md
 - Dockerfile
+- LICENSE.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - compose.yml
 - env.test
+- env.test.solr10
 - lib/solr_cloud/alias.rb
 - lib/solr_cloud/collection.rb
 - lib/solr_cloud/configset.rb
@@ -181,13 +181,13 @@ files:
 - lib/solr_cloud/connection/version.rb
 - lib/solr_cloud/errors.rb
 - readme.rb
+- solr10_compat_update_plan.md
 homepage: https://github.com/mlibrary/solr_cloud-connection
 licenses: []
 metadata:
   homepage_uri: https://github.com/mlibrary/solr_cloud-connection
   source_code_uri: https://github.com/mlibrary/solr_cloud-connection
   changelog_uri: https://github.com/mlibrary/solr_cloud-connection/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -202,8 +202,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Do basic administrative operations on a solr cloud instance and collections
   within