hubssolib 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c1a83a70b87a6c3cabd8bbb821dfc06ee467d382c9593cb7c1733152e136f5a1
-  data.tar.gz: 87f1dda92220f25326c8bbce597ecd97e74c3dd7e22fd0fbf89bfed6269b6b23
+  metadata.gz: 8fc6eb926595d43f0fe51803fb2dd817930adf4385a742461c13197c87ebd8a5
+  data.tar.gz: 3f532eca169d7497d595aeb15a31d47650ee13fd4973859041d40f66144217cc
 SHA512:
-  metadata.gz: cf2ae3afb91a4fcc3391cf4b156e3dd9e4d0be4cecafc10204cf6dc8a7d6b9d07d51dc08cd7fd22ee12a478025d03730227fa2602a194d4b0e6785d72af21295
-  data.tar.gz: 6ac8d8a0a1920d7f93604204ef0c254a094bd4a8559110bba2f630c1fe406f87966b0ba2289d017a9a48e90cd0d6e2eab0e1ae3872032c7bad389942965fe2b2
+  metadata.gz: 1c645f57251251d560c8940d25aaaade1e98b83fe7cf8ab0dff194c3738bfb0c0e8699a1aed7c4889b656e7c0da81f005722773c1af52205eb233f7f9b7ef3dc
+  data.tar.gz: 6927b5bd57c5d5c7eddb65cb36c20fc89f24d6cf8ac1ad341da2feedf4ae6e12f452351416d089eb046214a4895d2e7becf7c098bb4c1cd0c011bf8eaafd36c2

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+## 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:

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.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,6 +50,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'] || ''
@@ -438,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)
@@ -457,17 +500,27 @@ 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.
+    #               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)
+    # 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] }
-      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 }"
@@ -606,6 +659,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 +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
 
   #######################################################################
@@ -701,13 +814,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
@@ -1231,7 +1337,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, 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
@@ -1263,10 +1369,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, request.remote_ip, create: false)
 
           if hub_session.nil? # Invalid key in cookie
             @hubssolib_session = nil

metadata

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