flipper 0.17.1 → 0.21.0

data/docs/Caveats.md

@@ -1,4 +1,4 @@
 # Caveats
 
-1. The [individual actor gate](https://github.com/jnunemaker/flipper/blob/master/docs/Gates.md#2-individual-actor) is typically not designed for hundreds or thousands of actors to be enabled. This is an explicit choice to make it easier to batch load data from the adapters instead of performing individual checks for actors over and over. If you need to enable something for more than 20 individual people, I would recommend using a [group](https://github.com/jnunemaker/flipper/blob/master/docs/Gates.md#5-group).
-2. The disable method exists only to clear something that is enabled. If the thing you are disabling is not enabled, the disable is pointless. This means that if you enable one group an actor is in and disable another group, the feature will be enabled for the actor. ([related issue](https://github.com/jnunemaker/flipper/issues/71))
+1. The [individual actor gate](https://github.com/jnunemaker/flipper/blob/master/docs/Gates.md#2-individual-actor) is typically not designed for hundreds or thousands of actors to be enabled. This is an explicit choice to make it easier to batch load data from the adapters instead of performing individual checks for actors over and over. If you need to enable something for more than 100 individual actors, I would recommend using a [group](https://github.com/jnunemaker/flipper/blob/master/docs/Gates.md#5-group).
+2. The `disable` method exists only to clear something that is enabled. If the thing you are disabling is not enabled, the disable is pointless. This means that if you enable one group an actor is in and disable another group, the feature will be enabled for the actor. ([related issue](https://github.com/jnunemaker/flipper/issues/71))

data/docs/DockerCompose.md

@@ -11,7 +11,6 @@ new contributor could start working on code with a minumum efforts.
 1. Install gems `docker-compose run --rm app bundle install`
 1. Run specs `docker-compose run --rm app bundle exec rspec`
 1. Run tests `docker-compose run --rm app bundle exec rake test`
-1. Clear and check files with Rubocop `docker-compose run --rm  app bundle exec rubocop -D`
 1. Optional: log in to container an using a `bash` shell for running specs
 ```sh
 docker-compose run --rm app bash

data/docs/Gates.md

@@ -7,76 +7,82 @@ Out of the box several types of enabling are supported. They are checked in this
 All on or all off. Think top level things like `:stats`, `:search`, `:logging`, etc. Also, an easy way to release a new feature as once a feature is boolean enabled it is on for every situation.
 
 ```ruby
-flipper = Flipper.new(adapter)
-flipper[:stats].enable # turn on
-flipper[:stats].disable # turn off
-flipper[:stats].enabled? # check
+Flipper.enable :stats # turn on
+Flipper.disable :stats # turn off
+Flipper.enabled? :stats # check
 ```
 
 ## 2. Individual Actor
 
-Turn feature on for individual thing. Think enable feature for someone to test or for a buddy. The only requirement for an individual actor is that it must respond to `flipper_id`.
+Turn feature on for individual thing. Think enable feature for someone to test or for a buddy.
 
 ```ruby
-flipper = Flipper.new(adapter)
+Flipper.enable_actor :stats, user
+Flipper.enabled? :stats, user # true
 
-flipper[:stats].enable user
-flipper[:stats].enabled? user # true
-
-flipper[:stats].disable user
-flipper[:stats].enabled? user # false
+Flipper.disable_actor :stats, user
+Flipper.enabled? :stats, user # false
 
 # you can enable anything, does not need to be user or person
-flipper[:search].enable group
-flipper[:search].enabled? group
-
-# you can also use shortcut methods
-flipper.enable_actor :search, user
-flipper.disable_actor :search, user
-flipper[:search].enable_actor user
-flipper[:search].disable_actor user
-```
+Flipper.enable_actor :search, organization
+Flipper.enabled? :search, organization
 
-The key is to make sure you do not enable two different types of objects for the same feature. Imagine that user has a `flipper_id` of 6 and group has a `flipper_id` of 6. Enabling search for user would automatically enable it for group, as they both have a `flipper_id` of 6.
+# you can also save a reference to a specific feature
+feature = Flipper[:search]
+
+feature.enable_actor user
+feature.enabled? user # true
+feature.disable_actor user
+```
 
-The one exception to this rule is if you have globally unique `flipper_ids`, such as UUIDs. If your `flipper_ids` are unique globally in your entire system, enabling two different types should be safe. Another way around this is to prefix the `flipper_id` with the class name like this:
+The only requirement for an individual actor is that it must have a unique `flipper_id`. Include the `Flipper::Identifier` module for a default implementation which combines the class name and `id` (e.g. `User;6`).
 
 ```ruby
-class User
-  def flipper_id
-    "User;#{id}"
-  end
+class User < Struct.new(:id)
+  include Flipper::Identifier
 end
 
-class Group
+User.new(5).flipper_id # => "User;5"
+```
+
+You can also define your own implementation:
+
+```
+class Organization < Struct.new(:uuid)
   def flipper_id
-    "Group;#{id}"
+    uuid
   end
 end
+
+Organization.new("DEB3D850-39FB-444B-A1E9-404A990FDBE0").flipper_id
+# => "DEB3D850-39FB-444B-A1E9-404A990FDBE0"
 ```
 
+Just make sure each type of object has a unique `flipper_id`.
+
 ## 3. Percentage of Actors
 
 Turn this on for a percentage of actors (think user, member, account, group, whatever). Consistently on or off for this user as long as percentage increases. Think slow rollout of a new feature to a percentage of things.
 
 ```ruby
-flipper = Flipper.new(adapter)
-
-# returns a percentage of actors instance set to 10
-percentage = flipper.actors(10)
-
 # turn stats on for 10 percent of users in the system
-flipper[:stats].enable percentage
+Flipper.enable :stats, Flipper.actors(10)
+# or
+Flipper.enable_percentage_of_actors :stats, 10
 
 # checks if actor's flipper_id is in the enabled percentage by hashing
 # user.flipper_id.to_s to ensure enabled distribution is smooth
-flipper[:stats].enabled? user
+Flipper.enabled? :stats, user
 
-# you can also use shortcut methods
-flipper.enable_percentage_of_actors :search, 10
-flipper.disable_percentage_of_actors :search # sets to 0
-flipper[:search].enable_percentage_of_actors 10
-flipper[:search].disable_percentage_of_actors # sets to 0
+Flipper.disable_percentage_of_actors :search # sets to 0
+# or
+Flipper.disable :stats, Flipper.actors(0)
+
+# you can also save a reference to a specific feature
+feature = Flipper[:search]
+feature.enable_percentage_of_actors 10
+feature.enabled? user
+feature.disable_percentage_of_actors # sets to 0
 ```
 
 ## 4. Percentage of Time
@@ -84,22 +90,20 @@ flipper[:search].disable_percentage_of_actors # sets to 0
 Turn this on for a percentage of time. Think load testing new features behind the scenes and such.
 
 ```ruby
-flipper = Flipper.new(adapter)
-
-# get percentage of time instance set to 5
-percentage = flipper.time(5)
-
 # Register a feature called logging and turn it on for 5 percent of the time.
 # This could be on during one request and off the next
 # could even be on first time in request and off second time
-flipper[:logging].enable percentage
-flipper[:logging].enabled? # this will return true 5% of the time.
-
-# you can also use shortcut methods
-flipper.enable_percentage_of_time :search, 5 # registers a feature called "enable_percentage_of_time" and enables it 5% of the time
-flipper.disable_percentage_of_time :search # sets to 0
-flipper[:search].enable_percentage_of_time 5
-flipper[:search].disable_percentage_of_time # sets to 0
+Flipper.enable_percentage_of_time :logging, 5
+
+Flipper.enabled? :logging # this will return true 5% of the time.
+
+Flipper.disable_percentage_of_time :logging # sets to 0
+
+# you can also save a reference to a specific feature
+feature = Flipper[:search]
+feature.enable_percentage_of_time, 5
+feature.enabled?
+feature.disable_percentage_of_time
 ```
 
 Timeness is not a good idea for enabling new features in the UI. Most of the time you want a feature on or off for a user, but there are definitely times when I have found percentage of time to be very useful.
@@ -114,52 +118,48 @@ Flipper.register(:admins) do |actor|
   actor.respond_to?(:admin?) && actor.admin?
 end
 
-flipper = Flipper.new(adapter)
-
-flipper[:stats].enable flipper.group(:admins) # This registers a stats feature and turns it on for admins (which is anything that returns true from the registered block).
-flipper[:stats].disable flipper.group(:admins) # turn off the stats feature for admins
+Flipper.enable_group :stats, :admins # This registers a stats feature and turns it on for admins (which is anything that returns true from the registered block).
+Flipper.disable_group :stats, :admins # turn off the stats feature for admins
 
 person = Person.find(params[:id])
-flipper[:stats].enabled? person # check if enabled, returns true if person.admin? is true
+Flipper.enabled? :stats, person # check if enabled, returns true if person.admin? is true
 
-# you can also use shortcut methods. This also registers a stats feature and turns it on for admins.
-flipper.enable_group :stats, :admins
-person = Person.find(params[:id])
-flipper[:stats].enabled? person # same as above. check if enabled, returns true if person.admin? is true
 
-flipper.disable_group :stats, :admins
-flipper[:stats].enable_group :admins
-flipper[:stats].disable_group :admins
+# you can also use shortcut methods. This also registers a stats feature and turns it on for admins.
+feature = Flipper[:search]
+feature.enable_group :admins
+feature.enabled? person
+feature.disable_group :admins
 ```
 
 Here's a quick explanation of the above code block:
 
-```
+```ruby
 Flipper.register(:admins) do |actor|
   actor.respond_to?(:admin?) && actor.admin?
 end
 ```
-- The above first registers a group called `admins` which essentially saves a [Proc](http://www.eriktrautman.com/posts/ruby-explained-blocks-procs-and-lambdas-aka-closures) to be called later.
+- The above first registers a group called `admins` which essentially saves a [Proc](http://www.eriktrautman.com/posts/ruby-explained-blocks-procs-and-lambdas-aka-closures) to be called later. The `actor` is an instance of the `Flipper::Types::Actor` that wraps the thing being checked against and `actor.thing` is the original object being checked.
 
-```
-flipper[:stats].enable flipper.group(:admins)
+```ruby
+Flipper.enable_group :stats, :admins
 ```
 
 - The above enables the stats feature to any object that returns true from the `:admins` proc.
 
-```
+```ruby
 person = Person.find(params[:id])
-flipper[:stats].enabled? person # check if person is enabled, returns true if person.admin? is true
+Flipper.enabled? :stats, person # check if person is enabled, returns true if person.admin? is true
 ```
 
-When the `person` object is passed to the `enabled?` method, it is then passed into the proc. If the proc returns true, the entire statement returns true and so `flipper[:stats].enabled? person` returns true. Whatever logic follows this conditional check is then executed.
+When the `person` object is passed to the `enabled?` method, it is then passed into the proc. If the proc returns true, the entire statement returns true and so `Flipper[:stats].enabled? person` returns true. Whatever logic follows this conditional check is then executed.
 
 There is no requirement that the thing yielded to the block be a user model or whatever. It can be anything you want, therefore it is a good idea to check that the thing passed into the group block actually responds to what you are trying to do in the `register` proc.
 
 In your application code, you can do something like this now:
 
-```
-if flipper[:stats].enabled?(some_admin)
+```ruby
+if Flipper.enabled? :stats, some_admin
   # do thing...
 else
   # do not do thing

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/initializer/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.
-config.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
-config.middleware.use Flipper::Middleware::SetupEnv, -> { Flipper.new(...) }
-config.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
-    config.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
-    config.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
-    config.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/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
 ```