verikloak-bff 0.2.1 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 255d2d606e30f92f8c562d91d975be06975a7ba373bd607aa5057e5abcc279a6
-  data.tar.gz: 6f81b6407f5a1a6e5d307cb65981f48e12c5356ec411ba05d21829681bedb084
+  metadata.gz: 2e2d5b0966fddd564dcd1b6e48fb871f3239542204176f0291f4249f5770b713
+  data.tar.gz: c1f1c43a58c7428263757d2f051c3f988921d84b30fc5fbdc8995f0c5d55ef4c
 SHA512:
-  metadata.gz: 995250cf2096de074988c0a00d4c2de0ff4b03c798089acfd0f0e0e5e3c0cdc3717da82f4f85be74db68fe40ced3cda5c27ae9f14ae41385a38a24e2eb9c4814
-  data.tar.gz: 157ddfbc41d48b9903b59f732ef8128a4d27127fee098d4a6e2388ca713ce15a749acad287b4995f87515d70233f74d4f44f7ac9d289de34d548d26bef3e9d17
+  metadata.gz: a4c8c80a0fccd793d93b2ef98374fd0bca253d5a36ff4d690dbd67de622bebd92ad27ef141d3c65c56ddd8c1934b9e9818a51eb3ef0a40b780ad0bc491263503
+  data.tar.gz: 339f5c58833ebb8ef19b511725c3f540e7506f097032235852088e0594dc917702723f8084f1abbdfd050b41f738486665d1c8b93891fb9fc7293c31d6e0483d

data/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.2.3] - 2025-09-23
+
+### Changed
+- Stop inserting `Verikloak::BFF::HeaderGuard` automatically via the Railtie and provide a `rails g verikloak:bff:install` generator that drops an initializer to opt in when the core middleware is ready.
+
+## [0.2.2] - 2025-09-23
+
+### Changed
+- Improved middleware class extraction logic to reduce code duplication while maintaining functionality
+
 ## [0.2.1] - 2025-09-23
 
 ### Fixed

data/README.md

@@ -31,12 +31,16 @@ use Verikloak::BFF::HeaderGuard, trusted_proxies: ['127.0.0.1', '10.0.0.0/8']
 ```
 
 ### Rails Applications
-Simply add to your Gemfile and the middleware will be automatically integrated:
+Add the gem to your Gemfile and run the install generator to drop an initializer that wires the middleware into Rails:
 ```ruby
 gem 'verikloak-bff'
 ```
 
-The gem automatically inserts `Verikloak::BFF::HeaderGuard` into the Rails middleware stack after the core `Verikloak::Middleware`. If the core middleware is not present (e.g., discovery not configured), it gracefully skips insertion with a warning, allowing Rails to boot normally.
+```sh
+bin/rails g verikloak:bff:install
+```
+
+The generated initializer inserts `Verikloak::BFF::HeaderGuard` after the core `Verikloak::Middleware` during boot. If the core middleware is not present (for example, when verikloak-rails has not been fully configured yet), the initializer logs a warning and allows Rails to boot normally.
 
 For detailed configuration, proxy setup examples, and troubleshooting, see [docs/rails.md](docs/rails.md).
 

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'rails/generators/base'
+
+module Verikloak
+  module BFF
+    # Namespace for Rails generators related to Verikloak BFF
+    module Generators
+      # Rails generator for installing Verikloak BFF middleware integration.
+      #
+      # This generator creates a Rails initializer that safely inserts the
+      # Verikloak::BFF::HeaderGuard middleware into the Rails middleware stack.
+      # It replaces automatic middleware insertion to avoid boot failures when
+      # core Verikloak middleware is not yet configured.
+      #
+      # @example Basic usage
+      #   rails g verikloak:bff:install
+      #
+      # @example Custom initializer path
+      #   rails g verikloak:bff:install --initializer=config/initializers/custom_bff.rb
+      #
+      # @see Verikloak::BFF::Rails::Middleware
+      class InstallGenerator < ::Rails::Generators::Base
+        source_root File.expand_path('templates', __dir__)
+
+        # Configuration option for specifying the initializer file path.
+        #
+        # @option options [String] :initializer ('config/initializers/verikloak_bff.rb')
+        #   The path where the initializer file will be created
+        class_option :initializer, type: :string,
+                                   default: 'config/initializers/verikloak_bff.rb',
+                                   desc: 'Path for the generated initializer'
+
+        # Creates the Rails initializer file from template.
+        #
+        # Generates a Rails initializer that safely inserts the HeaderGuard
+        # middleware into the middleware stack with proper error handling.
+        # The initializer uses Verikloak::BFF::Rails::Middleware.insert_after_core
+        # to ensure graceful handling when core middleware is missing.
+        #
+        # @return [void]
+        def create_initializer
+          template 'initializer.rb.tt', initializer_path
+        end
+
+        private
+
+        # Returns the path where the initializer should be created.
+        #
+        # @return [String] The initializer file path from options
+        def initializer_path
+          options[:initializer]
+        end
+      end
+    end
+  end
+end

data/lib/verikloak/bff/rails.rb

@@ -29,6 +29,13 @@ module Verikloak
         #     logger: Rails.logger
         #   )
         def insert_after_core(stack, logger: nil)
+          return false unless auto_insert_enabled?
+
+          unless core_present?(stack)
+            log_skip(logger)
+            return false
+          end
+
           stack.insert_after(::Verikloak::Middleware, ::Verikloak::BFF::HeaderGuard)
           true
         rescue RuntimeError => e
@@ -38,6 +45,79 @@ module Verikloak
           false
         end
 
+        # Determine whether automatic insertion is enabled via Verikloak core configuration.
+        #
+        # When the core gem exposes +auto_insert_bff_header_guard+, respect that flag so
+        # consumers can opt out of automatic middleware wiring without triggering warnings.
+        # Any failures while reading configuration default to enabling insertion in order
+        # to preserve the previous behavior.
+        #
+        # @return [Boolean]
+        def auto_insert_enabled?
+          return true unless defined?(::Verikloak)
+          return true unless ::Verikloak.respond_to?(:config)
+
+          config = ::Verikloak.config
+          return true unless config
+          return config.auto_insert_bff_header_guard if config.respond_to?(:auto_insert_bff_header_guard)
+
+          true
+        rescue StandardError
+          true
+        end
+
+        # Detect whether the Verikloak core middleware is already present in the stack.
+        #
+        # @param stack [#include?, #each, nil]
+        # @return [Boolean]
+        def core_present?(stack)
+          return false unless stack
+
+          if stack.respond_to?(:include?)
+            begin
+              return true if stack.include?(::Verikloak::Middleware)
+            rescue StandardError
+              # Fall back to manual enumeration when include? is unsupported for this stack
+            end
+          end
+
+          return false unless stack.respond_to?(:each)
+
+          stack.each do |middleware|
+            return true if middleware_matches_core?(middleware)
+          end
+
+          false
+        end
+
+        # Check whether a middleware entry represents the Verikloak core middleware.
+        #
+        # @param middleware [Object]
+        # @return [Boolean]
+        def middleware_matches_core?(middleware)
+          candidate = middleware.is_a?(Array) ? middleware.first : middleware
+
+          klass = extract_middleware_class(candidate)
+
+          klass == ::Verikloak::Middleware ||
+            (klass.is_a?(String) && klass == 'Verikloak::Middleware') ||
+            (klass.respond_to?(:name) && klass.name == 'Verikloak::Middleware')
+        end
+
+        # Extracts the class or class-like identifier from a middleware candidate.
+        #
+        # @param candidate [Object]
+        # @return [Class, String, Object]
+        def extract_middleware_class(candidate)
+          if candidate.respond_to?(:klass)
+            candidate.klass
+          elsif candidate.respond_to?(:name)
+            candidate.name
+          else
+            candidate
+          end
+        end
+
         # Checks if the error indicates missing core Verikloak middleware
         #
         # Examines a RuntimeError to determine if it was caused by attempting
@@ -75,11 +155,7 @@ module Verikloak
             [verikloak-bff] Skipping Verikloak::BFF::HeaderGuard insertion because Verikloak::Middleware is not present. Configure verikloak-rails discovery settings and restart once core verification is enabled.
           MSG
 
-          if logger
-            logger.warn(message)
-          else
-            warn(message)
-          end
+          logger ? logger.warn(message) : warn(message)
         end
       end
     end

data/lib/verikloak/bff/railtie.rb

@@ -5,29 +5,27 @@ require_relative 'rails'
 module Verikloak
   # Module providing Verikloak BFF (Backend for Frontend) functionality
   module BFF
-    # Railtie class for integrating Verikloak BFF middleware into Rails applications
+    # Railtie for integrating Verikloak BFF with Rails applications.
     #
-    # This class automatically inserts Verikloak::BFF::Rails::Middleware into the
-    # Rails initialization process. The middleware is inserted after the
-    # 'verikloak.middleware' initializer and configured with an appropriate logger.
+    # This Railtie provides access to the BFF installation generator instead of
+    # automatically inserting middleware, which could cause boot failures when
+    # core Verikloak middleware is not yet configured.
     #
-    # @example Automatic initialization in Rails applications
-    #   # Simply adding verikloak-bff to Gemfile automatically enables it
-    #   gem 'verikloak-bff'
+    # @example Installing BFF middleware
+    #   rails g verikloak:bff:install
     #
     # @see Verikloak::BFF::Rails::Middleware
     class Railtie < ::Rails::Railtie
-      # Initializer that inserts Verikloak BFF middleware into Rails application
+      # Loads the install generator when Rails generator infrastructure is available.
       #
-      # This initializer runs after 'verikloak.middleware' and inserts
-      # Verikloak::BFF::Rails::Middleware at the appropriate position.
-      # Uses Rails.logger as the logger if available.
+      # Makes the `verikloak:bff:install` generator discoverable through `rails g`
+      # while keeping generators optional for non-Rails environments.
       #
-      # @param app [Rails::Application] Rails application instance
-      initializer 'verikloak.bff.insert_middleware', after: 'verikloak.middleware' do |app|
-        logger = ::Rails.logger if defined?(::Rails.logger)
+      # @return [void]
+      initializer 'verikloak.bff.load_generators' do
+        next unless defined?(Rails::Generators)
 
-        Verikloak::BFF::Rails::Middleware.insert_after_core(app.config.middleware, logger: logger)
+        require_relative '../../generators/verikloak/bff/install/install_generator'
       end
     end
   end

data/lib/verikloak/bff/version.rb

@@ -5,6 +5,6 @@
 # @return [String]
 module Verikloak
   module BFF
-    VERSION = '0.2.1'
+    VERSION = '0.2.3'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-bff
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.3
 platform: ruby
 authors:
 - taiyaky
@@ -78,6 +78,7 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- lib/generators/verikloak/bff/install/install_generator.rb
 - lib/verikloak-bff.rb
 - lib/verikloak/bff.rb
 - lib/verikloak/bff/configuration.rb
@@ -98,7 +99,7 @@ metadata:
   source_code_uri: https://github.com/taiyaky/verikloak-bff
   changelog_uri: https://github.com/taiyaky/verikloak-bff/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/taiyaky/verikloak-bff/issues
-  documentation_uri: https://rubydoc.info/gems/verikloak-bff/0.2.1
+  documentation_uri: https://rubydoc.info/gems/verikloak-bff/0.2.3
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: