toggly 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e803470a2b9ba974d853c9b93a9da9404467f701c76ed6fbb0bd678627da7112
+  data.tar.gz: 86c792820f5ddecf1c951118bafa9d8df632299e919d8c48165e2c80e13b4b9b
+SHA512:
+  metadata.gz: fae2c7e8f07c7e88050e459ebfe2762895ae4fcebb73aced9f03985a5a12c5f01e73cecfd1943352610ac08a50eb8e8d57553203f59c99a7fcf781a80fe01a92
+  data.tar.gz: 7bbe9e747d3aa3dcde62701bb26ccd3541184b68274e8da59d49fed6d515db3c6e3e9e63e964e28bed254c35d7e0ddefa130fc865a8886843a56e4b65b5b53c9

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,34 @@
+# toggly
+
+Core Ruby SDK for [Toggly](https://toggly.io) feature flag management.
+
+**Zero dependencies** - pure Ruby implementation.
+
+## Installation
+
+```ruby
+gem 'toggly'
+```
+
+## Quick Start
+
+```ruby
+require 'toggly'
+
+client = Toggly::Client.new(
+  app_key: 'your-app-key',
+  environment: 'Production'
+)
+
+if client.enabled?(:my_feature)
+  # Feature is enabled
+end
+```
+
+## Documentation
+
+See the [main README](../README.md) for full documentation.
+
+## License
+
+MIT

data/lib/toggly/client.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module Toggly
+  # Main client for interacting with Toggly feature flags.
+  #
+  # @example Basic usage
+  #   client = Toggly::Client.new(
+  #     app_key: "your-app-key",
+  #     environment: "Production"
+  #   )
+  #
+  #   if client.enabled?("my-feature")
+  #     # Feature is enabled
+  #   end
+  #
+  # @example With configuration object
+  #   config = Toggly::Config.new(
+  #     app_key: "your-app-key",
+  #     environment: "Production",
+  #     refresh_interval: 60
+  #   )
+  #   client = Toggly::Client.new(config)
+  class Client
+    # @return [Config] Client configuration
+    attr_reader :config
+
+    # @return [Hash<String, FeatureDefinition>] Current definitions
+    attr_reader :definitions
+
+    # @return [Boolean] Whether the client is ready
+    attr_reader :ready
+
+    # Create a new client
+    #
+    # @param config_or_options [Config, Hash] Configuration object or options hash
+    def initialize(config_or_options = {})
+      @config = config_or_options.is_a?(Config) ? config_or_options : Config.new(**config_or_options)
+      @config.validate!
+
+      @definitions = {}
+      @mutex = Mutex.new
+      @ready = false
+      @closed = false
+
+      @engine = EvaluationEngine.new(logger: @config.logger)
+      @provider = DefinitionsProvider.new(
+        config: @config,
+        logger: @config.logger,
+        on_definitions_updated: -> { refresh }
+      )
+
+      @refresh_thread = nil
+
+      initialize_definitions
+      start_background_refresh unless @config.disable_background_refresh
+    end
+
+    # Check if a feature is enabled
+    #
+    # @param feature_key [String, Symbol] The feature key
+    # @param context [Context, nil] Optional evaluation context
+    # @param default [Boolean] Default value if feature not found
+    # @return [Boolean]
+    def enabled?(feature_key, context: nil, default: nil)
+      key = feature_key.to_s
+
+      definition = @mutex.synchronize { @definitions[key] }
+
+      # Check defaults if not found
+      if definition.nil?
+        return default unless default.nil?
+        return @config.defaults[key] if @config.defaults.key?(key)
+        return @config.enable_undefined_in_dev if development?
+
+        return false
+      end
+
+      @engine.evaluate(definition, context)
+    end
+
+    # Check if a feature is disabled
+    #
+    # @param feature_key [String, Symbol] The feature key
+    # @param context [Context, nil] Optional evaluation context
+    # @param default [Boolean] Default value if feature not found
+    # @return [Boolean]
+    def disabled?(feature_key, context: nil, default: nil)
+      !enabled?(feature_key, context: context, default: default.nil? ? nil : !default)
+    end
+
+    # Get detailed evaluation result
+    #
+    # @param feature_key [String, Symbol] The feature key
+    # @param context [Context, nil] Optional evaluation context
+    # @return [EvaluationResult]
+    def evaluate(feature_key, context: nil)
+      key = feature_key.to_s
+      definition = @mutex.synchronize { @definitions[key] }
+
+      @engine.evaluate_with_details(definition, context)
+    end
+
+    # Get a feature definition
+    #
+    # @param feature_key [String, Symbol] The feature key
+    # @return [FeatureDefinition, nil]
+    def feature(feature_key)
+      @mutex.synchronize { @definitions[feature_key.to_s] }
+    end
+
+    # Get all feature keys
+    #
+    # @return [Array<String>]
+    def feature_keys
+      @mutex.synchronize { @definitions.keys }
+    end
+
+    # Get all features
+    #
+    # @return [Array<FeatureDefinition>]
+    def features
+      @mutex.synchronize { @definitions.values }
+    end
+
+    # Manually refresh definitions
+    #
+    # @param force [Boolean] Force refresh even if not modified
+    # @return [Boolean] Whether definitions were updated
+    def refresh(force: false)
+      return false if @config.offline_mode?
+
+      new_definitions = @provider.fetch(force: force)
+
+      if new_definitions
+        @mutex.synchronize do
+          @definitions = new_definitions
+          @ready = true
+        end
+
+        save_snapshot
+        log_info("Definitions refreshed (#{new_definitions.size} features)")
+        true
+      else
+        false
+      end
+    rescue StandardError => e
+      log_error("Failed to refresh definitions: #{e.message}")
+      false
+    end
+
+    # Close the client and stop background refresh
+    def close
+      @closed = true
+      @provider.stop_websocket
+      @refresh_thread&.kill
+      @refresh_thread = nil
+    end
+
+    # Check if client is closed
+    #
+    # @return [Boolean]
+    def closed?
+      @closed
+    end
+
+    # Wait for client to be ready
+    #
+    # @param timeout [Numeric] Maximum wait time in seconds
+    # @return [Boolean] Whether client became ready
+    def wait_for_ready(timeout: 5)
+      start_time = Time.now
+
+      until @ready
+        return false if (Time.now - start_time) > timeout
+
+        sleep(0.01)
+      end
+
+      true
+    end
+
+    private
+
+    def initialize_definitions
+      # Try to load from snapshot first
+      load_snapshot if @config.snapshot_provider
+
+      # Initialize with defaults if in offline mode
+      if @config.offline_mode?
+        @config.defaults.each do |key, value|
+          @definitions[key] = FeatureDefinition.new(
+            feature_key: key,
+            enabled: value
+          )
+        end
+        @ready = true
+        return
+      end
+
+      # Fetch from API
+      refresh(force: true)
+    rescue StandardError => e
+      log_error("Failed to initialize definitions: #{e.message}")
+
+      # Use snapshot or defaults as fallback
+      @ready = true if @definitions.any? || @config.defaults.any?
+    end
+
+    def start_background_refresh
+      return if @config.disable_background_refresh
+      return if @config.offline_mode?
+      return if @config.refresh_interval <= 0
+
+      @refresh_thread = Thread.new do
+        loop do
+          break if @closed
+
+          sleep(@config.refresh_interval)
+          break if @closed
+
+          # When WebSocket is connected, skip HTTP refresh unless
+          # the fallback interval has elapsed
+          next if @provider.should_skip_refresh?
+
+          refresh
+        end
+      end
+
+      @refresh_thread.abort_on_exception = false
+
+      # Start WebSocket live updates after background refresh is set up
+      start_live_updates
+    end
+
+    def start_live_updates
+      return unless @config.enable_live_updates
+      return if @config.offline_mode?
+
+      @provider.start_websocket
+    end
+
+    def load_snapshot
+      return unless @config.snapshot_provider
+
+      data = @config.snapshot_provider.load
+      return unless data
+
+      @mutex.synchronize do
+        @definitions = data[:definitions]
+      end
+
+      log_debug("Loaded #{@definitions.size} features from snapshot")
+    rescue StandardError => e
+      log_warn("Failed to load snapshot: #{e.message}")
+    end
+
+    def save_snapshot
+      return unless @config.snapshot_provider
+
+      @config.snapshot_provider.save(@definitions)
+      log_debug("Saved snapshot with #{@definitions.size} features")
+    rescue StandardError => e
+      log_warn("Failed to save snapshot: #{e.message}")
+    end
+
+    def development?
+      env = ENV["RACK_ENV"] || ENV["RAILS_ENV"] || ENV["APP_ENV"] || "development"
+      env.downcase == "development"
+    end
+
+    def log_info(message)
+      @config.logger&.info("[Toggly] #{message}")
+    end
+
+    def log_debug(message)
+      @config.logger&.debug("[Toggly] #{message}")
+    end
+
+    def log_warn(message)
+      @config.logger&.warn("[Toggly] #{message}")
+    end
+
+    def log_error(message)
+      @config.logger&.error("[Toggly] #{message}")
+    end
+  end
+end

data/lib/toggly/config.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Toggly
+  # Configuration for the Toggly client.
+  #
+  # @example
+  #   config = Toggly::Config.new(
+  #     app_key: "your-app-key",
+  #     environment: "Production"
+  #   )
+  class Config
+    # @return [String] Application key from Toggly dashboard
+    attr_accessor :app_key
+
+    # @return [String] Environment name (e.g., "Production", "Staging")
+    attr_accessor :environment
+
+    # @return [String] Base URL for Toggly API
+    attr_accessor :base_url
+
+    # @return [String] Definitions URL (overrides base_url for definitions)
+    attr_accessor :definitions_url
+
+    # @return [Integer] Refresh interval in seconds
+    attr_accessor :refresh_interval
+
+    # @return [Integer] HTTP timeout in seconds
+    attr_accessor :http_timeout
+
+    # @return [Boolean] Enable undefined features in development
+    attr_accessor :enable_undefined_in_dev
+
+    # @return [Boolean] Disable background refresh
+    attr_accessor :disable_background_refresh
+
+    # @return [Boolean] Enable WebSocket live updates (default: true)
+    attr_accessor :enable_live_updates
+
+    # @return [String] Application version
+    attr_accessor :app_version
+
+    # @return [String] Instance name for distributed systems
+    attr_accessor :instance_name
+
+    # @return [Hash<String, Boolean>] Default feature values for offline mode
+    attr_accessor :defaults
+
+    # @return [SnapshotProviders::Base, nil] Snapshot provider for persistence
+    attr_accessor :snapshot_provider
+
+    # @return [Boolean] Use signed definitions
+    attr_accessor :use_signed_definitions
+
+    # @return [Array<String>] Allowed key IDs for signed definitions
+    attr_accessor :allowed_key_ids
+
+    # @return [Logger, nil] Logger instance
+    attr_accessor :logger
+
+    # Default values
+    DEFAULT_BASE_URL = "https://definitions.toggly.io/"
+    DEFAULT_REFRESH_INTERVAL = 300 # 5 minutes
+    DEFAULT_HTTP_TIMEOUT = 10 # seconds
+    DEFAULT_ENVIRONMENT = "Production"
+
+    def initialize(**options)
+      @app_key = options[:app_key]
+      @environment = options[:environment] || DEFAULT_ENVIRONMENT
+      @base_url = normalize_url(options[:base_url] || DEFAULT_BASE_URL)
+      @definitions_url = options[:definitions_url]
+      @refresh_interval = options[:refresh_interval] || DEFAULT_REFRESH_INTERVAL
+      @http_timeout = options[:http_timeout] || DEFAULT_HTTP_TIMEOUT
+      @enable_undefined_in_dev = options[:enable_undefined_in_dev] || false
+      @disable_background_refresh = options[:disable_background_refresh] || false
+      @enable_live_updates = options.fetch(:enable_live_updates, true)
+      @app_version = options[:app_version]
+      @instance_name = options[:instance_name]
+      @defaults = options[:defaults] || {}
+      @snapshot_provider = options[:snapshot_provider]
+      @use_signed_definitions = options[:use_signed_definitions] || false
+      @allowed_key_ids = options[:allowed_key_ids] || []
+      @logger = options[:logger]
+    end
+
+    # Get the definitions endpoint URL
+    #
+    # @return [String]
+    def definitions_endpoint
+      base = @definitions_url || @base_url
+      endpoint = @use_signed_definitions ? "definitions-signed" : "definitions"
+      "#{normalize_url(base)}#{endpoint}/#{@app_key}/#{@environment}"
+    end
+
+    # Validate the configuration
+    #
+    # @raise [ConfigError] if configuration is invalid
+    def validate!
+      return if offline_mode?
+
+      raise ConfigError, "app_key is required" if @app_key.nil? || @app_key.empty?
+      raise ConfigError, "environment is required" if @environment.nil? || @environment.empty?
+    end
+
+    # Check if running in offline mode (defaults only)
+    #
+    # @return [Boolean]
+    def offline_mode?
+      (@app_key.nil? || @app_key.empty?) && !@defaults.empty?
+    end
+
+    # Convert to hash
+    #
+    # @return [Hash]
+    def to_h
+      {
+        app_key: @app_key,
+        environment: @environment,
+        base_url: @base_url,
+        definitions_url: @definitions_url,
+        refresh_interval: @refresh_interval,
+        http_timeout: @http_timeout,
+        enable_undefined_in_dev: @enable_undefined_in_dev,
+        disable_background_refresh: @disable_background_refresh,
+        enable_live_updates: @enable_live_updates,
+        app_version: @app_version,
+        instance_name: @instance_name,
+        use_signed_definitions: @use_signed_definitions
+      }
+    end
+
+    private
+
+    def normalize_url(url)
+      return url if url.nil?
+
+      url.end_with?("/") ? url : "#{url}/"
+    end
+  end
+end

data/lib/toggly/context.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Toggly
+  # Evaluation context containing user identity, groups, and traits.
+  #
+  # @example
+  #   context = Toggly::Context.new(
+  #     identity: "user-123",
+  #     groups: ["beta-testers", "premium"],
+  #     traits: { country: "US", plan: "enterprise" }
+  #   )
+  class Context
+    # @return [String, nil] User identity for percentage rollouts and targeting
+    attr_reader :identity
+
+    # @return [Array<String>] Groups the user belongs to
+    attr_reader :groups
+
+    # @return [Hash<String, Object>] Custom traits for contextual targeting
+    attr_reader :traits
+
+    def initialize(identity: nil, groups: [], traits: {})
+      @identity = identity&.to_s
+      @groups = Array(groups).map(&:to_s)
+      @traits = normalize_traits(traits)
+    end
+
+    # Create a context with just an identity
+    #
+    # @param identity [String] User identity
+    # @return [Context]
+    def self.with_identity(identity)
+      new(identity: identity)
+    end
+
+    # Create an empty/anonymous context
+    #
+    # @return [Context]
+    def self.anonymous
+      new
+    end
+
+    # Check if context has an identity
+    #
+    # @return [Boolean]
+    def identity?
+      !@identity.nil? && !@identity.empty?
+    end
+
+    # Check if user is in a specific group
+    #
+    # @param group [String, Symbol] Group name
+    # @return [Boolean]
+    def in_group?(group)
+      @groups.include?(group.to_s)
+    end
+
+    # Get a trait value
+    #
+    # @param key [String, Symbol] Trait key
+    # @return [Object, nil]
+    def trait(key)
+      @traits[key.to_s]
+    end
+    alias [] trait
+
+    # Check if a trait exists
+    #
+    # @param key [String, Symbol] Trait key
+    # @return [Boolean]
+    def trait?(key)
+      @traits.key?(key.to_s)
+    end
+
+    # Create a new context with additional traits
+    #
+    # @param new_traits [Hash] Traits to add
+    # @return [Context]
+    def with_traits(new_traits)
+      Context.new(
+        identity: @identity,
+        groups: @groups,
+        traits: @traits.merge(normalize_traits(new_traits))
+      )
+    end
+
+    # Create a new context with additional groups
+    #
+    # @param new_groups [Array<String>] Groups to add
+    # @return [Context]
+    def with_groups(*new_groups)
+      Context.new(
+        identity: @identity,
+        groups: @groups + new_groups.flatten.map(&:to_s),
+        traits: @traits
+      )
+    end
+
+    # Convert to hash for serialization
+    #
+    # @return [Hash]
+    def to_h
+      {
+        identity: @identity,
+        groups: @groups,
+        traits: @traits
+      }
+    end
+
+    # Check equality
+    #
+    # @param other [Context]
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(Context)
+
+      @identity == other.identity &&
+        @groups.sort == other.groups.sort &&
+        @traits == other.traits
+    end
+    alias eql? ==
+
+    # Hash code for use in collections
+    #
+    # @return [Integer]
+    def hash
+      [@identity, @groups.sort, @traits].hash
+    end
+
+    # Generate cache key
+    #
+    # @return [String]
+    def cache_key
+      "#{@identity}:#{@groups.sort.join(",")}:#{traits_cache_key}"
+    end
+
+    private
+
+    def normalize_traits(traits)
+      return {} unless traits.is_a?(Hash)
+
+      traits.transform_keys(&:to_s)
+    end
+
+    def traits_cache_key
+      @traits.sort.map { |k, v| "#{k}=#{v}" }.join(",")
+    end
+  end
+end