flipper 0.10.2 → 0.11.0.beta1

data/docs/api/README.md

@@ -23,26 +23,47 @@ 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
 ```
 
+### Mount Priority - important if using Flipper::UI
+
+There can be more than one router in your application. Make sure if you choose a path that begins with the same pattern as where Flipper::UI is mounted that the app with the longer pattern is mounted first.
+
+*bad:*
+```ruby
+YourRailsApp::Application.routes.draw do
+  mount Flipper::UI.app(flipper) => '/flipper'
+  mount Flipper::Api.app(flipper) => '/flipper/api'
+end
+```
+
+In this case any requests to /flipper\* will be routed to Flipper::UI - including /flipper/api* requests.  Simply swap these two to make sure that any requests that don't match /flipper/api\* will be routed to Flipper::UI.
+
+*good:*
+```ruby
+YourRailsApp::Application.routes.draw do
+  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`.
 
 ## Endpoints
 
-**Note:** Example CURL requests below assume a mount point of `/flipper-api`.
+**Note:** Example CURL requests below assume a mount point of `/flipper/api`.
 
 ### Get all features
 
 **URL**
 
-`GET /api/v1/features`
+`GET /features`
 
 **Request**
 
 ```
-curl http://example.com/flipper-api/api/v1/features
+curl http://example.com/flipper/api/features
 ```
 
 **Response**
@@ -122,7 +143,7 @@ Returns an array of feature objects:
 
 **URL**
 
-`POST /api/v1/features`
+`POST /features`
 
 **Parameters**
 
@@ -131,7 +152,7 @@ Returns an array of feature objects:
 **Request**
 
 ```
-curl -X POST -d "name=reports" http://example.com/flipper-api/api/v1/features
+curl -X POST -d "name=reports" http://example.com/flipper/api/features
 ```
 
 **Response**
@@ -142,7 +163,7 @@ On successful creation, the API will respond with an empty JSON response.
 
 **URL**
 
-`GET /api/v1/features/{feature_name}`
+`GET /features/{feature_name}`
 
 **Parameters**
 
@@ -151,7 +172,7 @@ On successful creation, the API will respond with an empty JSON response.
 **Request**
 
 ```
-curl http://example.com/flipper-api/api/v1/features/reports
+curl http://example.com/flipper/api/features/reports
 ```
 
 **Response**
@@ -196,7 +217,7 @@ Returns an individual feature object:
 
 **URL**
 
-`DELETE /api/v1/features/{feature_name}`
+`DELETE /features/{feature_name}`
 
 **Parameters**
 
@@ -205,24 +226,44 @@ Returns an individual feature object:
 **Request**
 
 ```
-curl -X DELETE http://example.com/flipper-api/api/v1/features/reports
+curl -X DELETE http://example.com/flipper/api/features/reports
 ```
 
 **Response**
 
 Successful deletion of a feature will return a 204 No Content response.
 
+### Clear a feature
+
+**URL**
+
+`DELETE /features/{feature_name}/clear`
+
+**Parameters**
+
+* `feature_name` - The name of the feature to clear
+
+**Request**
+
+```
+curl -X DELETE http://example.com/flipper/api/features/reports/clear
+```
+
+**Response**
+
+Successful clearing (removing of all gate values) of a feature will return a 204 No Content response.
+
 ## Gates
 
 The API supports enabling / disabling any of the Flipper [gates](https://github.com/jnunemaker/flipper/blob/master/docs/Gates.md). Gate endpoints follow the url convention:
 
 **enable**
 
-`POST /api/v1/{feature_name}/{gate_name}`
+`POST /{feature_name}/{gate_name}`
 
 **disable**
 
-`DELETE /api/v1/{feature_name}/{gate_name}`
+`DELETE /{feature_name}/{gate_name}`
 
 and on a succesful request return a 200 HTTP status and the feature object as the response body.
 
@@ -230,7 +271,7 @@ and on a succesful request return a 200 HTTP status and the feature object as th
 
 **URL**
 
-`POST /api/v1/features/{feature_name}/boolean`
+`POST /features/{feature_name}/boolean`
 
 **Parameters**
 
@@ -239,7 +280,7 @@ and on a succesful request return a 200 HTTP status and the feature object as th
 **Request**
 
 ```
-curl -X POST http://example.com/flipper-api/api/v1/features/reports/boolean
+curl -X POST http://example.com/flipper/api/features/reports/boolean
 ```
 
 **Response**
@@ -285,7 +326,7 @@ Successful enabling of the boolean gate will return a 200 HTTP status and the fe
 
 **URL**
 
-`DELETE /api/v1/features/{feature_name}/boolean`
+`DELETE /features/{feature_name}/boolean`
 
 **Parameters**
 
@@ -294,7 +335,7 @@ Successful enabling of the boolean gate will return a 200 HTTP status and the fe
 **Request**
 
 ```
-curl -X DELETE http://example.com/flipper-api/api/v1/features/reports/boolean
+curl -X DELETE http://example.com/flipper/api/features/reports/boolean
 ```
 
 **Response**
@@ -339,7 +380,7 @@ Successful disabling of the boolean gate will return a 200 HTTP status and the f
 
 **URL**
 
-`POST /api/v1/features/{feature_name}/groups`
+`POST /features/{feature_name}/groups`
 
 **Parameters**
 
@@ -350,7 +391,7 @@ Successful disabling of the boolean gate will return a 200 HTTP status and the f
 **Request**
 
 ```
-curl -X POST -d "name=admins" http://example.com/flipper-api/api/v1/features/reports/groups
+curl -X POST -d "name=admins" http://example.com/flipper/api/features/reports/groups
 ```
 
 **Response**
@@ -395,7 +436,7 @@ Successful enabling of the group will return a 200 HTTP status and the feature o
 
 **URL**
 
-`DELETE /api/v1/features/{feature_name}/groups`
+`DELETE /features/{feature_name}/groups`
 
 **Parameters**
 
@@ -406,7 +447,7 @@ Successful enabling of the group will return a 200 HTTP status and the feature o
 **Request**
 
 ```
-curl -X DELETE -d "name=admins" http://example.com/flipper-api/api/v1/features/reports/groups
+curl -X DELETE -d "name=admins" http://example.com/flipper/api/features/reports/groups
 ```
 
 **Response**
@@ -450,7 +491,7 @@ Successful disabling of the group will return a 200 HTTP status and the feature
 
 **URL**
 
-`POST /api/v1/features/{feature_name}/actors`
+`POST /features/{feature_name}/actors`
 
 **Parameters**
 
@@ -461,7 +502,7 @@ Successful disabling of the group will return a 200 HTTP status and the feature
 **Request**
 
 ```
-curl -X POST -d "flipper_id=User:1" http://example.com/flipper-api/api/v1/features/reports/actors
+curl -X POST -d "flipper_id=User:1" http://example.com/flipper/api/features/reports/actors
 ```
 
 **Response**
@@ -505,7 +546,7 @@ Successful enabling of the actor will return a 200 HTTP status and the feature o
 
 **URL**
 
-`DELETE /api/v1/features/{feature_name}/actors`
+`DELETE /features/{feature_name}/actors`
 
 **Parameters**
 
@@ -516,7 +557,7 @@ Successful enabling of the actor will return a 200 HTTP status and the feature o
 **Request**
 
 ```
-curl -X DELETE -d "flipper_id=User:1" http://example.com/flipper-api/api/v1/features/reports/actors
+curl -X DELETE -d "flipper_id=User:1" http://example.com/flipper/api/features/reports/actors
 ```
 
 **Response**
@@ -561,7 +602,7 @@ Successful disabling of the actor will return a 200 HTTP status and the feature
 
 **URL**
 
-`POST /api/v1/features/{feature_name}/percentage_of_actors`
+`POST /features/{feature_name}/percentage_of_actors`
 
 **Parameters**
 
@@ -572,7 +613,7 @@ Successful disabling of the actor will return a 200 HTTP status and the feature
 **Request**
 
 ```
-curl -X POST -d "percentage=20" http://example.com/flipper-api/api/v1/features/reports/percentage_of_actors
+curl -X POST -d "percentage=20" http://example.com/flipper/api/features/reports/percentage_of_actors
 ```
 
 **Response**
@@ -616,7 +657,7 @@ Successful enabling of a percentage of actors will return a 200 HTTP status and
 
 **URL**
 
-`DELETE /api/v1/features/{feature_name}/percentage_of_actors`
+`DELETE /features/{feature_name}/percentage_of_actors`
 
 **Parameters**
 
@@ -625,7 +666,7 @@ Successful enabling of a percentage of actors will return a 200 HTTP status and
 **Request**
 
 ```
-curl -X DELETE http://example.com/flipper-api/api/v1/features/reports/percentage_of_actors
+curl -X DELETE http://example.com/flipper/api/features/reports/percentage_of_actors
 ```
 
 **Response**
@@ -669,7 +710,7 @@ Successful disabling of a percentage of actors will set the percentage to 0 and
 
 **URL**
 
-`POST /api/v1/features/{feature_name}/percentage_of_time`
+`POST /features/{feature_name}/percentage_of_time`
 
 **Parameters**
 
@@ -680,7 +721,7 @@ Successful disabling of a percentage of actors will set the percentage to 0 and
 **Request**
 
 ```
-curl -X POST -d "percentage=20" http://example.com/flipper-api/api/v1/features/reports/percentage_of_time
+curl -X POST -d "percentage=20" http://example.com/flipper/api/features/reports/percentage_of_time
 ```
 
 **Response**
@@ -724,7 +765,7 @@ Successful enabling of a percentage of time will return a 200 HTTP status and th
 
 **URL**
 
-`DELETE /api/v1/features/{feature_name}/percentage_of_time`
+`DELETE /features/{feature_name}/percentage_of_time`
 
 **Parameters**
 
@@ -733,7 +774,7 @@ Successful enabling of a percentage of time will return a 200 HTTP status and th
 **Request**
 
 ```
-curl -X DELETE http://example.com/flipper-api/api/v1/features/reports/percentage_of_time
+curl -X DELETE http://example.com/flipper/api/features/reports/percentage_of_time
 ```
 
 **Response**

data/docs/http/README.md

@@ -0,0 +1,34 @@
+# Flipper Http
+
+HTTP adapter for use with the [Flipper Api](https://github.com/jnunemaker/flipper/blob/master/docs/api/README.md).
+
+Given you have [mounted](https://github.com/jnunemaker/flipper/blob/master/docs/api/README.md#user-content-usage) the Flipper Api on an application, you can use the HTTP adapter to interact with Flipper just like any other adapter, and internally it will handle all the http requests for you.  This means that you can have the application exposing the API store your Flipper data, but interact with it from other Ruby apps.
+
+Initialize the HTTP adapter with a configuration Hash.
+```ruby
+require 'flipper/adapters/http'
+
+configuration = {
+  uri: URI('http://app.com/mount-point'), # required
+  headers: { 'X-Custom-Header' => 'foo' },
+  basic_auth_username: 'user123',
+  basic_auth_password: 'password123'
+  read_timeout: 75,
+  open_timeout: 70
+}
+
+adapter = Flipper::Adapters::Http.new(configuration)
+flipper = Flipper.new(adapter)
+```
+
+**Required keys**:
+* uri: [URI](https://docs.ruby-lang.org/en/2.3.0/URI.html) object referencing url where [Flipper Api](https://github.com/jnunemaker/flipper/blob/master/docs/api/README.md) is mounted.
+
+**Optional keys**:
+*These will affect every request the adapter makes.  For example, send basic auth credentials with every request.*
+
+* headers: HTTP headers.
+* basic_auth_username:  Basic Auth username.
+* basic_auth_password: Basic Auth password.
+* read_timeout: [number in seconds](https://docs.ruby-lang.org/en/2.3.0/Net/HTTP.html#attribute-i-read_timeout).
+* open_timeout: [number in seconds](https://docs.ruby-lang.org/en/2.3.0/Net/HTTP.html#attribute-i-open_timeout).

data/docs/read-only/README.md

@@ -0,0 +1,22 @@
+# Flipper read-only
+
+A [read-only](https://github.com/jnunemaker/flipper/blob/master/lib/flipper/adapters/read_only.rb) adapter for [Flipper](https://github.com/jnunemaker/flipper).
+
+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/memory'
+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)
+
+# Enabling a feature
+> flipper[:dashboard_panel].enable
+=> Flipper::Adapters::ReadOnly::WriteAttempted: write attempted while in read only mode
+```

data/examples/percentage_of_actors_group.rb

@@ -0,0 +1,49 @@
+# This example shows how to setup a group that enables a feature for a
+# percentage of actors. It could be combined with other logic to enable a
+# feature for actors in a particular location or on a particular plan, but only
+# for a percentage of them. The percentage is a constant, but could easily be
+# plucked from memcached, redis, mysql or whatever.
+require File.expand_path('../example_setup', __FILE__)
+require 'flipper'
+require 'flipper/adapters/memory'
+
+adapter = Flipper::Adapters::Memory.new
+flipper = Flipper.new(adapter)
+stats = flipper[:stats]
+
+# Some class that represents what will be trying to do something
+class User
+  attr_reader :id
+
+  def initialize(id)
+    @id = id
+  end
+
+  # Must respond to flipper_id
+  def flipper_id
+    "User:#{@id}"
+  end
+end
+
+PERCENTAGE = 50
+Flipper.register(:experimental) do |actor|
+  if actor.respond_to?(:flipper_id)
+    Zlib.crc32(actor.flipper_id.to_s) % 100 < PERCENTAGE
+  else
+    false
+  end
+end
+
+# enable the experimental group
+flipper[:stats].enable_group :experimental
+
+# create a bunch of fake users and see how many are enabled
+total = 10_000
+users = (1..total).map { |n| User.new(n) }
+enabled = users.map { |user|
+  flipper[:stats].enabled?(user) ? true : nil
+}.compact
+
+# show the results
+actual = (enabled.size / total.to_f * 100).round
+puts "percentage: #{actual} vs hoped for: #{PERCENTAGE}"

data/flipper.gemspec

@@ -4,34 +4,34 @@ require File.expand_path('../lib/flipper/version', __FILE__)
 plugin_files = []
 plugin_test_files = []
 
-Dir['flipper-*.gemspec'].map { |gemspec|
+Dir['flipper-*.gemspec'].map do |gemspec|
   spec = eval(File.read(gemspec))
   plugin_files << spec.files
   plugin_test_files << spec.files
-}
+end
 
 ignored_files = plugin_files
 ignored_files << Dir['script/*']
-ignored_files << ".travis.yml"
-ignored_files << ".gitignore"
-ignored_files << "Guardfile"
+ignored_files << '.travis.yml'
+ignored_files << '.gitignore'
+ignored_files << 'Guardfile'
 ignored_files.flatten!.uniq!
 
 ignored_test_files = plugin_test_files
 ignored_test_files.flatten!.uniq!
 
 Gem::Specification.new do |gem|
-  gem.authors       = ["John Nunemaker"]
-  gem.email         = ["nunemaker@gmail.com"]
-  gem.summary       = %q{Feature flipper for ANYTHING}
-  gem.description   = %q{Feature flipper is the act of enabling/disabling features in your application, ideally without re-deploying or changing anything in your code base. Flipper makes this extremely easy to do with any backend you would like to use.}
-  gem.homepage      = "https://github.com/jnunemaker/flipper"
-  gem.license       = "MIT"
+  gem.authors       = ['John Nunemaker']
+  gem.email         = ['nunemaker@gmail.com']
+  gem.summary       = 'Feature flipper for ANYTHING'
+  gem.description   = 'Feature flipper is the act of enabling/disabling features in your application, ideally without re-deploying or changing anything in your code base. Flipper makes this extremely easy to do with any backend you would like to use.'
+  gem.homepage      = 'https://github.com/jnunemaker/flipper'
+  gem.license       = 'MIT'
 
-  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
-  gem.files         = `git ls-files`.split("\n") - ignored_files + ["lib/flipper/version.rb"]
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n") - ignored_files + ['lib/flipper/version.rb']
   gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n") - ignored_test_files
-  gem.name          = "flipper"
-  gem.require_paths = ["lib"]
+  gem.name          = 'flipper'
+  gem.require_paths = ['lib']
   gem.version       = Flipper::VERSION
 end