solr_cloud-connection 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2257fc2ce8c0a649712a66c5154222cfd6d2e0b0d837df583d297eba3d19d6bb
-  data.tar.gz: b9fdf5d5dd5a3c8d2fe4ec5a0e47f414fc9186a020292d34631e887591528327
+  metadata.gz: da67e9a6312ae058259368a9933abe711d1c0554337c59c5f688cf2f17cee606
+  data.tar.gz: 36b815217b2f3e806d9b639d4839f093d61327ee496fee1c3d4774039c688e48
 SHA512:
-  metadata.gz: 53b06b39cb208dff15696c94541aae3e3069d577be2b16d587f3a8fb86594dac0eef88a9fc4800564d469bfe898ae281421b04fef957af89472085e420f60de2
-  data.tar.gz: 3a6daabf59f8dc61fdd2d21019596714649219e50ce6983a4c6ba873d188782c6b3b6a32e932d66512e3e9eab83f4516137f3605f22fbab968811e73e5d78170
+  metadata.gz: c828e6c7f7976cee46ac7b81c8955d2253253e3084e3841e26a502bf2d03808327578e69e63a47c0907dd7d38df3db27747a2383a6e8a6f9f4b1a73c69832340
+  data.tar.gz: 25548a6825b308a62ec376bf1b59d596a557c8508f9feeb56cabd5bc402907ecf4f7602658c5087483424844d1fffddf2c7673ecc2f16cefb3ad79f03696aba5

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [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/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. 
 
@@ -22,7 +44,7 @@ a collections that's pointed to by an alias.
 ## Caveats
 
 * At this point the API is unstable
-* Performance is desperately, hilariously terrible. Solr has no sense of an atomic action and plenty of other ways
+*  Solr has no sense of an atomic action and plenty of other ways
   (e.g, the admin interface) to mess with things, so nothing is cached. 
   This means that individual actions can involve several round-trips to solr. If you're doing so much admin
   that this becomes a bottleneck, you're well outside this gem's target case.
@@ -34,70 +56,179 @@ a collections that's pointed to by an alias.
 The code below covers all the basics. See the docs for full sets of parameters, which errors are
 thrown, etc. 
 
+
+### Create a connection to the server
+
 ```ruby
+url = "http://localhost:9090/"
+user = "solr"
+password = "SolrRocks"
+config_directory = "/path/to/myconfig/conf" # Directory 'conf' contains solrconfig.xml
 
 require "solr_cloud/connection"
 
-server = SolrCloud::connect.new(url: "http://localhost:8023", username: "user", password: "password")
-#    #=> <SolrCloud::Connection http://localhost:8023/>
+server = SolrCloud::Connection.new(url: url, user: user, password: pass) 
+  #=> <SolrCloud::Connection http://localhost:9090>
 
-# or bring your own Faraday object
-# server = SolrCloud::connect.new_with_faraday(faraday_connection)
+  # or bring your own Faraday object
+  # server2 = SolrCloud::Connection.new_with_faraday(faraday_connection)
+
+  ### Get some basic info
+
+server.version_string #=> "8.11.2"
+server.cloud? #=> true
+server.mode #=> "solrcloud"
+```
 
+### Configsets
+```ruby
+# List the configsets
+server.configsets #=> [<SolrCloud::Configset '_default' at http://localhost:9090>]
+
+# Sometimes you just want the names.
 server.configset_names #=> ["_default"]
-default = server.get_configset("_default") #=> <SolrCloud::Configset '_default' at http://localhost:8983>
 
-# Create a new one by taking a directory, zipping it up, and sending it to solr
-cset = server.create_configset(name: "my_awesome_configset_for_cars", confdir: "/path/to/mycore/conf")
-server.configset_names #=> ["_default", "my_awesome_configset_for_cars"]
+# 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>
+server.configset_names #=> ["_default", "horseless"]
 
-# That's a dumb name. We'll try again.
-cset.delete!
-cset = server.create_configset(name: "cars_config", confdir: "/path/to/mycore/conf")
+# 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>]
 
-# Collections and aliases are mostly treated the same
-server.collection_names #=> ["cars_v1", "cars_v2", "cars"] -- collections AND aliases
-server.only_collection_names #=> ["cars_v1", "cars_v2"]
-server.alias_names #=> ["cars"]
+# 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 >
 
-typo = server.get_collection("cars__V2") #=> nil, doesn't exist
-cars_v2 = server.get_collection("cars_v2")
+# But you can force it
+server.create_configset(name: "cars_cfg", confdir: config_directory, force: true)
+  #=> <SolrCloud::Configset 'cars_cfg' at http://localhost:9090>
 
-cars_v2.alive? #=> true
-cars_v2.count #=> 133 -- we're assuming there's stuff in it.
+cfg = server.get_configset("cars_cfg") #=> <SolrCloud::Configset 'cars_cfg' at http://localhost:9090>
+cfg.in_use? #=> false
 
+```
 
-# Find out about its aliases, if any
-cars_v2.alias? #=> false. It's a true collection
-cars_v2.aliased? #=> true
-cars_v2.aliases #=> [<SolrCloud::Alias "cars" (alias of "cars_v2")> ]
-cars_v2.has_alias?("cars") #=> true
+### Collections
 
-cars_v2.delete! #=> SolrCloud::CollectionAliasedError: Collection 'cars_v2' can't be deleted; it's in use by aliases ["cars"]
+```ruby
+# Now create a collection based on an already-existing configset
+cars_v1 = server.create_collection(name: "cars_v1", configset: "cars_cfg") 
+  #=> <SolrCloud::Collection 'cars_v1'>
+server.collections #=> [<SolrCloud::Collection 'cars_v1'>]
+server.collection_names #=> ["cars_v1"]
 
-# Make a new collection
-cars_v3 = server.create_collection(name: "cars_v3", configset: "cars_config")
-cars_v3.aliased? #=> false
-cars_v3.count #=> 0
-cars_v3.configset #=> <SolrCloud::Configset 'cars_config' at http://localhost:8023>
+# Check it out quick
+cars_v1.alive? #=> "OK"
+cars_v1.healthy? #=> true
+cars_v1.count #=> 0
 
-# Work directly with an alias as if it's a collection
-cars = server.get_collection("cars")
-cars.alias? #=> true
+# Any aliases
+cars_v1.aliased? #=> false
+cars_v1.aliases #=> []
+
+# Its configset
+cars_v1.configset #=> <SolrCloud::Configset 'cars_cfg' at http://localhost:9090>
+
+# Commit anything that's been added
+cars_v1.commit #=> <SolrCloud::Collection 'cars_v1'>
+
+# Solr knows when a configset is in use, and won't delete it
+
+cfg.delete! 
+    #=> raised #<SolrCloud::ConfigSetInUseError: Can not delete ConfigSet 
+    # as it is currently being used by collection [cars_v1]>
+
+```
+
+### Aliases
+
+```ruby
+# We'll want to alias it so we can just use 'cars'
+cars = cars_v1.alias_as("cars") #=> <SolrCloud::Alias 'cars' (alias of 'cars_v1')>
+cars_v1.alias? #=> false
+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.get_alias("autos").delete! #=> <SolrCloud::Connection http://localhost:9090>
+cars_v1.aliases #=> [<SolrCloud::Alias 'cars' (alias of 'cars_v1')>]
+
+# There's syntactic sugar for switching out aliases
+cars_v2 = server.create_collection(name: "cars_v2", configset: "cars_cfg") #=> <SolrCloud::Collection 'cars_v2'>
+cars = server.get_alias("cars") #=> <SolrCloud::Alias 'cars' (alias of 'cars_v1')>
+
+cars.collection #=> <SolrCloud::Collection 'cars_v1' (aliased by 'cars')>
+cars.switch_collection_to("cars_v2") #=> <SolrCloud::Alias 'cars' (alias of 'cars_v2')>
 cars.collection #=> <SolrCloud::Collection 'cars_v2' (aliased by 'cars')>
+cars_v1.aliases #=> []
+cars_v2.aliases #=> [<SolrCloud::Alias 'cars' (alias of 'cars_v2')>]
+
+# Aliases will swap from collection to collection without warning
+cars_v1.alias_as("cars") #=> <SolrCloud::Alias 'cars' (alias of 'cars_v1')>
+
+# ...unless you use the bang(!) version
+cars_v2.alias_as!("cars") #=> raised #<SolrCloud::AliasAlreadyDefinedError: Alias cars already points to cars_v1>
+
+# You can also just switch it from the alias itself.
+cars.switch_collection_to("cars_v1") #=> <SolrCloud::Alias 'cars' (alias of 'cars_v1')>
+
+# Aliases show up as "collections" so you can just use them interchangeably
+server.collection_names #=> ["cars_v1", "cars_v2", "cars"]
+
+# They even == to each other
+cars #=> <SolrCloud::Alias 'cars' (alias of 'cars_v1')>
+cars == cars_v1 #=> true
+cars == cars_v2 #=> false
+
+# But sometimes you want to differentiate them from each other
+server.only_collection_names #=> ["cars_v1", "cars_v2"]
+cars.alias? #=> true
+cars_v1.alias? #=> false
+
+cars.collection #=> <SolrCloud::Collection 'cars_v1' (aliased by 'cars')>
+
+```
+
+### Accessing objects from other objects
+
+```ruby
+# You can grab existing collections/aliases/configsets from the server
+# as well as when they're returned by a create_* statement
+cv1 = server.get_collection("cars_v1") #=> <SolrCloud::Collection 'cars_v1' (aliased by 'cars')>
+cars = server.get_collection("cars") #=> <SolrCloud::Alias 'cars' (alias of 'cars_v1')>
+
+# get_* methods might return nil
+typo = "cars_V1" #=> "cars_V1"
+server.has_collection?(typo) #=> false
+dne = server.get_collection(typo) #=> nil
+
+# get_*! methods will throw an error
+dne = server.get_collection!(typo) #=> raised #<SolrCloud::NoSuchCollectionError: Collection 'cars_V1' not found>
+
+# alias#collection returns the underlying collection.
+# collection#collection returns itself. This makes it easier to
+# write code without differentiating between them.
 
-# Make a new alias to v2
-old_cars = cars_v2.alias_as("old_cars") #=> <SolrCloud::Alias "old_cars" (alias of "cars_v2")>
-cars_v2.aliases #=> [<SolrCloud::Alias "cars" (alias of "cars_v2")>, <SolrCloud::Alias "old_cars" (alias of "cars_v2")>]
+cars.collection #=> <SolrCloud::Collection 'cars_v1' (aliased by 'cars')>
+cars_v1.collection #=> <SolrCloud::Collection 'cars_v1' (aliased by 'cars')>
 
-# Now lets point the "cars" alias at cars_v3
-cars.switch_collection_to cars_v3
+# Configsets, Aliases, and Collections know how they're related
 
-cars.collection.name #=> "cars_v3"
-cars_v2.alias_names #=> ["old_cars"]
+cars_v1.aliases #=> [<SolrCloud::Alias 'cars' (alias of 'cars_v1')>]
+cars = cars_v1.get_alias("cars") #=> <SolrCloud::Alias 'cars' (alias of 'cars_v1')>
+cfg = cars.configset #=> <SolrCloud::Configset 'cars_cfg' at http://localhost:9090>
+cfg.collections #=> [<SolrCloud::Collection 'cars_v1' (aliased by 'cars')>, <SolrCloud::Collection 'cars_v2'>]
 
-# cars_v1 isn't doing anything for us anymore. Ditch it.
-cars_v1.delete!
 
 ```
 
@@ -126,4 +257,5 @@ This repository is set up to run tests under docker.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/mlibrary/solr_cloud-connection.
+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/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

@@ -7,7 +7,6 @@ module SolrCloud
   # A Collection provides basic services on the collection -- checking its health,
   # creating or reporting aliases, and deleting itself.
   class Collection
-
     extend Forwardable
 
     # Forward the HTTP verbs to the  underlying connection
@@ -50,13 +49,26 @@ module SolrCloud
       @sp = "/solr/#{name}"
     end
 
+    def collection
+      self
+    end
+
+    def ==(other)
+      case other
+      when SolrCloud::Collection
+        collection.name == other.collection.name
+      else
+        false
+      end
+    end
+
     # Delete this collection. Will no-op if the collection somehow doesn't still exist (because it was
     # deleted via a different method, such as through the API)
     # @return [Connection] The connection object used to create this collection object
     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
 
@@ -74,6 +86,8 @@ module SolrCloud
       false
     end
 
+    alias_method :ping, :alive?
+
     # Is this an alias?
     # Putting this in here breaks all sorts of isolation principles,
     # but being able to call #get_alias? on anything collection-like is
@@ -136,6 +150,13 @@ module SolrCloud
       connection.create_alias(name: alias_name, collection_name: name, force: true)
     end
 
+    def alias_as!(alias_name)
+      if connection.has_alias?(alias_name)
+        raise AliasAlreadyDefinedError.new("Alias #{alias_name} already points to #{connection.get_alias(alias_name).collection.name}")
+      end
+      alias_as(alias_name, force: false)
+    end
+
     # Send a commit (soft if unspecified)
     # @return self
     def commit(hard: false)
@@ -160,10 +181,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
@@ -179,10 +200,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
 
@@ -33,6 +32,8 @@ module SolrCloud
       connection.only_collections.select { |coll| coll.configset.name == name }
     end
 
+    alias_method :collections, :used_by
+
     # Are there any collections currently using this configset?
     # @return [Boolean]
     def in_use?

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)
@@ -83,5 +82,3 @@ module SolrCloud
     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

@@ -7,7 +7,6 @@ module SolrCloud
     # 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.
       # @param name [String] Name to give the new configset

data/lib/solr_cloud/connection/version.rb

@@ -2,6 +2,6 @@
 
 module SolrCloud
   class Connection
-    VERSION = "0.4.0"
+    VERSION = "0.6.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
@@ -192,6 +196,3 @@ module SolrCloud
     end
   end
 end
-
-
-

data/lib/solr_cloud/errors.rb

@@ -10,6 +10,8 @@ module SolrCloud
 
   class WontOverwriteError < RuntimeError; end
 
+  class AliasAlreadyDefinedError < RuntimeError; end
+
   class ConfigSetInUseError < RuntimeError; end
 
   class CollectionAliasedError < RuntimeError; end

data/readme.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "pathname"
+$LOAD_PATH.unshift Pathname.new(__dir__) + "lib"
+require_relative "lib/solr_cloud/connection"
+config_directory = "/Users/dueberb/devel/mlibrary/solr_cloud-connection/spec/data/simple_configuration/conf"
+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! }
+
+# or bring your own Faraday object
+# server2 = SolrCloud::Connection.new_with_faraday(faraday_connection)
+
+### Get some basic info
+
+server.version_string
+server.cloud?
+server.mode
+
+### Configsets
+
+# List the configsets
+server.configsets
+
+# Sometimes you just want the names.
+server.configset_names
+
+# 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)
+server.configset_names
+
+# That's a dumb name for a config set. Delete it and try again.
+cset.delete!
+cset = server.create_configset(name: "cars_cfg", confdir: config_directory)
+server.configsets
+
+# Can't be overwritten by accident
+begin
+  server.create_configset(name: "cars_cfg", confdir: config_directory)
+rescue => e
+end
+
+# But you can force it
+server.create_configset(name: "cars_cfg", confdir: config_directory, force: true)
+
+cfg = server.get_configset("cars_cfg")
+cfg.in_use?
+
+#### Collections
+
+# Now create a collection based on an already-existing configset
+cars_v1 = server.create_collection(name: "cars_v1", configset: "cars_cfg")
+server.collections
+server.collection_names
+
+# Check it out quick
+cars_v1.alive?
+cars_v1.healthy?
+cars_v1.count
+
+# Any aliases
+cars_v1.aliased?
+cars_v1.aliases
+
+# Its configset
+cars_v1.configset
+
+# Commit anything that's been added
+cars_v1.commit
+
+# Solr knows its configset is in use, and won't delete it
+
+begin
+  cfg.delete!
+rescue
+end
+
+##### Aliases
+
+# We'll want to alias it so we can just use 'cars'
+cars = cars_v1.alias_as("cars")
+cars_v1.alias?
+cars_v1.aliased?
+
+cars_v1.has_alias?("cars")
+cars_v1.alias_as("autos")
+cars_v1.aliases
+
+cars_v1.get_alias("autos").delete!
+cars_v1.aliases
+
+# There's syntactic sugar for switching out aliases
+cars_v2 = server.create_collection(name: "cars_v2", configset: "cars_cfg")
+cars = server.get_alias("cars")
+
+cars.collection
+cars.switch_collection_to("cars_v2")
+cars.collection
+cars_v1.aliases
+cars_v2.aliases
+
+# Aliases will swap from collection to collection without warning
+cars_v1.alias_as("cars")
+
+# ...unless you use the bang(!) version
+begin
+  cars_v2.alias_as!("cars")
+rescue
+end
+
+# You can also just switch it from the alias itself.
+cars.switch_collection_to("cars_v1")
+
+# Aliases show up as "collections" so you can just use them interchangeably
+server.collection_names
+
+# They even == to each other
+
+# But sometimes you want to differentiate them from each other
+server.only_collection_names
+cars.alias?
+cars_v1.alias?
+
+cars.collection
+
+### Ways to get access to aliases/collections/configsets
+
+# You can grab existing collections/aliases/configsets from the server
+# as well as when they're returned by a create_* statement
+cv1 = server.get_collection("cars_v1")
+cars = server.get_collection("cars")
+
+# get_*! methods raise an error
+typo = "cars_V1"
+server.has_collection?(typo)
+dne = server.get_collection(typo)
+
+begin
+  dne = server.get_collection!(typo)
+rescue
+end
+
+# alias#collection returns the underlying collection.
+# collection#collection returns itself. This makes it easier to
+# write code without differentiating between them.
+
+cars.collection
+cars_v1.collection
+
+# Configsets, Aliases, and Collections know how they're related
+
+cars_v1.aliases
+cars = cars_v1.get_alias("cars")
+cfg = cars.configset
+cfg.collections

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solr_cloud-connection
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Bill Dueber
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-07 00:00:00.000000000 Z
+date: 2024-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -16,112 +16,144 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.7.12
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.7.12
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: httpx
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.5
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.1.5
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.3.0
+        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'
+        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'
 description:
 email:
 - bill@dueber.com
@@ -148,6 +180,7 @@ files:
 - lib/solr_cloud/connection/configset_admin.rb
 - lib/solr_cloud/connection/version.rb
 - lib/solr_cloud/errors.rb
+- readme.rb
 homepage: https://github.com/mlibrary/solr_cloud-connection
 licenses: []
 metadata:
@@ -169,7 +202,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.17
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Do basic administrative operations on a solr cloud instance and collections