verikloak-audience 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 14464de9a3539e2ee4090afb4a1bc62b24f637bc7b8d272795592fe06f00f353
-  data.tar.gz: 1a2fb4b570a8396fba4733e0dd19f0bf984a5a5754c445d58e4f052abd1b3428
+  metadata.gz: 1ba5a1ca7162831839679e843f5def72fb8efeecb4b88e9cded4d6aa283c66a3
+  data.tar.gz: 4a4a71f5408b0b77cb63ffa9b5bc998a721de2083133234b1dfa2e96c4afb609
 SHA512:
-  metadata.gz: 26dba91989a702c379240bdc4190cae808b3a028994d3321c17d026bd116146e6b0157cebbbacf99f4f412a3311df8b4258df7070cf49b1ec8c9ebe9f2560413
-  data.tar.gz: 0bceb0d0575ec78727ac5aa179baeeeca0895646159f45e54e399d6a7a0dffc5cc6158f61f0c59585716b1a998a502c3ef09882c4a87d083e10a333371bed662
+  metadata.gz: d54e6ccb8c86555cb3c3821355912fc283e155fb103cdb7df5a0166e59163f9ea086ea1a7fcdbb7c7a82aa76b65b120d166379cfacd18fcff610bdb9fe4fc65a
+  data.tar.gz: c610ec408d85b8bd89b1a7f60d112731b3dbcaac696e66a993caa790c2ee5bb8c8b2f43227c87c681b3a1384fb59cca43e267ecd4a0f69f43f924187cc90f0ea

data/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.6] - 2025-09-23
+
+### Added
+- Rails generator `verikloak:audience:install` to create an initializer that inserts the audience middleware once the core Verikloak middleware is available.
+
+### Changed
+- Improved warning message when core Verikloak middleware is not present in the Rails middleware stack.
+- Enhanced middleware insertion logic to provide clearer guidance on setup requirements.
+
+## [0.2.5] - 2025-09-23
+
+### Changed
+- Use autoload for middleware to avoid circular require dependencies.
+- Improve module loading performance by deferring middleware class loading until accessed.
+
+### Added
+- Comprehensive test suite for standalone middleware require scenarios.
+- Test coverage for middleware functionality when loaded independently of main gem entrypoint.
+
 ## [0.2.4] - 2025-09-22
 
 ### Fixed

data/README.md

@@ -30,9 +30,17 @@ For the full error behaviour (response shapes, exception classes, logging hints)
 bundle add verikloak-audience
 ```
 
-## Rack / Rails usage
+In Rails applications, generate the initializer that automatically inserts the middleware:
 
-Insert **after** `Verikloak::Middleware`:
+```bash
+rails g verikloak:audience:install
+```
+
+This creates `config/initializers/verikloak_audience.rb` that will insert the audience middleware after the core Verikloak middleware once it's available.
+
+## Manual Rack / Rails setup
+
+Alternatively, you can manually insert **after** `Verikloak::Middleware`:
 
 ```ruby
 # config/application.rb

data/lib/generators/verikloak/audience/install/install_generator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+begin
+  require 'rails/generators'
+  require 'rails/generators/base'
+rescue LoadError
+  # Allow the generator to be required without Rails.
+end
+
+module Verikloak
+  module Audience
+    module Generators
+      # Installs the verikloak audience middleware configuration into a Rails
+      # application. This generator creates an initializer that inserts the
+      # audience middleware after the core Verikloak middleware once it is
+      # available.
+      class InstallGenerator < (defined?(Rails::Generators::Base) ? Rails::Generators::Base : Object)
+        source_root File.expand_path('templates', __dir__) if respond_to?(:source_root)
+
+        def create_initializer
+          return unless respond_to?(:template, true)
+
+          template 'verikloak_audience.rb.tt', 'config/initializers/verikloak_audience.rb'
+        end
+      end
+    end
+  end
+end

data/lib/verikloak/audience/railtie.rb

@@ -42,15 +42,70 @@ module Verikloak
       end
 
       # Performs the insertion into the middleware stack when the core
-      # Verikloak middleware is available. Extracted for testability without
-      # requiring a full Rails boot process.
+      # Verikloak middleware is available and already present. Extracted for
+      # testability without requiring a full Rails boot process.
       #
       # @param app [#middleware] An object exposing a Rack middleware stack via `#middleware`.
       # @return [void]
       def self.insert_middleware(app)
         return unless defined?(::Verikloak::Middleware)
 
-        app.middleware.insert_after ::Verikloak::Middleware, ::Verikloak::Audience::Middleware
+        middleware_stack = app.middleware
+        return unless middleware_stack.respond_to?(:include?)
+
+        unless middleware_stack.include?(::Verikloak::Middleware)
+          warn_missing_core_middleware
+          return
+        end
+
+        middleware_stack.insert_after ::Verikloak::Middleware, ::Verikloak::Audience::Middleware
+      end
+
+      WARNING_MESSAGE = <<~MSG
+        [verikloak-audience] Skipping automatic middleware insertion because ::Verikloak::Middleware
+        is not present in the Rails middleware stack.
+
+        To enable verikloak-audience, first ensure that the core Verikloak middleware (`Verikloak::Middleware`)
+        is added to your Rails middleware stack. Once the core middleware is present, you can run
+        `rails g verikloak:audience:install` to generate the initializer for the audience middleware,
+        or manually add:
+
+          config.middleware.insert_after Verikloak::Middleware, Verikloak::Audience::Middleware
+
+        This warning will disappear once the core middleware is properly configured and the audience
+        middleware is inserted.
+      MSG
+
+      # Logs a warning message when the core Verikloak middleware is missing
+      # from the Rails middleware stack. Uses the Rails logger if available,
+      # otherwise falls back to Kernel.warn for output.
+      #
+      # This method is called when automatic middleware insertion is skipped
+      # due to the absence of the required core middleware.
+      #
+      # @return [void]
+      def self.warn_missing_core_middleware
+        logger = rails_logger
+
+        if logger
+          logger.warn(WARNING_MESSAGE)
+        else
+          Kernel.warn(WARNING_MESSAGE)
+        end
+      end
+
+      # Retrieves the Rails application logger if available.
+      #
+      # This method safely attempts to access the Rails logger, returning nil
+      # if Rails is not defined, doesn't respond to the logger method, or if
+      # the logger itself is nil.
+      #
+      # @return [Logger, nil] the Rails logger instance, or nil if unavailable
+      def self.rails_logger
+        return unless defined?(::Rails)
+        return unless ::Rails.respond_to?(:logger)
+
+        ::Rails.logger
       end
 
       # Rails short commands (`g`, `d`) are stripped from ARGV fairly early in

data/lib/verikloak/audience/version.rb

@@ -4,6 +4,6 @@ module Verikloak
   module Audience
     # Current gem version.
     # @return [String]
-    VERSION = '0.2.4'
+    VERSION = '0.2.6'
   end
 end

data/lib/verikloak/audience.rb

@@ -5,13 +5,14 @@ require 'verikloak/audience/version'
 require 'verikloak/audience/configuration'
 require 'verikloak/audience/errors'
 require 'verikloak/audience/checker'
-require 'verikloak/audience/middleware'
 require 'verikloak/audience/railtie' if defined?(Rails::Railtie)
 
 module Verikloak
   # Audience configuration entrypoint and helpers.
   # This file also requires the public components of the gem.
   module Audience
+    autoload :Middleware, 'verikloak/audience/middleware'
+
     class << self
       # Configure verikloak-audience.
       #

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-audience
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.6
 platform: ruby
 authors:
 - taiyaky
@@ -59,6 +59,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- lib/generators/verikloak/audience/install/install_generator.rb
 - lib/verikloak-audience.rb
 - lib/verikloak/audience.rb
 - lib/verikloak/audience/checker.rb
@@ -74,7 +75,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak-audience
   changelog_uri: https://github.com/taiyaky/verikloak-audience/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak-audience/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak-audience/0.2.4
+  documentation_uri: https://rubydoc.info/gems/verikloak-audience/0.2.6
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: