solr_cloud-connection 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1989962c4834b362be714c08199791950034638d4e2ea26bfa1368e377390f3b
-  data.tar.gz: ed3621358d19671db37394b04b0df83e700b2dbd7b45dc7cd3e545c782ed64c6
+  metadata.gz: e273d22bc3c74c27f96e2e4441695c47c8561634d339b8dabdc0d9c0075922e6
+  data.tar.gz: e208564f23b12ad6554a075caf48f65d57e7dfbe15b800e85eb639f4d2dc6791
 SHA512:
-  metadata.gz: 6161fb600d516c459a843f9f8054cf2b3db2cb0eadf04678af037b7bc55e86b828b08e167f01391dbb9b7b2d4c5a5759851fc322a71a8d545651734e44df978c
-  data.tar.gz: 7082a625e5ffa7f04e17638db3782b0ac3715a3955413539543e39297cb589825cde87abd06dc2aff1cde7c59581da25a4d6fb372c7f3b177d780e035a5d1bdd
+  metadata.gz: 7a1ba3738d5908c753c49b6f813b14465ddb4213d925aa7c075d6665c01229d0aecd59b8479bf5ae54f1d94511579876e7d3c392847f1c0845eb130a0f9c0897
+  data.tar.gz: 14f6c01885f6d97b477311099e4399b9e74c400fce40c42cdccb3e56a798df3f0ce8b0475aa57299ad3054681c4de059bf80908102a9b98b3b67cd14ecbfb50b

data/{.env.local → .env.github}

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

data/CHANGELOG.md

@@ -1,4 +1,19 @@
-## [Unreleased]
+# Changelog
+
+## [0.3.0] - 2023-12-06
+
+- Major overhaul of the interface to use more-explicit and less-confusing method names
+- Remove code that tried to "version" collections and configsets, since it was dumb
+- Get github actions working to run tests
+- Make aliases even more of a paper-thin wrapper around collections, such that, e.g.
+  `coll = get_collection(alias_name)` will return the appropriate alias. Use
+  `coll.alias?` to determine if it's an alias or collection if that becomes important.
+
+## [0.2.0] - 2023-12-01
+
+- Added options `:date` and `:datetime` to the `version:` argument to `create_collection`
+  to automatically generate, e.g., "2023-12-01" or "2023-12-01-09-50-56" 
+- Added utility method `legal_solr_name?` to check for validity for collection names
 
 ## [0.1.0] - 2023-11-29
 

data/README.md

@@ -2,150 +2,108 @@
 
 Do basic administrative tasks on a running Solr cloud instance, including:
 
+* 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, just as you'd expect
+* treat an alias (mostly) as a collection
 * TODO automatically generate methods to talk to defined requestHandlers
-* TODO collect and deal with search results in a sane way
+* TODO Add something useful for configsets to do
+
+In almost all cases, you can treat an alias to a collection like the underlying collection. 
+
+## A note about deleting things
+
+Collections, aliases, and configsets all have a `#delete!` method. Keep in mind that solr 
+enforces a rule that nothing in-use can be deleted. This gem will throw appropriate errors
+if you try to delete a configset that's being used by a collection, or try to delete
+a collections that's pointed to by an alias.
 
 ## Caveats
 
-* At this point the API is unstable, and it doesn't do any actual, you know, searching.
-* Due to there not being any sense of an atomic action when administering solr, this gem does
-  _no caching_. This means the individual actions can involve several round-trips to solr. On the flip
-  side, if you're doing so much admin that it's a bottleneck, you're well outside this gem's target case.
+* 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
+  (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.
 * While solr aliases can point to more than one collection at a time, this gem enforces one collection
   per alias (although many aliases can point to the same collection)
 
 ## Usage
 
-### Create a connection to a running solr
-
-The connection object is the basis of all the other stuff. Everything will be created, directly
-or indirectly, through the connection. While using the collection/alias/configset objects
-is preferred, the connection on its own can do most anything. See SolrCloud::Connection for
-the docs. 
-
-A simple connection is made if you pass in basic info, or you can create a faraday connection
-and pass it in yourself.
+The code below covers all the basics. See the docs for full sets of parameters, which errors are
+thrown, etc. 
 
 ```ruby
 
 require "solr_cloud/connection"
 
-solr = SolrCloud::connect.new(url: "http://localhost:9999", username: "user", password: "password")
-#    #=> <SolrCloud::Connection http://localhost:9999/>
+server = SolrCloud::connect.new(url: "http://localhost:8023", username: "user", password: "password")
+#    #=> <SolrCloud::Connection http://localhost:8023/>
 
 # or bring your own Faraday object
-solr = SolrCloud::connect.new_with_faraday(faraday_connection)
-
-```
-
-### Configsets
-
-Configuration sets can be created by giving a path to the `conf` directory (with
-`solrconfig.xml` and the schema and such) and a name.
-
-```ruby
-connect.configset_names #=> []
-cset = connect.create_configset(name: "myconfig", confdir: "/path/to/yourconfig/conf")
-
-# Get a list of existing configsets
-arr_of_configsets_objects = @connect.configsets
-arr_of_names_as_strings = @connect.configset_names
-
-# Test and see if it exists by name
-connect.configset?("myconfig") #=> true
-
-# If it already exists, you can just grab it by name
-
-def_config = connect.configset("_default")
+# server = SolrCloud::connect.new_with_faraday(faraday_connection)
 
-# It makes sure you don't overwrite when creating a new set
-connect.create_configset(name: "myconfig", confdir: "/path/to/yourconfig/conf")
-      #=> WontOverwriteError
+server.configset_names #=> ["_default"]
+default = server.get_configset("_default") #=> <SolrCloud::Configset '_default' at http://localhost:8983>
 
-# ...but you can force it
-connect.create_configset(name: "myconfig", confdir: "/path/to/yourconfig/conf", force: true)
+# 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"]
 
-# And get rid of it
-myconfig.delete!
-connect.configset?("myconfig") #=> false
+# That's a dumb name. We'll try again.
+cset.delete!
+cset = server.create_configset(name: "cars_config", confdir: "/path/to/mycore/conf")
 
-```
-
-### Collections
-
-Collections can be listed, tested for health and aliases, used to create an alias, and deleted. 
-
-```ruby
-
-connect.collection_names #=> []
-connect.create_collection(name: "mycoll", configset: "does_not_exist") #=> SolrCloud::NoSuchConfigSetError: Configset does_not_exist doesn't exist
-mycoll = connect.create_collection(name: "mycoll", configset: "_default")
-mycoll.name #=> "mycoll"
+# 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"]
 
-# Test and see if it exists
-connect.collection?("mycoll") #=> true
+typo = server.get_collection("cars__V2") #=> nil, doesn't exist
+cars_v2 = server.get_collection("cars_v2")
 
-# Get all of them
+cars_v2.alive? #=> true
+cars_v2.count #=> 133 -- we're assuming there's stuff in it.
 
-arr_of_collection_objects = connect.collections
-arr_of_names_as_strings = connect.collection_names
 
-# or get a single one by name
-coll = connect.collection("some_other_collection")
+# 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
 
-mycoll.alive? # => true
-mycoll.healthy? #=> true. I'm not sure how these are different
+cars_v2.delete! #=> SolrCloud::CollectionAliasedError: Collection 'cars_v2' can't be deleted; it's in use by aliases ["cars"]
 
-mycoll.alias? # false. It's a collection. 
+# 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>
 
-# Which configset is it based on?
-mycoll.configset #=> <SolrCloud::Configset '_default' at http://localhost:9999/>
+# Work directly with an alias as if it's a collection
+cars = server.get_collection("cars")
+cars.alias? #=> true
+cars.collection #=> <SolrCloud::Collection 'cars_v2' (aliased by 'cars')>
 
-# Sniff out and create aliases
-mycoll.aliases #=> [] None as of yet
-myalias = mycoll.alias_as("myalias")
+# 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")>]
 
-mycoll.aliases #=> [<SolrCloud::Alias 'myalias' (alias of 'mycoll')>]
-mycoll.alias_names #=> ["myalias"]
+# Now lets point the "cars" alias at cars_v3
+cars.switch_collection_to cars_v3
 
-# Collection, Alias, and Configset can all access the underlying connection object
-# and call `get`, `post`, `put`, and `delete`
-mycoll.collection #=> 
-mycoll.collection.get("path/from/connection/url", arg1: "One", arg2: "Two")
+cars.collection.name #=> "cars_v3"
+cars_v2.alias_names #=> ["old_cars"]
 
-# Try to delete the collection
-mycoll.delete! #=> SolrCloud::CollectionAliasedError: Collection 'mycoll' can't be deleted; it's in use by aliases ["myalias"]
-myalias.delete!
-
-mycoll.delete!
+# cars_v1 isn't doing anything for us anymore. Ditch it.
+cars_v1.delete!
 
 ```
 
-### Aliases
-
-In all the important ways, aliases can be treated like collections. Here are the exceptions.
+## Documentation
 
-```ruby
-
-# You can create an alias from the collection you're aliasing
-myalias = mycoll.alias_as("myalias")
-
-# Ask the connection object if it exists, and get it
-connect.alias?("myalias") #=> true
-myalias = connect.alias("myalias")
-
-# As this object if it's an alias, as opposed to a collection
-myalias.alias? #=> true
-
-# Set the collection this alias points to, removing its link from its existing collection
-myalias.collection = my_other_collection #=> sets myalias to point at my_other_collection
-
-myalias.delete!
-```
+Run `bundle exec rake docs` to generate the documentation in `docs/`
 
 ## Installation
 
@@ -168,4 +126,4 @@ 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-connect.
+Bug reports and pull requests are welcome on GitHub at https://github.com/mlibrary/solr_cloud-connection.

data/Rakefile

@@ -7,4 +7,19 @@ RSpec::Core::RakeTask.new(:spec)
 
 require "standard/rake"
 
-task default: %i[spec standard]
+task default: %i[spec standard docs]
+task docs: %i[yard]
+
+require 'yard'
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ["lib/**/*.rb"] # optional
+  t.options = [
+    "-mmarkdown",
+    "--embed-mixin", "SolrCloud::Connection::CollectionAdmin",
+    "--embed-mixin", "SolrCloud::Connection::ConfigsetAdmin",
+    "--embed-mixin", "SolrCloud::Connection::AliasAdmin",
+    "--hide-void-return"
+  ]
+  # t.stats_options = ["--list-undoc"] # optional
+end

data/compose.yml

@@ -9,13 +9,13 @@ services:
       - gem_cache:/gems
     env_file:
       - .env
-      - env.development
+      - env.test
     command: "tail -f /dev/null"
 
   solr:
     build: spec/data/solr_docker/.
     ports:
-      - "9999:8983"
+      - "8983:8983"
     environment:
       - ZK_HOST=zoo:2181
     depends_on:

data/{env.development → env.test}

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

data/lib/solr_cloud/alias.rb

@@ -2,51 +2,58 @@
 
 module SolrCloud
   # An alias can mostly be just treated as a collection. It will identify itself as an alias if you
-  # call #alias, and it can return and change the underlying collection it points to.
+  # call #alias?, and it can return and change the underlying collection it points to.
 
   # An alias shouldn't be created directly. Rather, get an existing one with
   # Connection#alias, or from a collection, or create one with
   # Collection#alias_as
   class Alias < Collection
     # An alias is, shockingly, an alias. Convenience to differentiate aliases from collections.
-    # @see SolrCloud::Connection#alias?
+    # @see SolrCloud::Connection#get_alias?
     def alias?
       true
     end
 
-    # Delete this alias
-    # @return [SolrCloud::Connection]
+    # Delete this alias. Will be a no-op if it doesn't exist.
+    # @return [Connection] the connection
     def delete!
-      coll = collection
-      connection.delete_alias(name)
-      coll
+      return connection unless exist?
+      connection.get("solr/admin/collections", action: "DELETEALIAS", name: name)
+      connection
+    end
+
+    # Does this alias still exist?
+    def exist?
+      connection.alias_names.include?(name)
     end
 
     # Get the collection this alias points to.
     # In real life, Solr will allow an alias to point to more than one collection. Functionality
     # for this might be added at some point
-    # @return [SolrCloud::Collection]
+    # @return [Collection]
     def collection
-      connection.collection_for_alias(name)
+      connection.alias_map[name].collection
     end
 
     # Redefine what collection this alias points to
     # This is equivalent to dropping/re-adding the alias, or calling connection.create_alias with `force: true`
     # @param coll [String, Collection] either the name of the collection, or a collection object itself
     # @return [Collection] the now-current collection
-    def collection=(coll)
+    def switch_collection_to(coll)
       collect_name = case coll
-      when String
-        coll
-      when Collection
-        coll.name
-      else
-        raise "Alias#collection= only takes a name(string) or a collection, not '#{coll}'"
-      end
-      raise NoSuchCollectionError unless connection.collection?(collect_name)
+                       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
 
+    alias_method :collection=, :switch_collection_to
+
     # Get basic information on the underlying collection, so inherited methods that
     # use it (e.g., #healthy?) will work.
     # @overload info()

data/lib/solr_cloud/collection.rb

@@ -1,12 +1,42 @@
 # frozen_string_literal: true
 
 require "solr_cloud/connection"
+require "forwardable"
 
 module SolrCloud
   # A Collection provides basic services on the collection -- checking its health,
   # creating or reporting aliases, and deleting itself.
   class Collection
-    attr_reader :name, :connection
+
+    extend Forwardable
+
+    # Forward the HTTP verbs to the  underlying connection
+
+    # @!method get
+    # Forwarded on to the underlying SolrCloud connection
+    # @see SolrCloud::Connection#get
+    def_delegator :@connection, :get
+
+    # @!method post
+    # Forwarded on to the underlying SolrCloud connection
+    # @see SolrCloud::Connection#post
+    def_delegator :@connection, :post
+
+    # @!method delete
+    # Forwarded on to the underlying SolrCloud connection
+    # @see SolrCloud::Connection#delete
+    def_delegator :@connection, :delete
+
+    # @!method put
+    # Forwarded on to the underlying SolrCloud connection
+    # @see SolrCloud::Connection#put
+    def_delegator :@connection, :put
+
+    # @return [SolrCloud::Connection] the underlying SolrCloud connection
+    attr_reader :name
+
+    # @return The name of the get_collection
+    attr_reader :connection
 
     # In general, users shouldn't use Collection.new; instead, use
     # connection.create_collection(name: "coll_name", configset: "existing_configset_name")
@@ -14,22 +44,28 @@ module SolrCloud
     # @param [String] name The name of the (already existing) collection
     # @param [SolrCloud::Connection] connection Connection to the solr "root" (http://blah:8888/)
     def initialize(name:, connection:)
-      # raise NoSuchCollectionError.new("No collection #{name}") unless connection.collection?(name)
+      # raise NoSuchCollectionError.new("No collection #{name}") unless connection.has_collection?(name)
       @connection = connection.dup
       @name = name
       @sp = "/solr/#{name}"
     end
 
-    # Delete this collection. Unlike the #delete_collection call on a Connection object,
-    # for this one we throw an error if the collection isn't found, since that means
-    # it was deleted via some other mechanism after this object was created and should probably be investigated.
-    # @return [Connection] The underlying SolrCloud::Connection
+    # 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!
-      raise NoSuchCollectionError unless exist?
-      connection.delete_collection(name)
+      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
     end
 
+    # Does this collection still exist?
+    # @return [Boolean]
+    def exist?
+      connection.only_collection_names.include?(name)
+    end
+
     # Check to see if the collection is alive
     # @return [Boolean]
     def alive?
@@ -38,11 +74,9 @@ module SolrCloud
       false
     end
 
-    alias_method :exist?, :alive?
-
     # Is this an alias?
     # Putting this in here breaks all sorts of isolation principles,
-    # but being able to call #alias? on anything collection-like is
+    # but being able to call #get_alias? on anything collection-like is
     # convenient
     def alias?
       false
@@ -63,7 +97,7 @@ module SolrCloud
     # A (possibly empty) list of aliases targeting this collection
     # @return [Array<SolrCloud::Alias>] list of aliases that point to this collection
     def aliases
-      connection.raw_alias_map.select { |a, c| c == name }.keys.map { |aname| Alias.new(name: aname, connection: connection) }
+      connection.alias_map.select { |_alias_name, ac| ac.collection.name == name }.values.map(&:alias)
     end
 
     # The names of the aliases that point to this collection
@@ -72,10 +106,26 @@ module SolrCloud
       aliases.map(&:name)
     end
 
+    # Does this collection have at least one alias?
+    # @return [Boolean] whether or not it has an alias
+    def aliased?
+      !aliases.empty?
+    end
+
+    # Do we have an alias of the given name?
     # Get a specific alias by name
-    # @param aname [String] name of the alias
-    def alias(aname)
-      aliases.find {|a| a.name == aname} || (raise NoSuchAliasError.new("No alias named '#{aname}' pointing to collection #{name}"))
+    # @param alias_name [String] name of the alias
+    # @return [Boolean]
+    def has_alias?(alias_name)
+      alias_names.include?(alias_name)
+    end
+
+    # Get an alias that points to this collection by name, or nil if not found
+    # @param alias_name [String] name of the alias
+    # @return [Alias, nil] The alias object, or nil if not found
+    def get_alias(alias_name)
+      return nil unless has_alias?(alias_name)
+      connection.get_alias(alias_name)
     end
 
     # Create an alias for this collection. Always forces an overwrite unless you tell it not to
@@ -86,9 +136,6 @@ module SolrCloud
       connection.create_alias(name: alias_name, collection_name: name, force: true)
     end
 
-    alias_method :alias_to, :alias_as
-    alias_method :create_alias, :alias_as
-
     # Send a commit (soft if unspecified)
     # @return self
     def commit(hard: false)
@@ -106,13 +153,36 @@ module SolrCloud
       Configset.new(name: info["configName"], connection: connection)
     end
 
+    # Add a document or array of documents
+    # @todo Gotta check for errors and such!
+    # @param docs [Hash, Array<Hash>] One or more documents to add
+    # @return self
+
+    def add(docs)
+      docarray = if docs === Array
+                   docs
+                 else
+                   [docs]
+                 end
+      post("solr/#{name}/update/") do |r|
+        r.body = docarray
+      end
+      self
+    end
+
+    # Get a count of how many documents are in the index
+    # @return [Fixnum] the number of documents
+    def count
+      get("solr/#{name}/select", q: "*:*").body["response"]["numFound"]
+    end
+
     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,12 @@ module SolrCloud
   # throw an error if that's an illegal operation (because a collection is
   # using it)
   class Configset
-    attr_reader :name, :connection
+
+    # @return [String] the name of this configset
+    attr_reader :name
+
+    # @return [Connection] the connection object used to build this configset object
+    attr_reader :connection
 
     def initialize(name:, connection:)
       @name = name
@@ -15,11 +20,23 @@ module SolrCloud
     end
 
     # Delete this configset.
-    # @see SolrCloud::Connection#delete_configset
+    # @see Connection#delete_configset
     # @return The underlying connection
     def delete!
-      @connection.delete_configset(name)
-      @connection
+      connection.delete_configset(name)
+      connection
+    end
+
+    # Which collections use this configset?
+    # @return [Array<Collection>] The collections defined to use this configset
+    def used_by
+      connection.only_collections.select { |coll| coll.configset.name == name }
+    end
+
+    # Are there any collections currently using this configset?
+    # @return [Boolean]
+    def in_use?
+      !used_by.empty?
     end
 
     def inspect

data/lib/solr_cloud/connection/alias_admin.rb

@@ -5,56 +5,41 @@ 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)
 
-      # Create an alias for the given collection name
-      # @todo allow an alias to point to more than one collection?
+      # Create an alias for the given collection name.
+      #
+      # In general, prefer {Collection#alias_as} instead of
+      # running everything through the connection object.
       # @param name [String] Name of the new alias
       # @param collection_name [String] name of the collection
       # @param force [Boolean] whether to overwrite an existing alias
-      # @raise [WontOverwriteError] if the alias exists and force isn't true
       # @raise [NoSuchCollectionError] if the collections isn't found
       # @return [Alias] the newly-created alias
       def create_alias(name:, collection_name:, force: false)
-        raise NoSuchCollectionError.new("Can't find collection #{collection_name}") unless collection?(collection_name)
-        if alias?(name) && !force
-          raise WontOverwriteError.new("Alias '#{name}' already points to collection '#{self.alias(name).collection.name}'; won't overwrite without force: true")
+        unless legal_solr_name?(name)
+          raise IllegalNameError.new("'#{name}' is not a valid solr alias name. Use only ASCII letters/numbers, dash, and underscore")
+        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")
         end
         connection.get("solr/admin/collections", action: "CREATEALIAS", name: name, collections: collection_name)
-        SolrCloud::Alias.new(name: name, connection: self)
+        get_alias(name)
       end
 
       # Is there an alias with this name?
       # @return [Boolean]
-      def alias?(name)
+      def has_alias?(name)
         alias_names.include? name
       end
 
-      # Delete the alias
-      # @param name [String] Name of the alias to delete
-      # @return [SolrCloud::Connection]
-      def delete_alias(name)
-        connection.get("solr/admin/collections", action: "DELETEALIAS", name: name)
-      end
-
-      # The "raw" alias map, which just maps alias names to collection names
-      # @return [Hash<String, String>]
-      def raw_alias_map
-        connection.get("solr/admin/collections", action: "LISTALIASES").body["aliases"]
-      end
-
-      # Get the aliases and create a map of the form
-      # @return [Hash<String,Alias>] A hash mapping alias names to alias objects
-      def alias_map
-        raw_alias_map.keys.each_with_object({}) do |alias_name, h|
-          h[alias_name] = SolrCloud::Alias.new(name: alias_name, connection: self)
-        end
-      end
-
       # List of alias objects
       # @return [Array<SolrCloud::Alias>] List of aliases
       def aliases
-        alias_map.values
+        alias_map.values.map(&:alias)
       end
 
       # List of alias names
@@ -63,23 +48,40 @@ module SolrCloud
         alias_map.keys
       end
 
-      # Get an alias object for the given name
+      # Get an alias object for the given name, erroring out if not found
+      # @param name [String] the name of the existing alias
+      # @return [Alias, nil] The alias if found, otherwise nil
+      def get_alias(name)
+        return nil unless has_alias?(name)
+        alias_map[name].alias
+      end
+
+      # Get an alias object for the given name, erroring out if not found
       # @param name [String] the name of the existing alias
       # @raise [SolrCloud::NoSuchAliasError] if it doesn't exist
       # @return [SolrCloud::Alias]
-      def alias(name)
-        am = alias_map
-        raise NoSuchAliasError unless am[name]
-        am[name]
+      def get_alias!(name)
+        raise NoSuchAliasError unless has_alias?(name)
+        get_alias(name)
       end
 
-      # Get the collection associated with an alias
-      # @param name [String] alias name
-      # @return [Collection] collection associated with the alias
-      def collection_for_alias(name)
-        collname = connection.get("solr/admin/collections", action: "LISTALIASES").body["aliases"][name]
-        Collection.new(name: collname, connection: self)
+      # Get the aliases and create a map of the form AliasName -> AliasObject
+      # @return [Hash<String,Alias>] A hash mapping alias names to alias objects
+      def alias_map
+        raw_alias_map.keys.each_with_object({}) do |alias_name, h|
+          a = Alias.new(name: alias_name, connection: self)
+          c = Collection.new(name: raw_alias_map[alias_name], connection: self)
+          h[alias_name] = AliasCollectionPair.new(a, c)
+        end
+      end
+
+      # The "raw" alias map, which just maps alias names to collection names
+      # @return [Hash<String, String>]
+      def raw_alias_map
+        connection.get("solr/admin/collections", action: "LISTALIASES").body["aliases"]
       end
     end
   end
 end
+
+

data/lib/solr_cloud/connection/collection_admin.rb

@@ -2,79 +2,98 @@
 
 module SolrCloud
   class Connection
-    # methods having to do with connections, to be included by the connection object.
+    # methods having to do with collections, to be included by the connection object.
     # These are split out only to make it easier to deal with them.
+    #
+    # For almost everything in here, we treat aliases like collections -- calls to #collections,
+    # #has_collection?, #collection, etc. will respond to, and return, and alias if there is one.
+    # The idea is that you shouldn't need to know if something is an alias or a collection
+    # until it's relevant
     module CollectionAdmin
-      # Create a new collection
+      # Create and return a new collection.
       # @param name [String] Name for the new collection
-      # @param configset [String] name of the configset to use for this collection
-      # @param version [String] A "version" which will be appended to the name following an underscore, if given.
-      #   Useful for testing and cronjobs.
+      # @param configset [String, Configset] (name of) the configset to use for this collection
       # @param shards [Integer]
       # @param replication_factor [Integer]
-      # @todo Let version take symbols like :date and :datetime
+      # @raise [IllegalNameError]
       # @raise [NoSuchConfigSetError] if the named configset doesn't exist
       # @raise [WontOverwriteError] if the collection already exists
       # @return [Collection] the collection created
-      def create_collection(name:, configset:, version: nil, shards: 1, replication_factor: 1)
-        fullname = if version
-          "#{name}_#{version}"
-        else
-          name
+      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
 
-        raise WontOverwriteError.new("Collection #{fullname} already exists") if collection?(fullname)
-        raise NoSuchConfigSetError.new("Configset '#{configset}' doesn't exist") unless configset?(configset)
+        configset_name = case configset
+                           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)
 
         args = {
           :action => "CREATE",
-          :name => fullname,
+          :name => name,
           :numShards => shards,
           :replicationFactor => replication_factor,
-          "collection.configName" => configset
+          "collection.configName" => configset_name
         }
         connection.get("solr/admin/collections", args)
-        collection(name)
+        get_collection(name)
+      end
+
+      # Get a list of _only_ collections, as opposed to the mix of collections and aliases we
+      # usually do.
+      def only_collections
+        connection.get("api/collections").body["collections"].map { |c| Collection.new(name: c, connection: self) }
       end
 
-      # Get a list of existing collections
-      # @return [Array<SolrCloud::Collection>] possibly empty list of collection objects
+      # The names of only connections (and not aliases). Useful as a utility.
+      # @return [Array<String>] the names of the connections
+      def only_collection_names
+        only_collections.map(&:name)
+      end
+
+      # Get a list of collections (and aliases)
+      # @return [Array<Collection, Alias>] possibly empty list of collection and alias objects
       def collections
-        collection_names.map { |coll| collection(coll) }
+        only_collections.union(aliases)
       end
 
-      # A list of the names of existing collections
-      # @return [Array<String>] the collection names, or empty array if there are none
+      # A list of the names of existing collections and aliases
+      # @return [Array<String>] the collection/alias names, or empty array if there are none
       def collection_names
-        connection.get("api/collections").body["collections"]
+        collections.map(&:name)
       end
 
       # @param name [String] name of the collection to check on
       # @return [Boolean] Whether a collection with the passed name exists
-      def collection?(name)
+      def has_collection?(name)
         collection_names.include? name
       end
 
-      # Remove the configuration set with the given name. No-op if the
-      # collection doesn't actually exist. Use #connection? manually if you need to raise on does-not-exist
-      # @param [String,Symbol] name The name of the configuration set
-      # @return [Connection] self
-      def delete_collection(name)
-        if collection? name
-          connection.get("solr/admin/collections", {action: "DELETE", name: name})
+      # Get a collection object specifically for the named collection
+      # @param collection_name [String] name of the (already existing) collection
+      # @return [Collection, Alias, nil] The collection or alias if found, nil if not
+      def get_collection(collection_name)
+        return nil unless has_collection?(collection_name)
+        if only_collection_names.include?(collection_name)
+          Collection.new(name: collection_name, connection: self)
+        else
+          get_alias(collection_name)
         end
-        self
-      rescue Faraday::BadRequestError
-        raise SolrCloud::CollectionAliasedError.new("Collection '#{name}' can't be deleted; it's in use by aliases #{collection(name).alias_names}")
       end
 
-      # Get a connection object specifically for the named collection
+      # Get a connection/alias object, throwing an error if it's not found
       # @param collection_name [String] name of the (already existing) collection
-      # @return [SolrCloud::Connection::Collection] The collection connection
-      # @raise [NoSuchCollectionError] if the collection doesn't exist
-      def collection(collection_name)
-        raise NoSuchCollectionError.new("Collection '#{collection_name}' not found") unless collection?(collection_name)
-        Collection.new(name: collection_name, connection: self)
+      # @return [Collection, Alias] The collection or alias
+      # @raise [NoSuchCollectionError] if the collection/alias doesn't exist
+      def get_collection!(collection_name)
+        raise NoSuchCollectionError.new("Collection '#{collection_name}' not found") unless has_collection?(collection_name)
+        get_collection(collection_name)
       end
     end
   end

data/lib/solr_cloud/connection/configset_admin.rb

@@ -7,6 +7,34 @@ 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
+      # @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
+      # @return [Configset] the configset created
+      def create_configset(name:, confdir:, force: false)
+        config_set_name = name
+        unless legal_solr_name?(config_set_name)
+          raise IllegalNameError.new("'#{config_set_name}' is not a valid solr configset name. Use only ASCII letters/numbers, dash, and underscore")
+        end
+
+        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)
+        end
+        # TODO: Error check in here somewhere
+        FileUtils.rm(zfile, force: true)
+        get_configset(name)
+      end
+
       # Get a list of the already-defined configSets
       # @return [Array<Configset>] possibly empty list of configSets
       def configsets
@@ -18,47 +46,29 @@ module SolrCloud
         connection.get("api/cluster/configs").body["configSets"]
       end
 
-      alias_method :configurations, :configsets
-
       # Check to see if a configset is defined
       # @param name [String] Name of the configSet
       # @return [Boolean] Whether a configset with that name exists
-      def configset?(name)
+      def has_configset?(name)
         configset_names.include? name.to_s
       end
 
-      # 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
-      # @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
-      # @param version [String] A "version" which will be appended to the name if given. Useful for
-      # testing and cronjobs.
-      # @raise [WontOverwriteError] if the configset already exists and "force" is false
-      # @return [String] the name of the configset created
-      def create_configset(name:, confdir:, force: false, version: "")
-        config_set_name = name + version.to_s
-        if 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
-        @raw_connection.put("api/cluster/configs/#{config_set_name}") do |req|
-          req.body = File.binread(zfile)
-        end
-        # TODO: Error check in here somewhere
-        FileUtils.rm(zfile, force: true)
-        config_set_name
+      # Get an existing configset
+      def get_configset(name)
+        Configset.new(name: name, connection: self)
       end
 
       # Remove the configuration set with the given name. No-op if the
-      # configset doesn't actually exist. Use #configset? manually if you need to raise on does-not-exist
-      # @param [String,Symbol] name The name of the configuration set
+      # configset doesn't actually exist. Test with {#has_configset?} and
+      # {Configset#in_use?} manually if need be.
+      #
+      # 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
       # @return [Connection] self
       def delete_configset(name)
-        if configset? name
+        if has_configset? name
           connection.delete("api/cluster/configs/#{name}")
         end
         self
@@ -73,6 +83,8 @@ module SolrCloud
 
       # Pulled from the examples for rubyzip. No idea why it's not just a part
       # of the normal interface, but I guess I'm not one to judge.
+      #
+      # Code taken wholesale from https://github.com/rubyzip/rubyzip/blob/master/samples/example_recursive.rb
       class ZipFileGenerator
         # Initialize with the directory to zip and the location of the output archive.
         def initialize(input_dir, output_file)

data/lib/solr_cloud/connection/version.rb

@@ -2,6 +2,6 @@
 
 module SolrCloud
   class Connection
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/solr_cloud/connection.rb

@@ -28,9 +28,36 @@ module SolrCloud
     include CollectionAdmin
     include AliasAdmin
 
-    attr_reader :url, :logger, :raw_connection
+    # @return [String] String representation of the URL to solr
+    attr_reader :url
 
-    def_delegators :@raw_connection, :get, :post, :delete, :put
+    # @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
+    # Forwarded on to the underlying Faraday connection
+    # @see Faraday::Connection.get
+    def_delegator :@connection, :get
+
+    # @!method post
+    # Forwarded on to the underlying Faraday connection
+    # @see Faraday::Connection.post
+    def_delegator :@connection, :post
+
+    # @!method delete
+    # Forwarded on to the underlying Faraday connection
+    # @see Faraday::Connection.delete
+    def_delegator :@connection, :delete
+
+    # @!method put
+    # Forwarded on to the underlying Faraday connection
+    # @see Faraday::Connection.put
+    def_delegator :@connection, :put
 
     # Create a new connection to talk to solr
     # @param url [String] URL to the "root" of the solr installation. For a default solr setup, this will
@@ -38,21 +65,21 @@ module SolrCloud
     # @param user [String] username for basic auth, if you're using it
     # @param password [String] password for basic auth, if you're using it
     # @param logger [#info, :off, nil] An existing logger to pass in. The symbol ":off" means
-    # don't do logging. If left undefined, will create a standard ruby logger to $stdout
+    #   don't do logging. If left undefined, will create a standard ruby logger to $stdout
     # @param adapter [Symbol] The underlying http library to use within Faraday
     def initialize(url:, user: nil, password: nil, logger: nil, adapter: :httpx)
       @url = url
       @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
-      end
-      @raw_connection = create_raw_connection(url: url, adapter: adapter, user: user, password: password, logger: @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!
       @logger.info("Connected to supported solr at #{url}")
     end
@@ -61,7 +88,7 @@ module SolrCloud
     # @param faraday_connection [Faraday::Connection] A pre-build faraday connection object
     def self.new_from_faraday(faraday_connection)
       c = allocate
-      c.instance_variable_set(:@raw_connection, faraday_connection)
+      c.instance_variable_set(:@connection, faraday_connection)
       c.instance_variable_set(:@url, faraday_connection.build_url.to_s)
       c
     end
@@ -69,7 +96,7 @@ module SolrCloud
     # Create a Faraday connection object to base the API client off of
     # @see #initialize
     def create_raw_connection(url:, adapter: :httpx, user: nil, password: nil, logger: nil)
-      Faraday.new(request: {params_encoder: Faraday::FlatParamsEncoder}, url: URI(url)) do |faraday|
+      Faraday.new(request: { params_encoder: Faraday::FlatParamsEncoder }, url: URI(url)) do |faraday|
         faraday.use Faraday::Response::RaiseError
         faraday.request :url_encoded
         if user
@@ -87,7 +114,7 @@ module SolrCloud
 
     # 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, :raw_connection
+    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
@@ -145,6 +172,15 @@ module SolrCloud
       _version_part_int(2)
     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.
+    # @param str [String] string to check
+    # @return [Boolean]
+    def legal_solr_name?(str)
+      !(/[^a-zA-Z_\-0-9]/.match?(str) or str.start_with?("_"))
+    end
+
     def inspect
       "<#{self.class} #{@url}>"
     end
@@ -156,3 +192,5 @@ module SolrCloud
     end
   end
 end
+
+

data/lib/solr_cloud/errors.rb

@@ -19,4 +19,6 @@ module SolrCloud
   class Unauthorized < ArgumentError; end
 
   class ConnectionFailed < RuntimeError; end
+
+  class IllegalNameError < ArgumentError; end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solr_cloud-connection
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Bill Dueber
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-30 00:00:00.000000000 Z
+date: 2023-12-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -108,6 +108,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description:
 email:
 - bill@dueber.com
@@ -115,7 +129,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".env.local"
+- ".env.github"
 - ".rspec"
 - ".standard.yml"
 - CHANGELOG.md
@@ -124,7 +138,7 @@ files:
 - README.md
 - Rakefile
 - compose.yml
-- env.development
+- env.test
 - lib/solr_cloud/alias.rb
 - lib/solr_cloud/collection.rb
 - lib/solr_cloud/configset.rb