solr_cloud-connection 0.5.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0d4b1ea9a7eade492c2e88434c38dadc43bcbb5a28084c4be797ce2c77eb70ce
-  data.tar.gz: 5531b66702ac408e0631239568035f2693cbda02b06e5401b858caa3bd633d9f
+  metadata.gz: 19bcfd12d8bc2169aad5f3a01163996e671c0e8b2594ad50197ee7127abf15a9
+  data.tar.gz: 9088cfcdf21b11fe5ac92fd35ea2d5ec66ea55471d9a0e3a16edf2304db22bf4
 SHA512:
-  metadata.gz: b6fcb28bcf8a42191ce737b4c5ae431d669a66e92b3a2d947e26c7901f3a9b5ec0afd4353d00bf6db4ae397a10c4c8aee629c366fbb6976595170b47b7cf1e2a
-  data.tar.gz: c8689a6b34f2ba3307ac1bfd19adf2c5fff13ecfd7b6aa2fc934754c9667569b369fddfcb4f796528d3594d5babf3213c603a9871cb92edbbb28a6f78e45e006
+  metadata.gz: 61d0a5ce50ec30182bc0e60c915a78b6cc492039291634b53e48efb5fd91124643c97ebafc9ad9043d690bf0f28dbd047c5d1688acfb927c5ca126320d9e00c7
+  data.tar.gz: 9771f4d1047ef1210eecd1fc78b376363c7d9d7cd34b4c72023eb9f502aa746c1247844de176d03c9c3db8aec9673fa9d65edd97eb06c7f4d9bb18ec7a70a217

data/CHANGELOG.md

@@ -1,5 +1,43 @@
 # 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
+- Better errors
+- Flesh out README.md to be a useful document
+
+
 ## [0.4.0] - 2023-12-07
 - Fixed rules about what names are legal collections/configsets/aliases
 - Update version and changelog

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/README.md

@@ -1,14 +1,36 @@
 # SolrCloud::Connection
 
-Do basic administrative tasks on a running Solr cloud instance, including:
+## Common usage
 
-* create (i.e., upload) a configSet when given a `conf` directory
-* list, create, and delete configsets, collections, and aliases
-* get basic version information for the running solr
-* check on the health of individual collections
-* treat an alias (mostly) as a collection
-* TODO automatically generate methods to talk to defined requestHandlers
-* TODO Add something useful for configsets to do
+```ruby
+
+# Connect to the server, upload a config set, make a collection based on it,
+# and make an alias pointing to that collection
+
+server = SolrCloud::Connection.new(url: url, user: user, password: pass) 
+cfg = server.create_configset(name: "my_cfg", confdir: "/path/to/my/conf")
+cars_v1 = server.create_collection(name: "cars_v1", configset: "my_cfg")
+cars = cars_v1.alias_as("cars")
+
+```
+
+## Basic functionality / Roadmap
+
+Do basic administrative tasks on a running Solr cloud instance
+
+* [x] create (i.e., upload) a configSet when given a `conf` directory
+* [x] list, create, and delete configsets, collections, and aliases
+* [x] get basic version information for the running solr
+* [x] check on the health of individual collections
+* [x] treat an alias (mostly) as a collection
+* [ ] automatically generate methods to talk to defined requestHandlers and updateHandlers
+* [ ] provide a way to talk to the analyzer for testing of fieldTypes
+* [ ] hook into the schema API
+* [ ] allow it to work with cores, and not just solrcloud collections (which, you know bad naming then)
+* [ ] figure out how to deal with managed resources
+* [ ] get info from updateHandler metrics, esp. pending documents and cumulative errors
+* [ ] hook into performance metrics for easy reporting and checks
+* [ ] support more of the v2 API 
 
 In almost all cases, you can treat an alias to a collection like the underlying collection. 
 
@@ -43,6 +65,8 @@ user = "solr"
 password = "SolrRocks"
 config_directory = "/path/to/myconfig/conf" # Directory 'conf' contains solrconfig.xml
 
+require "solr_cloud/connection"
+
 server = SolrCloud::Connection.new(url: url, user: user, password: pass) 
   #=> <SolrCloud::Connection http://localhost:9090>
 
@@ -66,19 +90,25 @@ server.configset_names #=> ["_default"]
 
 # Create a new configset by taking a conf directory, zipping it up,
 # and sending it to solr
-cset = server.create_configset(name: "horseless", confdir: config_directory) #=> <SolrCloud::Configset 'horseless' at http://localhost:9090>
+cset = server.create_configset(name: "horseless", confdir: config_directory)
+  #=> <SolrCloud::Configset 'horseless' at http://localhost:9090>
 server.configset_names #=> ["_default", "horseless"]
 
 # That's a dumb name for a config set. Delete it and try again.
 cset.delete! #=> <SolrCloud::Connection http://localhost:9090>
-cset = server.create_configset(name: "cars_cfg", confdir: config_directory) #=> <SolrCloud::Configset 'cars_cfg' at http://localhost:9090>
-server.configsets #=> [<SolrCloud::Configset '_default' at http://localhost:9090>, <SolrCloud::Configset 'cars_cfg' at http://localhost:9090>]
+cset = server.create_configset(name: "cars_cfg", confdir: config_directory)
+  #=> <SolrCloud::Configset 'cars_cfg' at http://localhost:9090>
+server.configsets
+  #=> [<SolrCloud::Configset '_default' at http://localhost:9090>,
+  #    <SolrCloud::Configset 'cars_cfg' at http://localhost:9090>]
 
 # Can't be overwritten by accident
-server.create_configset(name: "cars_cfg", confdir: config_directory) #=> raised #<SolrCloud::WontOverwriteError: Won't replace configset cars_cfg unless 'force: true' passed >
+server.create_configset(name: "cars_cfg", confdir: config_directory)
+  #=> raised #<SolrCloud::WontOverwriteError: Won't replace configset cars_cfg unless 'force: true' passed >
 
 # But you can force it
-server.create_configset(name: "cars_cfg", confdir: config_directory, force: true) #=> <SolrCloud::Configset 'cars_cfg' at http://localhost:9090>
+server.create_configset(name: "cars_cfg", confdir: config_directory, force: true)
+  #=> <SolrCloud::Configset 'cars_cfg' at http://localhost:9090>
 
 cfg = server.get_configset("cars_cfg") #=> <SolrCloud::Configset 'cars_cfg' at http://localhost:9090>
 cfg.in_use? #=> false
@@ -127,7 +157,8 @@ cars_v1.aliased? #=> true
 
 cars_v1.has_alias?("cars") #=> true
 cars_v1.alias_as("autos") #=> <SolrCloud::Alias 'autos' (alias of 'cars_v1')>
-cars_v1.aliases #=> [<SolrCloud::Alias 'cars' (alias of 'cars_v1')>, <SolrCloud::Alias 'autos' (alias of 'cars_v1')>]
+cars_v1.aliases
+  #=> [<SolrCloud::Alias 'cars' (alias of 'cars_v1')>, <SolrCloud::Alias 'autos' (alias of 'cars_v1')>]
 
 cars_v1.get_alias("autos").delete! #=> <SolrCloud::Connection http://localhost:9090>
 cars_v1.aliases #=> [<SolrCloud::Alias 'cars' (alias of 'cars_v1')>]
@@ -226,5 +257,5 @@ This repository is set up to run tests under docker.
 
 ## Contributing
 
-Bugs, functionality suggestions, API suggestions, feature requests, etc. all welcom
+Bugs, functionality suggestions, API suggestions, feature requests, etc. all welcome
 on GitHub at https://github.com/mlibrary/solr_cloud-connection.

data/Rakefile

@@ -10,7 +10,7 @@ require "standard/rake"
 task default: %i[spec standard docs]
 task docs: %i[yard]
 
-require 'yard'
+require "yard"
 
 YARD::Rake::YardocTask.new do |t|
   t.files = ["lib/**/*.rb"] # optional

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/alias.rb

@@ -41,13 +41,13 @@ module SolrCloud
     # @return [Collection] the now-current collection
     def switch_collection_to(coll)
       collect_name = case coll
-                       when String
-                         coll
-                       when Collection
-                         coll.name
-                       else
-                         raise "Alias#switch_collection_to only takes a name(string) or a collection, not '#{coll}'"
-                     end
+      when String
+        coll
+      when Collection
+        coll.name
+      else
+        raise "Alias#switch_collection_to only takes a name(string) or a collection, not '#{coll}'"
+      end
       raise NoSuchCollectionError unless connection.has_collection?(collect_name)
       connection.create_alias(name: name, collection_name: collect_name, force: true)
     end

data/lib/solr_cloud/collection.rb

@@ -55,10 +55,10 @@ module SolrCloud
 
     def ==(other)
       case other
-        when SolrCloud::Collection
-          self.collection.name == other.collection.name
-        else
-          false
+      when SolrCloud::Collection
+        collection.name == other.collection.name
+      else
+        false
       end
     end
 
@@ -68,7 +68,7 @@ module SolrCloud
     def delete!
       return connection unless exist?
       raise CollectionAliasedError.new("Cannot delete collection #{name}; it has alias(s) #{alias_names.join(", ")}") if aliased?
-      connection.get("solr/admin/collections", { action: "DELETE", name: name })
+      connection.get("solr/admin/collections", {action: "DELETE", name: name})
       connection
     end
 
@@ -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?
@@ -181,10 +188,10 @@ module SolrCloud
 
     def add(docs)
       docarray = if docs === Array
-                   docs
-                 else
-                   [docs]
-                 end
+        docs
+      else
+        [docs]
+      end
       post("solr/#{name}/update/") do |r|
         r.body = docarray
       end
@@ -200,10 +207,10 @@ module SolrCloud
     def inspect
       anames = alias_names
       astring = if anames.empty?
-                  ""
-                else
-                  " (aliased by #{anames.map { |x| "'#{x}'" }.join(", ")})"
-                end
+        ""
+      else
+        " (aliased by #{anames.map { |x| "'#{x}'" }.join(", ")})"
+      end
       "<#{self.class} '#{name}'#{astring}>"
     end
 

data/lib/solr_cloud/configset.rb

@@ -7,7 +7,6 @@ module SolrCloud
   # throw an error if that's an illegal operation (because a collection is
   # using it)
   class Configset
-
     # @return [String] the name of this configset
     attr_reader :name
 

data/lib/solr_cloud/connection/alias_admin.rb

@@ -5,7 +5,6 @@ module SolrCloud
     # methods having to do with aliases, to be included by the connection object.
     # These are split out only to make it easier to deal with them.
     module AliasAdmin
-
       # A simple data-class to pair an alias with its collection
       AliasCollectionPair = Struct.new(:alias, :collection)
 
@@ -24,7 +23,7 @@ module SolrCloud
         end
         raise NoSuchCollectionError.new("Can't find collection #{collection_name}") unless has_collection?(collection_name)
         if has_alias?(name) && !force
-          raise WontOverwriteError.new("Alias '#{name}' already points to collection '#{self.get_alias(name).collection.name}'; won't overwrite without force: true")
+          raise WontOverwriteError.new("Alias '#{name}' already points to collection '#{get_alias(name).collection.name}'; won't overwrite without force: true")
         end
         connection.get("solr/admin/collections", action: "CREATEALIAS", name: name, collections: collection_name)
         get_alias(name)
@@ -75,13 +74,17 @@ 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
 end
-
-

data/lib/solr_cloud/connection/collection_admin.rb

@@ -20,17 +20,16 @@ module SolrCloud
       # @raise [WontOverwriteError] if the collection already exists
       # @return [Collection] the collection created
       def create_collection(name:, configset:, shards: 1, replication_factor: 1)
-
         unless legal_solr_name?(name)
           raise IllegalNameError.new("'#{name}' is not a valid solr name. Use only ASCII letters/numbers, dash, and underscore")
         end
 
         configset_name = case configset
-                           when Configset
-                             configset.name
-                           else
-                             configset.to_s
-                         end
+        when Configset
+          configset.name
+        else
+          configset.to_s
+        end
         raise WontOverwriteError.new("Collection #{name} already exists") if has_collection?(name)
         raise NoSuchConfigSetError.new("Configset '#{configset_name}' doesn't exist") unless has_configset?(configset_name)
 

data/lib/solr_cloud/connection/configset_admin.rb

@@ -4,16 +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
@@ -24,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
@@ -64,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
@@ -126,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.5.0"
+    VERSION = "1.0.0"
   end
 end

data/lib/solr_cloud/connection.rb

@@ -31,12 +31,20 @@ module SolrCloud
     # @return [String] String representation of the URL to solr
     attr_reader :url
 
+    # @return [String] solr user
+    attr_reader :user
+    alias_method :username, :user
+
+    # @return [String] Solr password
+    attr_reader :password
+
     # @return [#info] The logger
     attr_reader :logger
 
     # @return [Faraday::Connection] the underlying Faraday connection
     attr_reader :connection
 
+
     # let the underlying connection handle HTTP verbs
 
     # @!method get
@@ -72,12 +80,12 @@ module SolrCloud
       @user = user
       @password = password
       @logger = case logger
-                  when :off, :none
-                    Logger.new(File::NULL, level: Logger::FATAL)
-                  when nil
-                    Logger.new($stderr, level: Logger::WARN)
-                  else
-                    logger
+                when :off, :none
+                  Logger.new(File::NULL, level: Logger::FATAL)
+                when nil
+                  Logger.new($stderr, level: Logger::WARN)
+                else
+                  logger
                 end
       @connection = create_raw_connection(url: url, adapter: adapter, user: user, password: password, logger: @logger)
       bail_if_incompatible!
@@ -112,10 +120,6 @@ module SolrCloud
       end
     end
 
-    # Allow accessing the raw_connection via "connection". Yes, connection.connection
-    # can be confusing, but it makes the *_admin stuff easier to read.
-    alias_method :connection, :connection
-
     # Check to see if we can actually talk to the solr in question
     # raise [UnsupportedSolr] if the solr version isn't at least 8
     # raise [ConnectionFailed] if we can't connect for some reason
@@ -172,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.
@@ -192,6 +207,3 @@ module SolrCloud
     end
   end
 end
-
-
-

data/readme.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require "pathname"
 $LOAD_PATH.unshift Pathname.new(__dir__) + "lib"
 require_relative "lib/solr_cloud/connection"
@@ -7,13 +8,11 @@ url = "http://localhost:9090"
 user = "solr"
 pass = "SolrRocks"
 
-
 server = SolrCloud::Connection.new(url: url, user: user, password: pass) #=>
 
-
-server.aliases.each {|a| a.delete!}
-server.collections.each {|c| c.delete!}
-server.configsets.reject {|c| c.name == "_default"}.each {|c| c.delete!}
+server.aliases.each { |a| a.delete! }
+server.collections.each { |c| c.delete! }
+server.configsets.reject { |c| c.name == "_default" }.each { |c| c.delete! }
 
 # or bring your own Faraday object
 # server2 = SolrCloud::Connection.new_with_faraday(faraday_connection)
@@ -83,8 +82,6 @@ begin
 rescue
 end
 
-
-
 ##### Aliases
 
 # We'll want to alias it so we can just use 'cars'
@@ -125,9 +122,6 @@ cars.switch_collection_to("cars_v1")
 server.collection_names
 
 # They even == to each other
-cars
-cars == cars_v1
-cars == cars_v2
 
 # But sometimes you want to differentiate them from each other
 server.only_collection_names

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.5.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Bill Dueber
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-03-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -53,76 +52,107 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
-  name: dotenv
+  name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: standard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.35.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.35.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.22.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.22.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.9.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
-description:
+        version: 0.9.0
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.0
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 email:
 - bill@dueber.com
 executables: []
@@ -134,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
@@ -149,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
@@ -170,8 +202,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.17
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Do basic administrative operations on a solr cloud instance and collections
   within