solr_cloud-connection 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2257fc2ce8c0a649712a66c5154222cfd6d2e0b0d837df583d297eba3d19d6bb
-  data.tar.gz: b9fdf5d5dd5a3c8d2fe4ec5a0e47f414fc9186a020292d34631e887591528327
+  metadata.gz: 0d4b1ea9a7eade492c2e88434c38dadc43bcbb5a28084c4be797ce2c77eb70ce
+  data.tar.gz: 5531b66702ac408e0631239568035f2693cbda02b06e5401b858caa3bd633d9f
 SHA512:
-  metadata.gz: 53b06b39cb208dff15696c94541aae3e3069d577be2b16d587f3a8fb86594dac0eef88a9fc4800564d469bfe898ae281421b04fef957af89472085e420f60de2
-  data.tar.gz: 3a6daabf59f8dc61fdd2d21019596714649219e50ce6983a4c6ba873d188782c6b3b6a32e932d66512e3e9eab83f4516137f3605f22fbab968811e73e5d78170
+  metadata.gz: b6fcb28bcf8a42191ce737b4c5ae431d669a66e92b3a2d947e26c7901f3a9b5ec0afd4353d00bf6db4ae397a10c4c8aee629c366fbb6976595170b47b7cf1e2a
+  data.tar.gz: c8689a6b34f2ba3307ac1bfd19adf2c5fff13ecfd7b6aa2fc934754c9667569b369fddfcb4f796528d3594d5babf3213c603a9871cb92edbbb28a6f78e45e006

data/README.md

@@ -22,7 +22,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 +34,170 @@ 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
+
+server = SolrCloud::Connection.new(url: url, user: user, password: pass) 
+  #=> <SolrCloud::Connection http://localhost:9090>
 
-require "solr_cloud/connection"
+  # or bring your own Faraday object
+  # server2 = SolrCloud::Connection.new_with_faraday(faraday_connection)
 
-server = SolrCloud::connect.new(url: "http://localhost:8023", username: "user", password: "password")
-#    #=> <SolrCloud::Connection http://localhost:8023/>
+  ### Get some basic info
+
+server.version_string #=> "8.11.2"
+server.cloud? #=> true
+server.mode #=> "solrcloud"
+```
 
-# or bring your own Faraday object
-# server = SolrCloud::connect.new_with_faraday(faraday_connection)
+### 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 +226,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 welcom
+on GitHub at https://github.com/mlibrary/solr_cloud-connection.

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,6 +49,19 @@ module SolrCloud
       @sp = "/solr/#{name}"
     end
 
+    def collection
+      self
+    end
+
+    def ==(other)
+      case other
+        when SolrCloud::Collection
+          self.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
@@ -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)

data/lib/solr_cloud/configset.rb

@@ -33,6 +33,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/version.rb

@@ -2,6 +2,6 @@
 
 module SolrCloud
   class Connection
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   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,168 @@
+# 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
+cars
+cars == cars_v1
+cars == cars_v2
+
+# 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.5.0
 platform: ruby
 authors:
 - Bill Dueber
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-12-07 00:00:00.000000000 Z
+date: 2024-03-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -16,42 +16,42 @@ 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
   requirement: !ruby/object:Gem::Requirement
@@ -148,6 +148,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: