solr_cloud-connection 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1989962c4834b362be714c08199791950034638d4e2ea26bfa1368e377390f3b
+  data.tar.gz: ed3621358d19671db37394b04b0df83e700b2dbd7b45dc7cd3e545c782ed64c6
+SHA512:
+  metadata.gz: 6161fb600d516c459a843f9f8054cf2b3db2cb0eadf04678af037b7bc55e86b828b08e167f01391dbb9b7b2d4c5a5759851fc322a71a8d545651734e44df978c
+  data.tar.gz: 7082a625e5ffa7f04e17638db3782b0ac3715a3955413539543e39297cb589825cde87abd06dc2aff1cde7c59581da25a4d6fb372c7f3b177d780e035a5d1bdd

data/.env.local

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

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/testdouble/standard
+ruby_version: 2.6

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2023-11-29
+
+- Initial release

data/Dockerfile

@@ -0,0 +1,30 @@
+FROM ruby:3.2 AS development
+
+# Check https://rubygems.org/gems/bundler/versions for the latest version.
+ARG UNAME=app
+ARG UID=1000
+ARG GID=1000
+
+## Install Vim (optional)
+RUN apt-get update -yqq && apt-get install -yqq --no-install-recommends \
+  vim-tiny
+
+RUN gem install bundler
+
+RUN groupadd -g ${GID} -o ${UNAME}
+RUN useradd -m -d /app -u ${UID} -g ${GID} -o -s /bin/bash ${UNAME}
+RUN mkdir -p /gems && chown ${UID}:${GID} /gems
+
+ENV PATH="$PATH:/app/exe:/app/bin"
+USER $UNAME
+
+ENV BUNDLE_PATH /gems
+
+WORKDIR /app
+
+FROM development AS production
+
+COPY --chown=${UID}:${GID} . /app
+
+RUN bundle install
+

data/LICENSE.txt

@@ -0,0 +1,9 @@
+Copyright (c) 2022, 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 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 COPYRIGHT HOLDERS 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

@@ -0,0 +1,171 @@
+# SolrCloud::Connection
+
+Do basic administrative tasks on a running Solr cloud instance, including:
+
+* 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
+* TODO automatically generate methods to talk to defined requestHandlers
+* TODO collect and deal with search results in a sane way
+
+## 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.
+* 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.
+
+```ruby
+
+require "solr_cloud/connection"
+
+solr = SolrCloud::connect.new(url: "http://localhost:9999", username: "user", password: "password")
+#    #=> <SolrCloud::Connection http://localhost:9999/>
+
+# 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")
+
+# It makes sure you don't overwrite when creating a new set
+connect.create_configset(name: "myconfig", confdir: "/path/to/yourconfig/conf")
+      #=> WontOverwriteError
+
+# ...but you can force it
+connect.create_configset(name: "myconfig", confdir: "/path/to/yourconfig/conf", force: true)
+
+# And get rid of it
+myconfig.delete!
+connect.configset?("myconfig") #=> false
+
+```
+
+### 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"
+
+# Test and see if it exists
+connect.collection?("mycoll") #=> true
+
+# Get all of them
+
+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")
+
+mycoll.alive? # => true
+mycoll.healthy? #=> true. I'm not sure how these are different
+
+mycoll.alias? # false. It's a collection. 
+
+# Which configset is it based on?
+mycoll.configset #=> <SolrCloud::Configset '_default' at http://localhost:9999/>
+
+# Sniff out and create aliases
+mycoll.aliases #=> [] None as of yet
+myalias = mycoll.alias_as("myalias")
+
+mycoll.aliases #=> [<SolrCloud::Alias 'myalias' (alias of 'mycoll')>]
+mycoll.alias_names #=> ["myalias"]
+
+# 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")
+
+# 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!
+
+```
+
+### Aliases
+
+In all the important ways, aliases can be treated like collections. Here are the exceptions.
+
+```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!
+```
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add solr_cloud-connection
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install solr_cloud-connection
+
+## Testing
+
+This repository is set up to run tests under docker.
+
+1. docker compose build
+2. docker compose run app bundle install
+3. docker compose up
+4. docker compose run app bundle exec rspec
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/mlibrary/solr_cloud-connect.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/compose.yml

@@ -0,0 +1,34 @@
+services:
+  app:
+    build: 
+      context: .
+      target: development
+    platform: linux/amd64
+    volumes:
+      - .:/app
+      - gem_cache:/gems
+    env_file:
+      - .env
+      - env.development
+    command: "tail -f /dev/null"
+
+  solr:
+    build: spec/data/solr_docker/.
+    ports:
+      - "9999:8983"
+    environment:
+      - ZK_HOST=zoo:2181
+    depends_on:
+      - zoo
+    command: solr-foreground
+
+  zoo:
+    image: zookeeper
+    ports:
+      - 2999:2181
+    environment:
+      ZOO_MY_ID: 1
+      ZOO_SERVERS: server.1=0.0.0.0:2888:3888;2181
+        
+volumes:
+  gem_cache:

data/env.development

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

data/lib/solr_cloud/alias.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+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.
+
+  # 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?
+    def alias?
+      true
+    end
+
+    # Delete this alias
+    # @return [SolrCloud::Connection]
+    def delete!
+      coll = collection
+      connection.delete_alias(name)
+      coll
+    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]
+    def collection
+      connection.collection_for_alias(name)
+    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)
+      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)
+      connection.create_alias(name: name, collection_name: collect_name, force: true)
+    end
+
+    # Get basic information on the underlying collection, so inherited methods that
+    # use it (e.g., #healthy?) will work.
+    # @overload info()
+    def info
+      collection.info
+    end
+
+    def inspect
+      "<#{self.class} '#{name}' (alias of '#{collection.name}')>"
+    end
+
+    alias_method :to_s, :inspect
+
+    def pretty_print(q)
+      q.text inspect
+    end
+  end
+end

data/lib/solr_cloud/collection.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "solr_cloud/connection"
+
+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
+
+    # In general, users shouldn't use Collection.new; instead, use
+    # connection.create_collection(name: "coll_name", configset: "existing_configset_name")
+    #
+    # @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)
+      @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
+    def delete!
+      raise NoSuchCollectionError unless exist?
+      connection.delete_collection(name)
+      connection
+    end
+
+    # Check to see if the collection is alive
+    # @return [Boolean]
+    def alive?
+      connection.get("solr/#{name}/admin/ping").body["status"]
+    rescue Faraday::ResourceNotFound
+      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
+    # convenient
+    def alias?
+      false
+    end
+
+    # 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.
+    def info
+      connection.get("api/collections/#{name}").body["cluster"]["collections"][name]
+    end
+
+    # Reported as healthy?
+    # @return [Boolean]
+    def healthy?
+      info["health"] == "GREEN"
+    end
+
+    # 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) }
+    end
+
+    # The names of the aliases that point to this collection
+    # @return [Array<String>] the alias names
+    def alias_names
+      aliases.map(&:name)
+    end
+
+    # 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}"))
+    end
+
+    # Create an alias for this collection. Always forces an overwrite unless you tell it not to
+    # @param alias_name [String] name of the alias to create
+    # @param force [Boolean] whether or not to overwrite an existing alias
+    # @return [SolrCloud::Alias]
+    def alias_as(alias_name, force: true)
+      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)
+      if hard
+        connection.get("solr/#{name}/update", commit: true)
+      else
+        connection.get("solr/#{name}/update", softCommit: true)
+      end
+      self
+    end
+
+    # What configset was this created with?
+    # @return [SolrCloud::ConfigSet]
+    def configset
+      Configset.new(name: info["configName"], connection: connection)
+    end
+
+    def inspect
+      anames = alias_names
+      astring = if anames.empty?
+        ""
+      else
+        " (aliased by #{anames.map { |x| "'#{x}'" }.join(", ")})"
+      end
+      "<#{self.class} '#{name}'#{astring}>"
+    end
+
+    alias_method :to_s, :inspect
+
+    def pretty_print(q)
+      q.text inspect
+    end
+  end
+end

data/lib/solr_cloud/configset.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "solr_cloud/connection"
+
+module SolrCloud
+  # A configset can't do much by itself, other than try to delete itself and
+  # throw an error if that's an illegal operation (because a collection is
+  # using it)
+  class Configset
+    attr_reader :name, :connection
+
+    def initialize(name:, connection:)
+      @name = name
+      @connection = connection
+    end
+
+    # Delete this configset.
+    # @see SolrCloud::Connection#delete_configset
+    # @return The underlying connection
+    def delete!
+      @connection.delete_configset(name)
+      @connection
+    end
+
+    def inspect
+      "<#{self.class.name} '#{name}' at #{connection.url}>"
+    end
+
+    alias_method :to_s, :inspect
+
+    def pretty_print(q)
+      q.text inspect
+    end
+  end
+end

data/lib/solr_cloud/connection/alias_admin.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module SolrCloud
+  class Connection
+    # 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
+      AliasCollectionPair = Struct.new(:alias, :collection)
+
+      # Create an alias for the given collection name
+      # @todo allow an alias to point to more than one collection?
+      # @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")
+        end
+        connection.get("solr/admin/collections", action: "CREATEALIAS", name: name, collections: collection_name)
+        SolrCloud::Alias.new(name: name, connection: self)
+      end
+
+      # Is there an alias with this name?
+      # @return [Boolean]
+      def 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
+      end
+
+      # List of alias names
+      # @return [Array<String>] the alias names
+      def alias_names
+        alias_map.keys
+      end
+
+      # Get an alias object for the given name
+      # @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]
+      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)
+      end
+    end
+  end
+end

data/lib/solr_cloud/connection/collection_admin.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module SolrCloud
+  class Connection
+    # methods having to do with connections, to be included by the connection object.
+    # These are split out only to make it easier to deal with them.
+    module CollectionAdmin
+      # Create 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 shards [Integer]
+      # @param replication_factor [Integer]
+      # @todo Let version take symbols like :date and :datetime
+      # @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
+        end
+
+        raise WontOverwriteError.new("Collection #{fullname} already exists") if collection?(fullname)
+        raise NoSuchConfigSetError.new("Configset '#{configset}' doesn't exist") unless configset?(configset)
+
+        args = {
+          :action => "CREATE",
+          :name => fullname,
+          :numShards => shards,
+          :replicationFactor => replication_factor,
+          "collection.configName" => configset
+        }
+        connection.get("solr/admin/collections", args)
+        collection(name)
+      end
+
+      # Get a list of existing collections
+      # @return [Array<SolrCloud::Collection>] possibly empty list of collection objects
+      def collections
+        collection_names.map { |coll| collection(coll) }
+      end
+
+      # A list of the names of existing collections
+      # @return [Array<String>] the collection names, or empty array if there are none
+      def collection_names
+        connection.get("api/collections").body["collections"]
+      end
+
+      # @param name [String] name of the collection to check on
+      # @return [Boolean] Whether a collection with the passed name exists
+      def 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})
+        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
+      # @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)
+      end
+    end
+  end
+end

data/lib/solr_cloud/connection/configset_admin.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "zip"
+
+module SolrCloud
+  class Connection
+    # 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
+      # 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
+
+      # @return [Array<String>] the names of the config sets
+      def configset_names
+        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)
+        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
+      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
+      # @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
+          connection.delete("api/cluster/configs/#{name}")
+        end
+        self
+      rescue Faraday::BadRequestError => e
+        msg = e.response[:body]["error"]["msg"]
+        if msg.match?(/not delete ConfigSet/)
+          raise ConfigSetInUseError.new msg
+        else
+          raise e
+        end
+      end
+
+      # 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.
+      class ZipFileGenerator
+        # Initialize with the directory to zip and the location of the output archive.
+        def initialize(input_dir, output_file)
+          @input_dir = input_dir
+          @output_file = output_file
+        end
+
+        # Zip the input directory.
+        def write
+          entries = Dir.entries(@input_dir) - %w[. ..]
+          ::Zip::File.open(@output_file, create: true) do |zipfile|
+            write_entries entries, "", zipfile
+          end
+        end
+
+        private
+
+        # A helper method to make the recursion work.
+        def write_entries(entries, path, zipfile)
+          entries.each do |e|
+            zipfile_path = (path == "") ? e : File.join(path, e)
+            disk_file_path = File.join(@input_dir, zipfile_path)
+
+            if File.directory? disk_file_path
+              recursively_deflate_directory(disk_file_path, zipfile, zipfile_path)
+            else
+              put_into_archive(disk_file_path, zipfile, zipfile_path)
+            end
+          end
+        end
+
+        def recursively_deflate_directory(disk_file_path, zipfile, zipfile_path)
+          zipfile.mkdir zipfile_path
+          subdir = Dir.entries(disk_file_path) - %w[. ..]
+          write_entries subdir, zipfile_path, zipfile
+        end
+
+        def put_into_archive(disk_file_path, zipfile, zipfile_path)
+          zipfile.add(zipfile_path, disk_file_path)
+        end
+      end
+    end
+  end
+end

data/lib/solr_cloud/connection/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SolrCloud
+  class Connection
+    VERSION = "0.1.0"
+  end
+end

data/lib/solr_cloud/connection.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "httpx/adapters/faraday"
+require "logger"
+
+require_relative "connection/version"
+require_relative "connection/configset_admin"
+require_relative "connection/collection_admin"
+require_relative "connection/alias_admin"
+require_relative "collection"
+require_relative "alias"
+require_relative "configset"
+require_relative "errors"
+
+require "forwardable"
+
+module SolrCloud
+  # The connection object is the basis of all the other stuff. Everything will be created, directly
+  # or indirectly, through the connection.
+  #
+  # For convenience, it forwards #get, #post, #put, and #delete HTTP verbs to the underlying
+  # raw faraday http client.
+  class Connection
+    extend Forwardable
+
+    include ConfigsetAdmin
+    include CollectionAdmin
+    include AliasAdmin
+
+    attr_reader :url, :logger, :raw_connection
+
+    def_delegators :@raw_connection, :get, :post, :delete, :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
+    # just be the root url (_not_ including the `/solr`)
+    # @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
+    # @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)
+      bail_if_incompatible!
+      @logger.info("Connected to supported solr at #{url}")
+    end
+
+    # Pass in your own faraday connection
+    # @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(:@url, faraday_connection.build_url.to_s)
+      c
+    end
+
+    # 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.use Faraday::Response::RaiseError
+        faraday.request :url_encoded
+        if user
+          faraday.request :authorization, :basic, user, password
+        end
+        faraday.request :json
+        faraday.response :json
+        if logger
+          faraday.response :logger, logger
+        end
+        faraday.adapter adapter
+        faraday.headers["Content-Type"] = "application/json"
+      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, :raw_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
+    def bail_if_incompatible!
+      raise UnsupportedSolr.new("SolrCloud::Connection needs at least solr 8") if major_version < 8
+      raise UnsupportedSolr.new("SolrCloud::Connection only works in solr cloud mode") unless cloud?
+    rescue Faraday::ConnectionFailed
+      raise ConnectionFailed.new("Can't connect to #{url}")
+    end
+
+    # Get basic system info from the server
+    # @raise [Unauthorized] if the server gives a 401
+    # @return [Hash] The response from the info call
+    def system
+      resp = get("/solr/admin/info/system")
+      resp.body
+    rescue Faraday::UnauthorizedError
+      raise Unauthorized.new("Server reports failed authorization")
+    end
+
+    # @return [String] the mode ("solrcloud" or "std") solr is running in
+    def mode
+      system["mode"]
+    end
+
+    # @return [Boolean] whether or not solr is running in cloud mode
+    def cloud?
+      mode == "solrcloud"
+    end
+
+    # @return [String] the major.minor.patch string of the solr version
+    def version_string
+      system["lucene"]["solr-spec-version"]
+    end
+
+    # Helper method to get version parts as ints
+    # @return [Integer] Integerized version of the 0,1,2 portion of the version string
+    def _version_part_int(index)
+      version_string.split(".")[index].to_i
+    end
+
+    # @return [Integer] solr major version
+    def major_version
+      _version_part_int(0)
+    end
+
+    # @return [Integer] solr minor version
+    def minor_version
+      _version_part_int(1)
+    end
+
+    # @return [Integer] solr patch version
+    def patch_version
+      _version_part_int(2)
+    end
+
+    def inspect
+      "<#{self.class} #{@url}>"
+    end
+
+    alias_method :to_s, :inspect
+
+    def pretty_print(q)
+      q.text inspect
+    end
+  end
+end

data/lib/solr_cloud/errors.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Errors to make it more clear what's going on if things go south
+module SolrCloud
+  class NoSuchCollectionError < ArgumentError; end
+
+  class NoSuchConfigSetError < ArgumentError; end
+
+  class NoSuchAliasError < ArgumentError; end
+
+  class WontOverwriteError < RuntimeError; end
+
+  class ConfigSetInUseError < RuntimeError; end
+
+  class CollectionAliasedError < RuntimeError; end
+
+  class UnsupportedSolr < RuntimeError; end
+
+  class Unauthorized < ArgumentError; end
+
+  class ConnectionFailed < RuntimeError; end
+end

metadata

@@ -0,0 +1,163 @@
+--- !ruby/object:Gem::Specification
+name: solr_cloud-connection
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bill Dueber
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-11-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.7.12
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.7.12
+- !ruby/object:Gem::Dependency
+  name: httpx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.5
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.3.0
+- !ruby/object:Gem::Dependency
+  name: pry
+  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'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  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'
+- !ruby/object:Gem::Dependency
+  name: standard
+  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'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  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
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env.local"
+- ".rspec"
+- ".standard.yml"
+- CHANGELOG.md
+- Dockerfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- compose.yml
+- env.development
+- lib/solr_cloud/alias.rb
+- lib/solr_cloud/collection.rb
+- lib/solr_cloud/configset.rb
+- lib/solr_cloud/connection.rb
+- lib/solr_cloud/connection/alias_admin.rb
+- lib/solr_cloud/connection/collection_admin.rb
+- lib/solr_cloud/connection/configset_admin.rb
+- lib/solr_cloud/connection/version.rb
+- lib/solr_cloud/errors.rb
+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
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.17
+signing_key:
+specification_version: 4
+summary: Do basic administrative operations on a solr cloud instance and collections
+  within
+test_files: []