Merge branch 'master' into docs/fix-internal-links

.github/workflows/build_doc_prs.yaml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
-      - name: setup git config
+      - name: Build docs
         run: |
           # Build the site
           cd website && yarn && yarn build

src/lib/db/feature-strategy-store.ts

@@ -286,6 +286,7 @@ class FeatureStrategiesStore implements IFeatureStrategiesStore {
                 );
                 return e;
             });
+            featureToggle.variants = featureToggle.variants || [];
             featureToggle.archived = archived;
             return featureToggle;
         }

src/lib/db/feature-toggle-store.ts

@@ -161,12 +161,19 @@ export default class FeatureToggleStore implements IFeatureToggleStore {
             type: row.type,
             project: row.project,
             stale: row.stale,
-            variants: row.variants as unknown as IVariant[],
+            variants: (row.variants as unknown as IVariant[]) || [],
             createdAt: row.created_at,
             lastSeenAt: row.last_seen_at,
         };
     }
 
+    rowToVariants(row: FeaturesTable): IVariant[] {
+        if (!row) {
+            throw new NotFoundError('No feature toggle found');
+        }
+        return (row.variants as unknown as IVariant[]) || [];
+    }
+
     dtoToRow(project: string, data: FeatureToggleDTO): FeaturesTable {
         const row = {
             name: data.name,
@@ -175,7 +182,9 @@ export default class FeatureToggleStore implements IFeatureToggleStore {
             project,
             archived: data.archived || false,
             stale: data.stale,
-            variants: data.variants ? JSON.stringify(data.variants) : null,
+            variants: data.variants
+                ? JSON.stringify(data.variants)
+                : JSON.stringify([]),
             created_at: data.createdAt,
         };
         if (!row.created_at) {
@@ -232,6 +241,24 @@ export default class FeatureToggleStore implements IFeatureToggleStore {
             .returning(FEATURE_COLUMNS);
         return this.rowToFeature(row[0]);
     }
+
+    async getVariants(featureName: string): Promise<IVariant[]> {
+        const row = await this.db(TABLE)
+            .select('variants')
+            .where({ name: featureName });
+        return this.rowToVariants(row[0]);
+    }
+
+    async saveVariants(
+        featureName: string,
+        newVariants: IVariant[],
+    ): Promise<FeatureToggle> {
+        const row = await this.db(TABLE)
+            .update({ variants: JSON.stringify(newVariants) })
+            .where({ name: featureName })
+            .returning(FEATURE_COLUMNS);
+        return this.rowToFeature(row[0]);
+    }
 }
 
 module.exports = FeatureToggleStore;

src/lib/routes/admin-api/project/index.ts

@@ -6,6 +6,7 @@ import ProjectFeaturesController from './features';
 import EnvironmentsController from './environments';
 import ProjectHealthReport from './health-report';
 import ProjectService from '../../../services/project-service';
+import VariantsController from './variants';
 
 export default class ProjectApi extends Controller {
     private projectService: ProjectService;
@@ -17,6 +18,7 @@ export default class ProjectApi extends Controller {
         this.use('/', new ProjectFeaturesController(config, services).router);
         this.use('/', new EnvironmentsController(config, services).router);
         this.use('/', new ProjectHealthReport(config, services).router);
+        this.use('/', new VariantsController(config, services).router);
     }
 
     async getProjects(req: Request, res: Response): Promise<void> {

src/lib/routes/admin-api/project/variants.ts

@@ -0,0 +1,78 @@
+import FeatureToggleService from '../../../services/feature-toggle-service';
+import { Logger } from '../../../logger';
+import Controller from '../../controller';
+import { IUnleashConfig } from '../../../types/option';
+import { IUnleashServices } from '../../../types';
+import { Request, Response } from 'express';
+import { Operation } from 'fast-json-patch';
+import { UPDATE_FEATURE } from '../../../types/permissions';
+import { IVariant } from '../../../types/model';
+
+const PREFIX = '/:projectId/features/:featureName/variants';
+
+interface FeatureParams extends ProjectParam {
+    featureName: string;
+}
+
+interface ProjectParam {
+    projectId: string;
+}
+
+export default class VariantsController extends Controller {
+    private logger: Logger;
+
+    private featureService: FeatureToggleService;
+
+    constructor(
+        config: IUnleashConfig,
+        {
+            featureToggleService,
+        }: Pick<IUnleashServices, 'featureToggleService'>,
+    ) {
+        super(config);
+        this.logger = config.getLogger('admin-api/project/variants.ts');
+        this.featureService = featureToggleService;
+        this.get(PREFIX, this.getVariants);
+        this.patch(PREFIX, this.patchVariants, UPDATE_FEATURE);
+        this.put(PREFIX, this.overwriteVariants, UPDATE_FEATURE);
+    }
+
+    async getVariants(
+        req: Request<FeatureParams, any, any, any>,
+        res: Response,
+    ): Promise<void> {
+        const { featureName } = req.params;
+        const variants = await this.featureService.getVariants(featureName);
+        res.status(200).json({ version: '1', variants: variants || [] });
+    }
+
+    async patchVariants(
+        req: Request<FeatureParams, any, Operation[], any>,
+        res: Response,
+    ): Promise<void> {
+        const { featureName } = req.params;
+        const updatedFeature = await this.featureService.updateVariants(
+            featureName,
+            req.body,
+        );
+        res.status(200).json({
+            version: '1',
+            variants: updatedFeature.variants,
+        });
+    }
+
+    async overwriteVariants(
+        req: Request<FeatureParams, any, IVariant[], any>,
+        res: Response,
+    ): Promise<void> {
+        const { featureName } = req.params;
+        const updatedFeature = await this.featureService.saveVariants(
+            featureName,
+            req.body,
+        );
+        res.status(200).json({
+            version: '1',
+            variants: updatedFeature.variants,
+        });
+    }
+}

src/lib/schema/feature-schema.ts

@@ -42,6 +42,12 @@ export const variantsSchema = joi.object().keys({
     ),
 });
 
+export const variantsArraySchema = joi
+    .array()
+    .min(0)
+    .items(variantsSchema)
+    .unique((a, b) => a.name === b.name);
+
 export const featureMetadataSchema = joi
     .object()
     .keys({

src/lib/services/feature-toggle-service.ts

@@ -5,7 +5,11 @@ import BadDataError from '../error/bad-data-error';
 import NameExistsError from '../error/name-exists-error';
 import InvalidOperationError from '../error/invalid-operation-error';
 import { FOREIGN_KEY_VIOLATION } from '../error/db-error';
-import { featureMetadataSchema, nameSchema } from '../schema/feature-schema';
+import {
+    featureMetadataSchema,
+    nameSchema,
+    variantsArraySchema,
+} from '../schema/feature-schema';
 import {
     FeatureArchivedEvent,
     FeatureChangeProjectEvent,
@@ -40,6 +44,8 @@ import {
     IFeatureStrategy,
     IFeatureToggleQuery,
     IStrategyConfig,
+    IVariant,
+    WeightType,
 } from '../types/model';
 import { IFeatureEnvironmentStore } from '../types/stores/feature-environment-store';
 import { IFeatureToggleClientStore } from '../types/stores/feature-toggle-client-store';
@@ -389,6 +395,15 @@ class FeatureToggleService {
         );
     }
 
+    /**
+     * GET /api/admin/projects/:project/features/:featureName/variants
+     * @param featureName
+     * @return The list of variants
+     */
+    async getVariants(featureName: string): Promise<IVariant[]> {
+        return this.featureToggleStore.getVariants(featureName);
+    }
+
     async getFeatureMetadata(featureName: string): Promise<FeatureToggle> {
         return this.featureToggleStore.get(featureName);
     }
@@ -882,6 +897,63 @@ class FeatureToggleService {
             newProjectId,
         );
     }
+
+    async updateVariants(
+        featureName: string,
+        newVariants: Operation[],
+    ): Promise<FeatureToggle> {
+        const oldVariants = await this.getVariants(featureName);
+        const { newDocument } = await applyPatch(oldVariants, newVariants);
+        return this.saveVariants(featureName, newDocument);
+    }
+
+    async saveVariants(
+        featureName: string,
+        newVariants: IVariant[],
+    ): Promise<FeatureToggle> {
+        await variantsArraySchema.validateAsync(newVariants);
+        const fixedVariants = this.fixVariantWeights(newVariants);
+        return this.featureToggleStore.saveVariants(featureName, fixedVariants);
+    }
+
+    fixVariantWeights(variants: IVariant[]): IVariant[] {
+        let variableVariants = variants.filter((x) => {
+            return x.weightType === WeightType.VARIABLE;
+        });
+
+        if (variants.length > 0 && variableVariants.length === 0) {
+            throw new BadDataError(
+                'There must be at least one "variable" variant',
+            );
+        }
+
+        let fixedVariants = variants.filter((x) => {
+            return x.weightType === WeightType.FIX;
+        });
+
+        let fixedWeights = fixedVariants.reduce((a, v) => a + v.weight, 0);
+
+        if (fixedWeights > 1000) {
+            throw new BadDataError(
+                'The traffic distribution total must equal 100%',
+            );
+        }
+
+        let averageWeight = Math.floor(
+            (1000 - fixedWeights) / variableVariants.length,
+        );
+        let remainder = (1000 - fixedWeights) % variableVariants.length;
+
+        variableVariants = variableVariants.map((x) => {
+            x.weight = averageWeight;
+            if (remainder > 0) {
+                x.weight += 1;
+                remainder--;
+            }
+            return x;
+        });
+        return variableVariants.concat(fixedVariants);
+    }
 }
 
 export default FeatureToggleService;

src/lib/types/model.ts

@@ -8,7 +8,10 @@ export interface IConstraint {
     operator: string;
     values: string[];
 }
-
+export enum WeightType {
+    VARIABLE = 'variable',
+    FIX = 'fix',
+}
 export interface IStrategyConfig {
     id?: string;
     name: string;

src/lib/types/stores/feature-toggle-store.ts

@@ -1,4 +1,4 @@
-import { FeatureToggle, FeatureToggleDTO } from '../model';
+import { FeatureToggle, FeatureToggleDTO, IVariant } from '../model';
 import { Store } from './store';
 
 export interface IFeatureToggleQuery {
@@ -16,4 +16,9 @@ export interface IFeatureToggleStore extends Store<FeatureToggle, string> {
     archive(featureName: string): Promise<FeatureToggle>;
     revive(featureName: string): Promise<FeatureToggle>;
     getAll(query?: Partial<IFeatureToggleQuery>): Promise<FeatureToggle[]>;
+    getVariants(featureName: string): Promise<IVariant[]>;
+    saveVariants(
+        featureName: string,
+        newVariants: IVariant[],
+    ): Promise<FeatureToggle>;
 }

src/test/e2e/api/admin/client-metrics.e2e.test.ts

@@ -173,7 +173,7 @@ test('should return toggle summary', async () => {
 
 test('should only include last hour of metrics return toggle summary', async () => {
     const now = new Date();
-    const dateOneHourAgo = subHours(now, 1);
+    const dateTwoHoursAgo = subHours(now, 2);
     const metrics: IClientMetricsEnv[] = [
         {
             featureName: 'demo',
@@ -211,7 +211,7 @@ test('should only include last hour of metrics return toggle summary', async ()
             featureName: 'demo',
             appName: 'backend-api',
             environment: 'test',
-            timestamp: dateOneHourAgo,
+            timestamp: dateTwoHoursAgo,
             yes: 55,
             no: 55,
         },

src/test/e2e/api/admin/project/variants.e2e.test.ts

@@ -0,0 +1,716 @@
+import { IUnleashTest, setupApp } from '../../../helpers/test-helper';
+import dbInit, { ITestDb } from '../../../helpers/database-init';
+import getLogger from '../../../../fixtures/no-logger';
+import * as jsonpatch from 'fast-json-patch';
+import { IVariant, WeightType } from '../../../../../lib/types/model';
+
+let app: IUnleashTest;
+let db: ITestDb;
+
+beforeAll(async () => {
+    db = await dbInit('project_feature_variants_api_serial', getLogger);
+    app = await setupApp(db.stores);
+});
+
+afterAll(async () => {
+    await app.destroy();
+    await db.destroy();
+});
+
+test('Can get variants for a feature', async () => {
+    const featureName = 'feature-variants';
+    const variantName = 'fancy-variant';
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+        variants: [
+            {
+                name: variantName,
+                stickiness: 'default',
+                weight: 1000,
+                weightType: WeightType.VARIABLE,
+            },
+        ],
+    });
+    await app.request
+        .get(`/api/admin/projects/default/features/${featureName}/variants`)
+        .expect(200)
+        .expect((res) => {
+            expect(res.body.version).toBe('1');
+            expect(res.body.variants).toHaveLength(1);
+            expect(res.body.variants[0].name).toBe(variantName);
+        });
+});
+
+test('Trying to do operations on a non-existing feature yields 404', async () => {
+    await app.request
+        .get(
+            '/api/admin/projects/default/features/non-existing-feature/variants',
+        )
+        .expect(404);
+    const variants = [
+        {
+            name: 'variant-put-overwrites',
+            stickiness: 'default',
+            weight: 1000,
+            weightType: WeightType.VARIABLE,
+        },
+    ];
+    await app.request
+        .put('/api/admin/projects/default/features/${featureName}/variants')
+        .send(variants)
+        .expect(404);
+
+    const newVariants: IVariant[] = [];
+    const observer = jsonpatch.observe(newVariants);
+    newVariants.push({
+        name: 'variant1',
+        stickiness: 'default',
+        weight: 700,
+        weightType: WeightType.VARIABLE,
+    });
+    let patch = jsonpatch.generate(observer);
+    await app.request
+        .patch('/api/admin/projects/default/features/${featureName}/variants')
+        .send(patch)
+        .expect(404);
+});
+
+test('Can patch variants for a feature and get a response of new variant', async () => {
+    const featureName = 'feature-variants-patch';
+    const variantName = 'fancy-variant-patch';
+    const expectedVariantName = 'not-so-cool-variant-name';
+    const variants = [
+        {
+            name: variantName,
+            stickiness: 'default',
+            weight: 1000,
+            weightType: WeightType.VARIABLE,
+        },
+    ];
+
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+        variants,
+    });
+
+    const observer = jsonpatch.observe(variants);
+    variants[0].name = expectedVariantName;
+    const patch = jsonpatch.generate(observer);
+
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(patch)
+        .expect(200)
+        .expect((res) => {
+            expect(res.body.version).toBe('1');
+            expect(res.body.variants).toHaveLength(1);
+            expect(res.body.variants[0].name).toBe(expectedVariantName);
+        });
+});
+
+test('Can add variant for a feature', async () => {
+    const featureName = 'feature-variants-patch-add';
+    const variantName = 'fancy-variant-patch';
+    const expectedVariantName = 'not-so-cool-variant-name';
+    const variants = [
+        {
+            name: variantName,
+            stickiness: 'default',
+            weight: 1000,
+            weightType: WeightType.VARIABLE,
+        },
+    ];
+
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+        variants,
+    });
+
+    const observer = jsonpatch.observe(variants);
+    variants.push({
+        name: expectedVariantName,
+        stickiness: 'default',
+        weight: 1000,
+        weightType: WeightType.VARIABLE,
+    });
+    const patch = jsonpatch.generate(observer);
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(patch)
+        .expect(200);
+
+    await app.request
+        .get(`/api/admin/projects/default/features/${featureName}/variants`)
+        .expect((res) => {
+            expect(res.body.version).toBe('1');
+            expect(res.body.variants).toHaveLength(2);
+            expect(
+                res.body.variants.find((x) => x.name === expectedVariantName),
+            ).toBeTruthy();
+            expect(
+                res.body.variants.find((x) => x.name === variantName),
+            ).toBeTruthy();
+        });
+});
+
+test('Can remove variant for a feature', async () => {
+    const featureName = 'feature-variants-patch-remove';
+    const variantName = 'fancy-variant-patch';
+    const variants = [
+        {
+            name: variantName,
+            stickiness: 'default',
+            weight: 1000,
+            weightType: WeightType.VARIABLE,
+        },
+    ];
+
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+        variants,
+    });
+
+    const observer = jsonpatch.observe(variants);
+    variants.pop();
+    const patch = jsonpatch.generate(observer);
+
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(patch)
+        .expect(200);
+
+    await app.request
+        .get(`/api/admin/projects/default/features/${featureName}/variants`)
+        .expect((res) => {
+            expect(res.body.version).toBe('1');
+            expect(res.body.variants).toHaveLength(0);
+        });
+});
+
+test('PUT overwrites current variant on feature', async () => {
+    const featureName = 'variant-put-overwrites';
+    const variantName = 'overwriting-for-fun';
+    const variants = [
+        {
+            name: variantName,
+            stickiness: 'default',
+            weight: 1000,
+            weightType: WeightType.VARIABLE,
+        },
+    ];
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+        variants,
+    });
+
+    const newVariants: IVariant[] = [
+        {
+            name: 'variant1',
+            stickiness: 'default',
+            weight: 250,
+            weightType: WeightType.FIX,
+        },
+        {
+            name: 'variant2',
+            stickiness: 'default',
+            weight: 375,
+            weightType: WeightType.VARIABLE,
+        },
+        {
+            name: 'variant3',
+            stickiness: 'default',
+            weight: 450,
+            weightType: WeightType.VARIABLE,
+        },
+    ];
+    await app.request
+        .put(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(newVariants)
+        .expect(200)
+        .expect((res) => {
+            expect(res.body.variants).toHaveLength(3);
+        });
+    await app.request
+        .get(`/api/admin/projects/default/features/${featureName}/variants`)
+        .expect(200)
+        .expect((res) => {
+            expect(res.body.variants).toHaveLength(3);
+            expect(res.body.variants.reduce((a, v) => a + v.weight, 0)).toEqual(
+                1000,
+            );
+        });
+});
+
+test('PUTing an invalid variant throws 400 exception', async () => {
+    const featureName = 'variants-validation-feature';
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+    });
+
+    const invalidJson = [
+        {
+            name: 'variant',
+            weight: 500,
+            weightType: 'party',
+        },
+    ];
+    await app.request
+        .put(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(invalidJson)
+        .expect(400)
+        .expect((res) => {
+            expect(res.body.details).toHaveLength(1);
+            expect(res.body.details[0].message).toMatch(
+                /.*weightType\" must be one of/,
+            );
+        });
+});
+
+test('Invalid variant in PATCH also throws 400 exception', async () => {
+    const featureName = 'patch-validation-feature';
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+    });
+
+    const invalidPatch = `[{
+        "op": "add",
+        "path": "/1",
+        "value": {
+            "name": "not-so-cool-variant-name",
+            "stickiness": "default",
+            "weight": 2000,
+            "weightType": "variable"
+        }
+    }]`;
+
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .set('Content-Type', 'application/json')
+        .send(invalidPatch)
+        .expect(400)
+        .expect((res) => {
+            expect(res.body.details).toHaveLength(1);
+            expect(res.body.details[0].message).toMatch(
+                /.*weight\" must be less than or equal to 1000/,
+            );
+        });
+});
+
+test('PATCHING with all variable weightTypes forces weights to sum to no less than 1000 minus the number of variable variants', async () => {
+    const featureName = 'variants-validation-with-all-variable-weights';
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+    });
+
+    const newVariants: IVariant[] = [];
+
+    const observer = jsonpatch.observe(newVariants);
+    newVariants.push({
+        name: 'variant1',
+        stickiness: 'default',
+        weight: 700,
+        weightType: WeightType.VARIABLE,
+    });
+    let patch = jsonpatch.generate(observer);
+
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(patch)
+        .expect(200)
+        .expect((res) => {
+            expect(res.body.variants).toHaveLength(1);
+            expect(res.body.variants[0].weight).toEqual(1000);
+        });
+
+    newVariants.push({
+        name: 'variant2',
+        stickiness: 'default',
+        weight: 700,
+        weightType: WeightType.VARIABLE,
+    });
+
+    patch = jsonpatch.generate(observer);
+
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(patch)
+        .expect(200)
+        .expect((res) => {
+            expect(res.body.variants).toHaveLength(2);
+            expect(
+                res.body.variants.every((x) => x.weight === 500),
+            ).toBeTruthy();
+        });
+
+    newVariants.push({
+        name: 'variant3',
+        stickiness: 'default',
+        weight: 700,
+        weightType: WeightType.VARIABLE,
+    });
+
+    patch = jsonpatch.generate(observer);
+
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(patch)
+        .expect(200)
+        .expect((res) => {
+            res.body.variants.sort((v, other) => other.weight - v.weight);
+            expect(res.body.variants).toHaveLength(3);
+            expect(res.body.variants[0].weight).toBe(334);
+            expect(res.body.variants[1].weight).toBe(333);
+            expect(res.body.variants[2].weight).toBe(333);
+        });
+
+    newVariants.push({
+        name: 'variant4',
+        stickiness: 'default',
+        weight: 700,
+        weightType: WeightType.VARIABLE,
+    });
+
+    patch = jsonpatch.generate(observer);
+
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(patch)
+        .expect(200)
+        .expect((res) => {
+            expect(res.body.variants).toHaveLength(4);
+            expect(
+                res.body.variants.every((x) => x.weight === 250),
+            ).toBeTruthy();
+        });
+});
+
+test('PATCHING with no variable variants fails with 400', async () => {
+    const featureName = 'variants-validation-with-no-variable-weights';
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+    });
+
+    const newVariants: IVariant[] = [];
+
+    const observer = jsonpatch.observe(newVariants);
+    newVariants.push({
+        name: 'variant1',
+        stickiness: 'default',
+        weight: 900,
+        weightType: WeightType.FIX,
+    });
+
+    const patch = jsonpatch.generate(observer);
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(patch)
+        .expect(400)
+        .expect((res) => {
+            expect(res.body.details).toHaveLength(1);
+            expect(res.body.details[0].message).toEqual(
+                'There must be at least one "variable" variant',
+            );
+        });
+});
+
+test('Patching with a fixed variant and variable variants splits remaining weight among variable variants', async () => {
+    const featureName = 'variants-fixed-and-variable';
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+    });
+
+    const newVariants: IVariant[] = [];
+    const observer = jsonpatch.observe(newVariants);
+    newVariants.push({
+        name: 'variant1',
+        stickiness: 'default',
+        weight: 900,
+        weightType: WeightType.FIX,
+    });
+    newVariants.push({
+        name: 'variant2',
+        stickiness: 'default',
+        weight: 20,
+        weightType: WeightType.VARIABLE,
+    });
+    newVariants.push({
+        name: 'variant3',
+        stickiness: 'default',
+        weight: 123,
+        weightType: WeightType.VARIABLE,
+    });
+    newVariants.push({
+        name: 'variant4',
+        stickiness: 'default',
+        weight: 123,
+        weightType: WeightType.VARIABLE,
+    });
+    newVariants.push({
+        name: 'variant5',
+        stickiness: 'default',
+        weight: 123,
+        weightType: WeightType.VARIABLE,
+    });
+    newVariants.push({
+        name: 'variant6',
+        stickiness: 'default',
+        weight: 123,
+        weightType: WeightType.VARIABLE,
+    });
+    newVariants.push({
+        name: 'variant7',
+        stickiness: 'default',
+        weight: 123,
+        weightType: WeightType.VARIABLE,
+    });
+
+    const patch = jsonpatch.generate(observer);
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(patch)
+        .expect(200);
+
+    await app.request
+        .get(`/api/admin/projects/default/features/${featureName}/variants`)
+        .expect(200)
+        .expect((res) => {
+            let body = res.body;
+            expect(body.variants).toHaveLength(7);
+            expect(
+                body.variants.reduce((total, v) => total + v.weight, 0),
+            ).toEqual(1000);
+            body.variants.sort((a, b) => b.weight - a.weight);
+            expect(
+                body.variants.find((v) => v.name === 'variant1').weight,
+            ).toEqual(900);
+            expect(
+                body.variants.find((v) => v.name === 'variant2').weight,
+            ).toEqual(17);
+            expect(
+                body.variants.find((v) => v.name === 'variant3').weight,
+            ).toEqual(17);
+            expect(
+                body.variants.find((v) => v.name === 'variant4').weight,
+            ).toEqual(17);
+            expect(
+                body.variants.find((v) => v.name === 'variant5').weight,
+            ).toEqual(17);
+            expect(
+                body.variants.find((v) => v.name === 'variant6').weight,
+            ).toEqual(16);
+            expect(
+                body.variants.find((v) => v.name === 'variant7').weight,
+            ).toEqual(16);
+        });
+});
+
+test('Multiple fixed variants gets added together to decide how much weight variable variants should get', async () => {
+    const featureName = 'variants-multiple-fixed-and-variable';
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+    });
+
+    const newVariants: IVariant[] = [];
+
+    const observer = jsonpatch.observe(newVariants);
+    newVariants.push({
+        name: 'variant1',
+        stickiness: 'default',
+        weight: 600,
+        weightType: WeightType.FIX,
+    });
+    newVariants.push({
+        name: 'variant2',
+        stickiness: 'default',
+        weight: 350,
+        weightType: WeightType.FIX,
+    });
+    newVariants.push({
+        name: 'variant3',
+        stickiness: 'default',
+        weight: 350,
+        weightType: WeightType.VARIABLE,
+    });
+
+    const patch = jsonpatch.generate(observer);
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(patch)
+        .expect(200);
+    await app.request
+        .get(`/api/admin/projects/default/features/${featureName}/variants`)
+        .expect(200)
+        .expect((res) => {
+            let body = res.body;
+            expect(body.variants).toHaveLength(3);
+            expect(
+                body.variants.find((v) => v.name === 'variant3').weight,
+            ).toEqual(50);
+        });
+});
+
+test('If sum of fixed variant weight exceed 1000 fails with 400', async () => {
+    const featureName = 'variants-fixed-weight-over-1000';
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+    });
+
+    const newVariants: IVariant[] = [];
+
+    const observer = jsonpatch.observe(newVariants);
+    newVariants.push({
+        name: 'variant1',
+        stickiness: 'default',
+        weight: 900,
+        weightType: WeightType.FIX,
+    });
+    newVariants.push({
+        name: 'variant2',
+        stickiness: 'default',
+        weight: 900,
+        weightType: WeightType.FIX,
+    });
+    newVariants.push({
+        name: 'variant3',
+        stickiness: 'default',
+        weight: 350,
+        weightType: WeightType.VARIABLE,
+    });
+
+    const patch = jsonpatch.generate(observer);
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(patch)
+        .expect(400)
+        .expect((res) => {
+            expect(res.body.details).toHaveLength(1);
+            expect(res.body.details[0].message).toEqual(
+                'The traffic distribution total must equal 100%',
+            );
+        });
+});
+
+test('If sum of fixed variant weight equals 1000 variable variants gets weight 0', async () => {
+    const featureName = 'variants-fixed-weight-equals-1000-no-variable-weight';
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+    });
+
+    const newVariants: IVariant[] = [];
+
+    const observer = jsonpatch.observe(newVariants);
+    newVariants.push({
+        name: 'variant1',
+        stickiness: 'default',
+        weight: 900,
+        weightType: WeightType.FIX,
+    });
+    newVariants.push({
+        name: 'variant2',
+        stickiness: 'default',
+        weight: 100,
+        weightType: WeightType.FIX,
+    });
+    newVariants.push({
+        name: 'variant3',
+        stickiness: 'default',
+        weight: 350,
+        weightType: WeightType.VARIABLE,
+    });
+    newVariants.push({
+        name: 'variant4',
+        stickiness: 'default',
+        weight: 350,
+        weightType: WeightType.VARIABLE,
+    });
+
+    const patch = jsonpatch.generate(observer);
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(patch)
+        .expect(200);
+    await app.request
+        .get(`/api/admin/projects/default/features/${featureName}/variants`)
+        .expect(200)
+        .expect((res) => {
+            let body = res.body;
+            expect(body.variants).toHaveLength(4);
+            expect(
+                body.variants.find((v) => v.name === 'variant3').weight,
+            ).toEqual(0);
+            expect(
+                body.variants.find((v) => v.name === 'variant4').weight,
+            ).toEqual(0);
+        });
+});
+
+test('PATCH endpoint validates uniqueness of variant names', async () => {
+    const featureName = 'variants-uniqueness-names';
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+        variants: [
+            {
+                name: 'variant1',
+                weight: 1000,
+                weightType: WeightType.VARIABLE,
+                stickiness: 'default',
+            },
+        ],
+    });
+
+    const newVariants: IVariant[] = [];
+
+    const observer = jsonpatch.observe(newVariants);
+    newVariants.push({
+        name: 'variant1',
+        weight: 550,
+        weightType: WeightType.VARIABLE,
+        stickiness: 'default',
+    });
+    newVariants.push({
+        name: 'variant2',
+        weight: 550,
+        weightType: WeightType.VARIABLE,
+        stickiness: 'default',
+    });
+    const patch = jsonpatch.generate(observer);
+    await app.request
+        .patch(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send(patch)
+        .expect(400)
+        .expect((res) => {
+            expect(res.body.details[0].message).toMatch(
+                /contains a duplicate value/,
+            );
+        });
+});
+
+test('PUT endpoint validates uniqueness of variant names', async () => {
+    const featureName = 'variants-put-uniqueness-names';
+    await db.stores.featureToggleStore.create('default', {
+        name: featureName,
+        variants: [],
+    });
+    await app.request
+        .put(`/api/admin/projects/default/features/${featureName}/variants`)
+        .send([
+            {
+                name: 'variant1',
+                weightType: 'variable',
+                weight: 500,
+                stickiness: 'default',
+            },
+            {
+                name: 'variant1',
+                weightType: 'variable',
+                weight: 500,
+                stickiness: 'default',
+            },
+        ])
+        .expect(400)
+        .expect((res) => {
+            expect(res.body.details[0].message).toMatch(
+                /contains a duplicate value/,
+            );
+        });
+});

src/test/fixtures/fake-feature-toggle-store.ts

@@ -2,7 +2,11 @@ import {
     IFeatureToggleQuery,
     IFeatureToggleStore,
 } from '../../lib/types/stores/feature-toggle-store';
-import { FeatureToggle, FeatureToggleDTO } from '../../lib/types/model';
+import {
+    FeatureToggle,
+    FeatureToggleDTO,
+    IVariant,
+} from '../../lib/types/model';
 import NotFoundError from '../../lib/error/notfound-error';
 
 export default class FakeFeatureToggleStore implements IFeatureToggleStore {
@@ -123,4 +127,18 @@ export default class FakeFeatureToggleStore implements IFeatureToggleStore {
             }
         });
     }
+
+    async getVariants(featureName: string): Promise<IVariant[]> {
+        const feature = await this.get(featureName);
+        return feature.variants;
+    }
+
+    async saveVariants(
+        featureName: string,
+        newVariants: IVariant[],
+    ): Promise<FeatureToggle> {
+        const feature = await this.get(featureName);
+        feature.variants = newVariants;
+        return feature;
+    }
 }

website/docs/activation-strategies.md

@@ -1,88 +0,0 @@
----
-id: activation_strategy
-title: Activation Strategies
----
-
-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 users. We achieve this level of control with the help of activation strategies. The most straightforward strategy is the “default” strategy, which basically means that the feature should be enabled to everyone.
-
-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 various client implementations.
-
-Unleash comes with a few common activation strategies. Some of them require the client to provide the [unleash-context](./unleash-context.md), which gives the necessary context for Unleash.
-
-## default {#default}
-
-It is the simplest activation strategy and basically means "active for everyone".
-
-## userWithId {#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 for everyone else. To achieve this, we can use the “UserWithIdStrategy”. This strategy allows you to specify a list of 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 to be enabled for_
-
-## flexibleRollout {#flexiblerollout}
-
-A flexible rollout strategy which combines all gradual rollout strategies in to a single strategy (and will in time replace them). This strategy have different options for how you want to handle the stickiness, and have sane default mode.
-
-**Parameters**
-
-- **stickiness** is used to define how we guarantee consistency for gradual rollout. The same userId and the same rollout percentage should give predictable results. Configuration that should be supported:
-  - **default** - Unleash chooses the first value present on the context in defined order userId, sessionId, random.
-  - **userId** - guaranteed to be sticky on userId. If userId not present the behavior would be false
-  - **sessionId** - guaranteed to be sticky on sessionId. If sessionId not present the behavior would be false.
-  - **random** - no stickiness guaranteed. For every isEnabled call it will yield a random true/false based on the selected rollout percentage.
-- **groupId** is used to ensure that different toggles will **hash differently** for the same user. The groupId defaults to _feature toggle name_, but the use can override it to _correlate rollout_ of multiple feature toggles.
-- **rollout** The percentage (0-100) you want to enable the feature toggle for.
-
-### Customize stickiness (beta) {#customize-stickiness-beta}
-
-By enabling the stickiness option on a custom context field you can use it together with the flexible rollout strategy. This will guarantee a consistent behavior for specific values of this context field. PS! support for this feature currently being supported by the following SDKs:
-
-- [unleash-client-node](https://github.com/Unleash/unleash-client-node) (from v3.6.0)
-
-## gradualRolloutUserId {#gradualrolloutuserid}
-
-The `gradualRolloutUserId` strategy gradually activates a feature toggle for logged-in users. Stickiness is based on the user ID. The strategy guarantees that the same user gets the same experience every time across devices. It also assures that a user which is among the first 10% will also be among the first 20% of the users. That way, we ensure the users get the same experience, even if we gradually increase the number of users exposed to a particular feature. To achieve this, we hash the user ID and normalize the hash value to a number between 1 and 100 with a simple modulo operator.
-
-![hash_and_normalise](/img/hash_and_normalise.png)
-
-Starting from v3.x all clients should use the 32-bit [MurmurHash3](https://en.wikipedia.org/wiki/MurmurHash) algorithm to normalize values. ([issue 247](https://github.com/Unleash/unleash/issues/247))
-
-**Parameters**
-
-- percentage - _The percentage (0-100) you want to enable the feature toggle for._
-- groupId - _Used to define an activation group, which allows you to correlate rollout across feature toggles._
-
-## gradualRolloutSessionId {#gradualrolloutsessionid}
-
-Similar to `gradualRolloutUserId` strategy, this strategy gradually activates a feature toggle, with the exception being that the stickiness is based on the 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 the feature toggle for._
-- groupId - _Used to define an activation group, which allows you to correlate rollout across feature toggles._
-
-## gradualRolloutRandom {#gradualrolloutrandom}
-
-The `gradualRolloutRandom` strategy randomly activates a feature toggle and has no stickiness. We have found this rollout strategy very useful in some scenarios, especially when we enable 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 the feature toggle for._
-
-## remoteAddress {#remoteaddress}
-
-The remote address strategy activates a feature toggle for remote addresses defined in the IP list. We occasionally use this strategy to enable a feature only for IPs in our office network.
-
-**Parameters**
-
-- IPs - _List of IPs to enable the feature for._
-
-## applicationHostname {#applicationhostname}
-
-The application hostname strategy activates a feature toggle for client instances with a hostName in the `hostNames` list.
-
-**Parameters**
-
-- hostNames - _List of hostnames to enable the feature toggle for._

website/docs/advanced/custom-activation-strategy.md

@@ -3,7 +3,7 @@ id: custom_activation_strategy
 title: Custom Activation Strategy
 ---
 
-Even though Unleash comes with a few powerful [activation strategies](activation-strategies.md) there might be scenarios where you would like to extend Unleash with your own custom strategies.
+Even though Unleash comes with a few powerful [activation strategies](../user_guide/activation-strategies.md) there might be scenarios where you would like to extend Unleash with your own custom strategies.
 
 ### Example: TimeStamp Strategy {#example-timestamp-strategy}
 

website/docs/advanced/stickiness.md

@@ -0,0 +1,36 @@
+---
+id: stickiness
+title: Stickiness
+---
+
+_Stickiness_ is how Unleash guarantees that the same user gets the same features every time. Stickiness is useful in any scenario where you want to either show a feature to only a subset of users or give users a variant of a feature.
+
+## Calculation
+
+By default, Unleash calculates stickiness based on the user id and the group id. If the user id is unavailable, it falls back to using the session id instead. It hashes these values to a number between 0 and 100 using the [MurmurHash hash function](https://en.wikipedia.org/wiki/MurmurHash). This number is what determines whether a user will see a specific feature or variant. Because the process is deterministic, the same user will always get the same number.
+
+If both the user id and the session id is unavailable, the calculation returns a random value and stickiness is not guaranteed.
+
+## Consistency
+
+Because the number assigned to a user won't change, Unleash also guarantees that the a user will keep seeing the same features even if certain other parameters change.
+
+For instance: When using the [gradual rollout activation strategy](../user_guide/activation-strategies.md#gradual-rollout), any user whose number is less than or equal to the rollout percentage will see the feature. This means that the same users will keep seeing the feature even as you increase the percentage of your user base that sees the feature.
+
+## Custom stickiness (beta)
+
+:::info
+Custom stickiness is available starting from Unleash Enterprise v4.
+:::
+
+When using [the gradual rollout strategy](../user_guide/activation-strategies.md#gradual-rollout) or [feature toggle variants](./feature-toggle-variants.md), you can use parameters other than the user id to calculate stickiness. More specifically, you can use any field, custom or otherwise, of the [Unleash Context](../user_guide/unleash-context.md) as long as you have enabled custom stickiness for these fields.
+
+:::note
+This is a beta featue, so not all client SDKs support this feature yet. Check your SDK's documentation to learn more.
+:::
+
+### Enabling custom stickiness
+
+To enable custom stickiness on a field, navigate to the Create Context screen in the UI and find the field you want to enable. There's a "Custom stickiness" option at the bottom of the form. Enable this toggle and update the context field by pressing the "Update" button.
+
+![The Create Context screen in the Unleash UI. There's a toggle at the bottom to control custom stickiness.](/img/enable_custom_stickiness.png)

website/docs/api/admin/feature-toggles-api-v2.md

@@ -9,7 +9,7 @@ title: /api/admin/projects/:projectId
 In this document we will guide you on how you can work with feature toggles and their configuration. Please remember the following details:
 
 - All feature toggles exists _inside a project_. 
-- A feature toggles exists _across all environments_. 
+- A feature toggle exists _across all environments_. 
 - A feature toggle can take different configuration, activation strategies, per environment.
 
 TODO: Need to explain the following in a bit more details:
@@ -505,4 +505,99 @@ Transfer-Encoding: chunked
 
 Possible Errors:
 
-- _409 Conflict_ - You can not enable the environment before it has strategies.
+- _409 Conflict_ - You can not enable the environment before it has strategies.
+
+## Feature Variants
+
+### Put variants for Feature Toggle {#update-variants}
+
+This overwrites the current variants for the feature toggle specified in the :featureName parameter.
+The backend will validate the input for the following invariants
+
+* If there are variants, there needs to be at least one variant with `weightType: variable`
+* The sum of the weights of variants with `weightType: fix` must be below 1000 (< 1000)
+
+The backend will also distribute remaining weight up to 1000 after adding the variants with `weightType: fix` together amongst the variants of `weightType: variable`
+
+**Example Query**
+```bash
+echo '[
+	{
+		"name": "variant1",
+		"weightType": "fix",
+		"weight": 650
+	},
+	{
+		"name": "variant2",
+		"weightType": "variable",
+		"weight": 123
+	}
+]' | \
+http PUT http://localhost:4242/api/admin/projects/default/features/demo/variants Authorization:$KEY
+```
+
+**Example response:**
+
+```sh
+HTTP/1.1 200 OK
+Access-Control-Allow-Origin: *
+Connection: keep-alive
+Date: Tue, 23 Nov 2021 08:46:32 GMT
+Keep-Alive: timeout=60
+Transfer-Encoding: chunked
+Content-Type: application/json; charset=utf-8
+
+{
+  "version": "1",
+  "variants": [
+    {
+      "name": "variant2",
+      "weightType": "variable",
+      "weight": 350
+    },
+    {
+      "name": "variant1",
+      "weightType": "fix",
+      "weight": 650
+    }
+  ]
+}
+```
+
+### PATCH variants for a feature toggle
+
+**Example Query**
+
+```sh
+echo '[{"op": "add", "path": "/1", "value": {
+  "name": "new-variant",
+  "weightType": "fix",
+  "weight": 200
+}}]' | \
+http PATCH http://localhost:4242/api/admin/projects/default/features/demo/variants Authorization:$KEY
+```
+
+** Example Response **
+```json
+{
+  "version": "1",
+  "variants": [
+    {
+      "name": "variant2",
+      "weightType": "variable",
+      "weight": 150
+    },
+    {
+      "name": "new-variant",
+      "weightType": "fix",
+      "weight": 200
+    },
+    {
+      "name": "variant1",
+      "weightType": "fix",
+      "weight": 650
+    }
+  ]
+}
+```
+

website/docs/api/client/feature-toggles-api.md

@@ -117,7 +117,7 @@ Used to fetch details about a specific feature toggle. This is mainly provided t
 
 > This is a unleash-enterprise feature
 
-Strategy definitions may also contain a `constraints` property. Strategy constraints is a feature in Unleash which work on context fields, which is defined as part of the [Unleash Context](/unleash_context). The purpose is to define a set of rules where all needs to be satisfied in order for the activation strategy to . A [high level description](https://www.unleash-hosted.com/articles/strategy-constraints) of it is available online.
+Strategy definitions may also contain a `constraints` property. Strategy constraints is a feature in Unleash which work on context fields, which is defined as part of the [Unleash Context](../../user_guide/unleash-context.md). The purpose is to define a set of rules where all needs to be satisfied in order for the activation strategy to evaluate to true. A [high level description](https://www.unleash-hosted.com/articles/strategy-constraints) of it is available online.
 
 **Example response:**
 

website/docs/client-specification.md

@@ -94,7 +94,7 @@ function isEnabled(name, unleashContext = {}, defaultValue = false) {
 
 Activation strategies are defined and configured in the unleash-service. It is up to the client to provide the actual implementation of each activation strategy.
 
-Unleash also ships with a few built-in strategies, and expects client SDK's to implement these. Read more about these [activation strategies](activation-strategies.md). For the built-in strategies to work as expected the client should also allow the user to define an [unleash-context](unleash-context.md). The context should be possible to pass in as part of the `isEnabled` call.
+Unleash also ships with a few built-in strategies, and expects client SDK's to implement these. Read more about these [activation strategies](user_guide/activation-strategies.md). For the built-in strategies to work as expected the client should also allow the user to define an [unleash-context](user_guide/unleash-context.md). The context should be possible to pass in as part of the `isEnabled` call.
 
 ### Extension points {#extension-points}
 

website/docs/sdks/go.md

@@ -65,7 +65,7 @@ The Go client comes with implementations for the built-in activation strategies
 - RemoteAddressStrategy
 - ApplicationHostnameStrategy
 
-Read more about the strategies in [activation-strategy.md](/activation_strategy).
+Read more about the strategies in [the activation strategies document](../user_guide/activation_strategy).
 
 ### Unleash context {#unleash-context}
 

website/docs/unleash-context.md

@@ -1,21 +0,0 @@
----
-id: unleash_context
-title: Unleash Context
----
-
-To standardise a few activation strategies, we also needed to standardise the Unleash context, which contains fields that vary per request, required to implement the activation strategies.
-
-The unleash context is defined by these fields:
-
-- userId: String,
-- sessionId: String,
-- remoteAddress: String,
-- properties: Map<String, String>
-- appName: String
-- environment: 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 provide more arbitrary data to strategies. Typical usage is to add more metadata. For instance, the `betaUser` strategy may read a field from `properties` to check whether the current user is a beta user.

website/docs/user_guide/activation-strategies.md

@@ -40,7 +40,7 @@ A flexible rollout strategy which combines all gradual rollout strategies in to
   - **userId** - guaranteed to be sticky on userId. If userId not present the behavior would be false
   - **sessionId** - guaranteed to be sticky on sessionId. If sessionId not present the behavior would be false.
   - **random** - no stickiness guaranteed. For every isEnabled call it will yield a random true/false based on the selected rollout percentage.
-- **groupId** is used to ensure that different toggles will **hash differently** for the same user. The groupId defaults to _feature toggle name_, but the use can override it to _correlate rollout_ of multiple feature toggles.
+- **groupId** is used to ensure that different toggles will **hash differently** for the same user. The groupId defaults to _feature toggle name_, but the user can override it to _correlate rollout_ of multiple feature toggles.
 - **rollout** The percentage (0-100) you want to enable the feature toggle for.
 
 This strategy has the following modelling name in the code:

website/docs/user_guide/whats-new-v4.md

@@ -51,4 +51,5 @@ In version 4 we improved the API Access and made it available for Unleash Open-S
 
 ### Custom stickiness {#custom-stickiness}
 
-In Unleash Enterprise v4 you can configure stickiness when you are doing a gradual rollout with the "flexible rollout" strategy or together with feature toggle variants. This means that you can now have consistent behavior based on any field available on the [Unleash context](unleash-context.md).
+In Unleash Enterprise v4 you can configure stickiness when you are
+doing a gradual rollout with the "gradual rollout" strategy (previously known as "flexible rollout") or together with feature toggle variants. This means that you can now have consistent behavior based on any field available on the [Unleash context](unleash-context.md).

website/sidebars.js

@@ -54,6 +54,7 @@ module.exports = {
             'advanced/custom_activation_strategy',
             'advanced/feature_toggle_types',
             'advanced/toggle_variants',
+            'advanced/stickiness',
             'advanced/archived_toggles',
             'advanced/audit_log',
             'advanced/api_access',