toggly-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c6508b1078a5f1691f9ceaf7be6b3c51ff247f347ebbf7b109eacd683216fe7b
+  data.tar.gz: c2befaafb3b4605966294e8e9fff0e3499ac245edeb2ad9b5c457cefddcc3a8b
+SHA512:
+  metadata.gz: 8343572f95ce19a45bdb6127b64cbe494940cba780e98f80fc211dec31ea09750261d6dc60e43ea3ff5284d5014bc2e3f8731218d20b47bf69824d89d92c488d
+  data.tar.gz: 61a4937f82a36dd6db037337f7d469e208295d4cfc07e99d739dad0b573a7ef319e80ab79919fe7ad272c91a5b72b5b5447b8cb6f749249fc26ebdf3ec4a6f30

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2024-XX-XX
+
+### Added
+
+- Initial release of Toggly Ruby SDK
+- `toggly` - Core SDK with zero dependencies
+  - Client for feature flag evaluation
+  - Context for user identity, groups, and traits
+  - Evaluation engine with multiple rule types
+  - Percentage rollouts with consistent hashing
+  - User and group targeting
+  - Contextual targeting with operators
+  - Time window rules
+  - Memory and file snapshot providers
+  - Background refresh support
+  - Offline mode with defaults
+
+- `toggly-rails` - Rails integration
+  - Railtie for auto-configuration
+  - Controller concern with `feature_enabled?` helper
+  - View helpers (`when_feature_enabled`, `feature_switch`)
+  - Rack middleware for request context
+  - Context builder from current_user
+  - Rails.cache snapshot provider
+  - Generator for initializer
+  - Rake tasks (list, check, refresh, config)
+  - RSpec and Minitest helpers
+
+- `toggly-cache` - Redis caching support
+  - Redis snapshot provider
+  - Connection pool support
+  - TTL configuration
+  - Touch/extend TTL support

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Ops.ai
+
+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,54 @@
+# toggly-rails
+
+Rails integration for [Toggly](https://toggly.io) feature flag management.
+
+## Installation
+
+```ruby
+gem 'toggly-rails'
+```
+
+## Quick Start
+
+```bash
+rails generate toggly:install
+```
+
+Then configure in `config/initializers/toggly.rb`:
+
+```ruby
+Toggly::Rails.configure do |config|
+  config.app_key = ENV['TOGGLY_APP_KEY']
+  config.environment = Rails.env.production? ? 'Production' : 'Staging'
+end
+```
+
+## Usage
+
+### Controllers
+
+```ruby
+class DashboardController < ApplicationController
+  def show
+    if feature_enabled?(:new_dashboard)
+      render :new_dashboard
+    end
+  end
+end
+```
+
+### Views
+
+```erb
+<% if feature_enabled?(:promo) %>
+  <div class="promo">Special offer!</div>
+<% end %>
+```
+
+## Documentation
+
+See the [main README](../README.md) for full documentation.
+
+## License
+
+MIT

data/lib/toggly/rails/cache_snapshot_provider.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Rails
+    # Snapshot provider that uses Rails.cache.
+    #
+    # Stores feature definitions in the Rails cache store
+    # for persistence and sharing across processes.
+    class CacheSnapshotProvider < Toggly::SnapshotProviders::Base
+      # @param key_prefix [String] Cache key prefix
+      # @param expires_in [Integer, nil] Cache expiration in seconds (nil = no expiration)
+      def initialize(key_prefix: "toggly", expires_in: nil)
+        super()
+        @key_prefix = key_prefix
+        @expires_in = expires_in
+      end
+
+      # Save definitions to Rails cache
+      #
+      # @param definitions [Hash<String, FeatureDefinition>] Definitions
+      # @param metadata [Hash] Optional metadata
+      def save(definitions, metadata = {})
+        data = {
+          definitions: serialize_definitions(definitions),
+          metadata: metadata.merge(saved_at: Time.now.utc.iso8601)
+        }
+
+        cache_options = {}
+        cache_options[:expires_in] = @expires_in if @expires_in
+
+        ::Rails.cache.write(cache_key, data, **cache_options)
+      end
+
+      # Load definitions from Rails cache
+      #
+      # @return [Hash, nil] Hash with :definitions and :metadata
+      def load
+        data = ::Rails.cache.read(cache_key)
+        return nil unless data
+
+        {
+          definitions: deserialize_definitions(data[:definitions]),
+          metadata: data[:metadata] || {}
+        }
+      end
+
+      # Clear the cached snapshot
+      def clear
+        ::Rails.cache.delete(cache_key)
+      end
+
+      # Check if snapshot exists in cache
+      #
+      # @return [Boolean]
+      def exists?
+        ::Rails.cache.exist?(cache_key)
+      end
+
+      private
+
+      def cache_key
+        "#{@key_prefix}:snapshot"
+      end
+    end
+  end
+end

data/lib/toggly/rails/configuration.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Rails
+    # Rails-specific configuration for Toggly.
+    #
+    # Extends the base Toggly configuration with Rails-specific options
+    # like context builders and middleware settings.
+    class Configuration
+      # Core configuration options (delegated to Toggly::Config)
+      attr_accessor :app_key, :environment, :base_url, :definitions_url,
+                    :refresh_interval, :http_timeout,
+                    :enable_undefined_in_dev, :disable_background_refresh,
+                    :app_version, :instance_name, :defaults,
+                    :snapshot_provider, :use_signed_definitions, :allowed_key_ids
+
+      # Rails-specific options
+
+      # @return [Proc, nil] Custom context builder proc
+      attr_accessor :context_builder
+
+      # @return [Boolean] Enable request-scoped context (via middleware)
+      attr_accessor :request_context_enabled
+
+      # @return [Symbol] Method to call on current_user for identity
+      attr_accessor :identity_method
+
+      # @return [Symbol] Method to call on current_user for groups
+      attr_accessor :groups_method
+
+      # @return [Hash<Symbol, Proc>] Custom trait extractors
+      attr_accessor :trait_extractors
+
+      # @return [Boolean] Use Rails.cache as snapshot provider
+      attr_accessor :use_rails_cache
+
+      # @return [String] Cache key prefix for Rails.cache
+      attr_accessor :cache_key_prefix
+
+      def initialize
+        # Core defaults
+        @environment = ::Rails.env.production? ? "Production" : "Staging" if defined?(::Rails)
+        @refresh_interval = 300
+        @http_timeout = 10
+        @enable_undefined_in_dev = false
+        @disable_background_refresh = false
+        @defaults = {}
+        @use_signed_definitions = false
+        @allowed_key_ids = []
+
+        # Rails-specific defaults
+        @request_context_enabled = true
+        @identity_method = :id
+        @groups_method = nil
+        @trait_extractors = {}
+        @use_rails_cache = false
+        @cache_key_prefix = "toggly"
+      end
+
+      # Apply this configuration to a Toggly::Config object
+      #
+      # @param config [Toggly::Config]
+      # @return [void]
+      def apply_to(config)
+        config.app_key = app_key
+        config.environment = environment
+        config.base_url = base_url if base_url
+        config.definitions_url = definitions_url if definitions_url
+        config.refresh_interval = refresh_interval
+        config.http_timeout = http_timeout
+        config.enable_undefined_in_dev = enable_undefined_in_dev
+        config.disable_background_refresh = disable_background_refresh
+        config.app_version = app_version if app_version
+        config.instance_name = instance_name if instance_name
+        config.defaults = defaults
+        config.use_signed_definitions = use_signed_definitions
+        config.allowed_key_ids = allowed_key_ids
+
+        # Set up snapshot provider
+        config.snapshot_provider = build_snapshot_provider
+
+        # Use Rails logger
+        config.logger = ::Rails.logger if defined?(::Rails)
+      end
+
+      # Add a custom trait extractor
+      #
+      # @param name [Symbol] Trait name
+      # @yield [request, user] Block that returns the trait value
+      # @return [void]
+      def add_trait(name, &block)
+        @trait_extractors[name.to_sym] = block
+      end
+
+      private
+
+      def build_snapshot_provider
+        return snapshot_provider if snapshot_provider
+        return nil unless use_rails_cache && defined?(::Rails)
+
+        require_relative "cache_snapshot_provider"
+        CacheSnapshotProvider.new(key_prefix: cache_key_prefix)
+      end
+    end
+  end
+end

data/lib/toggly/rails/context_builder.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Rails
+    # Builds evaluation context from Rails request and user.
+    #
+    # Extracts identity, groups, and traits from the current request
+    # and authenticated user.
+    class ContextBuilder
+      # @param config [Configuration] Rails configuration
+      def initialize(config)
+        @config = config
+      end
+
+      # Build context from request and user
+      #
+      # @param request [ActionDispatch::Request, nil] Current request
+      # @param user [Object, nil] Current authenticated user
+      # @return [Toggly::Context]
+      def build(request: nil, user: nil)
+        identity = extract_identity(user)
+        groups = extract_groups(user)
+        traits = extract_traits(request, user)
+
+        Toggly::Context.new(
+          identity: identity,
+          groups: groups,
+          traits: traits
+        )
+      end
+
+      private
+
+      def extract_identity(user)
+        return nil unless user
+        return unless @config.identity_method && user.respond_to?(@config.identity_method)
+
+        user.public_send(@config.identity_method)&.to_s
+      end
+
+      def extract_groups(user)
+        return [] unless user && @config.groups_method
+        return [] unless user.respond_to?(@config.groups_method)
+
+        Array(user.public_send(@config.groups_method)).map(&:to_s)
+      end
+
+      def extract_traits(request, user)
+        traits = {}
+
+        # Add default request traits
+        if request
+          traits["request_ip"] = request.remote_ip if request.respond_to?(:remote_ip)
+          traits["user_agent"] = request.user_agent if request.respond_to?(:user_agent)
+          traits["locale"] = I18n.locale.to_s if defined?(I18n)
+        end
+
+        # Add custom trait extractors
+        @config.trait_extractors.each do |name, extractor|
+          value = extractor.call(request, user)
+          traits[name.to_s] = value unless value.nil?
+        rescue StandardError
+          # Ignore errors in trait extraction
+        end
+
+        traits
+      end
+    end
+  end
+end

data/lib/toggly/rails/controller_concern.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Rails
+    # Controller concern for feature flag checks.
+    #
+    # Include this module in your ApplicationController to add
+    # feature flag helpers.
+    #
+    # @example
+    #   class ApplicationController < ActionController::Base
+    #     include Toggly::Rails::ControllerConcern
+    #
+    #     # Optional: customize how the current user is identified
+    #     def toggly_current_user
+    #       current_user
+    #     end
+    #   end
+    module ControllerConcern
+      extend ActiveSupport::Concern
+
+      included do
+        helper_method :feature_enabled?, :feature_disabled? if respond_to?(:helper_method)
+
+        # Set up user in middleware on each request
+        before_action :set_toggly_context, if: -> { Toggly::Rails.configuration&.request_context_enabled }
+      end
+
+      # Check if a feature is enabled
+      #
+      # @param feature_key [String, Symbol] Feature key
+      # @param context [Toggly::Context, nil] Optional override context
+      # @return [Boolean]
+      def feature_enabled?(feature_key, context: nil)
+        ctx = context || toggly_context
+        Toggly.enabled?(feature_key, context: ctx)
+      end
+
+      # Check if a feature is disabled
+      #
+      # @param feature_key [String, Symbol] Feature key
+      # @param context [Toggly::Context, nil] Optional override context
+      # @return [Boolean]
+      def feature_disabled?(feature_key, context: nil)
+        !feature_enabled?(feature_key, context: context)
+      end
+
+      # Require a feature to be enabled, otherwise render not found
+      #
+      # @param feature_key [String, Symbol] Feature key
+      # @param context [Toggly::Context, nil] Optional override context
+      # @return [void]
+      def require_feature!(feature_key, context: nil)
+        return if feature_enabled?(feature_key, context: context)
+
+        respond_to do |format|
+          format.html { render file: "public/404.html", status: :not_found, layout: false }
+          format.json { render json: { error: "Not found" }, status: :not_found }
+          format.any { head :not_found }
+        end
+      end
+
+      # Get the current evaluation context
+      #
+      # @return [Toggly::Context]
+      def toggly_context
+        @toggly_context ||= build_toggly_context
+      end
+
+      # Set a custom context for this request
+      #
+      # @param context [Toggly::Context] Context to use
+      # @return [void]
+      def toggly_context=(context)
+        @toggly_context = context
+        Middleware.set_context(request.env, context) if request
+      end
+
+      protected
+
+      # Override this method to provide the current user
+      #
+      # @return [Object, nil]
+      def toggly_current_user
+        return current_user if respond_to?(:current_user, true)
+
+        nil
+      end
+
+      private
+
+      def set_toggly_context
+        return unless request
+
+        Middleware.set_user(request.env, toggly_current_user)
+        Middleware.set_context(request.env, toggly_context)
+      end
+
+      def build_toggly_context
+        config = Toggly::Rails.configuration
+        return Toggly::Context.anonymous unless config
+
+        # Use custom context builder if provided
+        return config.context_builder.call(request, toggly_current_user) if config.context_builder
+
+        # Use default context builder
+        builder = ContextBuilder.new(config)
+        builder.build(request: request, user: toggly_current_user)
+      end
+    end
+  end
+end

data/lib/toggly/rails/generators/toggly/install/install_generator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Toggly
+  module Generators
+    # Generator for Toggly Rails initializer.
+    #
+    # @example
+    #   rails generate toggly:install
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a Toggly initializer file"
+
+      class_option :app_key, type: :string, desc: "Your Toggly app key"
+      class_option :environment, type: :string, desc: "Environment name"
+
+      def create_initializer_file
+        template "toggly.rb.erb", "config/initializers/toggly.rb"
+      end
+
+      def show_post_install_message
+        say ""
+        say "Toggly has been installed! 🎉", :green
+        say ""
+        say "Next steps:"
+        say "  1. Update config/initializers/toggly.rb with your app key"
+        say "  2. Or add to your credentials: rails credentials:edit"
+        say "     toggly:"
+        say "       app_key: your-app-key"
+        say "       environment: Production"
+        say ""
+        say "Usage in controllers:"
+        say "  if feature_enabled?(:my_feature)"
+        say "    # feature is on"
+        say "  end"
+        say ""
+        say "Usage in views:"
+        say "  <% if feature_enabled?(:my_feature) %>"
+        say "    Feature content"
+        say "  <% end %>"
+        say ""
+      end
+
+      private
+
+      def app_key
+        options[:app_key] || "ENV.fetch('TOGGLY_APP_KEY', nil)"
+      end
+
+      def environment_name
+        options[:environment] || "Rails.env.production? ? 'Production' : 'Staging'"
+      end
+    end
+  end
+end

data/lib/toggly/rails/generators/toggly/install/templates/toggly.rb.erb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Toggly Feature Flags Configuration
+# https://docs.toggly.io/sdks/ruby
+
+Toggly::Rails.configure do |config|
+  # Required: Your Toggly app key
+  # Get this from your Toggly dashboard: https://app.toggly.io
+  config.app_key = <%= app_key %>
+
+  # Required: Environment name
+  # Common values: "Production", "Staging", "Development"
+  config.environment = <%= environment_name %>
+
+  # Optional: Custom API endpoint (for self-hosted or enterprise)
+  # config.base_url = "https://custom.toggly.io"
+
+  # Optional: How often to refresh definitions (in seconds)
+  # config.refresh_interval = 300
+
+  # Optional: HTTP timeout for API requests (in seconds)
+  # config.http_timeout = 10
+
+  # Optional: Enable features by default in development
+  # config.enable_undefined_in_dev = Rails.env.development?
+
+  # Optional: Disable background refresh (useful in tests)
+  # config.disable_background_refresh = Rails.env.test?
+
+  # Optional: Use Rails.cache for persistence
+  # config.use_rails_cache = true
+
+  # Optional: Custom context builder
+  # config.context_builder = ->(request, user) do
+  #   Toggly::Context.new(
+  #     identity: user&.id&.to_s,
+  #     groups: user&.roles&.pluck(:name) || [],
+  #     traits: {
+  #       plan: user&.subscription&.plan,
+  #       country: request&.headers["CF-IPCountry"]
+  #     }
+  #   )
+  # end
+
+  # Optional: Configure how user identity is extracted
+  # config.identity_method = :id  # Method to call on current_user
+
+  # Optional: Configure how user groups are extracted
+  # config.groups_method = :role_names  # Method to call on current_user
+
+  # Optional: Add custom trait extractors
+  # config.add_trait(:plan) { |request, user| user&.subscription&.plan }
+  # config.add_trait(:country) { |request, _user| request&.headers["CF-IPCountry"] }
+
+  # Optional: Default values for offline mode
+  # config.defaults = {
+  #   "critical-feature" => true,
+  #   "experimental-feature" => false
+  # }
+end

data/lib/toggly/rails/middleware.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Rails
+    # Rack middleware for request-scoped Toggly context.
+    #
+    # Stores the evaluation context in the request environment
+    # for access throughout the request lifecycle.
+    class Middleware
+      # Environment key for storing the context
+      CONTEXT_KEY = "toggly.context"
+      USER_KEY = "toggly.current_user"
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        # Clear any existing context at the start of the request
+        env.delete(CONTEXT_KEY)
+        env.delete(USER_KEY)
+
+        @app.call(env)
+      ensure
+        # Clean up after request
+        env.delete(CONTEXT_KEY)
+        env.delete(USER_KEY)
+      end
+
+      class << self
+        # Get the current context from the request environment
+        #
+        # @param env [Hash] Rack environment
+        # @return [Toggly::Context, nil]
+        def context(env)
+          env[CONTEXT_KEY]
+        end
+
+        # Set the current context in the request environment
+        #
+        # @param env [Hash] Rack environment
+        # @param context [Toggly::Context] Context to set
+        # @return [Toggly::Context]
+        def set_context(env, context)
+          env[CONTEXT_KEY] = context
+        end
+
+        # Set the current user for context building
+        #
+        # @param env [Hash] Rack environment
+        # @param user [Object] Current user
+        # @return [Object]
+        def set_user(env, user)
+          env[USER_KEY] = user
+        end
+
+        # Get the current user from the request environment
+        #
+        # @param env [Hash] Rack environment
+        # @return [Object, nil]
+        def user(env)
+          env[USER_KEY]
+        end
+      end
+    end
+  end
+end

data/lib/toggly/rails/railtie.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Rails
+    # Rails Railtie for automatic integration.
+    #
+    # Automatically configures:
+    # - Middleware for request context
+    # - View helpers
+    # - Controller helpers
+    class Railtie < ::Rails::Railtie
+      initializer "toggly.middleware" do |app|
+        app.middleware.use Toggly::Rails::Middleware
+      end
+
+      initializer "toggly.view_helpers" do
+        ActiveSupport.on_load(:action_view) do
+          include Toggly::Rails::ViewHelpers
+        end
+      end
+
+      initializer "toggly.controller_helpers" do
+        ActiveSupport.on_load(:action_controller) do
+          include Toggly::Rails::ControllerConcern
+        end
+      end
+
+      # Configure Toggly after Rails initializers have run
+      config.after_initialize do
+        next unless Toggly::Rails.configuration.nil?
+        next unless defined?(::Rails) && ::Rails.application
+
+        credentials = ::Rails.application.credentials
+        next unless credentials.respond_to?(:toggly) && credentials.toggly
+
+        Toggly::Rails.configure do |config|
+          config.app_key = credentials.toggly[:app_key]
+          config.environment = credentials.toggly[:environment] || (::Rails.env.production? ? "Production" : "Staging")
+        end
+      end
+
+      # Gracefully shutdown on Rails restart
+      config.after_initialize do
+        at_exit do
+          Toggly.client&.close
+        end
+      end
+
+      # Add rake tasks
+      rake_tasks do
+        load "toggly/rails/tasks.rake"
+      end
+
+      # Add generators
+      generators do
+        require_relative "generators/toggly/install/install_generator"
+      end
+    end
+  end
+end

data/lib/toggly/rails/tasks.rake

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+namespace :toggly do
+  desc "Refresh feature definitions from Toggly API"
+  task refresh: :environment do
+    if Toggly.client
+      puts "Refreshing Toggly feature definitions..."
+      if Toggly.client.refresh(force: true)
+        puts "Successfully refreshed #{Toggly.client.feature_keys.count} features"
+      else
+        puts "No changes detected"
+      end
+    else
+      puts "Toggly is not configured. Run rails generate toggly:install first."
+    end
+  end
+
+  desc "List all feature flags"
+  task list: :environment do
+    if Toggly.client
+      features = Toggly.client.features
+      if features.empty?
+        puts "No features found"
+      else
+        puts "Feature Flags (#{features.count}):"
+        puts "-" * 60
+        features.sort_by(&:feature_key).each do |feature|
+          status = feature.enabled ? "✓ enabled" : "✗ disabled"
+          puts "  #{feature.feature_key.ljust(40)} #{status}"
+        end
+      end
+    else
+      puts "Toggly is not configured. Run rails generate toggly:install first."
+    end
+  end
+
+  desc "Check if a specific feature is enabled"
+  task :check, [:feature_key] => :environment do |_t, args|
+    feature_key = args[:feature_key]
+    if feature_key.nil? || feature_key.empty?
+      puts "Usage: rake toggly:check[feature_key]"
+      exit 1
+    end
+
+    if Toggly.client
+      if Toggly.enabled?(feature_key)
+        puts "Feature '#{feature_key}' is ENABLED"
+      else
+        puts "Feature '#{feature_key}' is DISABLED"
+      end
+    else
+      puts "Toggly is not configured. Run rails generate toggly:install first."
+    end
+  end
+
+  desc "Show Toggly configuration"
+  task config: :environment do
+    if Toggly::Rails.configuration
+      config = Toggly::Rails.configuration
+      puts "Toggly Configuration:"
+      puts "-" * 40
+      puts "  App Key:          #{config.app_key ? "#{config.app_key[0..7]}..." : "(not set)"}"
+      puts "  Environment:      #{config.environment}"
+      puts "  Base URL:         #{config.base_url || Toggly::Config::DEFAULT_BASE_URL}"
+      puts "  Refresh Interval: #{config.refresh_interval}s"
+      puts "  Request Context:  #{config.request_context_enabled ? "enabled" : "disabled"}"
+      puts "  Rails Cache:      #{config.use_rails_cache ? "enabled" : "disabled"}"
+
+      if Toggly.client
+        puts "\nClient Status:"
+        puts "  Ready:    #{Toggly.client.ready ? "yes" : "no"}"
+        puts "  Features: #{Toggly.client.feature_keys.count}"
+      end
+    else
+      puts "Toggly is not configured. Run rails generate toggly:install first."
+    end
+  end
+end

data/lib/toggly/rails/testing.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Rails
+    # Testing helpers for RSpec and Minitest.
+    #
+    # @example RSpec
+    #   RSpec.configure do |config|
+    #     config.include Toggly::Rails::Testing::RSpecHelpers
+    #   end
+    #
+    #   describe "my feature" do
+    #     it "shows new UI when enabled" do
+    #       with_feature(:new_ui, enabled: true) do
+    #         visit dashboard_path
+    #         expect(page).to have_content("New Dashboard")
+    #       end
+    #     end
+    #   end
+    #
+    # @example Minitest
+    #   class MyTest < ActionDispatch::IntegrationTest
+    #     include Toggly::Rails::Testing::MinitestHelpers
+    #
+    #     test "shows new UI when enabled" do
+    #       with_feature(:new_ui, enabled: true) do
+    #         get dashboard_path
+    #         assert_includes response.body, "New Dashboard"
+    #       end
+    #     end
+    #   end
+    module Testing
+      # Stub a feature to return a specific value
+      #
+      # @param feature_key [String, Symbol] Feature key
+      # @param enabled [Boolean] Whether the feature should be enabled
+      # @yield Block during which the feature is stubbed
+      def with_feature(feature_key, enabled: true)
+        key = feature_key.to_s
+        original_definitions = Toggly.client&.definitions&.dup || {}
+
+        # Add or update the feature definition
+        Toggly.client.instance_variable_get(:@mutex).synchronize do
+          Toggly.client.definitions[key] = Toggly::FeatureDefinition.new(
+            feature_key: key,
+            enabled: enabled
+          )
+        end
+
+        yield
+      ensure
+        # Restore original definitions
+        Toggly.client&.instance_variable_get(:@mutex)&.synchronize do
+          Toggly.client.instance_variable_set(:@definitions, original_definitions)
+        end
+      end
+
+      # Stub multiple features at once
+      #
+      # @param features [Hash<String, Boolean>] Hash of feature keys to enabled states
+      # @yield Block during which the features are stubbed
+      def with_features(features)
+        original_definitions = Toggly.client&.definitions&.dup || {}
+
+        features.each do |key, enabled|
+          Toggly.client.instance_variable_get(:@mutex).synchronize do
+            Toggly.client.definitions[key.to_s] = Toggly::FeatureDefinition.new(
+              feature_key: key.to_s,
+              enabled: enabled
+            )
+          end
+        end
+
+        yield
+      ensure
+        Toggly.client&.instance_variable_get(:@mutex)&.synchronize do
+          Toggly.client.instance_variable_set(:@definitions, original_definitions)
+        end
+      end
+
+      # Enable a feature for the duration of a block
+      #
+      # @param feature_key [String, Symbol] Feature key
+      # @yield Block during which the feature is enabled
+      def enable_feature(feature_key, &block)
+        with_feature(feature_key, enabled: true, &block)
+      end
+
+      # Disable a feature for the duration of a block
+      #
+      # @param feature_key [String, Symbol] Feature key
+      # @yield Block during which the feature is disabled
+      def disable_feature(feature_key, &block)
+        with_feature(feature_key, enabled: false, &block)
+      end
+
+      # RSpec helpers
+      module RSpecHelpers
+        include Testing
+
+        # RSpec matcher for checking if a feature is enabled
+        #
+        # @example
+        #   expect(:new_feature).to be_feature_enabled
+        if defined?(RSpec::Matchers)
+          RSpec::Matchers.define :be_feature_enabled do
+            match do |feature_key|
+              Toggly.enabled?(feature_key)
+            end
+
+            failure_message do |feature_key|
+              "expected feature '#{feature_key}' to be enabled"
+            end
+
+            failure_message_when_negated do |feature_key|
+              "expected feature '#{feature_key}' to be disabled"
+            end
+          end
+        end
+      end
+
+      # Minitest helpers
+      module MinitestHelpers
+        include Testing
+
+        # Assert that a feature is enabled
+        #
+        # @param feature_key [String, Symbol] Feature key
+        # @param msg [String, nil] Custom failure message
+        def assert_feature_enabled(feature_key, msg = nil)
+          msg ||= "Expected feature '#{feature_key}' to be enabled"
+          assert Toggly.enabled?(feature_key), msg
+        end
+
+        # Assert that a feature is disabled
+        #
+        # @param feature_key [String, Symbol] Feature key
+        # @param msg [String, nil] Custom failure message
+        def assert_feature_disabled(feature_key, msg = nil)
+          msg ||= "Expected feature '#{feature_key}' to be disabled"
+          assert Toggly.disabled?(feature_key), msg
+        end
+      end
+    end
+  end
+end

data/lib/toggly/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/toggly/rails/view_helpers.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Rails
+    # View helpers for feature flags in Rails views.
+    #
+    # These helpers are automatically included in ActionView
+    # when using the Railtie.
+    module ViewHelpers
+      # Check if a feature is enabled
+      #
+      # @param feature_key [String, Symbol] Feature key
+      # @param context [Toggly::Context, nil] Optional override context
+      # @return [Boolean]
+      def feature_enabled?(feature_key, context: nil)
+        if controller.respond_to?(:feature_enabled?, true)
+          controller.send(:feature_enabled?, feature_key, context: context)
+        else
+          ctx = context || view_toggly_context
+          Toggly.enabled?(feature_key, context: ctx)
+        end
+      end
+
+      # Check if a feature is disabled
+      #
+      # @param feature_key [String, Symbol] Feature key
+      # @param context [Toggly::Context, nil] Optional override context
+      # @return [Boolean]
+      def feature_disabled?(feature_key, context: nil)
+        !feature_enabled?(feature_key, context: context)
+      end
+
+      # Render content only if feature is enabled
+      #
+      # @param feature_key [String, Symbol] Feature key
+      # @param context [Toggly::Context, nil] Optional override context
+      # @yield Content to render when enabled
+      # @return [String, nil]
+      def when_feature_enabled(feature_key, context: nil, &block)
+        return unless feature_enabled?(feature_key, context: context)
+
+        capture(&block) if block_given?
+      end
+
+      # Render content only if feature is disabled
+      #
+      # @param feature_key [String, Symbol] Feature key
+      # @param context [Toggly::Context, nil] Optional override context
+      # @yield Content to render when disabled
+      # @return [String, nil]
+      def when_feature_disabled(feature_key, context: nil, &block)
+        return if feature_enabled?(feature_key, context: context)
+
+        capture(&block) if block_given?
+      end
+
+      # Render enabled or disabled content based on feature state
+      #
+      # @param feature_key [String, Symbol] Feature key
+      # @param enabled [String, nil] Content when enabled
+      # @param disabled [String, nil] Content when disabled
+      # @param context [Toggly::Context, nil] Optional override context
+      # @return [String]
+      def feature_switch(feature_key, enabled: nil, disabled: nil, context: nil)
+        if feature_enabled?(feature_key, context: context)
+          enabled
+        else
+          disabled
+        end
+      end
+
+      private
+
+      def view_toggly_context
+        # Try to get context from controller
+        if controller.respond_to?(:toggly_context, true)
+          controller.send(:toggly_context)
+        else
+          Toggly::Context.anonymous
+        end
+      end
+    end
+  end
+end

data/lib/toggly-rails.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "toggly"
+require_relative "toggly/rails/version"
+require_relative "toggly/rails/configuration"
+require_relative "toggly/rails/context_builder"
+require_relative "toggly/rails/middleware"
+require_relative "toggly/rails/controller_concern"
+require_relative "toggly/rails/view_helpers"
+require_relative "toggly/rails/railtie" if defined?(Rails::Railtie)
+
+module Toggly
+  # Rails integration for Toggly feature flags.
+  #
+  # @example Basic Rails setup (config/initializers/toggly.rb)
+  #   Toggly::Rails.configure do |config|
+  #     config.app_key = Rails.application.credentials.toggly_app_key
+  #     config.environment = Rails.env.production? ? "Production" : "Staging"
+  #   end
+  #
+  # @example Controller usage
+  #   class ApplicationController < ActionController::Base
+  #     include Toggly::Rails::ControllerConcern
+  #
+  #     def show
+  #       if feature_enabled?(:new_dashboard)
+  #         render :new_dashboard
+  #       else
+  #         render :dashboard
+  #       end
+  #     end
+  #   end
+  #
+  # @example View usage
+  #   <% if feature_enabled?(:new_header) %>
+  #     <%= render "new_header" %>
+  #   <% else %>
+  #     <%= render "header" %>
+  #   <% end %>
+  module Rails
+    class << self
+      # @return [Configuration] Rails-specific configuration
+      attr_accessor :configuration
+
+      # Configure Toggly for Rails
+      #
+      # @yield [Configuration] Configuration block
+      # @return [void]
+      def configure
+        self.configuration ||= Configuration.new
+        yield(configuration) if block_given?
+
+        # Create the Toggly client from Rails configuration
+        Toggly.configure do |config|
+          configuration.apply_to(config)
+        end
+      end
+
+      # Reset configuration (mainly for testing)
+      def reset!
+        self.configuration = nil
+        Toggly.reset!
+      end
+
+      # Get the current Toggly client
+      #
+      # @return [Toggly::Client]
+      def client
+        Toggly.client
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: toggly-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ops.ai
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: toggly
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: Rails integration for Toggly feature flags including Railtie, controller
+  concerns, view helpers, Rack middleware, and generators.
+email:
+- support@ops.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/toggly-rails.rb
+- lib/toggly/rails/cache_snapshot_provider.rb
+- lib/toggly/rails/configuration.rb
+- lib/toggly/rails/context_builder.rb
+- lib/toggly/rails/controller_concern.rb
+- lib/toggly/rails/generators/toggly/install/install_generator.rb
+- lib/toggly/rails/generators/toggly/install/templates/toggly.rb.erb
+- lib/toggly/rails/middleware.rb
+- lib/toggly/rails/railtie.rb
+- lib/toggly/rails/tasks.rake
+- lib/toggly/rails/testing.rb
+- lib/toggly/rails/version.rb
+- lib/toggly/rails/view_helpers.rb
+homepage: https://toggly.io
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://toggly.io
+  source_code_uri: https://github.com/ops-ai/toggly-ruby
+  changelog_uri: https://github.com/ops-ai/toggly-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://docs.toggly.io/sdks/ruby
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Rails integration for Toggly feature flags
+test_files: []