lab

README

lab

lab is a library to handle feature switches and experiments with users.

Getting started

The lab

First step is to create your lab to do science.

myLab := lab.New()

Experiments

Then you can define your experiments.

myLab.Experiment("new-footer-design").
	Aim(lab.AimPercent(60))

myLab.Experiment("show-website-upside-down").
	Aim(lab.AimRandom())

Experiments have aims, which are the audiences of the experiment, that is, the people that will be able to see the experiment. These are the following kinds of aims:

• Percent: a percentage of the users will see the experiment.
• Random: users will randomly see the experiment.
• Strategy: users will see the experiment if they match the criteria of a defined strategy.
• Everyone: shows the experiment to everyone.
• Nobody: show the experiment to nobody.

You can use logical or and logical and to combine aims.

myLab.Experiment("new-footer-design").
	Aim(lab.Or(
		lab.AimPercent(60),
		lab.And(
			lab.AimStrategy("is-admin", nil),
			lab.AimStrategy("is-not-john", nil),
		),
	))

Experiment Aim are chainables and act like logical ands.

myLab.Experiment("john-birthday").
	Aim(lab.AimStrategy("is-admin", nil)).
	Aim(lab.AimStrategy("is-not-john", nil))

Strategies

You can define your own strategies. Strategies are used by aims to know if the experiments should be shown or not to visitors.

myLab.DefineStrategy("visitor-is-the-beast", func(v lab.Visitor, p lab.Params) bool {
	return v.ID() == "666"
})

The session

In order to run the experiment you need to create a session. A session is a lab playground for a particular user.

session := myLab.Session(myVisitor)

Visitors need to implement the lab.Visitor interface, which only requires to implement a method returning the string ID of the visitor.

Launch experiments

Finally, with the session, you can launch the experiments.

wasRun := session.Launch("visitor-is-the-beast", nil)

If the callback is nil, Launch will only report if the experiment should be shown. If the callback is given, it will be run.

session.Launch("visitor-is-the-beast", func() {
	wreakHavoc()
})

Example

You can see a silly small web application demo to learn how to use the library in the example folder.

Credits

Inspired by AirBnb's trebuchet. To the author of the scientist gopher, which I couldn't find anywhere.

Documentation

Index

• type AudienceAim
  • func AimEveryone() AudienceAim
  • func AimNobody() AudienceAim
  • func AimPercent(n int) AudienceAim
  • func AimRandom() AudienceAim
  • func AimStrategy(id string, fn func(Visitor) Params) AudienceAim
  • func And(aims ...AudienceAim) AudienceAim
  • func Or(aims ...AudienceAim) AudienceAim
• type Experiment
• type Lab
  • func New() Lab
• type Params
• type Session
• type Strategy
• type StrategyGetter
• type Visitor

Types

type AudienceAim

type AudienceAim interface {
	// contains filtered or unexported methods
}

AudienceAim is something that determines the audience that should be shown the experiment.

func AimEveryone

func AimEveryone() AudienceAim

AimEveryone will show the experiment to everyone.

func AimNobody

func AimNobody() AudienceAim

AimNobody will show the experiment to nobody.

func AimPercent

func AimPercent(n int) AudienceAim

AimPercent will randomly show the experiment to n % of the visitors.

func AimRandom

func AimRandom() AudienceAim

AimRandom will show the experiment randomly.

func AimStrategy

func AimStrategy(id string, fn func(Visitor) Params) AudienceAim

AimStrategy will show the experiment to the visitor if the given strategy determines it is ok to show it. A callback function can be given to return the Params to call the strategy based on the visitor.

func And

func And(aims ...AudienceAim) AudienceAim

And will show the experiment if all of the aims will show the experiment.

func Or

func Or(aims ...AudienceAim) AudienceAim

Or shows the experiment if one or more of the aims will show the experiment.

type Experiment

type Experiment interface {
	// Aim defines a restriction over the audience that will be shown this experiment.
	Aim(AudienceAim) Experiment
}

Experiment is a single experiment that wants to be run.

type Lab

type Lab interface {
	// DefineStrategy defines strategies to aim at visitors.
	DefineStrategy(string, Strategy)
	// Experiment defines an experiment or retrieves one that already exists.
	Experiment(string) Experiment
	// Session starts a new session for the given visitor.
	Session(Visitor) Session
}

Lab is a playground where you can define experiments and strategies.

func New

func New() Lab

New returns a new lab.

type Params

type Params map[string]interface{}

Params will hold all the parameters to call a strategy.

type Session

type Session interface {
	// Launch will run the given function for the given experiment ID only if the
	// visitor is a target of the experiment. Will return as well a boolean to report
	// if the visitor was shown the experiment.
	Launch(string, func()) bool
}

Session is a single session for a visitor.

type Strategy

type Strategy func(Visitor, Params) bool

Strategy will tell if the given Params and Visitor should be shown the experiment.

type StrategyGetter

type StrategyGetter interface {
	// Strategy returns the Strategy for the given ID.
	Strategy(string) (Strategy, bool)
}

StrategyGetter will retrieve strategies based on their ID.

type Visitor

type Visitor interface {
	// ID returns the ID of the visitor.
	ID() string
}

Visitor is something identified by an ID. Represents the visitor of a single session so all features are shown or not during the same session.