Merge pull request #208 from Unleash/add-built-in-strategies

Add default built-in strategies.

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2.1.0
+- Provide a set of pre-defined activation strategies:
+    - applicationHostname
+    - gradualRolloutRandom
+    - gradualRolloutSessionId
+    - gradualRolloutUserId
+    - remoteAddress
+    - userWithId
+
+## 2.0.4
+- bump unleash-frontend which includes a lot of UI improvements and bug-fixes.
+- Fix error message when trying to create a archived feature toggle. 
+
 ## 2.0.0 (January 2017)
 
 - Support multiple strategies. This makes it easy to use multiple activation strategies in combination.

README.md

@@ -18,7 +18,7 @@ This repo contains the unleash-server, which contains the admin UI and a place t
 In order to make use of unleash you will also need a client implementation.
 
 <kbd>
-![2016-12-28-211658_1115x752_scrot](https://github.com/Unleash/unleash/raw/master/docs/2017-02-06-130615_942x802_scrot.png)
+![Unleash UI](https://github.com/Unleash/unleash/raw/master/docs/assets/dashboard.png)
 </kbd>
 
 Online demo [version availble on heroku](https://unleash-new-ui.herokuapp.com/#/features).

docs/activation-strategies.md

@@ -1,14 +1,62 @@
 # Activation Strategies
 
-Activation strategies is a crutial part of Unleash. 
+It is powerful to be able to turn a feature on and off instantaneously, without redeploying the application. The next level of control comes when you are able to enable a feature for specific users or enable it for a small subset of the users. We achieve this level of control with the help of activation strategies. The simplest strategy is the “default” strategy, which basically means that the feature should be enabled to everyone.
 
-TODO! 
-- Definition lives in unleash-server
-- Implementation lives in the client implementations
-- Configuration is assiated with a feature toggle
-- Document common strategies, and how to implement them
- - gradual rollout (sticky vs. random)
- - active for user with id
- - active for host
- - active for remote host
- - totally custom
+The definition of an activation strategy lives in the Unleash API and can be created via the Unleash UI. The implementation of activation strategies lives in the various client implementations. 
+
+Unleash comes with a few common activation strategies. Some of them requires the client to provide the [unleash-context](./unleash-context.md), which gives necessary context for unleash. 
+
+## default
+Is the simples activation strategies and basically means "active for everyone".
+
+## userWithId
+Active for users with a userId defined in the userIds-list. Typically I want to enable a new feature only for myself in production, before I enable it of everyone else. To achieve this we can use the “UserWithIdStrategy”. This strategy allows you to specify a list of specific user ids that you want to expose the new feature for. (A user id may of course be an email if that is more appropriate in your system.)
+
+**Parameters**
+- userIds - *List of user ids you want the feature toggle should be enabled for*
+
+## gradualRolloutUserId
+Gradually activate feature toggle for logged in users. Stickiness based on user id. 
+This strategy guarantees that the same user gets the same experience every time, 
+across devices. It also guarantees that a user which is among the first 10% will 
+also be among the first 20% of the users. Thus we ensure that users get the same 
+experience. Even if we gradually increase the number of users who are exposed to 
+a particular feature. To achieve this we hash the user id and normalise the hash 
+value to a number between 1 and 100 with a simple modulo operator. 
+
+![hash_and_normalise](assets/hash_and_normalise.png)
+
+**Parameters**
+- percentage - *The percentage (0-100) you want to enable to feature toggle for.*
+- groupId - *Used to define a activation groups, which allows you to correlate across feature toggles.*
+
+## gradualRolloutSessionId
+Gradually activate feature toggle. Stickiness based on session id. It is almost 
+identical to the `gradualRolloutUserId` strategy, with the exception that it works 
+on session ids. This makes it possible to target all users (not just logged in 
+users), guaranteeing that a user will get the same experience within a session.
+
+**Parameters**
+- percentage - *The percentage (0-100) you want to enable to feature toggle for.*
+- groupId - *Used to define a activation groups, which allows you to correlate across feature toggles.*
+
+## gradualRolloutRandom 
+Randomly activate the feature toggle. No stickiness. We have found this rollout strategy 
+very useful in some scenarios, especially when we are enabling a feature which is not 
+visible to the user. It is also the strategy we use to sample metrics and error reports.
+
+**Parameters**
+- percentage - *The percentage (0-100) you want to enable to feature toggle for.*
+
+## remoteAddress
+Active for remote addresses defined in the IPs list. We sometimes use this strategy to 
+enable a feature only for IP's in our office network.
+
+**Parameters**
+- IPS - *List of IPs to enable the feature for.*
+
+## applicationHostname
+Active for client instances with a hostName in the hostNames-list.
+
+**Parameters**
+- hostNames - *List of hostnames to enable the feature toggle for.*

docs/unleash-context.md

@@ -0,0 +1,22 @@
+# Unleash Context
+
+In order to standardise a few activation strategies we also needed to 
+standardise a unleash context, which contains some fields that varies 
+per requests, needed to implement the activation strategies. 
+
+The unleash context is defined by these fields:
+
+- userId: String,
+- sessionId: String,
+- remoteAddress: String,
+- properties: Map<String, String>
+
+All fields are optional, but if they are not set you will not be able to use 
+certain activation strategies. 
+
+E.g. the userWithId-strategy obviously depends on the userId field. 
+
+The properties field is more generic and can be used to probide more abritary 
+data to the strategies. A common usage is to add more metadata, e.g. that the 
+current user is a beta user, and thus the betaUser-strategy will use this info
+in its implementation.

migrations/20170211085502-built-in-strategies.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const async = require('async');
+
+exports.up = function (db, cb) {
+    async.series([
+        db.addColumn.bind(db, 'strategies', 'built_in', { type: 'int', defaultValue: 0 }),
+        db.runSql.bind(db, 'UPDATE strategies SET built_in=1 where name=\'default\''),
+    ], cb);
+};
+
+exports.down = function (db, cb) {
+    return db.removeColumn('strategies', 'built_in', cb);
+};

migrations/20170211090541-add-default-strategies.js

@@ -0,0 +1,59 @@
+'use strict';
+
+const strategies = require('./default-strategies.json');
+const async = require('async');
+
+function insertStrategySQL (strategy) {
+    return `
+        INSERT INTO strategies (name, description, parameters, built_in)
+        SELECT '${strategy.name}', '${strategy.description}', '${JSON.stringify(strategy.parameters)}', 1
+        WHERE
+            NOT EXISTS (
+                SELECT name FROM strategies WHERE name = '${strategy.name}'
+        );`;
+}
+
+function insertEventsSQL (strategy) {
+    return `
+        INSERT INTO events (type, created_by, data)
+        SELECT 'strategy-created', 'migration', '${JSON.stringify(strategy)}'
+        WHERE
+            NOT EXISTS (
+                SELECT name FROM strategies WHERE name = '${strategy.name}'
+        );`;
+}
+
+function removeEventsSQL (strategy) {
+    return `
+        INSERT INTO events (type, created_by, data)
+        SELECT 'strategy-deleted', 'migration', '${JSON.stringify(strategy)}'
+        WHERE
+            EXISTS (
+                SELECT name FROM strategies WHERE name = '${strategy.name}' AND built_in = 1
+        );`;
+}
+
+function removeStrategySQL (strategy) {
+    return `
+        DELETE FROM strategies
+        WHERE name = '${strategy.name}' AND built_in = 1`;
+}
+
+exports.up = function (db, callback) {
+    const insertStrategies = strategies.map((s) => (cb) => {
+        db.runSql(insertEventsSQL(s), cb);
+        db.runSql(insertStrategySQL(s), cb);
+    });
+    async.series(insertStrategies, callback);
+};
+
+exports.down = function (db, callback) {
+    const removeStrategies = strategies
+        .filter(s => s.name !== 'default')
+        .map((s) => (cb) => {
+            db.runSql(removeEventsSQL(s), cb);
+            db.runSql(removeStrategySQL(s), cb);
+        });
+
+    async.series(removeStrategies, callback);
+};

migrations/default-strategies.json

@@ -0,0 +1,77 @@
+[
+  {
+    "name": "default",
+    "description": "Default on/off strategy.",
+    "parameters": []
+  },
+  {
+    "name": "userWithId",
+    "description": "Active for users with a userId defined in the userIds-list",
+    "parameters": [{
+      "name": "userIds",
+      "type": "list",
+      "description": "",
+      "required": false
+    }]
+  },
+  {
+    "name": "applicationHostname",
+    "description": "Active for client instances with a hostName in the hostNames-list.",
+    "parameters": [{
+      "name": "hostNames",
+      "type": "list",
+      "description": "List of hostnames to enable the feature toggle for.",
+      "required": false
+    }]
+  },
+  {
+    "name": "gradualRolloutRandom",
+    "description": "Randomly activate the feature toggle. No stickiness.",
+    "parameters": [{
+      "name": "percentage",
+      "type": "percentage",
+      "description": "",
+      "required": false
+    }]
+  },
+  {
+    "name": "gradualRolloutSessionId",
+    "description": "Gradually activate feature toggle. Stickiness based on session id.",
+    "parameters": [{
+      "name": "percentage",
+      "type": "percentage",
+      "description": "",
+      "required": false
+    },{
+      "name": "groupId",
+      "type": "string",
+      "description": "Used to define a activation groups, which allows you to correlate across feature toggles.",
+      "required": true
+    }]
+  },
+  {
+    "name": "gradualRolloutUserId",
+    "description": "Gradually activate feature toggle for logged in users. Stickiness based on user id.",
+    "parameters": [{
+      "name": "percentage",
+      "type": "percentage",
+      "description": "",
+      "required": false
+    },{
+      "name": "groupId",
+      "type": "string",
+      "description": "Used to define a activation groups, which allows you to correlate across feature toggles.",
+      "required": true
+    }]
+  },
+  {
+    "name": "remoteAddress",
+    "description": "Active for remote addresses defined in the IPs list.",
+    "parameters": [{
+      "name": "IPs",
+      "type": "list",
+      "description": "List of IPs to enable the feature toggle for.",
+      "required": true
+    }]
+  }
+]