flipper 0.20.3 → 0.22.0

data/docs/Optimization.md

@@ -1,52 +1,63 @@
 # Optimization
 
-## Memoizing Middleware
+## Memoization
 
-One optimization that flipper provides is a memoizing middleware. The memoizing middleware ensures that you only make one adapter call per feature per request. This means if you check the same feature over and over, it will only make one Mongo, Redis, or whatever call per feature for the length of the request.
+By default, Flipper will preload and memoize all features to ensure one adapter call per request. This means no matter how many times you check features, Flipper will only make one network request to Postgres, MySQL, Redis, Mongo or whatever adapter you are using for the length of the request.
 
-You can use the middleware like so for Rails:
+### Preloading
+
+Flipper will preload all features before each request by default, which is recommended if you have a limited number of features (< 100?) and they are used on most requests. If you have a lot of features, but only a few are used on most requests, you may want to customize preloading:
 
 ```ruby
-# setup default instance (perhaps in config/initializers/flipper.rb)
-Flipper.configure do |config|
-  config.default do
-    Flipper.new(...)
-  end
+# config/initializers/flipper.rb
+Rails.application.configure do
+  # Load specific features that are used on most requests
+  config.flipper.preload = [:stats, :search, :some_feature]
+
+  # Or completely disable preloading
+  config.flipper.preload = false
 end
+```
+
+Features that are not preloaded are still memoized, ensuring one adapter call per feature during a request.
+
+### Skip memoization
+
+Prevent preloading and memoization on specific requests by setting `memoize` to a proc that evaluates to false.
 
-# This assumes you setup a default flipper instance using configure.
-Rails.configuration.middleware.use Flipper::Middleware::Memoizer
+```ruby
+# config/initializers/flipper.rb
+Rails.application.configure do
+  config.flipper.memoize = ->(request) { !request.path.start_with?("/assets") }
+end
 ```
 
-**Note**: Be sure that the middleware is high enough up in your stack that all feature checks are wrapped.
+### Disable memoization
 
-**Also Note**: If you haven't setup a default instance, you can pass the instance to `SetupEnv` as `Memoizer` uses whatever is setup in the `env`:
+To disable memoization entirely:
 
 ```ruby
-Rails.configuration.middleware.use Flipper::Middleware::SetupEnv, -> { Flipper.new(...) }
-Rails.configuration.middleware.use Flipper::Middleware::Memoizer
+Rails.application.configure do
+  config.flipper.memoize = false
+end
 ```
 
-### Options
-
-The Memoizer middleware also supports a few options. Use either `preload` or `preload_all`, not both.
-
-* **`:preload`** - An `Array` of feature names (`Symbol`) to preload for every request. Useful if you have features that are used on every endpoint. `preload` uses `Adapter#get_multi` to attempt to load the features in one network call instead of N+1 network calls.
-    ```ruby
-    Rails.configuration.middleware.use Flipper::Middleware::Memoizer,
-      preload: [:stats, :search, :some_feature]
-    ```
-* **`:preload_all`** - A Boolean value (default: false) of whether or not all features should be preloaded. Using this results in a `preload_all` call with the result of `Adapter#get_all`. Any subsequent feature checks will be memoized and perform no network calls. I wouldn't recommend using this unless you have few features (< 100?) and nearly all of them are used on every request.
-    ```ruby
-    Rails.configuration.middleware.use Flipper::Middleware::Memoizer,
-      preload_all: true
-    ```
-* **`:unless`** - A block that prevents preloading and memoization if it evaluates to true.
-    ```ruby
-    # skip preloading and memoizing if path starts with /assets
-    Rails.configuration.middleware.use Flipper::Middleware::Memoizer,
-      unless: ->(request) { request.path.start_with?("/assets") }
-    ```
+### Advanced
+
+Memoization is implemented as a Rack middleware, which can be used manually in any Ruby app:
+
+```ruby
+use Flipper::Middleware::Memoizer,
+  preload: true,
+  unless: ->(request) { request.path.start_with?("/assets") }
+```
+
+**Also Note**: If you need to customize the instance of Flipper used by the memoizer, you can pass the instance to `SetupEnv`:
+
+```ruby
+use Flipper::Middleware::SetupEnv, -> { Flipper.new(...) }
+use Flipper::Middleware::Memoizer
+```
 
 ## Cache Adapters
 
@@ -61,11 +72,15 @@ https://github.com/petergoldstein/dalli
 Example using the Dalli cache adapter with the Memory adapter and a TTL of 600 seconds:
 
 ```ruby
-dalli_client = Dalli::Client.new('localhost:11211')
-memory_adapter = Flipper::Adapters::Memory.new
-adapter = Flipper::Adapters::Dalli.new(memory_adapter, dalli_client, 600)
-flipper = Flipper.new(adapter)
+Flipper.configure do |config|
+  config.adapter do
+    dalli = Dalli::Client.new('localhost:11211')
+    adapter = Flipper::Adapters::Memory.new
+    Flipper::Adapters::Dalli.new(adapter, dalli, 600)
+  end
+end
 ```
+
 ### RedisCache
 
 Applications using [Redis](https://redis.io/) via the [redis-rb](https://github.com/redis/redis-rb) client can take advantage of the RedisCache adapter.
@@ -75,12 +90,15 @@ Initialize `RedisCache`  with a flipper [adapter](https://github.com/jnunemaker/
 Example using the RedisCache adapter with the Memory adapter and a TTL of 4800 seconds:
 
 ```ruby
-  require 'flipper/adapters/redis_cache'
+require 'flipper/adapters/redis_cache'
 
-  redis = Redis.new(url: ENV['REDIS_URL'])
-  memory_adapter = Flipper::Adapters::Memory.new
-  adapter = Flipper::Adapters::RedisCache.new(memory_adapter, redis, 4800)
-  flipper = Flipper.new(adapter)
+Flipper.configure do |config|
+  config.adapter do
+    redis = Redis.new(url: ENV['REDIS_URL'])
+    memory_adapter = Flipper::Adapters::Memory.new
+    Flipper::Adapters::RedisCache.new(memory_adapter, redis, 4800)
+  end
+end
 ```
 
 ### ActiveSupportCacheStore
@@ -105,10 +123,15 @@ Example using the ActiveSupportCacheStore adapter with ActiveSupport's [MemorySt
 require 'active_support/cache'
 require 'flipper/adapters/active_support_cache_store'
 
-memory_adapter = Flipper::Adapters::Memory.new
-cache = ActiveSupport::Cache::MemoryStore.new
-adapter = Flipper::Adapters::ActiveSupportCacheStore.new(memory_adapter, cache, expires_in: 5.minutes)
-flipper = Flipper.new(adapter)
+Flipper.configure do |config|
+  config.adapter do
+    Flipper::Adapters::ActiveSupportCacheStore.new(
+      Flipper::Adapters::Memory.new,
+      ActiveSupport::Cache::MemoryStore.new # Or Rails.cache,
+      expires_in: 5.minutes
+    )
+  end
+end
 ```
 
 Setting `expires_in` is optional and will set an expiration time on Flipper cache keys.  If specified, all flipper keys will use this `expires_in` over the `expires_in` passed to your ActiveSupport cache constructor.

data/docs/api/README.md

@@ -23,7 +23,7 @@ Or install it yourself as:
 ```ruby
 # config/routes.rb
 YourRailsApp::Application.routes.draw do
-  mount Flipper::Api.app(flipper) => '/flipper/api'
+  mount Flipper::Api.app(Flipper) => '/flipper/api'
 end
 ```
 
@@ -34,8 +34,8 @@ There can be more than one router in your application. Make sure if you choose a
 *bad:*
 ```ruby
 YourRailsApp::Application.routes.draw do
-  mount Flipper::UI.app(flipper) => '/flipper'
-  mount Flipper::Api.app(flipper) => '/flipper/api'
+  mount Flipper::UI.app(Flipper) => '/flipper'
+  mount Flipper::Api.app(Flipper) => '/flipper/api'
 end
 ```
 
@@ -44,8 +44,8 @@ In this case any requests to /flipper\* will be routed to Flipper::UI - includin
 *good:*
 ```ruby
 YourRailsApp::Application.routes.draw do
-  mount Flipper::Api.app(flipper) => '/flipper/api'
-  mount Flipper::UI.app(flipper) => '/flipper'
+  mount Flipper::Api.app(Flipper) => '/flipper/api'
+  mount Flipper::UI.app(Flipper) => '/flipper'
 end
 ````
 For more advanced mounting techniques and for suggestions on how to mount in a non-Rails application, it is recommend that you review the [`Flipper::UI` usage documentation](https://github.com/jnunemaker/flipper/blob/master/docs/ui/README.md#usage) as the same approaches apply to `Flipper::Api`.

data/docs/http/README.md

@@ -8,17 +8,18 @@ Initialize the HTTP adapter with a configuration Hash.
 ```ruby
 require 'flipper/adapters/http'
 
-configuration = {
-  url: 'http://app.com/mount-point', # required
-  headers: { 'X-Custom-Header' => 'foo' },
-  basic_auth_username: 'user123',
-  basic_auth_password: 'password123'
-  read_timeout: 5,
-  open_timeout: 2,
-}
-
-adapter = Flipper::Adapters::Http.new(configuration)
-flipper = Flipper.new(adapter)
+Flipper.configure do |config|
+  config.adapter do
+    Flipper::Adapters::Http.new({
+      url: 'http://app.com/mount-point', # required
+      headers: { 'X-Custom-Header' => 'foo' },
+      basic_auth_username: 'user123',
+      basic_auth_password: 'password123'
+      read_timeout: 5,
+      open_timeout: 2,
+    })
+  end
+end
 ```
 
 **Required keys**:

data/docs/read-only/README.md

@@ -5,17 +5,20 @@ A [read-only](https://github.com/jnunemaker/flipper/blob/master/lib/flipper/adap
 Use this adapter to wrap another adapter and raise an exception for any writes.
 
 Any attempted write raises `Flipper::Adapters::ReadOnly::WriteAttempted`  with message  `'write attempted while in read only mode'`
+
 ## Usage
+
 ```ruby
 # example wrapping memory adapter
 require 'flipper/adapters/read_only'
 
-memory_adapter = Flipper::Adapters::Memory.new
-read_only_adapter = Flipper::Adapters::ReadOnly.new(memory_adapter)
-
-flipper = Flipper.new(read_only_adapter)
+Flipper.configure do |config|
+  config.adapter do
+    Flipper::Adapters::ReadOnly.new(Flipper::Adapters::Memory.new)
+  end
+end
 
 # Enabling a feature
-> flipper[:dashboard_panel].enable
+> Flipper[:dashboard_panel].enable
 => Flipper::Adapters::ReadOnly::WriteAttempted: write attempted while in read only mode
 ```

data/examples/api/basic.ru

@@ -0,0 +1,19 @@
+#
+# Usage:
+#   # if you want it to not reload and be really fast
+#   bin/rackup examples/api/basic.ru -p 9999
+#
+#   # if you want reloading
+#   bin/shotgun examples/api/basic.ru -p 9999
+#
+#   http://localhost:9999/
+#
+
+require 'bundler/setup'
+require "flipper/api"
+require "flipper/adapters/pstore"
+
+# You can uncomment this to get some default data:
+# Flipper.enable :logging
+
+run Flipper::Api.app

data/examples/api/custom_memoized.ru

@@ -0,0 +1,37 @@
+#
+# Usage:
+#   # if you want it to not reload and be really fast
+#   bin/rackup examples/api/custom_memoized.ru -p 9999
+#
+#   # if you want reloading
+#   bin/shotgun examples/api/custom_memoized.ru -p 9999
+#
+#   http://localhost:9999/
+#
+
+require 'bundler/setup'
+require "active_support/notifications"
+require "flipper/api"
+require "flipper/adapters/pstore"
+
+adapter = Flipper::Adapters::Instrumented.new(
+  Flipper::Adapters::PStore.new,
+  instrumenter: ActiveSupport::Notifications,
+)
+flipper = Flipper.new(adapter)
+
+ActiveSupport::Notifications.subscribe(/.*/, ->(*args) {
+  name, start, finish, id, data = args
+  case name
+  when "adapter_operation.flipper"
+    p data[:adapter_name] => data[:operation]
+  end
+})
+
+# You can uncomment this to get some default data:
+# flipper[:logging].enable_percentage_of_time 5
+
+run Flipper::Api.app(flipper) { |builder|
+  builder.use Flipper::Middleware::SetupEnv, flipper
+  builder.use Flipper::Middleware::Memoizer, preload: true
+}

data/examples/api/memoized.ru

@@ -0,0 +1,43 @@
+#
+# Usage:
+#   # if you want it to not reload and be really fast
+#   bin/rackup examples/api/memoized.ru -p 9999
+#
+#   # if you want reloading
+#   bin/shotgun examples/api/memoized.ru -p 9999
+#
+#   http://localhost:9999/
+#
+
+require 'bundler/setup'
+require "active_support/notifications"
+require "flipper/api"
+require "flipper/adapters/pstore"
+
+Flipper.configure do |config|
+  config.adapter {
+    Flipper::Adapters::Instrumented.new(
+      Flipper::Adapters::PStore.new,
+      instrumenter: ActiveSupport::Notifications,
+    )
+  }
+end
+
+ActiveSupport::Notifications.subscribe(/.*/, ->(*args) {
+  name, start, finish, id, data = args
+  case name
+  when "adapter_operation.flipper"
+    p data[:adapter_name] => data[:operation]
+  end
+})
+
+Flipper.register(:admins) { |actor|
+  actor.respond_to?(:admin?) && actor.admin?
+}
+
+# You can uncomment this to get some default data:
+# Flipper.enable :logging
+
+run Flipper::Api.app { |builder|
+  builder.use Flipper::Middleware::Memoizer, preload: true
+}

data/examples/basic.rb

@@ -1,17 +1,6 @@
-require File.expand_path('../example_setup', __FILE__)
-
+require 'bundler/setup'
 require 'flipper'
 
-Flipper.configure do |config|
-  config.default do
-    # pick an adapter, this uses memory, any will do
-    adapter = Flipper::Adapters::Memory.new
-
-    # pass adapter to handy DSL instance
-    Flipper.new(adapter)
-  end
-end
-
 # check if search is enabled
 if Flipper.enabled?(:search)
   puts 'Search away!'

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
+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
@@ -59,18 +48,18 @@ 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
+puts Flipper.time(5).inspect
 
 # get an instance of the percentage of actors type set to 15
-puts flipper.actors(15).inspect
+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
+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
+puts Flipper.actor(thing).inspect
 
 # register a top level group
 admins = Flipper.register(:admins) { |actor|