flipper 0.16.0 → 1.4.0

data/examples/cloud/cloud_setup.rb

@@ -0,0 +1,20 @@
+if ENV["FLIPPER_CLOUD_TOKEN"].nil? || ENV["FLIPPER_CLOUD_TOKEN"].empty?
+  warn "FLIPPER_CLOUD_TOKEN missing so skipping cloud example."
+  exit
+end
+
+matrix_key = if ENV["CI"]
+  suffix_rails = ENV["RAILS_VERSION"].split(".").take(2).join
+  suffix_ruby = RUBY_VERSION.split(".").take(2).join
+  "FLIPPER_CLOUD_TOKEN_#{suffix_ruby}_#{suffix_rails}"
+else
+  "FLIPPER_CLOUD_TOKEN"
+end
+
+if matrix_token = ENV[matrix_key]
+  puts "Using #{matrix_key} for FLIPPER_CLOUD_TOKEN"
+  ENV["FLIPPER_CLOUD_TOKEN"] = matrix_token
+else
+  warn "Missing #{matrix_key}. Go create an environment in flipper cloud and set #{matrix_key} to the adapter token for that environment in github actions secrets."
+  exit 1
+end

data/examples/cloud/forked.rb

@@ -0,0 +1,36 @@
+# Usage (from the repo root):
+# env FLIPPER_CLOUD_TOKEN=<token> bundle exec ruby examples/cloud/threaded.rb
+
+require_relative "./cloud_setup"
+require 'bundler/setup'
+require 'flipper/cloud'
+
+puts Process.pid
+
+# Make a call in the parent process so we can detect forking.
+Flipper.enabled?(:stats)
+
+pids = 2.times.map do |n|
+  fork {
+    # Check every second to see if the feature is enabled
+    threads = []
+    2.times do
+      threads << Thread.new do
+        loop do
+          sleep rand
+
+          if Flipper[:stats].enabled?
+            puts "#{Process.pid} #{Time.now.to_i} Enabled!"
+          else
+            puts "#{Process.pid} #{Time.now.to_i} Disabled!"
+          end
+        end
+      end
+    end
+    threads.map(&:join)
+  }
+end
+
+pids.each do |pid|
+  Process.waitpid pid, 0
+end

data/examples/cloud/import.rb

@@ -0,0 +1,17 @@
+# Usage (from the repo root):
+#   env FLIPPER_CLOUD_TOKEN=<token> bundle exec ruby examples/cloud/import.rb
+
+require_relative "./cloud_setup"
+require 'bundler/setup'
+require 'flipper'
+require 'flipper/cloud'
+
+Flipper.enable(:test)
+Flipper.enable(:search)
+Flipper.enable_actor(:stats, Flipper::Actor.new("jnunemaker"))
+Flipper.enable_percentage_of_time(:logging, 5)
+
+cloud = Flipper::Cloud.new
+
+# makes cloud identical to memory flipper
+cloud.import(Flipper)

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/cloud/threaded.rb

@@ -0,0 +1,33 @@
+# Usage (from the repo root):
+# env FLIPPER_CLOUD_TOKEN=<token> bundle exec ruby examples/cloud/threaded.rb
+
+require_relative "./cloud_setup"
+require 'bundler/setup'
+require 'flipper/cloud'
+
+puts Process.pid
+
+Flipper.configure do |config|
+  config.default {
+    Flipper::Cloud.new(
+      local_adapter: config.adapter,
+      debug_output: STDOUT,
+    )
+  }
+end
+
+# You might want to do this at some point to see different results:
+# Flipper.enable(:search)
+# Flipper.disable(:stats)
+
+# Check every second to see if the feature is enabled
+5.times.map { |i|
+  Thread.new {
+    loop do
+      sleep rand
+
+      Flipper.enabled?(:stats)
+      Flipper.enabled?(:search)
+    end
+  }
+}.each(&:join)

data/examples/configuring_default.rb

@@ -1,12 +1,9 @@
-require File.expand_path('../example_setup', __FILE__)
-
+require 'bundler/setup'
 require 'flipper'
 
 # sets up default adapter so Flipper works like Flipper::DSL
 Flipper.configure do |config|
-  config.default do
-    Flipper.new Flipper::Adapters::Memory.new
-  end
+  config.adapter { Flipper::Adapters::Memory.new }
 end
 
 puts Flipper.enabled?(:search) # => false

data/examples/dsl.rb

@@ -1,20 +1,9 @@
-require File.expand_path('../example_setup', __FILE__)
-
+require 'bundler/setup'
 require 'flipper'
 
-adapter = Flipper::Adapters::Memory.new
-flipper = Flipper.new(adapter)
-
-# create a thing with an identifier
-class Person
-  attr_reader :id
-
-  def initialize(id)
-    @id = id
-  end
-
-  # Must respond to flipper_id
-  alias_method :flipper_id, :id
+# create an actor with an identifier
+class Person < Struct.new(:id)
+  include Flipper::Identifier
 end
 
 person = Person.new(1)
@@ -22,14 +11,14 @@ person = Person.new(1)
 puts "Stats are disabled by default\n\n"
 
 # is a feature enabled
-puts "flipper.enabled? :stats: #{flipper.enabled? :stats}"
+puts "flipper.enabled? :stats: #{Flipper.enabled? :stats}"
 
 # is a feature on or off for a particular person
-puts "flipper.enabled? :stats, person: #{flipper.enabled? :stats, person}"
+puts "Flipper.enabled? :stats, person: #{Flipper.enabled? :stats, person}"
 
 # get at a feature
-puts "\nYou can also get an individual feature like this:\nstats = flipper[:stats]\n\n"
-stats = flipper[:stats]
+puts "\nYou can also get an individual feature like this:\nstats = Flipper[:stats]\n\n"
+stats = Flipper[:stats]
 
 # is that feature enabled
 puts "stats.enabled?: #{stats.enabled?}"
@@ -39,7 +28,7 @@ puts "stats.enabled? person: #{stats.enabled? person}"
 
 # enable a feature by name
 puts "\nEnabling stats\n\n"
-flipper.enable :stats
+Flipper.enable :stats
 
 # or, you can use the feature to enable
 stats.enable
@@ -49,7 +38,7 @@ puts "stats.enabled? person: #{stats.enabled? person}"
 
 # oh, no, let's turn this baby off
 puts "\nDisabling stats\n\n"
-flipper.disable :stats
+Flipper.disable :stats
 
 # or we can disable using feature obviously
 stats.disable
@@ -58,20 +47,6 @@ puts "stats.enabled?: #{stats.enabled?}"
 puts "stats.enabled? person: #{stats.enabled? person}"
 puts
 
-# get an instance of the percentage of time type set to 5
-puts flipper.time(5).inspect
-
-# get an instance of the percentage of actors type set to 15
-puts flipper.actors(15).inspect
-
-# get an instance of an actor using an object that responds to flipper_id
-responds_to_flipper_id = Struct.new(:flipper_id).new(10)
-puts flipper.actor(responds_to_flipper_id).inspect
-
-# get an instance of an actor using an object
-thing = Struct.new(:flipper_id).new(22)
-puts flipper.actor(thing).inspect
-
 # register a top level group
 admins = Flipper.register(:admins) { |actor|
   actor.respond_to?(:admin?) && actor.admin?

data/examples/enabled_for_actor.rb

@@ -1,5 +1,4 @@
-require File.expand_path('../example_setup', __FILE__)
-
+require 'bundler/setup'
 require 'flipper'
 
 # Some class that represents what will be trying to do something
@@ -22,21 +21,17 @@ end
 user1 = User.new(1, true)
 user2 = User.new(2, false)
 
-# pick an adapter
-adapter = Flipper::Adapters::Memory.new
-
-# get a handy dsl instance
-flipper = Flipper.new(adapter)
-
 Flipper.register :admins do |actor|
   actor.admin?
 end
 
-flipper[:search].enable
-flipper[:stats].enable_actor user1
-flipper[:pro_stats].enable_percentage_of_actors 50
-flipper[:tweets].enable_group :admins
-flipper[:posts].enable_actor user2
+Flipper.enable :search
+Flipper.enable_actor :stats, user1
+Flipper.enable_percentage_of_actors :pro_stats, 50
+Flipper.enable_group :tweets, :admins
+Flipper.enable_actor :posts, user2
 
-pp flipper.features.select { |feature| feature.enabled?(user1) }.map(&:name)
-pp flipper.features.select { |feature| feature.enabled?(user2) }.map(&:name)
+pp Flipper.features.select { |feature| feature.enabled?(user1) }.map(&:name).sort
+pp Flipper.features.select { |feature| feature.enabled?(user2) }.map(&:name).sort
+pp Flipper.features.select { |feature| feature.enabled?(user1, user2) }.map(&:name).sort
+pp Flipper.features.select { |feature| feature.enabled?([user2, user1]) }.map(&:name).sort