verikloak-bff 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91439a22efdb87206de07fbff74c284cba33a05cb1c7392070c0b9f7c837734f
-  data.tar.gz: be08bb99047e72502cad67dbea7c41b916aef6d49fb103e3dbf53ab79082f6db
+  metadata.gz: 8fbec3da2912582f3684c1682fb75b45f9d26c3a1ebf3b7a41d4a5392fbe36c1
+  data.tar.gz: d1b5b9f750bd3cdbbf3308f1581c8327c039f87b660cde73a799a83740f818ae
 SHA512:
-  metadata.gz: 135054bc3b1556597924c843a834d87c46c291da4d880ed63ef611cafb9705984694062f64d25a08f8d3f932f304cfb7277c4d25f25dfb3f35ad3d83f0768e47
-  data.tar.gz: 3358b1f9f3114e9a00a7d4edd283e5b2c81dd6166ec1a5718a581f5f83a7c1cf75d27f300da01d5dc25763f4569a50be2393203130c5a67adb00ffb1a42fc1d9
+  metadata.gz: 33655caab83ec29f7159264b660aadb878a61c3ca52c4f23e4256cdb30519384833d7ea8244de5c8252368227ef3999691eb1aa282d907c42e94db69fb39ecb3
+  data.tar.gz: d1442646ce08bd0a98ca211f781f0ba623d58d51323ed86492c01cee60086a27c5f27c1fd8d65e4b7ab5ea10c52a9bf6b4942e09c0be80cc8e4d250d6bfb4f48

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [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
+- Skip inserting `Verikloak::BFF::HeaderGuard` in Rails when `Verikloak::Middleware` is absent (e.g., discovery not configured)
+  so that generators and boot sequences no longer fail.
+
 ## [0.2.0] - 2025-09-22
 
 ### Added

data/README.md

@@ -23,8 +23,22 @@ bundle add verikloak-bff
 
 ## Usage
 
-- Rack-only apps: `use Verikloak::BFF::HeaderGuard` before your core Verikloak middleware.
-- Rails apps: see the full guide in [docs/rails.md](docs/rails.md) (Gemfile, middleware order、initializer、proxy examples)。
+### Rack Applications
+Add to your `config.ru`:
+```ruby
+use Verikloak::BFF::HeaderGuard, trusted_proxies: ['127.0.0.1', '10.0.0.0/8']
+# Place before your core Verikloak middleware
+```
+
+### Rails Applications
+Simply add to your Gemfile and the middleware will be automatically integrated:
+```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.
+
+For detailed configuration, proxy setup examples, and troubleshooting, see [docs/rails.md](docs/rails.md).
 
 ## Consistency mapping
 

data/lib/verikloak/bff/rails.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Verikloak
+  module BFF
+    # Rails-specific functionality for Verikloak BFF
+    module Rails
+      # Middleware management utilities for Rails applications
+      #
+      # This module provides functionality to insert Verikloak BFF middleware
+      # into Rails middleware stack, with proper error handling for cases where
+      # the core Verikloak middleware is not present.
+      module Middleware
+        module_function
+
+        # Inserts Verikloak::BFF::HeaderGuard middleware after Verikloak::Middleware
+        #
+        # Attempts to insert the HeaderGuard middleware into the Rails middleware stack
+        # after the core Verikloak::Middleware. If the core middleware is not present,
+        # logs a warning and gracefully skips the insertion.
+        #
+        # @param stack [ActionDispatch::MiddlewareStack] Rails middleware stack
+        # @param logger [Logger, nil] Optional logger for warning messages
+        # @return [Boolean] true if insertion succeeded, false if skipped due to missing core
+        # @raise [RuntimeError] Re-raises non-middleware-related runtime errors
+        #
+        # @example Inserting middleware in Rails configuration
+        #   Verikloak::BFF::Rails::Middleware.insert_after_core(
+        #     Rails.application.config.middleware,
+        #     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
+          raise unless missing_core?(e)
+
+          log_skip(logger)
+          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
+        # to insert middleware after a non-existent Verikloak::Middleware.
+        #
+        # @param error [RuntimeError] The error to examine
+        # @return [Boolean] true if error indicates missing Verikloak::Middleware
+        #
+        # @example Checking for missing middleware error
+        #   begin
+        #     stack.insert_after(::Verikloak::Middleware, SomeMiddleware)
+        #   rescue RuntimeError => e
+        #     puts "Missing core!" if missing_core?(e)
+        #   end
+        def missing_core?(error)
+          error.message.include?('No such middleware') &&
+            error.message.include?('Verikloak::Middleware')
+        end
+
+        # Logs a warning message about skipping middleware insertion
+        #
+        # Outputs a descriptive warning message explaining why the HeaderGuard
+        # middleware insertion was skipped and provides guidance for resolution.
+        # Uses the provided logger if available, otherwise falls back to warn().
+        #
+        # @param logger [Logger, nil] Optional logger instance for structured logging
+        #
+        # @example Logging with Rails logger
+        #   log_skip(Rails.logger)
+        #
+        # @example Logging without logger (uses warn)
+        #   log_skip(nil)
+        def log_skip(logger)
+          message = <<~MSG.chomp
+            [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
+
+          logger ? logger.warn(message) : warn(message)
+        end
+      end
+    end
+  end
+end

data/lib/verikloak/bff/railtie.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+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
+    #
+    # 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.
+    #
+    # @example Automatic initialization in Rails applications
+    #   # Simply adding verikloak-bff to Gemfile automatically enables it
+    #   gem 'verikloak-bff'
+    #
+    # @see Verikloak::BFF::Rails::Middleware
+    class Railtie < ::Rails::Railtie
+      # Initializer that inserts Verikloak BFF middleware into Rails application
+      #
+      # This initializer runs after 'verikloak.middleware' and inserts
+      # Verikloak::BFF::Rails::Middleware at the appropriate position.
+      # Uses Rails.logger as the logger if available.
+      #
+      # @param app [Rails::Application] Rails application instance
+      initializer 'verikloak.bff.insert_middleware', after: 'verikloak.middleware' do |app|
+        logger = ::Rails.logger if defined?(::Rails.logger)
+
+        Verikloak::BFF::Rails::Middleware.insert_after_core(app.config.middleware, logger: logger)
+      end
+    end
+  end
+end

data/lib/verikloak/bff/version.rb

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

data/lib/verikloak-bff.rb

@@ -18,3 +18,6 @@ require 'verikloak/bff/proxy_trust'
 require 'verikloak/bff/forwarded_token'
 require 'verikloak/bff/consistency_checks'
 require 'verikloak/bff/header_guard'
+require 'verikloak/bff/rails'
+
+require 'verikloak/bff/railtie' if defined?(Rails::Railtie)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: verikloak-bff
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - taiyaky
@@ -55,7 +55,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: 0.2.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -65,7 +65,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.5
+        version: 0.2.0
     - - "<"
       - !ruby/object:Gem::Version
         version: 1.0.0
@@ -87,6 +87,8 @@ files:
 - lib/verikloak/bff/forwarded_token.rb
 - lib/verikloak/bff/header_guard.rb
 - lib/verikloak/bff/proxy_trust.rb
+- lib/verikloak/bff/rails.rb
+- lib/verikloak/bff/railtie.rb
 - lib/verikloak/bff/version.rb
 - lib/verikloak/header_sources.rb
 homepage: https://github.com/taiyaky/verikloak-bff
@@ -96,7 +98,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.0
+  documentation_uri: https://rubydoc.info/gems/verikloak-bff/0.2.2
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: