hubssolib 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59532e45ebc82569e9f43aab07611c7092c5cf8f140db8bc08a6b98043d7e500
-  data.tar.gz: 0e59ad5183becc64d8ff59b71062eec2b18c77b916f4030053010214ae8e6289
+  metadata.gz: c6df4bbfdb7389a9ae74fd974f9aec00f80caccf38a9702514bea230563c8abf
+  data.tar.gz: 6714640777624dc0a90744f125218375c42ff322401bcf65dc2d730df2de4a0c
 SHA512:
-  metadata.gz: f046c3981c7749598f57e68a4db7fd6528c1d97e74bb4fe437fc4a72c31ceb011eb4a7c8f4cd59a820b0d14ee18e5947da533b987b2a73f91101582c6e4e1286
-  data.tar.gz: e3389646a064fd1e077ea4b5649d7d984b723933643003974134dd02c0f718ee063ea523b24a369b328a04ffcff9fd5cc3842f3bd9e5510f44fbe60a3af878a3
+  metadata.gz: 52375b875cda94de7b2823a1b718a5588f27c0c093d4f0010373670ffc4b54da4c5211e627719a56f10179cb3a91b86403a31f955b07348f7bfdaa25906de410
+  data.tar.gz: 5ef7b400a85299a3925994bba59d8c6ff1b1ded612541affd288413955eee935971e7d0bb8e61855fef42955baa3b6b2331333b720de82f1cdfcfff0f4a5eb94

data/CHANGELOG.md

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

data/README.md

@@ -118,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 ]
 })
 ```
 
@@ -140,14 +140,15 @@ 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.
 
@@ -156,6 +157,44 @@ If you want to integrate Hub with an application which already has the concept o
 
 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.
@@ -178,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 ]
 })
 ```
 
@@ -191,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...
   })
 
@@ -199,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
 ```
 
@@ -212,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...

data/hubssolib.gemspec

@@ -4,7 +4,7 @@ spec = Gem::Specification.new do |s|
   s.platform = Gem::Platform::RUBY
   s.name     = 'hubssolib'
 
-  s.version  = '3.1.0'
+  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,6 +34,19 @@ 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'] || ''
@@ -710,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
 
@@ -794,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.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - Andrew Hodgkinson and others
 bindir: bin
 cert_chain: []
-date: 2025-02-14 00:00:00.000000000 Z
+date: 2025-02-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: drb