rails_feature_guard 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bdfc76503e1ab6424a9ed5ac61137f96182ec1c92521f7b18e0facffaaa792b1
+  data.tar.gz: 44d3aa0e13d1dbccd05a7025323fab483a9ca9f59b0b42e2f562dc49bec90d17
+SHA512:
+  metadata.gz: 9e29b6d8620a16053849fc59dd5a20166bd7542cbd2f8f812e665b5368f354f446acbbf46a59da14e5735944ba2edfd4e8d6b4340236b0399c491cc0a71c8da9
+  data.tar.gz: 4430ab07f840ba963bbe591458a3c8d9db56da2790edc0073fd1f86a872822bcd26a0f20d62beecd5f1009fd1830fcc367997b110c82ec71c697cb3817232dad

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+## [Unreleased]
+
+## [0.1.2] - 2026-09-16
+
+- Publish the gem as `rails_feature_guard`.
+- Add a matching entrypoint for Bundler and Rails.
+
+## [0.1.1] - 2026-09-16
+
+- Add MIT licensing and RubyGems metadata.
+
+## [0.1.0] - 2026-08-27
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jam Vito Cruz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,165 @@
+# FeatureGuard
+
+FeatureGuard protects Rails controller actions with feature flags stored on an
+account's settings record. It also exposes the same checks to views.
+
+## Installation
+
+Add the gem to the Rails application's `Gemfile`:
+
+```ruby
+gem "rails_feature_guard"
+```
+
+Then install dependencies:
+
+```bash
+bundle install
+```
+
+## Configuration
+
+Create `config/initializers/feature_guard.rb`:
+
+```ruby
+FeatureGuard.configure do |config|
+  config.redirect_method = :dashboards_path
+end
+```
+
+The default values are:
+
+```ruby
+redirect_method: :root_path
+```
+
+`redirect_method` is combined with the controller's first namespace. For
+example, `:dashboards_path` in a `Partner` controller becomes
+`partner_dashboards_path`.
+
+## Settings record
+
+The account's settings record must have a boolean attribute for each feature:
+
+```ruby
+# current_account.feature_setting
+inventory_enabled # true or false
+reports_enabled   # true or false
+```
+
+For example, an account can expose its settings record like this:
+
+```ruby
+class Account < ApplicationRecord
+  has_one :feature_setting
+end
+```
+
+## Protect a controller action
+
+Declare a feature in a controller:
+
+```ruby
+class InventoryController < ApplicationController
+  feature :inventory_enabled
+
+  def index
+  end
+end
+```
+
+The feature name must exactly match a boolean column on
+`current_account.feature_setting`. `feature :inventory_enabled` calls
+`inventory_enabled?` on the feature policy. When that method is not defined,
+the policy reads `inventory_enabled?` from the settings record. If that column
+is missing, FeatureGuard raises `FeatureGuard::MissingFeatureColumnError`.
+FeatureGuard adds a `before_action`:
+
+```text
+inventory_enabled is true  -> the action runs
+inventory_enabled is false -> the request redirects
+```
+
+Limit a feature check to specific actions with normal `before_action` options:
+
+```ruby
+class InventoryController < ApplicationController
+  feature :inventory_enabled, only: :index
+end
+```
+
+For example, `feature :inventory_access_enabled` requires an
+`inventory_access_enabled` settings column and uses
+`inventory_access_enabled?` on both the policy and settings record.
+
+## Feature policy
+
+Create a policy in the Rails application and have the host controller provide
+one instance per request. Include `FeatureGuard::Policy`; the module provides
+the common feature-resolution behavior.
+
+```ruby
+# app/policies/feature_policy.rb
+class FeaturePolicy
+  include FeatureGuard::Policy
+
+  def inventory_enabled?
+    current_user.admin?
+  end
+end
+```
+
+```ruby
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  private
+
+  def feature_guard_policy
+    @feature_guard_policy ||= FeaturePolicy.new(
+      current_user: current_user,
+      feature_setting: current_account&.feature_setting
+    )
+  end
+end
+```
+
+The policy receives the account's `feature_setting` and `current_user`. A
+defined policy method fully controls its declared feature. When it is absent,
+`FeatureGuard::Policy#method_missing` reads the identically named setting
+predicate. Policy and settings names must match exactly.
+
+Define the private `#feature_guard_policy` instance method on the base
+controller so all controllers can build a request policy. For namespaced
+controllers, define it on that namespace's base controller. If it is missing,
+the gem raises `FeatureGuard::MissingPolicyError`.
+
+To use a differently named factory method, select it with the class-level
+`feature_guard_policy_method` declaration:
+
+```ruby
+feature_guard_policy_method :my_custom_feature_policy
+```
+
+## Use a feature in a view
+
+`module_enabled?` is available in controller actions and views:
+
+```erb
+<% if module_enabled?(:inventory_enabled) %>
+  <%= link_to "Inventory", inventory_path %>
+<% end %>
+```
+
+You may use `module_enabled?` without declaring `feature :inventory_enabled` in the
+controller. Declaring `feature` is only required when you want FeatureGuard to
+add the automatic redirect callback.
+
+## Errors and missing settings
+
+- If the account has no settings record, `module_enabled?` returns `false`.
+- If the settings record lacks the expected feature column, FeatureGuard raises
+  `FeatureGuard::MissingFeatureColumnError`.
+- If the base controller does not implement `feature_guard_policy`, FeatureGuard
+  raises `FeatureGuard::MissingPolicyError`.
+- If the namespaced dashboard route does not exist, FeatureGuard raises
+  `FeatureGuard::MissingRouteError`.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/feature_guard/configuration.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module FeatureGuard
+  class Configuration
+    attr_accessor :redirect_method
+
+    def initialize
+      # Combined with the controller namespace to build the redirect helper.
+      @redirect_method = :root_path
+    end
+  end
+end

data/lib/feature_guard/controller.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module FeatureGuard
+  # Mixed into ActionController::Base by the Railtie. It provides the `feature`
+  # class method for declaring protected features and `module_enabled?` for
+  # checking those features in controller actions and views.
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :policy_name, default: :feature_guard_policy
+
+      helper_method :module_enabled?
+    end
+
+    # Declares a feature that is protected by the persisted feature setting. The
+    # feature is checked before each action, and the user is redirected to the
+    # configured path if the feature is disabled.
+    class_methods do
+      # Selects the controller instance method that builds the request policy.
+      # Without this declaration, FeatureGuard calls `#feature_guard_policy`.
+      def feature_guard_policy_method(method_name)
+        self.policy_name = method_name.to_sym
+      end
+
+      def feature(feature_name, **options)
+        feature_name = feature_name.to_sym
+
+        if feature_name.to_s.end_with?('?')
+          raise ArgumentError,
+                'Feature name must not end with a question mark. Use :inventory_enable instead of :inventory_enable?.'
+        end
+
+        before_action(**options) do
+          enforce_module_availability(feature_name)
+        end
+      end
+    end
+
+    # Returns whether a feature is enabled for the current account. Results are
+    # cached for the current controller instance, which lasts one request.
+    def module_enabled?(feature_name)
+      feature_name = feature_name.to_sym
+
+      @module_availability_cache ||= {}
+
+      return @module_availability_cache[feature_name] if @module_availability_cache.key?(feature_name)
+
+      @module_availability_cache[feature_name] = resolve_module(feature_name)
+    end
+
+    private
+
+    # Redirects instead of continuing to the action when the feature is off.
+    def enforce_module_availability(module_name)
+      return if module_enabled?(module_name)
+
+      redirect_to(
+        feature_guard_redirect_path,
+        alert: 'This feature is not available for your account.'
+      )
+    end
+
+    # Asks the controller-owned application policy whether the feature is enabled.
+    def resolve_module(feature_name)
+      policy = feature_guard_policy_instance
+
+      return false unless policy
+
+      policy.public_send(:"#{feature_name}?")
+    end
+
+    # Calls the policy factory selected by `feature_guard_policy`. Policy
+    # factories may be private methods on the application's base controller.
+    def feature_guard_policy_instance
+      policy_method = self.class.policy_name
+
+      return feature_guard_policy if policy_method == :feature_guard_policy
+
+      send(policy_method)
+    end
+
+    # Host controllers must provide the policy instance for the request
+    def feature_guard_policy
+      namespace = self.class.name.split('::').first
+      base_name = namespace.empty? ? 'ApplicationController' : "#{namespace}Controller"
+
+      raise MissingPolicyError,
+            "Define #feature_guard_policy in #{base_name}, or configure a custom policy " \
+            'with feature_guard_policy_method'
+    end
+
+    def feature_guard_redirect_path
+      namespace = controller_path.split('/').first
+      dashboard_path = :"#{namespace}_#{FeatureGuard.configuration.redirect_method}"
+
+      return public_send(dashboard_path) if respond_to?(dashboard_path)
+
+      raise MissingRouteError,
+            "Expected route helper #{dashboard_path} for #{self.class.name}"
+    end
+  end
+end

data/lib/feature_guard/policy.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module FeatureGuard
+  module Policy
+    # `feature_setting` is used for declared feature methods that the policy
+    # does not override directly.
+    def initialize(current_user:, feature_setting:)
+      @current_user = current_user
+      @feature_setting = feature_setting
+    end
+
+    # A missing policy predicate falls back to the identically named persisted
+    # setting predicate. Defined policy methods fully override that setting.
+    def method_missing(method_name, ...)
+      return super unless method_name.to_s.end_with?('?')
+
+      persisted_feature_enabled?(method_name)
+    end
+
+    def respond_to_missing?(method_name, include_private = false)
+      return super unless method_name.to_s.end_with?('?')
+
+      @feature_setting.respond_to?(method_name, include_private) || super
+    end
+
+    private
+
+    def persisted_feature_enabled?(method_name)
+      return false unless @feature_setting
+
+      unless @feature_setting.respond_to?(method_name)
+        raise MissingFeatureColumnError,
+              "Missing setting column #{method_name.to_s.delete_suffix('?')} for #{@feature_setting.class.name}."
+      end
+
+      @feature_setting.public_send(method_name)
+    end
+  end
+end

data/lib/feature_guard/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module FeatureGuard
+  class Railtie < Rails::Railtie
+    initializer 'feature_guard.controller' do
+      ActiveSupport.on_load(:action_controller_base) do
+        # Makes FeatureGuard available to every controller through inheritance.
+        # Applications can override methods such as `feature_guard_policy` in
+        # their base controller to provide request-specific behavior.
+        include FeatureGuard::Controller
+      end
+    end
+  end
+end

data/lib/feature_guard/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FeatureGuard
+  VERSION = '0.1.2'
+end

data/lib/feature_guard.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+# `FeatureGuard::Controller` is an ActiveSupport concern and uses
+# `class_attribute` to keep each controller's feature declarations.
+require 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
+require 'active_support/core_ext/string/inflections'
+
+require_relative 'feature_guard/version'
+require_relative 'feature_guard/configuration'
+require_relative 'feature_guard/policy'
+require_relative 'feature_guard/controller'
+require_relative 'feature_guard/railtie'
+
+module FeatureGuard
+  # Custom error classes for the gem
+  class MissingFeatureColumnError < StandardError; end
+  class MissingRouteError < StandardError; end
+  class MissingPolicyError < StandardError; end
+
+  class << self
+    attr_writer :configuration
+
+    # Returns one shared configuration object for the application. The object
+    # is created only on first use, then kept in memory for later calls.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the shared configuration object so an initializer can customize
+    # the application policy and redirect path.
+    def configure
+      yield(configuration)
+    end
+  end
+end

data/lib/rails_feature_guard.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'feature_guard'

data/sig/feature_guard.rbs

@@ -0,0 +1,4 @@
+module FeatureGuard
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: rails_feature_guard
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Jam Vito Cruz
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: Guards Rails features with account settings and optional policy overrides.
+email:
+- vitocruzjemmalyn@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/feature_guard.rb
+- lib/feature_guard/configuration.rb
+- lib/feature_guard/controller.rb
+- lib/feature_guard/policy.rb
+- lib/feature_guard/railtie.rb
+- lib/feature_guard/version.rb
+- lib/rails_feature_guard.rb
+- sig/feature_guard.rbs
+homepage: https://github.com/jamvitocruz/feature_guard
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jamvitocruz/feature_guard
+  source_code_uri: https://github.com/jamvitocruz/feature_guard/tree/main
+  changelog_uri: https://github.com/jamvitocruz/feature_guard/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.9
+specification_version: 4
+summary: Feature flags for Rails controllers and views.
+test_files: []