hubssolib 3.4.0 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1a83a70b87a6c3cabd8bbb821dfc06ee467d382c9593cb7c1733152e136f5a1
-  data.tar.gz: 87f1dda92220f25326c8bbce597ecd97e74c3dd7e22fd0fbf89bfed6269b6b23
+  metadata.gz: faacd8f740f867ee072f0f8e0f15324109941026b836cb3fcc8618f61ee68e02
+  data.tar.gz: 6ef08dccd8bbe03a974c238353a27d7f249a40911a40d65dfcd481dd6fe7b48e
 SHA512:
-  metadata.gz: cf2ae3afb91a4fcc3391cf4b156e3dd9e4d0be4cecafc10204cf6dc8a7d6b9d07d51dc08cd7fd22ee12a478025d03730227fa2602a194d4b0e6785d72af21295
-  data.tar.gz: 6ac8d8a0a1920d7f93604204ef0c254a094bd4a8559110bba2f630c1fe406f87966b0ba2289d017a9a48e90cd0d6e2eab0e1ae3872032c7bad389942965fe2b2
+  metadata.gz: 67b9f58743d8f9ed2983d3b9b970fd00d50ba335dcd761f8c9626866c9c91a1e65c378bb0139835c1e8eb48557e681ea510f6391373d06e1a6806aaf8b8fc2e2
+  data.tar.gz: d4e6efe525fb55b25f40c888ab4d05a7041c90c1cddcba7bab74002d299b2a1f96e35f58ea211cb666da68fda3d129400a7bf874bc8b7ddf09e9fdd6a8d1fbd2

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## 3.6.0, 26-Mar-2025
+
+Cleans up and offers new enumeration features. Ordering by last-recently-active first allows clients to be deterministic about enumerated sessions. Features created to support improvements in the Hub app v3.6.0.
+
+Note that the session generator in the factory - HubSsoLib::SessionFactory#get_hub_session_proxy - no longer pays attention to IP address parameter, which should now be omitted (it is now an ignored parameter that defaults to +nil+). See implementation comments for rationale, but basically, IP addresses can legitimately change for users due to DHCP (even if that's rare) and given v3.5.0's on-shutdown session store, it didn't seem wise to keep IP addresses around inside there for any length of time. It was cleanest to just drop them. PII in persisted data is once again limited to "real name" and e-mail address.
+s
+## 3.5.0, 25-Mar-2025
+
+Builds on the cleaner session interface with some changes and improvements:
+
+* Removed the 'clean up other sessions under that user ID' code, since that stopped you being able to log in on more than one browser - notably, both e.g. a desktop/laptop computer's browser and a mobile device's browser. This does carry a risk of stale session cookies for a user building up over time, but the sweeper Rake task will attend to those in due course.
+* On the other hand the Hub core explicitly say whether or not it is trying to read or create a session, so the internal lazy-create no longer triggers for outdated session cookies, resulting in unnecessary "empty" sessions where all the user properties are "nil". This prevents accumulation of sessions for some cases.
+
+Minor version number arises due to a new feature:
+
+* If the DRb server receives signals `TERM` (e.g. default `kill`) or `INT` (e.g. `Ctrl`+`C`) it now gracefully shuts down, dumping user sessions to a YAML file in a location of `~/.hub_ses_arc` by default, or the filename in environment variable `HUB_SESSION_ARCHIVE`, if defined.
+* On startup, this file is loaded. If exceptions are encountered they are ignored and session data is ignored, leading to a clean start. Likewise simply deleting the file leads to a clean start - otherwise, it becomes possible to cycle the DRb server and retain session data! **A self-sweep of ancient sessions is conducted at startup**, which takes the same action as the `hub_sessions:sweep` Rake task.
+* Once the server is running the file is deleted, so in case of hard crash or forced exit via other signals (e.g. `kill -9`) - so a new session dump is _not_ made - then session data is lost, by design. The assumption in such circumstances is that session data is unreliable and may even have been the cause of a crash.
+
 ## 3.4.0, 24-Mar-2025
 
 The session interface has now been cleaned up. While the public API is unchanged, you:
@@ -16,7 +35,6 @@ In addition:
 
 * Iteration over the sessions object for active user enumeration could cause failures. The process could be time consuming and, during it, the client side is iterating over a remote object that the DRb server maintains for any new, inbound sessions which may be started by other web server request threads into the Hub app. This would lead to `can't add a new key into hash during iteration` exceptions. This is fixed via more aggressive mutex use.
 
-
 ## 3.3.0, 16-Feb-2025
 
 Sentry support, for use by the DRb server. If you use Sentry, define your account's `SENTRY_DSN` in the environment where the DRb server runs and exceptions will be reported.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    hubssolib (3.4.0)
+    hubssolib (3.5.0)
       base64 (~> 0.2)
       drb (~> 2.2)
 
@@ -13,7 +13,7 @@ GEM
     debug (1.10.0)
       irb (~> 1.10)
       reline (>= 0.3.8)
-    diff-lcs (1.6.0)
+    diff-lcs (1.6.1)
     docile (1.4.1)
     doggo (1.4.0)
       rspec-core (~> 3.13)

data/README.md

@@ -208,6 +208,8 @@ User-idle session expiry is routinely handled in the "beforehand" callback so th
 
 Users who log in but then go idle will not cause any natural session expiry by virtue of there being no new page fetch activity provoking the idle timeout check. For users who've just gone away full stop, this means a session record is left hanging around in DRb server memory (or if future iterations support other storage methods, they'd persist in whatever storage that is). For this reason, the Hub _application_ provides a Rake task which sweeps sessions based on things idle for three times the `HUB_IDLE_TIME_LIMIT`, or two days, whichever is longer (so short idle timers still give users a couple of days to potentially come back to their old session and get the "nice" expiry message). Run `bundle exec rake hub_sessions:sweep` whenever you want (in practice, once a day is enough). **Be sure to set up any custom Hub environment variables for your setup** so that the Rake task knows where to find the DRb socket for the running server, what your expiry time is if so customised, and so-on.
 
+* **Note:** The DRb server persists sessions upon graceful shutdown (`INT` or `TERM` signals) into file `~/.hub_ses_arc` by default, or the filename in environment variable `HUB_SESSION_ARCHIVE` if defined. When the server restarts, it loads this data **and runs the same very old session expiry** algorithm. This means that shutting down and restarting the DRb server is another way to expire very old sessions, but that results in downtime, even if only brief; so for general maintenance with uptime maintained, the Rake task should be used.
+
 
 
 ## Hub library API

data/hubssolib.gemspec

@@ -4,7 +4,7 @@ spec = Gem::Specification.new do |s|
   s.platform = Gem::Platform::RUBY
   s.name     = 'hubssolib'
 
-  s.version  = '3.4.0'
+  s.version  = '3.6.0'
   s.author   = 'Andrew Hodgkinson and others'
   s.email    = 'ahodgkin@rowing.org.uk'
   s.homepage = 'http://pond.org.uk/'

data/lib/hub_sso_lib.rb

@@ -1,6 +1,6 @@
 #######################################################################
 # Module:  HubSsoLib                                                  #
-#          (C) Hipposoft 2006-2019                                    #
+#          (C) Hipposoft 2006-2025                                    #
 #                                                                     #
 # Purpose: Cross-application same domain single sign-on support.      #
 #                                                                     #
@@ -13,6 +13,7 @@
 #          09-Mar-2011 (ADH): Updated for Hub on Rails 2.3.11 along   #
 #                             with several important bug fixes.       #
 #          01-May-2019 (ADH): Updated for Ruby 2.5.x.                 #
+#          25-Mar-2025 (ADH): Major 2025 overhaul for ROOL site.      #
 #######################################################################
 
 module HubSsoLib
@@ -20,8 +21,10 @@ module HubSsoLib
   require 'drb'
   require 'securerandom'
   require 'json'
+  require 'yaml'
 
-  # DRb connection
+  # DRb connection.
+  #
   HUB_CONNECTION_URI = ENV['HUB_CONNECTION_URI'] || 'drbunix:' + File.join( ENV['HOME'] || '/', '/.hub_drb')
 
   unless HUB_CONNECTION_URI.downcase.start_with?('drbunix:')
@@ -34,7 +37,8 @@ module HubSsoLib
     raise 'Exiting'
   end
 
-  # External application command registry for on-user-change events
+  # External application command registry for on-user-change events.
+  #
   HUB_COMMAND_REGISTRY = ENV['HUB_COMMAND_REGISTRY'] || File.join( ENV['HOME'] || '/', '/.hub_cmd_reg')
 
   unless Dir.exist?(File.dirname(HUB_COMMAND_REGISTRY))
@@ -47,6 +51,20 @@ module HubSsoLib
     raise 'Exiting'
   end
 
+  # DRb session on-shutdown dumped cache/archive.
+  #
+  HUB_SESSION_ARCHIVE = ENV['HUB_SESSION_ARCHIVE'] || File.join( ENV['HOME'] || '/', '/.hub_ses_arc')
+
+  unless Dir.exist?(File.dirname(HUB_SESSION_ARCHIVE))
+    puts
+    puts '*' * 80
+    puts "Invalid path specified by HUB_SESSION_ARCHIVE (#{ HUB_SESSION_ARCHIVE.inspect })"
+    puts '*' * 80
+    puts
+
+    raise 'Exiting'
+  end
+
   # Location of Hub application root.
   #
   HUB_PATH_PREFIX = ENV['HUB_PATH_PREFIX'] || ''
@@ -57,19 +75,33 @@ module HubSsoLib
   #
   HUB_IDLE_TIME_LIMIT = ENV['HUB_IDLE_TIME_LIMIT']&.to_i || 4 * 60 * 60
 
+  # Archive time for very old sessions that are kicked out foricbly.
+  #
+  HUB_ARCHIVE_TIME_LIMIT = [ HUB_IDLE_TIME_LIMIT * 3, 172_800 ].max() # (2 days or more)
+
+  # If you use live session enumeration, this is the hard-coded limit for the
+  # number of session keys that can be returned. If there are more active
+  # sessions that this, bulk session enumeration is not permitted.
+  #
+  HUB_SESSION_ENUMERATION_KEY_MAX = ENV['HUB_SESSION_ENUMERATION_KEY_MAX']&.to_i || 2000
+
   # Shared cookie name.
+  #
   HUB_COOKIE_NAME = :hubapp_shared_id
 
   # Principally for #hubssolib_account_link.
+  #
   HUB_LOGIN_INDICATOR_COOKIE       = :hubapp_shared_id_alive
   HUB_LOGIN_INDICATOR_COOKIE_VALUE = 'Y'
 
   # Bypass SSL, for testing purposes? Rails 'production' mode will
   # insist on SSL otherwise. Development & test environments do not,
   # so do not need this variable setting.
+  #
   HUB_BYPASS_SSL = ( ENV['HUB_BYPASS_SSL'] == "true" )
 
   # Thread safety.
+  #
   HUB_MUTEX = Mutex.new
 
   #######################################################################
@@ -403,7 +435,6 @@ module HubSsoLib
     attr_accessor :session_flash
     attr_accessor :session_user
     attr_accessor :session_rotated_key
-    attr_accessor :session_ip
 
     def initialize
       @session_last_used   = Time.now.utc
@@ -411,7 +442,6 @@ module HubSsoLib
       @session_flash       = {}
       @session_user        = HubSsoLib::User.new
       @session_rotated_key = nil
-      @session_ip          = nil
 
     rescue => e
       Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
@@ -438,7 +468,33 @@ module HubSsoLib
       @hub_be_quiet = ! ENV['HUB_QUIET_SERVER'].nil?
       @hub_sessions = {}
 
-      puts "Session factory: Awaken" unless @hub_be_quiet
+      puts "Session factory: Awakening..." unless @hub_be_quiet
+
+      if File.exist?(HUB_SESSION_ARCHIVE)
+        begin
+          restored_sessions = ::YAML.load_file(
+            HUB_SESSION_ARCHIVE,
+            permitted_classes: [
+              ::HubSsoLib::Session,
+              ::HubSsoLib::User,
+              Time
+            ]
+          )
+
+          @hub_sessions = restored_sessions || {}
+          self.destroy_ancient_sessions()
+          puts "Session factory: Reloaded #{@hub_sessions.size} from archive" unless @hub_be_quiet
+
+        rescue => e
+          puts "Session factory: Ignored archive due to error #{e.message.inspect}" unless @hub_be_quiet
+
+        ensure
+          File.unlink(HUB_SESSION_ARCHIVE)
+
+        end
+      end
+
+      puts "Session factory: ...Awakened" unless @hub_be_quiet
 
     rescue => e
       Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
@@ -456,35 +512,39 @@ module HubSsoLib
     #
     # The returned object is proxied via DRb - it is shared between processes.
     #
-    # +key+::       Session key; lazy-initialises a new session under this key
-    #               if none is found, then immediately rotates it.
+    # +key+:: Session key; lazy-initialises a new session under this key if
+    #         none is found, then immediately rotates it by default, but may
+    #         return no session for unrecognised keys depending on the +create+
+    #         parameter, described below.
+    #
+    # The "_ignored" parameter is for backwards compatibility for older clients
+    # calling into a newer gem. This used to take an IP address of the request
+    # and would discard a session if the current IP address had changed, but
+    # since DHCP is a Thing then - even though in practice most IP addresses
+    # from ISPs are very stable - this wasn't really a valid security measure.
+    # It required us to process and store IP data which is now often considered
+    # PII and we'd rather not (especially given their arising storage in
+    # HUB_SESSION_ARCHIVE on shutdown). This is, of course, quite ironic given
+    # the reason for removal is IP address unreliability when used as PII!
     #
-    # +remote_ip+:: Request's remote IP address. If there is an existing
-    #               session which matches this, it's returned. If there is an
-    #               existing session but the IP mismatches, it's treated as
-    #               invalid and discarded.
+    # In addition, the following optional named parameters can be given:
     #
-    def get_hub_session_proxy(key, remote_ip)
+    # +create+:: Default +true+ - an unknown key causes creation of an empty,
+    #            new session under that key. If +false+, attempts to read with
+    #            an unrecognised key yield +nil+.
+    #
+    def get_hub_session_proxy(key, _ignored = nil, create: true)
       hub_session = HUB_MUTEX.synchronize { @hub_sessions[key] }
-      message     = hub_session.nil? ? 'Created' : 'Retrieving'
-      new_key     = SecureRandom.uuid
+      return nil if create == false && hub_session.nil? # NOTE EARLY EXIT
+
+      message = hub_session.nil? ? 'Created' : 'Retrieving'
+      new_key = SecureRandom.uuid
 
       unless @hub_be_quiet
         puts "Session factory: #{ message } session for key #{ key } and rotating to #{ new_key }"
       end
 
-      unless hub_session.nil? || hub_session.session_ip == remote_ip
-        unless @hub_be_quiet
-          puts "Session factory: WARNING: IP address changed from #{ hub_session.session_ip } to #{ remote_ip } -> discarding session"
-        end
-
-        hub_session = nil
-      end
-
-      if hub_session.nil?
-        hub_session            = HubSsoLib::Session.new
-        hub_session.session_ip = remote_ip
-      end
+      hub_session = HubSsoLib::Session.new if hub_session.nil?
 
       HUB_MUTEX.synchronize do
         @hub_sessions.delete(key)
@@ -499,34 +559,90 @@ module HubSsoLib
       raise
     end
 
+    # THIS INTERFACE IS DEPRECATED and will be removed in Hub 4. Change to
+    # #enumerate_hub_session_keys instead.
+    #
     # Enumerate all currently known sessions. The format is a Hash, with the
     # session key UUIDs as keys and the related HubSsoLib::Session instances as
-    # values.
+    # values. If you attempt it iterate over this data YOU MUST USE A COPY of
+    # the keys to do so, since Hub users may log in or out at any time and Ruby
+    # will raise an exception if the session data changes during enumeration -
+    # end users will see errors.
+    #
+    def enumerate_hub_sessions()
+      @hub_sessions
+
+    rescue => e
+      Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
+      raise
+    end
+
+    # Returns all currently known session keys. This is a COPY of the internal
+    # keyset, since otherwise it would be necessary to try and enumerate keys
+    # on a Hash which is subject to change at any moment if a user logs in or
+    # out. Since Ruby raises an exception should an under-iteration Hash be
+    # changed, we can't do that, which is why the keys are returned as a copied
+    # array instead.
     #
-    # WARNING: This returns all Hub sessions maintained by the server instance
-    # but it's returning a reference to the live object with everything being
-    # managed over DRb. If a caller iterates over this object, then it can fall
-    # foul of other request threads making changes to the underlying data and
-    # Ruby raising exceptions about e.g. hashes being modified during
-    # enumeration.
+    # Keys are ordered by least-recently-active first to most-recent last.
     #
-    # To prevent this, if intending to iterate over the collection, really the
-    # only safe way is to duplicate it first on "your side" (the client side)
-    # of the DRb connection. This of course consumes RAM, so you might choose
-    # to evaluate e.g. the number of keys in the returned session data and only
-    # permit enumeration if they fall below some previously-measured "allowed"
-    # value wherein RAM consumption is acceptable.
+    # Call #retrieve_session_by_key(...) to get session details for that key.
+    # Bear in mind that +nil+ returns are possible, since the session data may
+    # be changing rapidly and a user might've logged out or had their session
+    # expired in the time between you retrieving the list of current keys here,
+    # then requesting details of the session for that key later.
     #
-    # See HubSsoLib::Core#hubssolib_enumerate_users for an example.
+    # To avoid unbounded RAM requirements arising, the maximum number of keys
+    # returned herein is limited to HUB_SESSION_ENUMERATION_KEY_MAX.
     #
-    def enumerate_hub_sessions()
-      @hub_sessions
+    # Returns a Hash with Symbol keys that have values as follows:
+    #
+    # +count+:: The number of known sessions - just a key count.
+    # +keys+::  If +count+ exceeds HUB_SESSION_ENUMERATION_KEY_MAX, this is
+    #           +nil+, else an array of zero or more session keys.
+    #
+    def enumerate_hub_session_ids()
+      count = @hub_sessions.size
+      keys  = if count > HUB_SESSION_ENUMERATION_KEY_MAX
+        nil
+      else
+        @hub_sessions.keys # (Hash#keys returns a new array)
+      end
+
+      return { count: count, keys: keys }
 
     rescue => e
       Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
       raise
     end
 
+    # Retrieve session data (as a HubSsoLib::Session instance) based on the
+    # given session key. No key rotation occurs. Returns +nil+ if no entry is
+    # found for that key.
+    #
+    def retrieve_session_by_key(key)
+      @hub_sessions[key]
+    end
+
+    # WARNING: Comparatively slow.
+    #
+    # This is usually only called in administrative interfaces to look at the
+    # known sessions for a specific user of interest. An Hash of session key
+    # values yielding HubSsoLib::Session instances as values is returned.
+    #
+    # The array is ordered by least-recently-active first to most-recent last.
+    #
+    # IN THE CURRENT IMPLEMENTATION THIS JUST SEQUENTIALLY SCANS ALL ACTIVE
+    # SESSIONS IN THE HASH and must therefore lock on mutex for the duration.
+    #
+    def retrieve_sessions_by_user_id(user_id)
+      HUB_MUTEX.synchronize do
+        @hub_sessions.select do | key, session |
+          session&.session_user&.user_id == user_id
+        end
+      end
+    end
+
     # Given a session key (which, if a session has been looked up and the key
     # thus rotated, ought to be that new, rotated key), destroy the associated
     # session data. Does nothing if the key is not found.
@@ -541,7 +657,7 @@ module HubSsoLib
       raise
     end
 
-    # WARNING: Comparatively slow
+    # WARNING: Comparatively slow.
     #
     # This is called in rare cases such as user deletion or being asked for a
     # session under an old key, indicating loss of key rotation sequence.
@@ -562,7 +678,7 @@ module HubSsoLib
       raise
     end
 
-    # WARNING: Slow
+    # WARNING: Slow.
     #
     # This is a housekeeping task which checks sessions against Hub expiry and,
     # if the session keys look to be substantially older than the value set in
@@ -577,23 +693,21 @@ module HubSsoLib
     # session data while the method runs will block until method finishes.
     #
     def destroy_ancient_sessions
-      time_limit = HUB_IDLE_TIME_LIMIT * 3 # (TODO: This is fairly arbitrary...)
-      time_limit = 172_800 if time_limit < 172_800 # (2 days)
-      destroyed  = 0
-
       unless @hub_be_quiet
-        puts "Session factory: Sweeping sessions inactive for more than #{ time_limit } seconds..."
+        puts "Session factory: Sweeping sessions inactive for more than #{ HUB_ARCHIVE_TIME_LIMIT } seconds..."
       end
 
+      destroyed = 0
+
       HUB_MUTEX.synchronize do
-        count_before = @hub_sessions.keys.size
+        count_before = @hub_sessions.size
 
         @hub_sessions.reject! do | key, session |
           last_used = session&.session_last_used
-          last_used.nil? || Time.now.utc - last_used > time_limit
+          last_used.nil? || Time.now.utc - last_used > HUB_ARCHIVE_TIME_LIMIT
         end
 
-        count_after = @hub_sessions.keys.size
+        count_after = @hub_sessions.size
         destroyed   = count_before - count_after
       end
 
@@ -606,6 +720,41 @@ module HubSsoLib
       raise
     end
 
+    # Lock the session store and dump all sessions with a non-nil session user
+    # ID to a YAML file at HUB_SESSION_ARCHIVE. This is expected to only be
+    # called by the graceful shutdown code in HubSsoLib::Server.
+    #
+    def dump_sessions!
+      written_record_count = 0
+
+      # Why not just do ::YAML.dump(@hub_sessions)? Well, it'd be faster, but
+      # it builds the YAML data all in RAM which would cause a huge RAM spike
+      # of unknown size (depends on live session count) and that's Bad.
+      #
+      # If any no-user sessions have crept in for any reason, this also gives
+      # us a chance to skip them.
+      #
+      HUB_MUTEX.synchronize do
+        File.open(HUB_SESSION_ARCHIVE, 'w') do | f |
+          f.write("---\n") # (document marker)
+
+          @hub_sessions.each do | key, session |
+            next if session&.session_user&.user_id.nil? # NOTE EARLY LOOP RESTART
+
+            dump = ::YAML.dump({key => session})
+            dump.sub!(/^---\n/, '') # (avoid multiple document markers)
+
+            f.write(dump)
+            written_record_count += 1
+          end
+        end
+      end
+
+      # Simple if slightly inefficient way to deal with zero actual useful
+      # session records being present - an unusual real-world edge case.
+      #
+      File.unlink(HUB_SESSION_ARCHIVE) if written_record_count == 0
+    end
   end
 
   #######################################################################
@@ -626,16 +775,41 @@ module HubSsoLib
 
   module Server
     def hubssolib_launch_server
-      puts "Server: Starting at #{ HUB_CONNECTION_URI }" unless ENV['HUB_QUIET_SERVER'].nil?
+      ::HubSsoLib::Server::Runner.run
+    end
 
-      @@hub_session_factory = HubSsoLib::SessionFactory.new
-      DRb.start_service(HUB_CONNECTION_URI, @@hub_session_factory, { :safe_level => 1 })
-      DRb.thread.join
+    class Runner
+      QUEUE = ::Queue.new
 
-    rescue => e
-      Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
-      raise
-    end
+      def self.run
+        puts "Server: Starting at #{ HUB_CONNECTION_URI }" if ENV['HUB_QUIET_SERVER'].nil?
+
+        @@hub_session_factory = HubSsoLib::SessionFactory.new
+
+        Signal.trap('INT' ) { QUEUE << :INT  }
+        Signal.trap('TERM') { QUEUE << :TERM }
+
+        DRb.start_service(HUB_CONNECTION_URI, @@hub_session_factory, { :safe_level => 1 })
+
+        QUEUE.pop
+
+        self.shutdown()
+        exit
+
+      rescue => e
+        Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
+        raise
+      end
+
+      def self.shutdown
+        puts "Server: Graceful shutdown..."
+
+        @@hub_session_factory.dump_sessions!
+        DRb.stop_service
+
+        puts "Server: ...completed."
+      end
+    end # Runner class
   end # Server module
 
   #######################################################################
@@ -689,6 +863,18 @@ module HubSsoLib
       user        = hub_session&.session_user
 
       return (user&.user_id.nil? ? nil : user)
+
+    rescue Exception => e
+
+      # At this point there tends to be no Session data, so we're going to have
+      # to encode the exception data into the URI... It must be escaped twice,
+      # as many servers treat "%2F" in a URI as a "/". Apache can then fail to
+      # serve the page, raising a 404 error unless "AllowEncodedSlashes on" is
+      # specified in its configuration.
+      #
+      suffix   = '/' + CGI::escape(CGI::escape(hubssolib_set_exception_data(e)))
+      new_path = HUB_PATH_PREFIX + '/tasks/service'
+      redirect_to(new_path + suffix) unless request.path.include?(new_path)
     end
 
     # Sets the currently signed in user. Note that although this works and is
@@ -701,13 +887,6 @@ module HubSsoLib
       if user.nil?
         self.hubssolib_destroy_session!
       else
-
-        # Stale sessions may exist for this user. The frequency of logins is
-        # very low compared to frequency of page requests, so we perform this
-        # expensive method here as a least-worst option!
-        #
-        hubssolib_factory().destroy_sessions_by_user_id(user.user_id)
-
         hub_session = self.hubssolib_create_session()
         hub_session.session_user = user
       end
@@ -865,6 +1044,80 @@ module HubSsoLib
       user ? "#{user.user_real_name} (#{user.user_id})" : 'Anonymous'
     end
 
+    # WARNING: Slow.
+    #
+    # Return an Array of HubSsoLib::User objects for all logged-in users, in an
+    # array. If a user is logged into more than one browser and thus has more
+    # than one session active, they will accordingly appear more than once in
+    # the returned data. This can also happen if a user loses key rotation and
+    # leaves an old, but not yet expired session behind when they log in anew.
+    #
+    # In accordance with HubSsoLib::SessionFactory#enumerate_hub_session_ids
+    # documentation, a maximum of HUB_SESSION_ENUMERATION_KEY_MAX users can be
+    # returned here. If this is exceeded, an *empty* array is returned. If you
+    # are processing this information for display in a UI which itself requires
+    # a logged in user of some sort (which is very likely) and therefore know
+    # that at least *one* session does exist, you can treat an empty array as
+    # confirmation of "lots of sessions". If you can't be sure of at least one
+    # logged in user, then there is obvious arising ambiguity and this method
+    # does not solve it for you - it's just "zero, or very many users".
+    #
+    # Users are ordered by least-recently-active first, most-recent last.
+    #
+    # For information about performance limitations, see
+    # HubSsoLib::SessionFactory#enumerate_hub_session_ids.
+    #
+    def hubssolib_enumerate_users
+      hub_session_info = hubssolib_factory().enumerate_hub_session_ids()
+      hub_users        = []
+
+      unless hub_session_info[:keys].nil? # (keyset too large, enumeration prohibited)
+        hub_session_info[:keys].each do | key |
+          session = hubssolib_factory().retrieve_session_by_key(key)
+          hub_users << session.session_user unless session&.session_user&.user_id.nil?
+        end
+      end
+
+      return hub_users
+    end
+
+    # WARNING: Comparatively slow.
+    #
+    # For a given HubSsoLib::User's user ID, return any known sessions held by
+    # the DRb server, as an Hash of session keys with HubSsoLib::Session
+    # instances as values.
+    #
+    # Returns an empty Hash if the given ID is +nil+.
+    #
+    # Note that Hub sessions can disappear at any moment, so the session keys
+    # you find in the Hash might refer to extinct sessions by the time you get
+    # to do something with them. You can still access the data, but if you were
+    # to try and ask the DRb server for that key, it'd return +nil+.
+    #
+    # Sessions are ordered by least-recently-active first, most-recent last.
+    #
+    # For information about performance limitations, see
+    # HubSsoLib::SessionFactory#retrieve_sessions_by_user_id.
+    #
+    def hubssolib_retrieve_user_sessions(hub_user_id)
+      if hub_user_id.nil?
+        {}
+      else
+        hubssolib_factory().retrieve_sessions_by_user_id(hub_user_id)
+      end
+    end
+
+    # WARNING: Comparatively slow.
+    #
+    # Remove all sessions under a given ID.
+    #
+    # For information about performance limitations, see
+    # HubSsoLib::SessionFactory#destroy_sessions_by_user_id.
+    #
+    def hubssolib_destroy_user_sessions(hub_user_id)
+      hubssolib_factory().destroy_sessions_by_user_id(hub_user_id) unless hub_user_id.nil?
+    end
+
     # If an application needs to know about changes of a user e-mail address
     # or display name (e.g. because of sync to a local relational store of
     # users related to other application-managed resources, with therefore a
@@ -1052,18 +1305,17 @@ module HubSsoLib
     # We can return to this location by calling #redirect_back_or_default.
     #
     def hubssolib_store_location(uri_str = request.url)
-
       if (uri_str && !uri_str.empty?)
         uri_str = hubssolib_promote_uri_to_ssl(uri_str, request.host) unless request.ssl?
         hubssolib_set_return_to(uri_str)
       else
         hubssolib_set_return_to(nil)
       end
-
     end
 
     # Redirect to the URI stored by the most recent store_location call or
     # to the passed default.
+    #
     def hubssolib_redirect_back_or_default(default)
       url = hubssolib_get_return_to()
       hubssolib_set_return_to(nil)
@@ -1075,7 +1327,7 @@ module HubSsoLib
     # sets the host you provide (or leaves it alone if you omit the
     # parameter), then forces the scheme to 'https'. Returns the result
     # as a flat string.
-
+    #
     def hubssolib_promote_uri_to_ssl(uri_str, host = nil)
       uri = URI.parse(uri_str)
       uri.host = host if host
@@ -1231,7 +1483,7 @@ module HubSsoLib
       self.hubssolib_destroy_session! unless old_session.nil?
 
       start_key          = SecureRandom.uuid
-      @hubssolib_session = hubssolib_factory().get_hub_session_proxy(start_key, request.remote_ip)
+      @hubssolib_session = hubssolib_factory().get_hub_session_proxy(start_key, create: true)
 
       # The session is now stored under the rotated key, so put that into the
       # Hub session cookie so that on the next request, we can retrieve the
@@ -1263,10 +1515,12 @@ module HubSsoLib
       if @hubssolib_session.nil?
         key = cookies[HUB_COOKIE_NAME]
 
-        if key.nil? || key == ''
+        # See #hubssolib_create_session - valid keys are 36-char UUIDs
+        #
+        if key.nil? || key.size != 36
           @hubssolib_session = nil
         else
-          hub_session = hubssolib_factory().get_hub_session_proxy(key, request.remote_ip)
+          hub_session = hubssolib_factory().get_hub_session_proxy(key, create: false)
 
           if hub_session.nil? # Invalid key in cookie
             @hubssolib_session = nil
@@ -1326,13 +1580,14 @@ module HubSsoLib
     # halted (since the overall return value is therefore 'false').
     #
     def hubssolib_must_login
+
       # If HTTP, redirect to the same place, but HTTPS. Then we can store the
       # flash and return-to in the session data. We'll have the same set of
       # before-filter operations running and they'll find out we're either
       # authorised after all, or come back to this very function, which will
       # now be happily running from an HTTPS connection and will go on to set
       # the flash and redirect to the login page.
-
+      #
       if hubssolib_ensure_https
         hubssolib_set_flash(:alert, 'You must log in before you can continue.')
         redirect_to HUB_PATH_PREFIX + '/account/login'
@@ -1394,47 +1649,6 @@ module HubSsoLib
       )
     end
 
-    # Return an array of Hub User objects representing users based on a list of
-    # known sessions returned by the DRb server. Note that if an application
-    # exposes this method to a view, it is up to the application to ensure
-    # sufficient access permission protection for that view according to the
-    # webmaster's choice of site security level. Generally, normal users should
-    # not be allowed access!
-    #
-    # Due to the session pool being held in the DRb server and subject to
-    # alteration at any time by other requests (assuming the server supports
-    # more than just one request at a time, that is!) then the session data
-    # must be copied locally before iterating. Otherwise, exceptions arise from
-    # attempts to alter an under-iteration Hash. This in turn raises a worry
-    # about RAM usage. For that reason, a (somewhat arbitrary) limit of
-    # 2000 active users is applied. More than that and the method returns an
-    # empty array.
-    #
-    def hubssolib_enumerate_users
-      hub_session_data = hubssolib_factory().enumerate_hub_sessions()
-      return [] if hub_session_data.keys.size > 2000 # NOTE EARLY EXIT
-
-      sessions = hub_session_data.values.dup
-      users    = sessions.inject( [] ) do | memo, session |
-        user = session.session_user
-        memo << user unless user&.user_id.nil?
-        memo
-      end
-
-      return users
-
-    rescue Exception => e
-
-      # At this point there tends to be no Session data, so we're
-      # going to have to encode the exception data into the URI...
-      # See earlier for double-escaping rationale.
-
-      suffix   = '/' + CGI::escape(CGI::escape(hubssolib_set_exception_data(e)))
-      new_path = HUB_PATH_PREFIX + '/tasks/service'
-      redirect_to new_path + suffix unless request.path.include?(new_path)
-      return nil
-    end
-
     # Encode exception data into a string suitable for using in a URL
     # if CGI escaped first. Pass the exception object; stores only the
     # message.

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: hubssolib
 version: !ruby/object:Gem::Version
-  version: 3.4.0
+  version: 3.6.0
 platform: ruby
 authors:
 - Andrew Hodgkinson and others
 bindir: bin
 cert_chain: []
-date: 2025-03-24 00:00:00.000000000 Z
+date: 2025-03-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: drb