hubssolib 3.3.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b434d369e25dc81a74c87385df70cade7dfd40c47abfae2c05732b471b6e1f5e
-  data.tar.gz: 41d2303f125f52a5f957f851f1a8d5ae7067ab8233fcfa5359640f88e3bceb06
+  metadata.gz: 8fc6eb926595d43f0fe51803fb2dd817930adf4385a742461c13197c87ebd8a5
+  data.tar.gz: 3f532eca169d7497d595aeb15a31d47650ee13fd4973859041d40f66144217cc
 SHA512:
-  metadata.gz: 7dc3e04c0b1e75eecf504c61d19834151179666b7e601d974cbf74509f1ab1197bbf74cf347c63b4e1aef61d744bceb96621b7fccb8017654f6d4266eea21246
-  data.tar.gz: ba3e8e1985dd91185c6049e25212dcade4dfe064faf31c4e1c1d013ac8851984f3b48ee47df5de16d097863ea36c9165c93790e05703f8fa640908e7260c3b4b
+  metadata.gz: 1c645f57251251d560c8940d25aaaade1e98b83fe7cf8ab0dff194c3738bfb0c0e8699a1aed7c4889b656e7c0da81f005722773c1af52205eb233f7f9b7ef3dc
+  data.tar.gz: 6927b5bd57c5d5c7eddb65cb36c20fc89f24d6cf8ac1ad341da2feedf4ae6e12f452351416d089eb046214a4895d2e7becf7c098bb4c1cd0c011bf8eaafd36c2

data/CHANGELOG.md

@@ -1,3 +1,35 @@
+## 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:
+
+* ...are encouraged to change uses of `hubssolib_current_user = foo` over to `hubssolib_log_in()`
+* ...are likewise encouraged to change `hubssolib_current_user = nil` over to `hubssolib_log_out()`
+
+There are many fixes in the overhauled session management:
+
+* Session data is only stored when a user logs in, else no session cookie is built
+* If a user logs in, possible stale older sessions they might have are swept out
+* When the user logs out their session data is entirely deleted
+* The Hub app includes a Rake task that makes use of a new internal session factory feature to clean up sessions with a very old idle timeout (more than 3 times the usual in-app 'you were logged out' notification mechanism's delay via `HUB_IDLE_TIME_LIMIT`, or 2 days, whichever is larger) and delete such sessions - yes, this means that if a user did then come in even later on a now-deleted session ID, they'd simply be logged out without the warning message about why, but it was a serious oversight prior to allow the sessions to just accumulate.
+
+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.1.0)
+    hubssolib (3.4.0)
       base64 (~> 0.2)
       drb (~> 2.2)
 
@@ -29,7 +29,7 @@ GEM
     psych (5.2.3)
       date
       stringio
-    rdoc (6.12.0)
+    rdoc (6.13.0)
       psych (>= 4.0.0)
     reline (0.6.0)
       io-console (~> 0.5)
@@ -52,7 +52,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
-    stringio (3.1.3)
+    stringio (3.1.5)
 
 PLATFORMS
   ruby

data/README.md

@@ -202,6 +202,16 @@ The four arguments are guaranteed to be present and non-empty, with leading or t
 
 
 
+## Session maintenance
+
+User-idle session expiry is routinely handled in the "beforehand" callback so that we can see the session is valid but expired, expire it and add a via-flash warning about what happened so the user is fully informed. The Hub gem tries to be nice about `POST`, `PATCH` and `PUT` operations too and allows those to complete before the expected subsequent redirection `GET` causing expiry, to try and avoid users losing form submission data entirely.
+
+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
 
 The Hub component interfaces that should be used by application authors when integrating with the Hub single sign-on mechanism are described below. If you want a complete list of all public interfaces, consult the file `hub_sso_lib.rb` inside the Hub gem. All functions and classes therein are fully commented to describe the purpose of each class, along with the purpose, input parameters and return values of class methods and instance methods.

data/hubssolib.gemspec

@@ -4,7 +4,7 @@ spec = Gem::Specification.new do |s|
   s.platform = Gem::Platform::RUBY
   s.name     = 'hubssolib'
 
-  s.version  = '3.3.0'
+  s.version  = '3.5.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

@@ -20,8 +20,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 +36,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,13 +50,27 @@ 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'] || ''
 
-  # Time limit, *in seconds*, for the account inactivity timeout.
-  # If a user performs no Hub actions during this time they will
-  # be automatically logged out upon their next action.
+  # Time limit, *in seconds*, for the account inactivity timeout. If a user
+  # performs no Hub actions during this time they will be automatically logged
+  # out upon their next action, with a Flash message set to explain why.
   #
   HUB_IDLE_TIME_LIMIT = ENV['HUB_IDLE_TIME_LIMIT']&.to_i || 4 * 60 * 60
 
@@ -402,16 +419,16 @@ module HubSsoLib
     attr_accessor :session_return_to
     attr_accessor :session_flash
     attr_accessor :session_user
-    attr_accessor :session_key_rotation
+    attr_accessor :session_rotated_key
     attr_accessor :session_ip
 
     def initialize
-      @session_last_used    = Time.now.utc
-      @session_return_to    = nil
-      @session_flash        = {}
-      @session_user         = HubSsoLib::User.new
-      @session_key_rotation = nil
-      @session_ip           = nil
+      @session_last_used   = Time.now.utc
+      @session_return_to   = nil
+      @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)
@@ -423,8 +440,10 @@ module HubSsoLib
   # Class:   SessionFactory                                             #
   #          (C) Hipposoft 2006                                         #
   #                                                                     #
-  # Purpose: Build Session objects for DRb server clients. Maintains a  #
-  #          hash of Session objects.                                   #
+  # Purpose: Manage Session objects for DRb server clients. This class  #
+  #          implements the API exposed by the HubSsoLib::Server DRb    #
+  #          endpoint, so this is the remote object that clients will   #
+  #          be calling into.                                           #
   #                                                                     #
   # Author:  A.D.Hodgkinson                                             #
   #                                                                     #
@@ -436,7 +455,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.keys.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)
@@ -448,32 +493,42 @@ module HubSsoLib
     # recorded in existing session data.
     #
     # Whether new or pre-existing, the returned session will have changed key
-    # as a result of being read; check the #session_key_rotation property to
+    # as a result of being read; check the #session_rotated_key property to
     # find out the new key. If you fail to do this, you'll lose access to the
     # session data as you won't know which key it lies under.
     #
     # 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.
+    #               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.
     #
     # +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.
     #
-    def get_hub_session_proxy(key, remote_ip)
-      hub_session = @hub_sessions[key]
-      message     = hub_session.nil? ? 'Created' : 'Retrieving'
-      new_key     = SecureRandom.uuid
+    # In addition, the following optional named parameters can be given:
+    #
+    # +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, remote_ip, create: true)
+      hub_session = HUB_MUTEX.synchronize { @hub_sessions[key] }
+      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 "#{ message } session for key #{ key } and rotating to #{ new_key }"
+        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 "WARNING: IP address changed from #{ hub_session.session_ip } to #{ remote_ip } -> discarding session"
+          puts "Session factory: WARNING: IP address changed from #{ hub_session.session_ip } to #{ remote_ip } -> discarding session"
         end
 
         hub_session = nil
@@ -484,10 +539,12 @@ module HubSsoLib
         hub_session.session_ip = remote_ip
       end
 
-      @hub_sessions.delete(key)
-      @hub_sessions[new_key] = hub_session
+      HUB_MUTEX.synchronize do
+        @hub_sessions.delete(key)
+        @hub_sessions[new_key] = hub_session
+      end
 
-      hub_session.session_key_rotation = new_key
+      hub_session.session_rotated_key = new_key
       return hub_session
 
     rescue => e
@@ -495,6 +552,26 @@ module HubSsoLib
       raise
     end
 
+    # 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.
+    #
+    # 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.
+    #
+    # 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.
+    #
+    # See HubSsoLib::Core#hubssolib_enumerate_users for an example.
+    #
     def enumerate_hub_sessions()
       @hub_sessions
 
@@ -502,6 +579,121 @@ module HubSsoLib
       Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
       raise
     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.
+    #
+    def destroy_session_by_key(key)
+      HUB_MUTEX.synchronize do
+        @hub_sessions.delete(key)
+      end
+
+    rescue => e
+      Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
+      raise
+    end
+
+    # 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.
+    # Removes all sessions found for a given user ID.
+    #
+    # IN THE CURRENT IMPLEMENTATION THIS JUST SEQUENTIALLY SCANS ALL ACTIVE
+    # SESSIONS IN THE HASH and must therefore lock on mutex for the duration.
+    #
+    def destroy_sessions_by_user_id(user_id)
+      HUB_MUTEX.synchronize do
+        @hub_sessions.reject! do | key, session |
+          session&.session_user&.user_id == user_id
+        end
+      end
+
+    rescue => e
+      Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
+      raise
+    end
+
+    # 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
+    # HUB_IDLE_TIME_LIMIT, the session simply deleted. If a user does return
+    # later, they'll see themselves in logged out state without the Flash
+    # warning them of an expired session, but we can't allow session keys to
+    # just hang around forever so *some* kind of sweep is needed.
+    #
+    # This method clearly needs to iterate over all sessions under a mutex and
+    # makes relatively complex checks for each, so it's fairly slow compared
+    # to most methods. Call it infrequently; any and all other attempts to read
+    # 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..."
+      end
+
+      HUB_MUTEX.synchronize do
+        count_before = @hub_sessions.keys.size
+
+        @hub_sessions.reject! do | key, session |
+          last_used = session&.session_last_used
+          last_used.nil? || Time.now.utc - last_used > time_limit
+        end
+
+        count_after = @hub_sessions.keys.size
+        destroyed   = count_before - count_after
+      end
+
+      unless @hub_be_quiet
+        puts "Session factory: ...Destroyed #{destroyed} session(s)"
+      end
+
+    rescue => e
+      Sentry.capture_exception(e) if defined?(Sentry) && Sentry.respond_to?(:capture_exception)
+      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
 
   #######################################################################
@@ -522,16 +714,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
 
   #######################################################################
@@ -550,14 +767,58 @@ module HubSsoLib
 
   module Core
 
-    # Returns true or false if the user is logged in.
+    # Log in the user. This is just syntax sugar for setting the current user
+    # via #hubssolib_current_user, really. You can freely use either approach
+    # according to your preferred aesthetics, but this method is preferred.
+    #
+    # +user+:: A valid HubSsoLib::User instance. If this has a +nil+ value for
+    #          +user_id+, or if +user+ is itself +nil+, you'll cause the same
+    #          effect as if explicitly logging *out*.
+    #
+    def hubssolib_log_in(user)
+      self.hubssolib_current_user = user # (which deals with all related session and cookie consequences)
+    end
+
+    # Log out the user. Very few applications should ever need to call this,
+    # though Hub certainly does and it gets used internally too.
     #
-    # Preloads @hubssolib_current_user with user data if logged in.
+    def hubssolib_log_out
+      self.hubssolib_current_user = nil # (which deals with all related session and cookie consequences)
+    end
+
+    # Returns true or false if a user is logged in or not, respectively.
     #
     def hubssolib_logged_in?
       !!self.hubssolib_current_user
     end
 
+    # Accesses the current user, via the DRb server if necessary. Returns a
+    # HubSsoLib::User object, or +nil+ if none is available (this indicates
+    # that nobody is logged in, but #hubssolib_logged_in? should be used to
+    # check that, to allow for possible future more advanced logic within).
+    #
+    def hubssolib_current_user
+      hub_session = self.hubssolib_get_session()
+      user        = hub_session&.session_user
+
+      return (user&.user_id.nil? ? nil : user)
+    end
+
+    # Sets the currently signed in user. Note that although this works and is
+    # maintained, it is recommended that #hubssolib_log_in gets called instead.
+    #
+    # +user+:: A valid HubSsoLib::User. This will replace any existing logged
+    #          in user. If there is no session yet, one will be created.
+    #
+    def hubssolib_current_user=(user)
+      if user.nil?
+        self.hubssolib_destroy_session!
+      else
+        hub_session = self.hubssolib_create_session()
+        hub_session.session_user = user
+      end
+    end
+
     # Returns markup for a link that leads to Hub's conditional login endpoint,
     # inline-styled as a red "Log in" or green "Account" button. This can be
     # used in page templates to avoid needing any additional images or other
@@ -570,7 +831,6 @@ module HubSsoLib
     #
     def hubssolib_account_link
       logged_in        = self.hubssolib_logged_in?()
-
       ui_href          = "#{HUB_PATH_PREFIX}/account/login_conditional"
       noscript_img_src = "#{HUB_PATH_PREFIX}/account/login_indication.png"
       noscript_img_tag = helpers.image_tag(noscript_img_src, size: '90x22', border: '0', alt: 'Log in or out')
@@ -667,51 +927,12 @@ module HubSsoLib
       return (puser && !puser.empty? && puser != pnormal)
     end
 
-    # Log out the user. Very few applications should ever need to call this,
-    # though Hub certainly does and it gets used internally too.
-    #
-    def hubssolib_log_out
-      # Causes the "hubssolib_current_[foo]=" methods to run, which
-      # deal with everything else.
-      self.hubssolib_current_user = nil
-      @hubssolib_current_session_proxy = nil
-    end
-
-    # Accesses the current session from the cookie. Creates a new session
-    # object if need be, but can return +nil+ if e.g. attempting to access
-    # session cookie data without SSL.
-    #
-    def hubssolib_current_session
-      @hubssolib_current_session_proxy ||= hubssolib_get_session_proxy()
-    end
-
-    # Accesses the current user, via the DRb server if necessary.
-    #
-    def hubssolib_current_user
-      hub_session = self.hubssolib_current_session
-      user        = hub_session.nil? ? nil : hub_session.session_user
-
-      if (user && user.user_id)
-        return user
-      else
-        return nil
-      end
-    end
-
-    # Store the given user data in the cookie
-    #
-    def hubssolib_current_user=(user)
-      hub_session = self.hubssolib_current_session
-      hub_session.session_user = user unless hub_session.nil?
-    end
-
     # Public read-only accessor methods for common user activities:
     # return the current user's roles as a Roles object, or nil if
     # there's no user.
     #
     def hubssolib_get_user_roles
-      user = self.hubssolib_current_user
-      user ? user.user_roles.to_authenticated_roles : nil
+      self.hubssolib_current_user&.user_roles&.to_authenticated_roles
     end
 
     # Public read-only accessor methods for common user activities:
@@ -719,8 +940,7 @@ module HubSsoLib
     # no user. See also hubssolib_unique_name.
     #
     def hubssolib_get_user_name
-      user = self.hubssolib_current_user
-      user ? user.user_real_name : nil
+      self.hubssolib_current_user&.user_real_name
     end
 
     # Public read-only accessor methods for common user activities:
@@ -728,8 +948,7 @@ module HubSsoLib
     # nil if there's no user. See also hubssolib_unique_name.
     #
     def hubssolib_get_user_id
-      user = self.hubssolib_current_user
-      user ? user.user_id : nil
+      self.hubssolib_current_user&.user_id
     end
 
     # Public read-only accessor methods for common user activities:
@@ -737,8 +956,7 @@ module HubSsoLib
     # no user.
     #
     def hubssolib_get_user_address
-      user = self.hubssolib_current_user
-      user ? user.user_email : nil
+      self.hubssolib_current_user&.user_email
     end
 
     # Return a human-readable unique ID for a user. We don't want to
@@ -863,15 +1081,13 @@ module HubSsoLib
         cookies.delete(HUB_LOGIN_INDICATOR_COOKIE, domain: :all, path: '/')
 
         if login_is_required
-          hubssolib_store_location
-          return hubssolib_must_login
+          hubssolib_store_location()
+          return hubssolib_must_login()
         else
           return true
         end
       end
 
-      # Definitely logged in.
-      #
       cookies[HUB_LOGIN_INDICATOR_COOKIE] = {
         value:    HUB_LOGIN_INDICATOR_COOKIE_VALUE,
         path:     '/',
@@ -892,8 +1108,8 @@ module HubSsoLib
         # if OK, else indicate that access is denied.
 
         if (hubssolib_session_expired?)
-          hubssolib_store_location
-          hubssolib_log_out
+          hubssolib_store_location()
+          hubssolib_log_out()
           hubssolib_set_flash(:attention, 'Sorry, your session timed out; you need to log in again to continue.')
 
           # We mean this: redirect_to :controller => 'account', :action => 'login'
@@ -902,7 +1118,7 @@ module HubSsoLib
           redirect_to HUB_PATH_PREFIX + '/account/login'
         else
           hubssolib_set_last_used(Time.now.utc)
-          return hubssolib_authorized? ? true : hubssolib_access_denied
+          return hubssolib_authorized? ? true : hubssolib_access_denied()
         end
 
       else
@@ -955,7 +1171,7 @@ module HubSsoLib
     # 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
+      url = hubssolib_get_return_to()
       hubssolib_set_return_to(nil)
 
       redirect_to(url || default)
@@ -987,26 +1203,29 @@ module HubSsoLib
       end
     end
 
-    # Public methods to set some data that would normally go in @session,
-    # but can't because it needs to be accessed across applications. It is
-    # put in an insecure support cookie instead. There are some related
-    # private methods for things like session expiry too.
+    # Flash data can be carried across the Hub session, stored in the DRb
+    # server as a result, and is thus cleared automatically if a session gets
+    # dropped. However, we also want this to work without being logged in, so
+    # in that case it uses the normal flash as a backup when *writing*.
     #
-    def hubssolib_get_flash()
-      f = self.hubssolib_current_session ? self.hubssolib_current_session.session_flash : nil
-      return f || {}
+    def hubssolib_get_flash
+      session = self.hubssolib_get_session()
+      session&.session_flash || {}
     end
 
     def hubssolib_set_flash(symbol, message)
-      return unless self.hubssolib_current_session
-      f = hubssolib_get_flash
-      f[symbol.to_s] = message
-      self.hubssolib_current_session.session_flash = f
+      session = self.hubssolib_get_session()
+      f       = hubssolib_get_flash() unless session.nil?
+      f       = self.flash if f.nil? && self.respond_to?(:flash)
+
+      f[symbol] = message
+
+      session.session_flash = f unless session.nil?
     end
 
     def hubssolib_clear_flash
-      return unless self.hubssolib_current_session
-      self.hubssolib_current_session.session_flash = {}
+      session = self.hubssolib_get_session()
+      session.session_flash = {} unless session.nil?
     end
 
     # Return flash data for known keys, then all remaining keys, from both
@@ -1063,21 +1282,22 @@ module HubSsoLib
       hubssolib_get_exception_data(CGI::unescape(id_data))
     end
 
-    # Inclusion hook to make various methods available as ActionView
-    # helper methods.
+    # Inclusion hook to make various methods available as ActionView helpers.
     #
     def self.included(base)
-      base.send :helper_method,
-                :hubssolib_current_user,
-                :hubssolib_unique_name,
-                :hubssolib_logged_in?,
-                :hubssolib_account_link,
-                :hubssolib_authorized?,
-                :hubssolib_privileged?,
-                :hubssolib_flash_data
-    rescue
-      # We're not always included in controllers...
-      nil
+      if base.respond_to?(:helper_method)
+        base.send(
+          :helper_method,
+
+          :hubssolib_current_user,
+          :hubssolib_unique_name,
+          :hubssolib_logged_in?,
+          :hubssolib_authorized?,
+          :hubssolib_privileged?,
+          :hubssolib_account_link,
+          :hubssolib_flash_data
+        )
+      end
     end
 
   private
@@ -1104,6 +1324,110 @@ module HubSsoLib
       HUB_BYPASS_SSL || ! Rails.env.production?
     end
 
+    # Create a new session. This MUST ONLY BE CALLED at a "log in" phase, since
+    # it discards any existing session and creates a new, valid one, whether or
+    # not a valid session key was being presented for the old session. It is,
+    # in essence, a "clean slate" start.
+    #
+    # On exit, @hubssolib_session is updated; see #hubssolib_get_session for
+    # the significance of that.
+    #
+    def hubssolib_create_session
+      old_session = self.hubssolib_get_session()
+      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, 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
+      # session data (and at that time, once again rotate the key).
+      #
+      next_key = @hubssolib_session.session_rotated_key
+      self.hubssolib_store_key(next_key)
+
+      return @hubssolib_session
+    end
+
+    # Gets session data based on the current +request+ details.
+    #
+    # * If there is no session cookie, returns +nil+
+    # * If there is a session cookie but the session key is invalid, returns
+    #   +nil+.
+    # * If there is a session cookie with valid key, session data is retrieved
+    #   and returned; the session key is rotated and the session cookie updated
+    #   with new key (that is to say that this request's response, under normal
+    #   conditions, will include an appropriate Set-Cookie header).
+    #
+    # The ivar @hubssolib_session is consulted first to avoid repeating work
+    # during request processing, where it's likely that more than one call
+    # will occur. This ivar is an known internal implementation detail; it is
+    # also set by #hubssolib_create_session, and is cleared by calls to
+    # #hubssolib_destroy_session!.
+    #
+    def hubssolib_get_session
+      if @hubssolib_session.nil?
+        key = cookies[HUB_COOKIE_NAME]
+
+        # 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, create: false)
+
+          if hub_session.nil? # Invalid key in cookie
+            @hubssolib_session = nil
+          else
+            @hubssolib_session = hub_session
+
+            next_key = @hubssolib_session.session_rotated_key
+            self.hubssolib_store_key(next_key)
+          end
+        end
+      end
+
+      return @hubssolib_session
+    end
+
+    # Destroys the current session. If there isn't one, then it has few side
+    # effects other than making sure all session-related cookies are deleted.
+    #
+    def hubssolib_destroy_session!
+      session = self.hubssolib_get_session()
+
+      # Remember, if creating or retrieving a session for a request, the key is
+      # rotated and stored in the session under #session_rotated_key. To delete
+      # that session within that same request - since rotation happens even if
+      # the first place the session gets read is right here, in this method -
+      # we must use the rotated key.
+      #
+      unless session.nil?
+        hubssolib_factory().destroy_session_by_key(session.session_rotated_key)
+      end
+
+      @hubssolib_session = nil
+
+      cookies.delete(HUB_COOKIE_NAME,            domain: :all, path: '/')
+      cookies.delete(HUB_LOGIN_INDICATOR_COOKIE, domain: :all, path: '/')
+    end
+
+    # Store the Hub's session key in the Hub cookie.
+    #
+    # +key+:: Session key used to retrieve the session again on the *next*
+    #         request. The session has already been stored under that new key
+    #         internally. Do not call with +nil+ or blank keys.
+    #
+    def hubssolib_store_key(key)
+      cookies[HUB_COOKIE_NAME] = {
+        value:    key,
+        path:     '/',
+        domain:   :all,
+        secure:   ! hub_bypass_ssl?,
+        httponly: true
+      }
+    end
+
     # Indicate that the user must log in to complete their request.
     # Returns false to enable a before_filter to return through this
     # method while ensuring that the previous action processing is
@@ -1164,64 +1488,45 @@ module HubSsoLib
       # have not logged out anyway, and the Hub isn't intended for Fort Knox.
       # At the time of writing the trade-off of usability vs security is
       # considered acceptable, though who knows, the view may change in future.
+      #
+      # Same applies for PATCH and PUT.
+      #
+      last_used = self.hubssolib_get_last_used
 
-      last_used = hubssolib_get_last_used
-      (request.method != :post && last_used && Time.now.utc - last_used > HUB_IDLE_TIME_LIMIT)
-    end
-
-    def hubssolib_get_session_proxy
-      # If we're not using SSL, forget it
-      return nil unless request.ssl? || hub_bypass_ssl?
-
-      key         = cookies[HUB_COOKIE_NAME] || SecureRandom.uuid
-      hub_session = hubssolib_factory().get_hub_session_proxy(key, request.remote_ip)
-      key         = hub_session.session_key_rotation unless hub_session.nil?
-
-      cookies[HUB_COOKIE_NAME] = {
-        value:    key,
-        path:     '/',
-        domain:   :all,
-        secure:   ! hub_bypass_ssl?,
-        httponly: true
-      }
-
-      return hub_session
-
-    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 "/" and Apache may flat refuse 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)
-
-      return nil
-    end
+      (
+        request.method != :post  &&
+        request.method != :patch &&
+        request.method != :put   &&
 
-    def hubssolib_set_session_data(session)
-      # Nothing to do presently - DRb handles everything
+        last_used && Time.now.utc - last_used > HUB_IDLE_TIME_LIMIT
+      )
     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.
+    # 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
-      sessions = hubssolib_factory().enumerate_hub_sessions()
-      users    = []
-
-      sessions.each do |key, value|
-        user = value.session_user
-        users.push(user) if (user && user.respond_to?(:user_id) && user.user_id)
+      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
@@ -1263,23 +1568,21 @@ module HubSsoLib
     # the session data is available, else return default values.
 
     def hubssolib_get_last_used
-      session = self.hubssolib_current_session
-      session ? session.session_last_used : Time.now.utc
+      self.hubssolib_get_session()&.session_last_used || Time.now.utc
     end
 
     def hubssolib_set_last_used(time)
-      return unless self.hubssolib_current_session
-      self.hubssolib_current_session.session_last_used = time
+      session = self.hubssolib_get_session()
+      session.session_last_used = time unless session.nil?
     end
 
     def hubssolib_get_return_to
-      session = self.hubssolib_current_session
-      session ? session.session_return_to : nil
+      self.hubssolib_get_session()&.session_return_to
     end
 
     def hubssolib_set_return_to(uri)
-      return unless self.hubssolib_current_session
-      self.hubssolib_current_session.session_return_to = uri
+      session = self.hubssolib_get_session()
+      session.session_return_to = uri unless session.nil?
     end
 
   end # Core module

metadata

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