hubssolib 3.0.3 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 891c5bc596ecfdd5f9f1e9b844ac77eaa443426607d55ba16110cc194baca3a8
-  data.tar.gz: 42ffee7f098f4c9cbd1eec9e42e2c0f2e10a700ebd85b083113b517cd6706619
+  metadata.gz: c6df4bbfdb7389a9ae74fd974f9aec00f80caccf38a9702514bea230563c8abf
+  data.tar.gz: 6714640777624dc0a90744f125218375c42ff322401bcf65dc2d730df2de4a0c
 SHA512:
-  metadata.gz: 7d0046239b22405b6e6cf47d3e8e326bcc9f4c88a58ced4b13a3eab14fd822bb16bc63d3b06523a926abda7d46d53a15211000fdd9b7aff7e071ba2b708afd92
-  data.tar.gz: 0a1cd9ccaab6b08ae323ad572f3a563fa002c7a2250073cb0b76848f8f2c8879350828664fe37ee9a0590d134a8949dacb4419a54520569a3468d6a5b86eb3da
+  metadata.gz: 52375b875cda94de7b2823a1b718a5588f27c0c093d4f0010373670ffc4b54da4c5211e627719a56f10179cb3a91b86403a31f955b07348f7bfdaa25906de410
+  data.tar.gz: 5ef7b400a85299a3925994bba59d8c6ff1b1ded612541affd288413955eee935971e7d0bb8e61855fef42955baa3b6b2331333b720de82f1cdfcfff0f4a5eb94

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 3.2.0, 15-Feb-2025
+
+Introduces the user change handler mechanism, a scheme whereby an external application tells Hub about a Rake task that the application has implemented, through which Hub can inform if of changes to a user's e-mail address or "real" name. See the gem's `README.md` for details, under "Applications with an existing user model".
+
+## 3.1.0, 14-Feb-2025
+
+Environment variable `HUB_IDLE_TIME_LIMIT` can be used to override the idle timeout, with a value expressed in seconds. It must be set in the environment of any application using Hub, including the Hub application itself.
+
 ## 3.0.3, 10-Feb-2025
 
 Change JavaScript code used for the login indicator so that simpler engines such as [Duktape](https://duktape.org) can run it. Operates correctly in script-enabled [NetSurf](https://www.netsurf-browser.org) now.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    hubssolib (3.0.3)
+    hubssolib (3.1.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.5.1)
+    diff-lcs (1.6.0)
     docile (1.4.1)
     doggo (1.4.0)
       rspec-core (~> 3.13)
@@ -52,7 +52,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.1)
     simplecov_json_formatter (0.1.4)
-    stringio (3.1.2)
+    stringio (3.1.3)
 
 PLATFORMS
   ruby

data/README.md

@@ -48,13 +48,15 @@ Finally you can install the Hub application using whatever mechanism you prefer
 
 Some configuration is needed using externally set environment variables. These are actually picked up by the Hub gem but you won't know what values to set until the application, DRb server and gem are all installed.
 
-*   `HUB_CONNECTION_URI` — as already discussed, this holds a DRb URI giving the connection socket on which the server listens and to which clients connect; it defaults to `~/.hub_drb`.
-*   `HUB_PATH_PREFIX` — sometimes the Hub Gem redirects to various locations within the Hub application. If you have installed the application away from document root, specify the prefix to put onto redirection paths here (otherwise, provide an empty string). For example, when redirecting to the `account` controller's `login` method, the path used is `HUB_PATH_PREFIX + '/account/login'`.
-*   `HUB_BYPASS_SSL` - normally Hub sets cookies as secure-only in Production mode, requiring `https` fetches. This isn't enforced in e.g. development mode. If you want to allow insecure transport in Production, set `HUB_BYPASS_SSL` to `true`.
+* `HUB_CONNECTION_URI` — as already discussed, this holds a DRb URI giving the connection socket on which the server listens and to which clients connect; it defaults to `~/.hub_drb`.
+* `HUB_PATH_PREFIX` — sometimes the Hub Gem redirects to various locations within the Hub application. If you have installed the application away from document root, specify the prefix to put onto redirection paths here (otherwise, provide an empty string). For example, when redirecting to the `account` controller's `login` method, the path used is `HUB_PATH_PREFIX + '/account/login'`.
+* `HUB_BYPASS_SSL` - normally Hub sets cookies as secure-only in Production mode, requiring `https` fetches. This isn't enforced in e.g. development mode. If you want to allow insecure transport in Production, set `HUB_BYPASS_SSL` to `true`.
 
-Usually, these are set up in a Web server configuration file as part of launching an FCGI process to host the Hub application.
+Usually, these are set up in a Web server configuration file as part of launching an FCGI process to host the Hub application. Don't forget to set up the application's `database.yml` file in the usual fashion. use `rake db:migrate` to build the empty database structure.
 
-Don't forget to set up the application's `database.yml` file in the usual fashion. use `rake db:migrate` to build the empty database structure.
+Optional environment variables for configuration are:
+
+* `HUB_IDLE_TIME_LIMIT` - by default Hub applies a 4 hour session idle timeout. Override by setting this variable to a number **in seconds**. This must be set equally in the environment of **all applications using Hub** including Hub itself, since it is the "beforehand" callback that checks the idle timer; this can run at any time in any of your collection of Hub-integrated applications, depending on the part of your site with which the user next interacts.
 
 ## Cookies and domains
 
@@ -105,7 +107,7 @@ For full integration with Hub, particularly when it comes to showing or hiding t
 
 Applications with no concept of user log-in are easy to integrate with Hub. Applications with only the concept of logging in for administrative purposes are similarly easy, provided your administrators do not mind having to log in using the application's own administrative mechanisms (so you basically treat the application as if it has no existing user model).
 
-To integrate, add the Hub filters into `application.rb` just inside the definition of the `ApplicationController` class:
+To integrate, add the Hub callbacks into `application.rb` just inside the definition of the `ApplicationController` class:
 
 ```ruby
 # Hub single sign-on support.
@@ -116,20 +118,20 @@ before_action :hubssolib_beforehand
 after_action :hubssolib_afterwards</pre>
 ```
 
-Within any controller which has actions which you wish to protect with Hub login, define a variable `@@hubssolib_permissions` and provide an accessor method for it. I'll deal with the accessor method first; for a controller called `FooController`, add the following to `foo_controller.rb`:
+Within any controller which has actions which you wish to protect with Hub login, define a constant `HUBSSOLIB_PERMISSIONS` and provide an accessor method for it. I'll deal with the accessor method first; in any controller for which Hub is to guard access, add the following:
 
 ```ruby
-def FooController.hubssolib_permissions
-  @@hubssolib_permissions
+def self.hubssolib_permissions
+  HUBSSOLIB_PERMISSIONS
 end
 ```
 
 More details are provided [below](#permissions) but, in brief, to define the permissions variable you create an instance of `HubSsoLib::Permissions`. The constructor is passed a hash. The hash keys are symbolized names of the controller actions you want to protect. The hash values are an array of privileges required to access the action, from a choice of one or more of `:admin`, `:webmaster`, `:privileged` and `:normal`. These relate to the roles you can assign to accounts as Hub administrator. For example:
 
 ```ruby
-@@hubssolib_permissions = HubSsoLib::Permissions.new({
-  :show => [ :admin, :webmaster, :privileged, :normal ],
-  :edit => [ :admin, :webmaster ]
+HUBSSOLIB_PERMISSIONS = HubSsoLib::Permissions.new({
+  show: [ :admin, :webmaster, :privileged, :normal ],
+  edit: [ :admin, :webmaster ]
 })
 ```
 
@@ -138,22 +140,61 @@ In this example, any user can access the controller's `show` action but only use
 A user's role(s) must match at least one of the privileges in the array for a given action — so even if your account has an administrator role (and _only_ an administrator role), it won't be able to access a protected action unless `:admin` is included in the array given within the hash to the `HubSsoLib::Permissions` constructor. For example:
 
 ```ruby
-@@hubssolib_permissions = HubSsoLib::Permissions.new({
-  :weblist => [ :webmaster, :privileged ]
+HUBSSOLIB_PERMISSIONS = HubSsoLib::Permissions.new({
+  weblist: [ :webmaster, :privileged ]
 })
 ```
 
 Here, only accounts with the webmaster or privileged role associated can access the `weblist` action. If an account has only normal and/or administrative roles, it won't be allowed through.
 
 ### Applications with an existing user model
+#### General concerns
 
 If you want to integrate Hub with an application which already has the concept of user accounts, logging in and logging out, there are two main approaches.
 
-*   Remove the existing mechanism and replace with Hub (see above). Removal may be through actually deleting code, models and filters related to that mechanism or simply removing or blocking access to the parts of the application that deal with the users and dropping in Hub equivalents over a minimum amount of code, reducing overall changes to the application but leaving a less clean result.
+*   Remove the existing mechanism and replace with Hub (see above). Removal may be through actually deleting code, models and callbacks related to that mechanism or simply removing or blocking access to the parts of the application that deal with the users and dropping in Hub equivalents over a minimum amount of code, reducing overall changes to the application but leaving a less clean result.
 *   Use a `before_action` in the application controller to run special code which you write, which maps a logged in Hub user to an existing application user. If the visitor is logged into Hub and no corresponding local application user account exists, one is created automatically based on the Hub account credentials.
 
 Neither approach is problem-free and both require quite a lot of effort and testing. Automated testing is very hard because the modified application's behaviour depends upon logging in or out of Hub, which is running elsewhere. Unfortunately Rails doesn't offer a universally supported single sign-on mechanism so applications all use different approaches to user management; this means that there is no magic bullet to integration with Hub. You have to learn and understand the structure of the application being integrated and be prepared to make changes that are potentially quite extensive.
 
+#### Synchronisation concerns, where applicable
+
+Some applications might use local User records for relational purposes. Suppose users could author Posts. We could simply freeze the author name with a Post using a column in that table. This means the author name of any Post is easy to display. However, if that author changed their name, only new Posts would show the new name. If the application wanted to answer a question such as, "List all Posts by a given author", it would be relatively expensive. And if an application wanted to internally keep a record of author e-mail addresses for things like e-mailed notifications of some kind, it would get worse; the author might change their e-mail address in Hub and the integrated application would not know.
+
+To solve these problems, external applications integrated with Hub can participate in the user change handler mechanism. The Hub-integrated external application calls `HubSsoLib::Core#hubssolib_register_user_change_handler` to register an interest in Hub user alterations. The mechanism invokes an application-defined Rake task, which can update user records however it sees fit. The method is given the application's name, it's Rails application root - the filesystem location of the application, since we need to use that as a current working directory to issue a `bundle exec rake your:task:name...` - and the name of the Rake task to run. Registration is usually done in `config/application.rb` - for example:
+
+```ruby
+module Foo
+  class Application < Rails::Application
+    require HubSsoLib::Core
+
+    hubssolib_register_user_change_handler(
+      app_name: Rails.application.name,
+      app_root: Rails.root,
+      task_name: 'hub:update_user'
+    )
+
+    # ...etc...
+  end
+end
+```
+
+The Rake task can have any name that works for your application. A "hub" namespace is recommended but entirely optional. If a Hub user edits their details, then the task is invoked with four positional parameters - the user's old e-mail address and old Hub unique name, as returned by `HubSsoLib::Core#hubssolib_unique_name` - followed by the new e-mail address and new unique name (at least one, or both of those will always have actually changed). The Rake task can then look up the external application's User record via the old address or unique name and, if found, update it. It should either throw an exception or `exit` with a non-zero status code if it fails to store the updated details - in that case, Hub will roll back user changes on its side and warn the end user.
+
+For example, `lib/tasks/hub.rake` might look like this:
+
+```ruby
+namespace :hub do
+  desc 'Update a user with details sent from Hub'
+  task :update_user, [:old_email, :old_name, :new_email, :new_name] => :environment do | t, args |
+    user = User.find_by_email_address(old_email)
+    user&.update!(email_address: new_email, display_name: new_name)
+  end
+end
+```
+
+
+
 ## 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.
@@ -176,9 +217,9 @@ Hub protects against access to actions in controller by using a `before_action`
 Permitted roles are expressed as single symbols or their equivalent strings, or an array containing many symbols or equivalent strings. Most often, an array of symbols is used. To create a permissions object, instantiate `HubSsoLib::Permissions`. For example:
 
 ```ruby
-@@hubssolib_permissions = HubSsoLib::Permissions.new({
-  :show => [ :admin, :webmaster, :privileged, :normal ],
-  :edit => [ :admin, :webmaster ]
+HUBSSOLIB_PERMISSIONS = HubSsoLib::Permissions.new({
+  show: [ :admin, :webmaster, :privileged, :normal ],
+  edit: [ :admin, :webmaster ]
 })
 ```
 
@@ -189,7 +230,7 @@ The above line of code typically appears at the start of the class definition fo
 ```ruby
 class AccountController < ApplicationController
 
-  @@hubssolib_permissions = HubSsoLib::Permissions.new({
+  HUBSSOLIB_PERMISSIONS = HubSsoLib::Permissions.new({
     # ...permissions here...
   })
 
@@ -197,11 +238,11 @@ class AccountController < ApplicationController
 end
 ```
 
-Having created the permissions object, you need to expose variable `@@hubssolib_permissions` to Hub in a way that it understands. To do this, create an instance method called `hubssolib_permissions` that just returns the variable:
+Having created the permissions object, you need to expose constant `HUBSSOLIB_PERMISSIONS` to Hub in a way that it understands. To do this, create a class method called `hubssolib_permissions` that just returns the variable:
 
 ```ruby
-  def AccountController.hubssolib_permissions
-    @@hubssolib_permissions
+  def self.hubssolib_permissions
+    HUBSSOLIB_PERMISSIONS
   end
 ```
 
@@ -210,12 +251,12 @@ So the full preamble in this example is:
 ```ruby
 class AccountController < ApplicationController
 
-  @@hubssolib_permissions = HubSsoLib::Permissions.new({
+  HUBSSOLIB_PERMISSIONS = HubSsoLib::Permissions.new({
     ...permissions here...
   })
 
-  def AccountController.hubssolib_permissions
-    @@hubssolib_permissions
+  def self.hubssolib_permissions
+    HUBSSOLIB_PERMISSIONS
   end
 
   ...existing class contents here...
@@ -247,7 +288,7 @@ Before any action in a Hub integrated application, `hubssolib_beforehand` must b
 before_action :hubssolib_beforehand
 ```
 
-The filter is the core of the Hub protection mechanism, making sure that no action can run unless the user is logged in (unless the action is completely protected) and their account is associated with at least one of the roles required to access the action.
+This callback is the core of the Hub protection mechanism, making sure that no action can run unless the user is logged in (unless the action is completely protected) and their account is associated with at least one of the roles required to access the action.
 
 #### The "after" action: `hubssolib_afterwards`
 
@@ -257,8 +298,6 @@ After any action in a Hub integrated application, `hubssolib_afterward` must be
 after_action :hubssolib_afterwards
 ```
 
-At the time of writing the filter does nothing, but is included to allow for future expansion and avoid API changes that might force application integrators to modify their code.
-
 #### Finding out about the current user
 
 Most Hub integration methods are geared around making it easy to find out about a currently logged in user.

data/hubssolib.gemspec

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

@@ -19,6 +19,7 @@ module HubSsoLib
 
   require 'drb'
   require 'securerandom'
+  require 'json'
 
   # DRb connection
   HUB_CONNECTION_URI = ENV['HUB_CONNECTION_URI'] || 'drbunix:' + File.join( ENV['HOME'] || '/', '/.hub_drb')
@@ -33,13 +34,28 @@ module HubSsoLib
     raise 'Exiting'
   end
 
+  # 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))
+    puts
+    puts '*' * 80
+    puts "Invalid path specified by HUB_COMMAND_REGISTRY (#{ HUB_COMMAND_REGISTRY.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.
-  HUB_IDLE_TIME_LIMIT = 4 * 60 * 60
+  #
+  HUB_IDLE_TIME_LIMIT = ENV['HUB_IDLE_TIME_LIMIT']&.to_i || 4 * 60 * 60
 
   # Shared cookie name.
   HUB_COOKIE_NAME = :hubapp_shared_id
@@ -708,9 +724,96 @@ module HubSsoLib
       user ? "#{user.user_real_name} (#{user.user_id})" : 'Anonymous'
     end
 
-    # Main filter method to implement HubSsoLib permissions management,
-    # session expiry and so-on. Call from controllers only, always as a
-    # before_fitler.
+    # 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
+    # desire to keep that store up to date), it can register a task to run
+    # on-change here. When a user edits their information, Hub runs through
+    # all such commands, allowing external applications to manage their own
+    # state with no need for coupled configuration or other duplication.
+    #
+    # The registered name must be a Rake task and the application must specify
+    # its location in the filesystem so that the PWD can be changed there, in
+    # order to execute the Rake task via "bundle exec". The task is passed the
+    # following parameters, in the specified order:
+    #
+    # - User's old e-mail address
+    # - User's old unique display name (as returned by #hubssolib_unique_name)
+    # - User's new e-mail address (which might be the same as the old)
+    # - User's old unique display name (which might be unchanged too)
+    #
+    # This is a newer Hub interface which uses named parameters rather than
+    # positional:
+    #
+    # +app_name+::  Application name, e.g. "beast"; make sure this is unique.
+    # +app_root+::  Application's Rails root, e.g. "/home/fred/rails/beast".
+    # +task_name+:: Rake task name, e.g. "hub:update_user".
+    #
+    # An example invocation in "config/application.rb" might look like this:
+    #
+    #     module Foo
+    #       class Application < Rails::Application
+    #         require HubSsoLib::Core
+    #
+    #         hubssolib_register_user_change_handler(
+    #           app_name:  Rails.application.name,
+    #           app_root:  Rails.root,
+    #           task_name: 'hub:update_user'
+    #         )
+    #
+    #         config.load_defaults 8.0 # ...etc...
+    #       end
+    #     end
+    #
+    def hubssolib_register_user_change_handler(app_name:, app_root:, task_name:)
+      File.open(HUB_COMMAND_REGISTRY, File::RDWR | File::CREAT) do |file|
+        file.flock(File::LOCK_EX)
+
+        commands_json   = file.read()
+        commands_hash   = (JSON.parse(commands_json) rescue nil) if commands_json.present?
+        commands_hash ||= {}
+
+        file.rewind()
+
+        commands_hash[app_name] = {
+          root: app_root,
+          task: task_name
+        }
+
+        file.write(JSON.fast_generate(commands_hash))
+        file.truncate(file.pos)
+      end
+    end
+
+    # Returns all change handlers registered by prior calls made to
+    # #hubssolib_register_user_change_handler. Returns a Hash, keyed by Rails
+    # application name, with values of another Hash:
+    #
+    # * +root+ => Rails application root
+    # * +task+ => Name of Rake task to be run
+    #
+    # All keys are Strings.
+    #
+    # This is usually called by the Hub application only, when it is processing
+    # a user's request to change their information.
+    #
+    def hubssolib_registered_user_change_handlers
+      commands_hash = {}
+
+      File.open(HUB_COMMAND_REGISTRY, File::RDWR | File::CREAT) do |file|
+        file.flock(File::LOCK_EX)
+
+        commands_json   = file.read()
+        commands_hash   = (JSON.parse(commands_json) rescue nil) if commands_json.present?
+        commands_hash ||= {}
+      end
+
+      return commands_hash
+    end
+
+    # Mandatory controller "before_action" callback method which activates
+    # HubSsoLib permissions management, session expiry and so-on. Usually
+    # invoked in ApplicationController.
     #
     def hubssolib_beforehand
 
@@ -792,7 +895,8 @@ module HubSsoLib
       end
     end
 
-    # Main after_filter method to tidy up after running state changes.
+    # Mandatory controller "after_action" callback method to tidy up after Hub
+    # actions during a request. Usually invoked in ApplicationController.
     #
     def hubssolib_afterwards
       begin

metadata

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