togglecraft 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e77c8218c124ce83fbdc25f2f2975f50ca69fde64b3109116e639580ac5be42
+  data.tar.gz: 872451734b10596e4b11337275454a998605a7966ff7e9f5d575c4764ff2a89e
+SHA512:
+  metadata.gz: 3353a6384c9c2ab564c5244f0c015a723c403287213e6fa6542c0b8cbfbb49bf804d303f3c1d51510c1a07858884b2626a0128a05744d2d0a7e394ad6f1f43b0
+  data.tar.gz: 6a31210c7fb15839f8b5bbb2b85b37c13129f00ea26a57796d885331a5cf981e6c4eefaf7ad69fdd882a05a29acb2b9175321784892a750d087ef9deba4c4e96

data/CHANGELOG.md

@@ -0,0 +1,108 @@
+# 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).
+
+## [1.0.0] - 2025-10-26
+
+### Added
+
+**Core Features:**
+- Real-time feature flag evaluation with Server-Sent Events (SSE)
+- Three flag types: boolean, multivariate, and percentage rollout
+- Advanced targeting rules with 14 operators (equals, contains, regex, semver, etc.)
+- Scheduled rollout stages with automatic percentage transitions
+- Local flag evaluation for zero-latency performance
+- Smart caching with TTL support (memory adapter included)
+- Thread-safe connection pooling for multi-client efficiency
+- Event system for real-time updates (ready, flags_updated, disconnected, error, reconnecting, rollout_stage_changed)
+
+**Client Features:**
+- `Client#enabled?` - Boolean flag evaluation
+- `Client#variant` - Multivariate flag evaluation with weighted distribution
+- `Client#in_percentage?` - Percentage rollout evaluation with consistent hashing
+- `Client#wait_for_ready` - Synchronous initialization support
+- `Client#on`/`once`/`off` - Event listener management
+- Automatic reconnection with exponential backoff and hybrid strategy
+- Graceful degradation with default values
+
+**Connection Management:**
+- Shared SSE connection pooling (default)
+- Dedicated SSE connections (opt-in)
+- Heartbeat mechanism with jitter (0-30s) to prevent thundering herd
+- Zombie connection prevention (critical for billing accuracy)
+- Automatic reconnection with exponential backoff
+- Hybrid reconnection strategy (fast mode → slow mode)
+
+**Developer Experience:**
+- Comprehensive RSpec test suite (375 tests, 87.36% coverage)
+- Full YARD documentation
+- Thread-safe for Puma, Sidekiq, and multi-threaded environments
+- Rails-friendly with initializer examples
+- Zero-build philosophy compatibility
+- Debug logging support
+
+**Documentation:**
+- Complete README with quick start guide
+- API reference documentation
+- Advanced configuration guide
+- Framework integration examples (Rails, Sidekiq)
+- Troubleshooting guide
+- Security policy (SECURITY.md)
+- Publishing guide (PUBLISHING.md)
+
+### Technical Highlights
+
+- **Zombie Connection Prevention:** Heartbeat only sent when SSE connection is actually open, preventing billing for dead connections
+- **Consistent Hashing:** Same user always gets same variant/percentage result across all SDKs
+- **Jitter Support:** Version update fetching includes configurable jitter (default 1500ms) to prevent thundering herd
+- **Thread Safety:** Uses `Concurrent::Map`, `Concurrent::AtomicBoolean`, and proper mutex locking throughout
+- **Connection Pooling:** Multiple clients can share a single SSE connection for efficiency
+- **Rollout Stage Polling:** Automatic detection of scheduled percentage increases (every 60s, configurable)
+
+### Dependencies
+
+**Runtime:**
+- `concurrent-ruby` ~> 1.2 (thread-safe data structures)
+- `http` ~> 5.0 (HTTP client for SSE and heartbeat)
+
+**Development:**
+- `rspec` ~> 3.12 (testing framework)
+- `rubocop` ~> 1.59 (linting)
+- `simplecov` ~> 0.22 (code coverage)
+- `webmock` ~> 3.19 (HTTP mocking)
+
+### Requirements
+
+- Ruby 3.0 or higher
+- Compatible with Rails 6.0+, Sinatra, Hanami, and standalone Ruby applications
+
+### Performance
+
+- **Zero-latency local evaluation:** All flag evaluation happens locally after initial SSE connection
+- **Minimal bandwidth:** Only flag changes trigger SSE messages
+- **Efficient connection pooling:** Share one SSE connection across multiple client instances
+- **Smart caching:** Reduces server load with configurable TTL
+
+### Security
+
+- MFA required for RubyGems publishing (`rubygems_mfa_required: true`)
+- No credentials in code (SDK key passed at initialization)
+- HTTPS-only connections (enforced)
+- Security policy documented in SECURITY.md
+
+---
+
+## [Unreleased]
+
+### Planned Features
+- Redis cache adapter
+- Custom cache adapter support
+- Additional targeting operators
+- Metrics and analytics integration
+
+---
+
+[1.0.0]: https://github.com/togglecraft/ruby-sdk/releases/tag/v1.0.0

data/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2025 ToggleCraft
+
+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,347 @@
+# ToggleCraft Ruby SDK
+
+A lightweight, real-time feature flag SDK for Ruby applications. Thread-safe, Rails-friendly, and built for production.
+
+## Why ToggleCraft?
+
+- 🚀 **Real-time Updates** - Instant flag changes via Server-Sent Events
+- 🧵 **Thread-Safe** - Built for Puma, Sidekiq, and multi-threaded environments
+- 💾 **Smart Caching** - Works offline with memory or Redis support
+- 🔒 **Production Ready** - 214 passing tests with comprehensive coverage
+- 🌐 **Universal** - Works with Rails, Sinatra, Hanami, and standalone Ruby
+- ♻️ **Auto-reconnection** - Resilient connection handling
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'togglecraft'
+```
+
+Or install directly:
+
+```bash
+gem install togglecraft
+```
+
+## Quick Start
+
+### Ruby
+
+```ruby
+require 'togglecraft'
+
+# Initialize client
+client = ToggleCraft::Client.new(sdk_key: 'your-sdk-key')
+
+# Connect and wait for flags
+client.connect
+client.wait_for_ready
+
+# Use your flags
+if client.enabled?('new-feature', user: { id: current_user.id })
+  # Feature is enabled
+end
+```
+
+### Rails
+
+```ruby
+# config/initializers/togglecraft.rb
+Rails.application.config.togglecraft = ToggleCraft::Client.new(
+  sdk_key: ENV['TOGGLECRAFT_SDK_KEY'],
+  cache_adapter: :memory,
+  logger: Rails.logger,
+  debug: Rails.env.development?
+)
+
+Rails.application.config.togglecraft.connect
+
+at_exit do
+  Rails.application.config.togglecraft.destroy
+end
+```
+
+Then use in your controllers:
+
+```ruby
+class DashboardController < ApplicationController
+  def index
+    if togglecraft.enabled?('premium-dashboard', user: { id: current_user.id })
+      render :premium
+    else
+      render :standard
+    end
+  end
+
+  private
+
+  def togglecraft
+    Rails.application.config.togglecraft
+  end
+end
+```
+
+## Basic Usage
+
+### Boolean Flags
+
+Simple on/off feature toggles:
+
+```ruby
+if client.enabled?('dark-mode', user: { id: '123' })
+  enable_dark_mode
+end
+```
+
+### Multivariate Flags
+
+A/B/n testing with multiple variants:
+
+```ruby
+variant = client.variant('checkout-flow', user: { id: '123' })
+
+case variant
+when 'one-page'
+  render_one_page_checkout
+when 'multi-step'
+  render_multi_step_checkout
+else
+  render_default_checkout
+end
+```
+
+### Percentage Rollouts
+
+Gradual feature rollouts:
+
+```ruby
+if client.in_percentage?('new-algorithm', user: { id: '123' })
+  use_new_algorithm
+else
+  use_legacy_algorithm
+end
+```
+
+## Configuration
+
+```ruby
+client = ToggleCraft::Client.new(
+  # Required
+  sdk_key: 'your-sdk-key',              # Get from ToggleCraft dashboard
+
+  # Optional - Common settings
+  enable_cache: true,                   # Enable caching (default: true)
+  cache_adapter: :memory,               # :memory or :redis (default: :memory)
+  cache_ttl: 300,                       # Cache TTL in seconds (default: 5 minutes)
+  debug: false                          # Enable debug logging (default: false)
+)
+```
+
+**Need more control?** See [Advanced Configuration →](docs/ADVANCED.md)
+
+## Evaluation Context
+
+The context object provides data for targeting rules:
+
+```ruby
+context = {
+  user: {
+    id: 'user-123',                     # Required for consistent evaluation
+    email: 'user@example.com',
+    plan: 'premium',
+    # Add any custom attributes you need
+    role: 'admin',
+    company_id: 'acme-corp'
+  },
+  request: {
+    ip: '192.168.1.1',
+    country: 'US'
+  },
+  device: {
+    type: 'mobile',
+    os: 'iOS'
+  }
+}
+
+client.enabled?('premium-feature', context)
+```
+
+You can add any custom properties - the SDK evaluates all attributes using dot notation (e.g., `user.role`, `request.country`).
+
+## Framework Integration
+
+### Rails
+
+```ruby
+# config/initializers/togglecraft.rb
+Rails.application.config.togglecraft = ToggleCraft::Client.new(
+  sdk_key: ENV['TOGGLECRAFT_SDK_KEY'],
+  cache_adapter: :memory,
+  logger: Rails.logger
+)
+```
+
+[Full Rails Integration Guide →](docs/FRAMEWORKS.md#rails)
+
+### Sidekiq
+
+```ruby
+class FeatureWorker
+  include Sidekiq::Worker
+
+  def togglecraft
+    @togglecraft ||= ToggleCraft::Client.new(
+      sdk_key: ENV['TOGGLECRAFT_SDK_KEY'],
+      share_connection: true  # Share connection with other workers
+    )
+  end
+
+  def perform(user_id)
+    togglecraft.connect unless togglecraft.connected?
+
+    if togglecraft.enabled?('batch-processing', user: { id: user_id })
+      # Use new batch processing
+    end
+  end
+end
+```
+
+[Full Sidekiq Integration Guide →](docs/FRAMEWORKS.md#sidekiq)
+
+## Event Handling
+
+Listen for real-time updates:
+
+```ruby
+# Flags are ready
+client.on(:ready) do
+  puts 'Client ready!'
+end
+
+# Flags updated in real-time
+client.on(:flags_updated) do |flags|
+  puts "Flags updated: #{flags.keys.join(', ')}"
+end
+
+# Connection lost
+client.on(:disconnected) do
+  puts 'Disconnected - using cached flags'
+end
+
+# Error occurred
+client.on(:error) do |error|
+  logger.error "ToggleCraft error: #{error}"
+end
+```
+
+## Error Handling
+
+Always provide default values and handle errors gracefully:
+
+```ruby
+# Safe evaluation with defaults
+is_enabled = client.enabled?('feature', context, default: false)
+# Returns false if flag doesn't exist or on error
+
+# Handle connection errors
+begin
+  client.connect
+rescue StandardError => e
+  logger.error "Failed to connect: #{e}"
+  # App still works with cached values or defaults
+end
+```
+
+## Best Practices
+
+1. **Initialize Once** - Create a single client instance and reuse it
+2. **Always Provide Context** - Include at least `user.id` for consistent evaluation
+3. **Use Default Values** - Handle missing flags gracefully
+4. **Clean Up on Shutdown** - Call `client.destroy` when closing
+
+```ruby
+# On application shutdown
+at_exit do
+  client.destroy
+end
+```
+
+## API Reference
+
+**Core Methods:**
+- `enabled?(flag_key, context = {}, default: false)` - Check boolean flags
+- `variant(flag_key, context = {}, default: nil)` - Get multivariate variant
+- `in_percentage?(flag_key, context = {}, default: false)` - Check percentage rollout
+
+**Connection:**
+- `connect` - Connect to SSE server
+- `disconnect` - Disconnect from server
+- `ready?` - Check if client has flags loaded
+- `wait_for_ready(timeout: 5)` - Wait for client to be ready
+
+[Full API Documentation →](docs/API.md)
+
+## Advanced Features
+
+Power users can customize:
+- Connection pooling and reconnection strategies
+- Scheduled rollout stages with automatic transitions
+- Redis cache adapter
+- Hybrid reconnection with exponential backoff
+
+[Advanced Features Guide →](docs/ADVANCED.md)
+
+## Troubleshooting
+
+**Client not connecting?**
+- Verify your SDK key is correct
+- Check that you called `connect` before using the client
+- Ensure your firewall allows connections to `sse.togglecraft.io`
+
+**Flags not updating?**
+- Verify the SSE connection is established (`client.connected?`)
+- Check the logs for error messages
+- Enable debug mode: `debug: true`
+
+[More Troubleshooting →](docs/TROUBLESHOOTING.md)
+
+## Requirements
+
+- **Ruby 3.0+**
+- **Dependencies:**
+  - `concurrent-ruby` (~> 1.2) - Thread-safe data structures
+  - `http` (~> 5.0) - HTTP client for API requests
+  - `semantic` (~> 1.6) - Semantic version comparison
+
+## Thread Safety
+
+This SDK is fully thread-safe and production-ready for:
+- **Puma** - Multi-threaded Rails server
+- **Sidekiq** - Background job processing
+- **Any multi-threaded Ruby environment**
+
+All critical sections use `Concurrent::Map`, `Mutex`, and `Concurrent::AtomicBoolean` for thread safety.
+
+## Documentation
+
+- [API Reference](docs/API.md) - Complete API documentation
+- [Advanced Features](docs/ADVANCED.md) - Connection pooling, rollout stages, custom configuration
+- [Framework Integration](docs/FRAMEWORKS.md) - Rails, Sidekiq, and other framework guides
+- [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions
+- [Security](SECURITY.md) - Security best practices and policies
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on GitHub.
+
+## Support
+
+- **Documentation:** [GitHub Repository](https://github.com/togglecraft/ruby-sdk)
+- **Issues:** [GitHub Issues](https://github.com/togglecraft/ruby-sdk/issues)
+- **Security:** See [SECURITY.md](SECURITY.md) for reporting vulnerabilities

data/lib/togglecraft/cache.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require_relative 'cache_adapters/memory_adapter'
+
+module ToggleCraft
+  # Cache manager with TTL support and multiple adapters
+  class Cache
+    attr_reader :adapter, :default_ttl
+
+    # Initialize the cache
+    # @param adapter [Symbol, Object] The cache adapter (:memory or custom adapter instance)
+    # @param ttl [Integer] Default TTL in seconds (default: 300 = 5 minutes)
+    def initialize(adapter: :memory, ttl: 300)
+      @default_ttl = ttl
+      @adapter = case adapter
+                 when :memory
+                   CacheAdapters::MemoryAdapter.new
+                 else
+                   adapter
+                 end
+      @cleanup_thread = nil
+      start_cleanup
+    end
+
+    # Get a value from cache
+    # Returns nil if key doesn't exist or is expired
+    # @param key [String] The cache key
+    # @return [Object, nil] The cached value or nil
+    def get(key)
+      entry = @adapter.get(key)
+      return nil unless entry
+      return nil if expired?(entry)
+
+      entry[:value]
+    end
+
+    # Set a value in cache with optional TTL override
+    # @param key [String] The cache key
+    # @param value [Object] The value to cache
+    # @param ttl [Integer, nil] Optional TTL override in seconds
+    def set(key, value, ttl: nil)
+      entry = {
+        value: value,
+        timestamp: Time.now.to_f,
+        ttl: ttl || @default_ttl
+      }
+      @adapter.set(key, entry)
+    end
+
+    # Delete a value from cache
+    # @param key [String] The cache key
+    # @return [Boolean] true if deleted, false otherwise
+    def delete(key)
+      @adapter.delete(key)
+    end
+
+    # Clear all cache entries
+    def clear
+      @adapter.clear
+    end
+
+    # Check if a key exists in cache (and is not expired)
+    # @param key [String] The cache key
+    # @return [Boolean]
+    def has?(key)
+      entry = @adapter.get(key)
+      return false unless entry
+      return false if expired?(entry)
+
+      true
+    end
+
+    # Delete all keys matching a prefix
+    # @param prefix [String] The prefix to match
+    def clear_by_prefix(prefix)
+      keys_to_delete = @adapter.keys.select { |key| key.start_with?(prefix) }
+      keys_to_delete.each { |key| delete(key) }
+    end
+
+    # Get all cached flags (non-expired)
+    # @return [Hash] Hash of flag_key => flag_data
+    def all_flags
+      flags = {}
+      @adapter.keys.each do |key|
+        next unless key.start_with?('flag:')
+
+        flag_key = key.sub('flag:', '')
+        value = get(key)
+        flags[flag_key] = value if value
+      end
+      flags
+    end
+
+    # Store all flags at once
+    # @param flags [Hash] Hash of flag_key => flag_data
+    # @param ttl [Integer, nil] Optional TTL override
+    def set_all_flags(flags, ttl: nil)
+      flags.each do |flag_key, flag_data|
+        set("flag:#{flag_key}", flag_data, ttl: ttl)
+      end
+    end
+
+    # Clean up resources and stop background cleanup
+    def destroy
+      stop_cleanup
+      clear
+    end
+
+    private
+
+    # Check if an entry is expired
+    # @param entry [Hash] The cache entry
+    # @return [Boolean]
+    def expired?(entry)
+      return false unless entry[:timestamp] && entry[:ttl]
+
+      Time.now.to_f - entry[:timestamp] > entry[:ttl]
+    end
+
+    # Start periodic cleanup of expired entries
+    def start_cleanup
+      return if @cleanup_thread
+
+      @cleanup_thread = Thread.new do
+        loop do
+          sleep 60 # Run cleanup every minute
+          cleanup_expired
+        rescue StandardError => e
+          warn "[ToggleCraft Cache] Cleanup thread error: #{e.message}"
+        end
+      end
+      @cleanup_thread.abort_on_exception = false
+    end
+
+    # Clean up expired entries
+    def cleanup_expired
+      @adapter.keys.each do |key|
+        entry = @adapter.get(key)
+        delete(key) if entry && expired?(entry)
+      end
+    end
+
+    # Stop the cleanup thread
+    def stop_cleanup
+      return unless @cleanup_thread
+
+      @cleanup_thread.kill
+      @cleanup_thread = nil
+    end
+  end
+end

data/lib/togglecraft/cache_adapters/memory_adapter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'concurrent'
+
+module ToggleCraft
+  module CacheAdapters
+    # In-memory cache adapter using thread-safe Concurrent::Map
+    # Suitable for single-process applications
+    class MemoryAdapter
+      def initialize
+        @store = Concurrent::Map.new
+      end
+
+      # Get a value from the store
+      # @param key [String] The cache key
+      # @return [Object, nil] The stored value or nil
+      def get(key)
+        @store[key]
+      end
+
+      # Set a value in the store
+      # @param key [String] The cache key
+      # @param value [Object] The value to store
+      def set(key, value)
+        @store[key] = value
+      end
+
+      # Delete a value from the store
+      # @param key [String] The cache key
+      # @return [Boolean] true if deleted, false otherwise
+      def delete(key)
+        !@store.delete(key).nil?
+      end
+
+      # Clear all values from the store
+      def clear
+        @store.clear
+      end
+
+      # Check if a key exists in the store
+      # @param key [String] The cache key
+      # @return [Boolean]
+      def has?(key)
+        @store.key?(key)
+      end
+
+      # Get all keys in the store
+      # @return [Array<String>]
+      def keys
+        @store.keys
+      end
+    end
+  end
+end