# Determinator

A gem that works with _Florence_ to deterministically calculate whether an **actor** should have a feature flag turned on or off, or which variant they should see in an experiment.

![Arnold Schwarzenegger might say "Come with me if you want to experiment" if he played The Determinator instead of The Terminator.](docs/img/determinator.jpg)

---

#### Useful documentation

- [Terminology and Background](docs/background.md)
- [Local development](docs/local_development.md)
- [Example implemention in Rails](examples/determinator-rails)

#### Getting help

For Deliveroo Employees:

- Many people contribute to Determinator and Florence. We hang out in [this Slack channel](https://deliveroo.slack.com/app_redirect?channel=florence_wg)
- [This JIRA board](https://deliveroo.atlassian.net/secure/RapidBoard.jspa?rapidView=156) covers pieces of work that are planned or in-flight
- [This Workplace group](https://deliveroo.facebook.com/groups/1893254264328414/) holds more general discussions about the Florence ecosystem

At the moment we can only promise support for Determinator within Deliveroo, but if you add [issues to this github repo](https://github.com/deliveroo/determinator/issues) we'll try and help if we can!

## Basic Use

Once [set up](#installation), determinator can be used to determine whether a **feature flag** or **experiment** is on or off for the current actor (or user) and, for experiments, which **variant** they should see.

```ruby
# Feature flags: the basics
Determinator.instance.feature_flag_on?(:my_feature_name, id: 'some user')
# => true
Determinator.instance.feature_flag_on?(:my_feature_name, id: 'another user')
# => false

# A handy short cut…
def determinator
  # See the urther Usage section below for a handy shorthand which means ID
  # and GUID don't need to be specified every time you need a determination.
end

# Which means you can also do:
if determinator.feature_flag_on?(:my_feature_name)
  # Show the feature
end

# Experiments
case determinator.which_variant(:my_experiment_name)
when false
  # This actor isn't in a target group for this experiment
when 'control'
  # Do nothing different
when 'sloths'
  # Show some sloth pictures
when 'velociraptors'
  # RUN!
end
```

Please note that Determinator requires an identifier for your actor — either an ID (when they are logged in, eg. a user id), or a globally unique id (GUID) that identifies them across sessions (which would normally be storied in a cookie or in a long-lived session store).

Feature flags and experiments can be limited to actors with specific properties by specifying them when (which must match the constraints defined in the feature).

```ruby
# Targeting specific actors
variant = determinator.which_variant(
  :my_experiment_name,
  properties: {
    employee: current_user.employee?
  }
)
```

Writing tests? Check out the [Local development](docs/local_development.md) docs to see examples of `RSpec::Determinator` to help you mock your Feature Flags and Experiments.

## Installation

Determinator requires a initialiser block somewhere in your application's boot process, it might look something like this:

```ruby
# config/initializers/determinator.rb

require 'determinator/retrieve/routemaster'
Determinator.configure(
  retrieval: Determinator::Retrieve::Routemaster.new(
    discovery_url: 'https://flo.dev/'
    retrieval_cache: ActiveSupport::Cache::MemoryStore.new(expires_in: 1.minute)
  ),
  errors: -> error { NewRelic::Agent.notice_error(error) },
  missing_features: -> feature_name { STATSD.increment 'determinator.missing_feature', tags: ["feature:#{name}"] }
)
```

This configures the `Determinator.instance` with:

- What **retrieval** mechanism should be used to get feature details
- (optional) How **errors** should be reported
- (optional) How **missing features** should be monitored (as they indicate something's up with your code or your set up!)

You may also want to configure a `determinator` helper method inside your web request scope, see below for more information.

## Further Usage

Once this is done you can ask for a determination like this:

```ruby
# Anywhere in your application:
variant = Determinator.instance.which_variant?(
  :my_experiment_name,
  id: 123,
  guid: 'anonymous id',
  properties: {
    employee: true,
    using_top_level_domain: 'uk'
  }
)
```

Or, if you're within a web request, you might want to use a shorthand, and let determinator remember the ID, GUID and any properties which will be true. The following will have the same effect:

```ruby
# Somewhere inside your request's scope:
def determinator
  @determinator ||= Determinator.instance.for_actor(
    id: 123,
    guid: 'anonymous id',
    default_properties: {
      employee: true,
      using_top_level_domain: 'uk'
    }
  )
end

# Anywhere in your requests' scope:
determinator.which_variant(:my_experiment_name)
```

Check the example Rails app in the `examples` directory for more information on how to make use of this gem.

### Routemaster

Determinator's [Routemaster](https://github.com/deliveroo/routemaster) integration requires your application to be subscribed to the a `features` topic.

The drain must expire the routemaster cache on receipt of events, making use of  `Routemaster::Drain::CacheBusting.new` or similar is recommended.

### Using Determinator in RSpec

* Include the  `spec_helper.rb`.

```ruby
require 'rspec/determinator'

Determinator.configure(retrieval: nil)
```

* Tag your rspec test with `:determinator_support`, so the `forced_determination` helper method will be available.

```ruby
RSpec.describe "something", :determinator_support do

  context "something" do
    forced_determination(:my_feature_flag, true)
    forced_determination(:my_experiment, "variant_a")
    forced_determination(:my_lazyexperiment, :some_lazy_variable)
    let(:some_lazy_variable) { 'variant_b' }

    it "uses forced_determination" do
      expect(Determinator.instance.feature_flag_on?(:my_feature_flag)).to eq(true)
      expect(Determinator.instance.which_variant(:my_experiment)).to eq("variant_a")
      expect(Determinator.instance.which_variant(:my_lazy_experiment)).to eq("variant_b")
    end
  end
end
```

* Check out [the specs for `RSpec::Determinator`](spec/rspec/determinator_spec.rb) to find out what you can do!

### Retrieval Cache

Determinator will function fully without a retrieval_cache set, although Determinator will produce 1 Redis query for every determination. By setting a `retrieval_cache` as an instance of `ActiveSupport::Cache::MemoryStore` (or equivalent) this can be reduced per application instance. This cache is not expired so *must* have a `expires_in` set, ideally to a short amount of time.

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/deliveroo/determinator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.

Any PR should include a new section at the top of the `CHANGELOG.md` (if it doesn't exist) called 'Unreleased' of a similar format to the lines below. Upon release, this will be used to detail what has been added.

## License

The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).