determinator 0.1.0

data/examples/determinator-rails/Procfile

@@ -0,0 +1,2 @@
+web: bundle exec rails s
+worker: bundle exec sidekiq

data/examples/determinator-rails/README.md

@@ -0,0 +1,35 @@
+# Rails and Determinator example
+
+This example Rails app has been configured so that Determinator is correctly configured, and (with an instance of the Actor Tracking Service and Routemaster running alongside) it will correctly determine feature rollout and experiment variant selection.
+
+## Points of interest
+
+### `config/initializers/determinator.rb`
+
+This file sets up the singleton Determinator instance for the application.
+
+### `config/routes.rb`
+
+Using Determinator with Routemaster means that you must expose an endpoint to be informed of changes to Features. Determinator makes it easy to set this up with the `#configure_rails_router` helper method.
+
+### `Procfile`
+
+Bear in mind that, because routemaster depends on background workers to populate the cache, Sidekiq (or Resque) must be running alongside the app.
+
+### `app/controllers/index_controller.rb`
+
+An example of how Determinator can be used for feature flags.
+
+### `app/controllers/application_controller.rb`
+
+An example of how a GUID could be assigned to every visitor to the site. Storing this in the session means it will be reset upon log out.
+
+The `determinator` method memoizes the instance of the `ActorControl` helper class for ease of use throughout this request.
+
+### `config/application.rb`
+
+Ensure you've required the job runner backend appropriate for your set up. Routemaster Drain currently supports Sidekiq and Resque.
+
+### `config/sidekiq.yml`
+
+This example uses Sidekiq as the background processor, ensure you've set it up correctly for notifications to cache in the background.

data/examples/determinator-rails/Rakefile

@@ -0,0 +1,3 @@
+require_relative 'config/application'
+
+Rails.application.load_tasks

data/examples/determinator-rails/app/controllers/application_controller.rb

@@ -0,0 +1,20 @@
+class ApplicationController < ActionController::API
+  def current_user
+    # DETERMINATOR: This would return a User object in most applications
+    # http://guides.rubyonrails.org/action_controller_overview.html#accessing-the-session
+    nil
+  end
+
+  def guid
+    session[:guid] ||= SecureRandom.uuid
+  end
+
+  def determinator
+    # DETERMINATOR: A memoized instance of the ActorControl helper class
+    # which allows simple use throughout the app
+    @_determinator ||= Determinator.instance.for_actor(
+      id: current_user && current_user.id || nil,
+      guid: guid
+    )
+  end
+end

data/examples/determinator-rails/app/controllers/index_controller.rb

@@ -0,0 +1,9 @@
+class IndexController < ApplicationController
+  def show
+    if determinator.feature_flag_on?(:colloquial_welcome)
+      render json: { welcome: 'hi world' }
+    else
+      render json: { welcome: 'hello world' }
+    end
+  end
+end

data/examples/determinator-rails/app/jobs/application_job.rb

@@ -0,0 +1,2 @@
+class ApplicationJob < ActiveJob::Base
+end

data/examples/determinator-rails/bin/bundle

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../../Gemfile', __FILE__)
+load Gem.bin_path('bundler', 'bundle')

data/examples/determinator-rails/bin/rails

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+APP_PATH = File.expand_path('../config/application', __dir__)
+require_relative '../config/boot'
+require 'rails/commands'

data/examples/determinator-rails/bin/rake

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require_relative '../config/boot'
+require 'rake'
+Rake.application.run

data/examples/determinator-rails/config.ru

@@ -0,0 +1,3 @@
+require_relative 'config/environment'
+
+run Rails.application

data/examples/determinator-rails/config/application.rb

@@ -0,0 +1,18 @@
+require_relative 'boot'
+
+require "rails"
+require "active_model/railtie"
+require "active_job/railtie"
+require "action_controller/railtie"
+require "action_view/railtie"
+
+# DETERMINATOR: We must explicitly require the routemaster backend we want to use
+require "routemaster/jobs/backends/sidekiq"
+
+Bundler.require(*Rails.groups)
+
+module DeterminatorExample
+  class Application < Rails::Application
+    config.api_only = true
+  end
+end

data/examples/determinator-rails/config/boot.rb

@@ -0,0 +1,3 @@
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
+
+require 'bundler/setup'

data/examples/determinator-rails/config/environment.rb

@@ -0,0 +1,2 @@
+require_relative 'application'
+Rails.application.initialize!

data/examples/determinator-rails/config/environments/development.rb

@@ -0,0 +1,18 @@
+Rails.application.configure do
+  config.cache_classes = false
+  config.eager_load = false
+  config.consider_all_requests_local = true
+  if Rails.root.join('tmp/caching-dev.txt').exist?
+    config.action_controller.perform_caching = true
+
+    config.cache_store = :memory_store
+    config.public_file_server.headers = {
+      'Cache-Control' => 'public, max-age=172800'
+    }
+  else
+    config.action_controller.perform_caching = false
+
+    config.cache_store = :null_store
+  end
+  config.active_support.deprecation = :log
+end

data/examples/determinator-rails/config/environments/production.rb

@@ -0,0 +1,17 @@
+Rails.application.configure do
+  config.cache_classes = true
+  config.eager_load = true
+  config.consider_all_requests_local       = false
+  config.action_controller.perform_caching = true
+  config.public_file_server.enabled = ENV['RAILS_SERVE_STATIC_FILES'].present?
+  config.log_level = :debug
+  config.log_tags = [ :request_id ]
+  config.i18n.fallbacks = true
+  config.active_support.deprecation = :notify
+  config.log_formatter = ::Logger::Formatter.new
+  if ENV["RAILS_LOG_TO_STDOUT"].present?
+    logger           = ActiveSupport::Logger.new(STDOUT)
+    logger.formatter = config.log_formatter
+    config.logger = ActiveSupport::TaggedLogging.new(logger)
+  end
+end

data/examples/determinator-rails/config/environments/test.rb

@@ -0,0 +1,13 @@
+Rails.application.configure do
+  config.cache_classes = true
+  config.eager_load = false
+  config.public_file_server.enabled = true
+  config.public_file_server.headers = {
+    'Cache-Control' => 'public, max-age=3600'
+  }
+  config.consider_all_requests_local       = true
+  config.action_controller.perform_caching = false
+  config.action_dispatch.show_exceptions = false
+  config.action_controller.allow_forgery_protection = false
+  config.active_support.deprecation = :stderr
+end

data/examples/determinator-rails/config/initializers/determinator.rb

@@ -0,0 +1,7 @@
+require 'determinator/retrieve/routemaster'
+
+Determinator.configure(
+  retrieval: Determinator::Retrieve::Routemaster.new(
+    discovery_url: 'https://florence.dev/'
+  )
+)

data/examples/determinator-rails/config/initializers/filter_parameter_logging.rb

@@ -0,0 +1 @@
+Rails.application.config.filter_parameters += [:password]

data/examples/determinator-rails/config/initializers/new_framework_defaults.rb

@@ -0,0 +1,3 @@
+ActiveSupport.to_time_preserves_timezone = true
+ActiveSupport.halt_callback_chains_on_return_false = false
+Rails.application.config.ssl_options = { hsts: { subdomains: true } }

data/examples/determinator-rails/config/initializers/wrap_parameters.rb

@@ -0,0 +1,3 @@
+ActiveSupport.on_load(:action_controller) do
+  wrap_parameters format: [:json]
+end

data/examples/determinator-rails/config/puma.rb

@@ -0,0 +1,5 @@
+threads_count = ENV.fetch("RAILS_MAX_THREADS") { 5 }.to_i
+threads threads_count, threads_count
+port        ENV.fetch("PORT") { 3000 }
+environment ENV.fetch("RAILS_ENV") { "development" }
+plugin :tmp_restart

data/examples/determinator-rails/config/routes.rb

@@ -0,0 +1,6 @@
+Rails.application.routes.draw do
+  root to: 'index#show'
+
+  # DETERMINATOR: Make sure the routemaster routes are mapped to the containing app.
+  Determinator.instance.retrieval.configure_rails_router(self)
+end

data/examples/determinator-rails/config/secrets.yml

@@ -0,0 +1,8 @@
+development:
+  secret_key_base: 2e9ca36ffd3a739ffc56c560e81083f8a9d924049406a595c114dd4b709e87de3989cb013df72812c3dabe6e4035288eb6b79355608a34392dfda1cadf1f6690
+
+test:
+  secret_key_base: 03b771d3fe30c854fea8fa6a122f48c4ea37a73c4fdb7a75139d0879f991fa59c02ea816a0981b6444b1db5403f47982019c6305b86481e7ffb129c706837ec7
+
+production:
+  secret_key_base: <%= ENV["SECRET_KEY_BASE"] %>

data/examples/determinator-rails/config/sidekiq.yml

@@ -0,0 +1,2 @@
+:queues:
+  - routemaster

data/examples/determinator-rails/public/robots.txt

@@ -0,0 +1,5 @@
+# See http://www.robotstxt.org/robotstxt.html for documentation on how to use the robots.txt file
+#
+# To ban all spiders from the entire site uncomment the next two lines:
+# User-agent: *
+# Disallow: /

data/lib/determinator.rb

@@ -0,0 +1,16 @@
+require 'determinator/version'
+require 'determinator/control'
+require 'determinator/feature'
+require 'determinator/target_group'
+require 'determinator/retrieve/routemaster'
+
+module Determinator
+  def self.configure(retrieval:)
+    @instance = Control.new(retrieval: retrieval)
+  end
+
+  def self.instance
+    raise "No singleton Determinator instance defined" unless @instance
+    @instance
+  end
+end

data/lib/determinator/actor_control.rb

@@ -0,0 +1,41 @@
+module Determinator
+  # A decorator to provide syntactic sugar for Determinator::Control.
+  # Useful for contexts where the actor remains constant (eg. inside
+  # the request cycle in a webapp)
+  class ActorControl
+    attr_reader :id, :guid, :default_constraints
+
+    def initialize(controller, id: nil, guid: nil, default_constraints: {})
+      @id = id
+      @guid = guid
+      @default_constraints = default_constraints
+      @controller = controller
+    end
+
+    def which_variant(name, constraints: {})
+      controller.which_variant(
+        name,
+        id: id,
+        guid: guid,
+        constraints: default_constraints.merge(constraints)
+      )
+    end
+
+    def feature_flag_on?(name, constraints: {})
+      controller.feature_flag_on?(
+        name,
+        id: id,
+        guid: guid,
+        constraints: default_constraints.merge(constraints)
+      )
+    end
+
+    def inspect
+      "#<Determinator::ActorControl id=#{id.inspect} guid=#{guid.inspect}>"
+    end
+
+    private
+
+    attr_reader :controller
+  end
+end

data/lib/determinator/control.rb

@@ -0,0 +1,119 @@
+require 'digest/md5'
+require 'determinator/actor_control'
+
+module Determinator
+  class Control
+    attr_reader :retrieval
+
+    def initialize(retrieval:)
+      @retrieval = retrieval
+    end
+
+    # @return [ActorControl] A helper object removing the need to know id and guid everywhere
+    def for_actor(id: nil, guid: nil, default_constraints: {})
+      ActorControl.new(self, id: id, guid: guid, default_constraints: default_constraints)
+    end
+
+    # Determines whether a specific feature is on or off for the given actor
+    #
+    # @return [true,false] Whether the feature is on (true) or off (false) for this actor
+    def feature_flag_on?(name, id: nil, guid: nil, constraints: {})
+      determinate(name, id: id, guid: guid, constraints: constraints) do |feature|
+        feature.feature_flag?
+      end
+    end
+
+    # Determines what an actor should see for a specific experiment
+    #
+    # @return [false,String] Returns false, if the actor is not in this experiment, or otherwise the variant name.
+    def which_variant(name, id: nil, guid: nil, constraints: {})
+      determinate(name, id: id, guid: guid, constraints: constraints) do |feature|
+        feature.experiment?
+      end
+    end
+
+    def inspect
+      '#<Determinator::Control>'
+    end
+
+    private
+
+    Indicators = Struct.new(:rollout, :variant)
+
+    def determinate(name, id:, guid:, constraints:)
+      feature = retrieval.retrieve(name)
+      return false unless feature
+
+      # Calling method can place constraints on the feature, eg. experiment only
+      return false if block_given? && !yield(feature)
+
+      # Overrides take precedence
+      return feature.override_value_for(id) if feature.overridden_for?(id)
+
+      target_group = choose_target_group(feature, constraints)
+      # Given constraints have excluded this actor from this experiment
+      return false unless target_group
+
+      indicators = indicators_for(feature, id, guid)
+      # This actor isn't described in enough detail to form indicators
+      return false unless indicators
+
+      # Actor's indicator has excluded them from the feature
+      return false if indicators.rollout >= target_group.rollout
+
+      # Features don't need variant determination and, at this stage,
+      # they have been rolled out to.
+      return true unless feature.experiment?
+
+      variant_for(feature, indicators.variant)
+    end
+
+    def choose_target_group(feature, constraints)
+      feature.target_groups.select { |tg|
+        tg.constraints.reduce(true) do |fit, (scope, *required)|
+          present = [*constraints[scope]]
+          fit && (required.flatten & present.flatten).any?
+        end
+      # Must choose target group deterministically, if more than one match
+      }.sort_by { |tg| tg.rollout }.last
+    end
+
+    def indicators_for(feature, id, guid)
+      # If we're slicing by guid then we never pay attention to id
+      actor_identifier = case feature.bucket_type
+                         when :id       then id
+                         when :guid     then guid
+                         when :fallback then id || guid
+                         end
+      # No identified means not enough info was given by the caller
+      # to determine an outcome for this feature
+      return unless actor_identifier
+
+      # Cryptographic hash (will have random distribution)
+      hash = Digest::MD5.new
+      hash.update [feature.identifier, actor_identifier].map(&:to_s).join(',')
+
+      # Use lowest 16 bits for rollout indicator
+      # Use next 16 bits for variant indicator
+      rollout, variant = hash.digest.unpack("nn")
+
+      Indicators.new(rollout, variant)
+    end
+
+    def variant_for(feature, indicator)
+      # Scale up the weights so the variants fit within the possible space for the variant indicator
+      variant_weight_total = feature.variants.values.reduce(:+)
+      scale_factor = 65_535 / variant_weight_total.to_f
+
+      # Find the variant the indicator sits within
+      previous_upper_bound = 0
+      feature.variants.each do |name, weight|
+        new_upper_bound = previous_upper_bound + scale_factor * weight
+        return name if indicator <= new_upper_bound
+        previous_upper_bound = new_upper_bound
+      end
+
+      raise ArgumentError, "A variant should have been found by this point, there is a bug in the code."
+    end
+  end
+end

data/lib/determinator/feature.rb

@@ -0,0 +1,48 @@
+module Determinator
+  # A model for an individual feature or experiment
+  #
+  # @attr_reader [nil,Hash<String,Integer>] variants The variants for this experiment, with the name of the variant as the key and the weight as the value. Will be nil for non-experiments.
+  class Feature
+    attr_reader :name, :identifier, :bucket_type, :variants, :target_groups
+
+    BUCKET_TYPES = %i(id guid fallback)
+
+    def initialize(name:, identifier:, bucket_type:, target_groups:, variants: {}, overrides: {})
+      @name = name.to_s
+      @identifier = identifier.to_s
+      @variants = variants
+      @target_groups = target_groups
+
+      @bucket_type = bucket_type.to_sym
+      raise ArgumentError, "Unknown bucket type: #{bucket_type}" unless BUCKET_TYPES.include?(@bucket_type)
+
+      # To prevent confusion between actor id data types
+      @overrides = Hash[overrides.map { |k, v| [k.to_s, v] }]
+    end
+
+    # @return [true,false] Is this feature an experiment?
+    def experiment?
+      variants.any?
+    end
+
+    # @return [true,false] Is this feature a feature flag?
+    def feature_flag?
+      variants.empty?
+    end
+
+    # Is this feature overridden for the given actor id?
+    #
+    # @return [true,false] Whether this feature is overridden for this actor
+    def overridden_for?(id)
+      overrides.has_key?(id.to_s)
+    end
+
+    def override_value_for(id)
+      overrides[id.to_s]
+    end
+
+    private
+
+    attr_reader :overrides
+  end
+end