flipper 1.3.5 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a0f7fc2b532a31e1f4b4cf56421b7e296d12ad92eb12d817571d480d211004c6
-  data.tar.gz: 37fccbcff9644cda8c874f745b32ce5dbcdd650494f9921807985e8a7da83cdf
+  metadata.gz: 881ca599099f433a4204f2a058c512b6b9198f529d1db4fd3a3445ba822dcd9b
+  data.tar.gz: 5ad5da793cec928e09357f2d46ddb139c159dfc1d5b9ddea4ae4c0c52193a75b
 SHA512:
-  metadata.gz: b452ac3f04236bc0adcf1f96b086cc7c29780d694fceddae975687dfbbaf796b41eaa867d2c5748cf61b4071b9d4f2b189f2921fe8a37b85222499fb9207aea2
-  data.tar.gz: 2eb9788694d89d2777386032f173f3a616438d4f57f29b1b84a2321cd44e4aa4fb342c89c8f891e353710f5a41329f5473bbbe824385bd5a419d8463961c33a8
+  metadata.gz: 9b049bcd83af70810efd36f1873fb9d72cf22f95cf460d80829b7ad7ed68b7ef11e619b621ea001c230dfdbee43c453e76326de59be2306ee52b23444b50619b
+  data.tar.gz: fb82eca0e34233cf3fe9e001923f3b87ae2acf9f7dfdbbdce553d1b8408d5f23df075d789f5be2f975d6facf077637294f306d774e026005e4a7a13124866a3a

data/.github/workflows/ci.yml

@@ -1,9 +1,11 @@
 name: CI
-on: [push, pull_request]
+on: [push]
+
 jobs:
   test:
     name: Test on ruby ${{ matrix.ruby }} and rails ${{ matrix.rails }}
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     services:
       redis:
         image: redis
@@ -13,6 +15,9 @@ jobs:
           --health-interval 10s
           --health-timeout 5s
           --health-retries 5
+      memcached:
+        image: memcached
+        ports: ["11211:11211"]
       postgres:
         image: postgres:13
         ports:
@@ -81,14 +86,12 @@ jobs:
     steps:
       - name: Set up MySQL
         run: sudo /etc/init.d/mysql start
-      - name: Setup memcached
-        uses: KeisukeYamashita/memcached-actions@v1
       - name: Start MongoDB
-        uses: supercharge/mongodb-github-action@1.12.0
+        uses: supercharge/mongodb-github-action@1.12.1
         with:
           mongodb-version: 4.0
       - name: Check out repository code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Do some action caching
         uses: actions/cache@v4
         with:

data/.github/workflows/examples.yml

@@ -1,10 +1,11 @@
 name: Examples
-on: [push, pull_request]
+on: [push]
 jobs:
   test:
     if: github.repository_owner == 'flippercloud'
     name: Example on ruby ${{ matrix.ruby }} and rails ${{ matrix.rails }}
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     services:
       redis:
         image: redis
@@ -66,11 +67,11 @@ jobs:
       - name: Setup memcached
         uses: KeisukeYamashita/memcached-actions@v1
       - name: Start MongoDB
-        uses: supercharge/mongodb-github-action@1.12.0
+        uses: supercharge/mongodb-github-action@1.12.1
         with:
           mongodb-version: 4.0
       - name: Check out repository code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
       - name: Do some action caching
         uses: actions/cache@v4
         with:

data/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # RubyGems trusted publishing (OIDC)
+      contents: write   # Create GitHub Releases
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+
+      - name: Build all gems
+        run: |
+          for gemspec in *.gemspec; do
+            gem build "$gemspec"
+          done
+          mkdir -p pkg
+          mv *.gem pkg/
+          echo "Built gems:"
+          ls -la pkg/
+
+      - name: Configure RubyGems credentials
+        uses: rubygems/configure-rubygems-credentials@v1.0.0
+
+      - name: Publish all gems
+        run: |
+          # Push core gem first since other gems depend on it
+          echo "Pushing flipper core gem..."
+          gem push pkg/flipper-[0-9]*.gem || echo "Core gem already pushed, continuing..."
+
+          for gem_file in pkg/flipper-*.gem; do
+            basename="$(basename "$gem_file")"
+            if [[ "$basename" =~ ^flipper-[0-9] ]]; then
+              continue
+            fi
+            echo "Pushing $basename..."
+            gem push "$gem_file" || echo "Failed to push $basename, continuing..."
+          done
+
+      - name: Create draft GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          draft: true
+          generate_release_notes: true
+          files: pkg/*.gem

data/CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Testing
+- `bundle exec rake` - Run all tests (RSpec, Minitest, and Rails tests)
+- `bundle exec rspec` - Run RSpec tests only
+- `bundle exec rake spec:ui` - Run UI-specific specs
+- `bundle exec rake test` - Run Minitest tests only
+- `bundle exec rake test_rails` - Run Rails generator tests
+- `script/test` - Bootstrap and run tests across multiple Rails versions (5.0-8.0)
+
+### Development Setup
+- `script/bootstrap` - Bundle install dependencies and setup binstubs
+- `script/console` - Start interactive console with Flipper loaded (uses Pry)
+- `script/server` - Start local UI server on port 9999 for testing web interface
+
+### Releasing
+1. Bump version in `lib/flipper/version.rb`, commit, and push to main
+2. Tag and push: `git tag v1.x.x && git push origin v1.x.x`
+3. GitHub Actions (`.github/workflows/release.yml`) builds and publishes all 12 gems via RubyGems trusted publishing, then creates a draft GitHub Release
+4. Edit and publish the draft release at https://github.com/flippercloud/flipper/releases
+
+- `bundle exec rake build` - Build all gems locally into pkg/ directory
+- `script/release` - Manual fallback for local releases (prompts for OTP)
+
+## Architecture Overview
+
+Flipper is a feature flag library for Ruby with a modular adapter-based architecture:
+
+### Core Components
+
+**DSL Layer** (`lib/flipper/dsl.rb`):
+- Main interface for feature flag operations
+- Delegates to Feature instances
+- Handles memoization and instrumentation
+- Thread-safe instance management
+
+**Feature** (`lib/flipper/feature.rb`):
+- Represents individual feature flags
+- Manages enable/disable operations through gates
+- Handles instrumentation events
+- Works with adapters for persistence
+
+**Adapters** (`lib/flipper/adapters/`):
+- Pluggable storage backends (Redis, ActiveRecord, Memory, etc.)
+- Common interface for all storage implementations
+- Support for caching, failover, and synchronization patterns
+
+**Gates** (`lib/flipper/gates/`):
+- Different targeting mechanisms:
+  - Boolean (on/off for everyone)
+  - Actor (specific users/entities)
+  - Group (predefined user groups)
+  - Percentage of Actors (rollout to X% of users)
+  - Percentage of Time (probabilistic enabling)
+  - Expression (complex conditional logic)
+
+### Multi-Gem Structure
+
+The project is structured as multiple gems:
+- `flipper` - Core library
+- `flipper-ui` - Web interface
+- `flipper-api` - REST API
+- `flipper-cloud` - Cloud service integration
+- `flipper-*` - Various adapter gems (redis, active_record, mongo, etc.)
+
+### Key Patterns
+
+**Configuration**: Global configuration through `Flipper.configure` with per-thread instances
+**Instrumentation**: Built-in event system for monitoring and debugging
+**Memoization**: Automatic caching of feature checks within request/thread scope
+**Type Safety**: Strong typing system for actors, percentages, and other values
+
+### Serialization and HTTP
+
+Use `Flipper::Typecast` for JSON and gzip serialization instead of calling `JSON.generate`/`JSON.parse` or `Zlib` directly:
+- `Typecast.to_json(hash)` / `Typecast.from_json(string)` for JSON serialization
+- `Typecast.to_gzip(string)` / `Typecast.from_gzip(string)` for gzip compression
+
+For outbound HTTP requests, use `Flipper::Adapters::Http::Client` instead of raw `Net::HTTP`. It provides timeouts, retries (`max_retries`), SSL verification, and diagnostic headers (user-agent, client-language, client-platform, etc.). See `lib/flipper/cloud/migrate.rb` for an example.
+
+### Testing
+
+Uses both RSpec (currently preferred for new tests) and Minitest. Shared adapter specs ensure consistency across all storage backends. Extensive testing across multiple Rails versions (5.0-8.0).

data/README.md

@@ -97,9 +97,10 @@ We also have a [free plan](https://www.flippercloud.io?utm_source=oss&utm_medium
 
 ## Releasing
 
-1. Update the version to be whatever it should be and commit.
-2. `script/release`
-3. Create a new [GitHub Release](https://github.com/flippercloud/flipper/releases/new)
+1. Update the version in `lib/flipper/version.rb` and commit.
+2. Tag and push: `git tag v1.x.x && git push origin v1.x.x`
+3. GitHub Actions builds and publishes all gems to RubyGems automatically.
+4. Edit and publish the draft [GitHub Release](https://github.com/flippercloud/flipper/releases).
 
 ## Brought To You By
 

data/examples/cloud/poll_interval/README.md

@@ -0,0 +1,111 @@
+# Poll Interval Dynamic Adjustment Demo
+
+This demo shows how the Flipper poller dynamically adjusts its polling interval based on the `poll-interval` header from the server, and how it responds to the `poll-shutdown` header.
+
+## Files
+
+- `server.rb` - Test server that responds with configurable headers
+- `client.rb` - Client that polls the server and logs interval changes
+- `README.md` - This file
+
+## How to Run
+
+### Terminal 1: Start the Server
+
+```bash
+bundle exec ruby examples/cloud/poll_interval/server.rb
+```
+
+The server will start on http://localhost:3000 and show a prompt where you can control what headers to send.
+
+### Terminal 2: Start the Client
+
+```bash
+bundle exec ruby examples/cloud/poll_interval/client.rb
+```
+
+The client will start polling the server every 10 seconds (the minimum) and log all activity.
+
+## Testing Scenarios
+
+### 1. Change Poll Interval
+
+In the **server terminal**, type a number to set the poll interval:
+
+```
+> 20
+```
+
+In the **client terminal**, you'll see:
+
+```
+[HH:MM:SS] WARN: ⚠️  INTERVAL CHANGED: 10.0s → 20.0s
+```
+
+The client will now poll every 20 seconds instead of 10.
+
+### 2. Try an Invalid Interval (Below Minimum)
+
+In the **server terminal**:
+
+```
+> 5
+```
+
+In the **client terminal**, you'll see a warning:
+
+```
+Flipper::Cloud poll interval must be greater than or equal to 10 but was 5.0. Setting interval to 10.
+```
+
+The interval will remain at 10 seconds (the minimum).
+
+### 3. Trigger Shutdown
+
+In the **server terminal**:
+
+```
+> shutdown
+```
+
+In the **client terminal**, you'll see:
+
+```
+[HH:MM:SS] WARN: Shutdown requested by server via poll-shutdown header
+[HH:MM:SS] WARN: Poller stopped
+[HH:MM:SS] WARN: Poller thread is no longer running
+```
+
+The poller will stop gracefully.
+
+### 4. Reset Headers
+
+In the **server terminal**:
+
+```
+> reset
+```
+
+The server will stop sending special headers. The client will continue with its current interval.
+
+## What You'll Learn
+
+- How `poll-interval` header dynamically adjusts polling frequency
+- How `poll-shutdown` header gracefully stops the poller
+- How minimum interval enforcement works (10 seconds minimum)
+- How the poller continues working even if the server returns errors
+- Real-time logging of poller events via instrumentation
+
+## Implementation Details
+
+The poller checks response headers in the `ensure` block of the `sync` method, which means:
+
+- Interval adjustments happen even if the sync fails with an error
+- Shutdown signals are never missed, even during failures
+- The poller is resilient to network issues
+
+The `interval=` setter handles all validation:
+
+- Type conversion via `Flipper::Typecast.to_float`
+- Minimum enforcement (10 seconds)
+- Warning messages for invalid values

data/examples/cloud/poll_interval/client.rb

@@ -0,0 +1,108 @@
+# Example showing poll interval being dynamically adjusted via poll-interval header
+#
+# Usage:
+#   1. Terminal 1: bundle exec ruby examples/cloud/poll_interval/server.rb
+#   2. Terminal 2: bundle exec ruby examples/cloud/poll_interval/client.rb
+
+require 'bundler/setup'
+require 'flipper'
+require 'flipper/adapters/http'
+require 'flipper/poller'
+require 'logger'
+
+# Setup logging to show what's happening
+logger = Logger.new(STDOUT)
+logger.level = Logger::INFO
+logger.formatter = proc do |severity, datetime, progname, msg|
+  "[#{datetime.strftime('%H:%M:%S')}] #{severity}: #{msg}\n"
+end
+
+# Create HTTP adapter pointing to localhost:3000
+http_adapter = Flipper::Adapters::Http.new(url: 'http://localhost:3000/flipper')
+
+# Create instrumenter to log poller events
+instrumenter = Module.new do
+  def self.instrument(name, payload = {})
+    case payload[:operation]
+    when :poll
+      logger.info "Polling remote adapter..."
+    when :shutdown_requested
+      logger.warn "Shutdown requested by server via poll-shutdown header"
+    when :stop
+      logger.warn "Poller stopped"
+    when :thread_start
+      logger.info "Poller thread started"
+    end
+
+    result = yield if block_given?
+
+    if payload[:operation] == :poll && result
+      logger.info "Poll completed successfully"
+    end
+
+    result
+  end
+
+  def self.logger=(l)
+    @logger = l
+  end
+
+  def self.logger
+    @logger
+  end
+end
+instrumenter.logger = logger
+
+# Create poller with custom instrumenter and short initial interval
+poller = Flipper::Poller.new(
+  remote_adapter: http_adapter,
+  interval: 5,  # Start with 5 second interval (will be enforced to 10 minimum)
+  instrumenter: instrumenter,
+  start_automatically: false,
+  shutdown_automatically: false
+)
+
+logger.info "Starting poller with interval: #{poller.interval} seconds"
+logger.info "Minimum allowed interval: #{Flipper::Poller::MINIMUM_POLL_INTERVAL} seconds"
+logger.info ""
+logger.info "Server can control polling via response headers:"
+logger.info "  - poll-interval: <seconds>  (adjust poll frequency)"
+logger.info "  - poll-shutdown: true       (stop polling)"
+logger.info ""
+
+# Track interval changes
+last_interval = poller.interval
+
+# Start the poller
+poller.start
+
+# Monitor for interval changes and log them
+logger.info "Monitoring poller... (Ctrl+C to exit)"
+logger.info ""
+
+begin
+  loop do
+    sleep 2
+
+    current_interval = poller.interval
+
+    # Highlight when it changes
+    if current_interval != last_interval
+      logger.warn "⚠️  INTERVAL CHANGED: #{last_interval}s → #{current_interval}s"
+      last_interval = current_interval
+    end
+
+    # Check if poller thread is still alive
+    unless poller.thread&.alive?
+      logger.warn "Poller thread is no longer running"
+      break
+    end
+  end
+rescue Interrupt
+  logger.info ""
+  logger.info "Interrupted by user"
+ensure
+  logger.info "Stopping poller..."
+  poller.stop
+  logger.info "Final interval: #{poller.interval} seconds"
+end

data/examples/cloud/poll_interval/server.rb

@@ -0,0 +1,98 @@
+# Simple test server for demonstrating poll interval changes
+#
+# Usage:
+#   1. Terminal 1: bundle exec ruby examples/cloud/poll_interval/server.rb
+#   2. Terminal 2: bundle exec ruby examples/cloud/poll_interval/client.rb
+#
+# Commands in server terminal:
+#   - Type a number (e.g., "15") to set poll-interval header to that value
+#   - Type "shutdown" to send poll-shutdown: true header
+#   - Type "reset" to stop sending special headers
+#   - Ctrl+C to exit
+
+require 'bundler/setup'
+require 'webrick'
+require 'json'
+
+# State for what headers to send
+$poll_interval = nil
+$poll_shutdown = false
+
+# Thread to handle user input for changing headers
+input_thread = Thread.new do
+  puts ""
+  puts "=" * 60
+  puts "Server Controls:"
+  puts "  Type a number (e.g., '15') to set poll-interval"
+  puts "  Type 'shutdown' to trigger poll shutdown"
+  puts "  Type 'reset' to clear all special headers"
+  puts "=" * 60
+  puts ""
+
+  loop do
+    print "> "
+    input = gets&.chomp
+    break if input.nil?
+
+    case input
+    when /^\d+$/
+      $poll_interval = input.to_i
+      puts "✓ Will send poll-interval: #{$poll_interval}"
+    when "shutdown"
+      $poll_shutdown = true
+      puts "✓ Will send poll-shutdown: true"
+    when "reset"
+      $poll_interval = nil
+      $poll_shutdown = false
+      puts "✓ Cleared all special headers"
+    else
+      puts "Unknown command. Use a number, 'shutdown', or 'reset'"
+    end
+  end
+end
+
+# Setup WEBrick server
+server = WEBrick::HTTPServer.new(
+  Port: 3000,
+  Logger: WEBrick::Log.new($stdout, WEBrick::Log::INFO),
+  AccessLog: [[
+    $stdout,
+    WEBrick::AccessLog::COMMON_LOG_FORMAT
+  ]]
+)
+
+# Handle GET /flipper/features
+server.mount_proc '/flipper/features' do |req, res|
+  # Build response
+  response_body = {
+    features: []
+  }
+
+  res.status = 200
+  res['Content-Type'] = 'application/json'
+  res.body = JSON.generate(response_body)
+
+  # Add special headers if configured
+  if $poll_interval
+    res['poll-interval'] = $poll_interval.to_s
+    puts "→ Sent poll-interval: #{$poll_interval}"
+  end
+
+  if $poll_shutdown
+    res['poll-shutdown'] = 'true'
+    puts "→ Sent poll-shutdown: true"
+  end
+end
+
+# Trap interrupt and shutdown gracefully
+trap('INT') do
+  puts "\nShutting down server..."
+  server.shutdown
+  input_thread.kill
+end
+
+puts "Server starting on http://localhost:3000"
+puts "Endpoint: GET http://localhost:3000/flipper/features"
+puts ""
+
+server.start

data/examples/expressions.rb

@@ -31,13 +31,9 @@ class Org < Struct.new(:id, :flipper_properties)
   include Flipper::Identifier
 end
 
-NOW = Time.now.to_i
-DAY = 60 * 60 * 24
-
 org = Org.new(1, {
   "type" => "Org",
   "id" => 1,
-  "now" => NOW,
 })
 
 user = User.new(1, {
@@ -46,7 +42,6 @@ user = User.new(1, {
   "plan" => "basic",
   "age" => 39,
   "team_user" => true,
-  "now" => NOW,
 })
 
 admin_user = User.new(2, {
@@ -54,7 +49,6 @@ admin_user = User.new(2, {
   "id" => 2,
   "admin" => true,
   "team_user" => true,
-  "now" => NOW,
 })
 
 other_user = User.new(3, {
@@ -63,7 +57,6 @@ other_user = User.new(3, {
   "plan" => "plus",
   "age" => 18,
   "org_admin" => true,
-  "now" => NOW - DAY,
 })
 
 age_expression = Flipper.property(:age).gte(21)
@@ -205,9 +198,40 @@ assert Flipper.enabled?(:something, user)
 assert Flipper.enabled?(:something, admin_user)
 refute Flipper.enabled?(:something, other_user)
 
-puts "\n\nEnabling based on time"
-scheduled_time_expression = Flipper.property(:now).gte(NOW)
-Flipper.enable :something, scheduled_time_expression
+puts "\n\nEnabling based on time (epoch)"
+scheduled_epoch = Flipper.now.gte(Flipper.time(Time.now.to_i - 86_400))
+Flipper.enable :something, scheduled_epoch
 assert Flipper.enabled?(:something, user)
 assert Flipper.enabled?(:something, admin_user)
-refute Flipper.enabled?(:something, other_user)
+assert Flipper.enabled?(:something, other_user)
+reset
+
+puts "\n\nEnabling based on time (datetime)"
+past_time = (Time.now.utc - 86_400).iso8601
+scheduled_datetime = Flipper.now.gte(Flipper.time(past_time))
+Flipper.enable :something, scheduled_datetime
+assert Flipper.enabled?(:something, user)
+assert Flipper.enabled?(:something, admin_user)
+assert Flipper.enabled?(:something, other_user)
+reset
+
+puts "\n\nDisabling after a time (expiring feature)"
+future_time = (Time.now.utc + 86_400).iso8601
+expiring_expression = Flipper.now.lt(Flipper.time(future_time))
+Flipper.enable :something, expiring_expression
+assert Flipper.enabled?(:something, user)
+assert Flipper.enabled?(:something, admin_user)
+assert Flipper.enabled?(:something, other_user)
+reset
+
+puts "\n\nEnabling within a time window"
+start_time = (Time.now.utc - 86_400).iso8601
+end_time = (Time.now.utc + 86_400).iso8601
+time_window = Flipper.all(
+  Flipper.now.gte(Flipper.time(start_time)),
+  Flipper.now.lt(Flipper.time(end_time))
+)
+Flipper.enable :something, time_window
+assert Flipper.enabled?(:something, user)
+assert Flipper.enabled?(:something, admin_user)
+assert Flipper.enabled?(:something, other_user)

data/lib/flipper/adapter.rb

@@ -31,7 +31,7 @@ module Flipper
     # Public: Get all features and gate values in one call. Defaults to one call
     # to features and another to get_multi. Feel free to override per adapter to
     # make this more efficient.
-    def get_all
+    def get_all(**kwargs)
       instances = features.map { |key| Flipper::Feature.new(key, self) }
       get_multi(instances)
     end
@@ -73,6 +73,22 @@ module Flipper
     def name
       @name ||= self.class.name.split('::').last.split(/(?=[A-Z])/).join('_').downcase.to_sym
     end
+
+    # Public: Returns a string representation of the adapter stack for debugging.
+    # Shows the full chain of wrapped adapters.
+    #
+    # Examples:
+    #   "memoizable -> active_support_cache_store -> active_record"
+    #   "memoizable -> failover(primary: redis, secondary: memory)"
+    #
+    # Returns a String.
+    def adapter_stack
+      if respond_to?(:adapter) && adapter
+        "#{name} -> #{adapter.adapter_stack}"
+      else
+        name.to_s
+      end
+    end
   end
 end