shamu 0.0.1 → 0.0.2

data/lib/shamu/features/conditions/schedule_at.rb

@@ -0,0 +1,27 @@
+module Shamu
+  module Features
+    module Conditions
+
+      # Match against the current date and time.
+      class ScheduleAt < Conditions::Condition
+
+        # (see Condition#match?)
+        def match?( context )
+          context.time >= timestamp
+        end
+
+        private
+
+          def timestamp
+            @timestamp ||=
+              case config
+              when Date   then config.to_time
+              when String then Time.zone ? Time.zone.parse( config ) : Time.parse( config )
+              end
+          end
+
+      end
+
+    end
+  end
+end

data/lib/shamu/features/conditions.rb

@@ -0,0 +1,18 @@
+module Shamu
+  module Features
+
+    # Conditions that must match for a {Selector} to enable a {Toggle}.
+    module Conditions
+      require "shamu/features/conditions/condition"
+
+      require "shamu/features/conditions/env"
+      require "shamu/features/conditions/hosts"
+      require "shamu/features/conditions/matching"
+      require "shamu/features/conditions/not_matching"
+      require "shamu/features/conditions/percentage"
+      require "shamu/features/conditions/proc"
+      require "shamu/features/conditions/roles"
+      require "shamu/features/conditions/schedule_at"
+    end
+  end
+end

data/lib/shamu/features/config_service.rb

@@ -0,0 +1,10 @@
+module Shamu
+  module Features
+
+    # Present a unified get/set interface for some distributed feature
+    # configuration stored in an external persistence system (redis,
+    # ActiveRecord, consul, etc, etc.).
+    class ConfigService < Services::Service
+    end
+  end
+end

data/lib/shamu/features/context.rb

@@ -0,0 +1,80 @@
+require "socket"
+
+module Shamu
+  module Features
+
+    # Captures the environment and request specific context used to match
+    # {Toggle} selectors and determine if a feature should be enabled.
+    class Context
+      include Shamu::Attributes
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!attribute
+      # @return [Time] the current time.
+      attribute :time do
+        Time.zone ? Time.zone.now : Time.now
+      end
+
+      # @!attribute
+      # @return [Array<Symbol>] roles assigned to the current user.
+      attribute :roles
+
+      # @!attribute
+      # @return [String] the name of the host machine.
+      attribute :host do
+        Socket.gethostname
+      end
+
+      # @!attribute
+      # @return [Integer,String] id of the current user - either an Integer, or a UUID.
+      attribute :user_id
+
+      # @!attribute
+      # @return [Scorpion] used to dynamically look up dependencies by
+      #     {Conditions}.
+      attribute :scorpion
+
+      #
+      # @!endgroup Attributes
+
+      def initialize( features_service, **attributes )
+        @features_service = features_service
+        super( **attributes )
+      end
+
+      # Retrieve a value from the host machine's environment. Abstracts over the
+      # ENV hash to permit some filtering and to facilitate specs.
+      #
+      # @param [String] name of the environment variable.
+      # @return [String] the environment variable.
+      def env( name )
+        ENV[name]
+      end
+
+      # Check if feature is enabled.
+      def enabled?( name )
+        features_service.enabled?( name )
+      end
+
+      # Remember the toggle selection in persistent storage for the user so that
+      # they will receive the same result each time.
+      def sticky!
+        @sticky = true
+        self
+      end
+
+      # @return [Boolean] true if the feature election should be remembered
+      #     between requests.
+      def sticky?
+        @sticky
+      end
+
+      private
+
+        attr_reader :features_service
+    end
+  end
+end

data/lib/shamu/features/env_store.rb

@@ -0,0 +1,88 @@
+module Shamu
+  module Features
+
+    # Expose a read-only runtime environment for consumption by the
+    # {FeaturesService}. By default blends a Rack env request headers (if using
+    # Rack) with the host env. The request env overrides the host.
+    #
+    # When {#fetch fetching}, EnvStore will look for an `X-Shamu-Features` header
+    # sent in the HTTP request. It should be constructed using {.pack} to
+    # build a verifiable hash of feature settings.
+    #
+    # If a rack value is not set, EnvStore will fall back to looking for the
+    # toggle in the host's environment with the name `TOGGLE_{ toggle name
+    # upcased and underscored }`. For example `buy_now/one_click` will look for
+    # `TOGGLE_BUY_NOW_ONE_CLICK` in the environment.
+    class EnvStore < Services::Service
+
+      RACK_ENV_KEY      = "HTTP_X_SHAMU_FEATURES".freeze
+      RACK_PARAMS_KEY   = "shamu.features".freeze
+      RACK_PARAMS_FEATURES_KEY = "shamu.features.from_params".freeze
+      RACK_HEADER_FEATURES_KEY = "shamu.features.from_header".freeze
+
+      # ============================================================================
+      # @!group Dependencies
+      #
+
+      # @!attribute
+      # @return [ToggleCode] code used to pack and unpack the features.
+      attr_dependency :codec, ToggleCodec
+
+      #
+      # @!endgroup Dependencies
+
+      # Fetch a value from the environment.
+      def fetch( key, &block )
+        return env_fetch( key, &block ) unless defined? Rack
+        rack_params_fetch( key, &block )
+      end
+
+      # @return [String] the expected ENV key name for the given toggle name.
+      def self.env_key_name( key )
+        key = key.upcase
+        key.tr! "/", "_"
+        key
+      end
+
+      private
+
+        def env_fetch( key, &block )
+          key = self.class.env_key_name( key )
+          if ENV.key?( key )
+            ENV[ key ].to_bool
+          elsif block_given?
+            yield
+          end
+        end
+
+        def rack_header_fetch( key, &block )
+          rack_env = scorpion.fetch( Scorpion::Rack::Env )
+          return env_fetch( key, &block ) unless header = rack_env[RACK_ENV_KEY]
+
+          features = rack_env.fetch( RACK_HEADER_FEATURES_KEY ) do
+            rack_env[ RACK_HEADER_FEATURES_KEY ] = codec.unpack( header )
+          end
+
+          features.fetch( key ) do
+            env_fetch( key, &block )
+          end
+        end
+
+        def rack_params_fetch( key, &block )
+          rack_env = scorpion.fetch( Scorpion::Rack::Env )
+          request  = ::Rack::Request.new( rack_env )
+
+          return rack_header_fetch( key, &block ) unless param = request.params[ RACK_PARAMS_KEY ]
+
+          features = rack_env.fetch( RACK_PARAMS_FEATURES_KEY ) do
+            rack_env[ RACK_PARAMS_FEATURES_KEY ] = codec.unpack( param )
+          end
+
+          features.fetch( key ) do
+            rack_header_fetch( key, &block )
+          end
+        end
+
+    end
+  end
+end

data/lib/shamu/features/errors.rb

@@ -0,0 +1,29 @@
+module Shamu
+  module Features
+
+    # An error occcured in the Features domain.
+    class Error < Shamu::Error
+
+      private
+
+        def translation_scope
+          super.dup.insert( 1, :features )
+        end
+
+    end
+
+    # An feature toggle was checked that has been marked as retired.
+    class RetiredToggleError < Error
+
+      # @!attribute
+      # @return [Toggle] the retired toggle
+      attr_reader :toggle
+
+      def initialize( toggle )
+        @toggle = toggle
+
+        super translate( :retired_toggle_checked, name: toggle.name, retire_at: toggle.retire_at.to_s )
+      end
+    end
+  end
+end

data/lib/shamu/features/features_service.rb

@@ -0,0 +1,168 @@
+require "listen"
+
+module Shamu
+  module Features
+
+    # ...
+    class FeaturesService < Services::Service
+      include Security::Support
+
+      SESSION_KEY = "shamu.toggles".freeze
+
+      # ============================================================================
+      # @!group Dependencies
+      #
+
+      # @!attribute
+      # @return [Shamu::Sessions::SessionStore]
+      #
+      # A persistent storage for a user session where the feature service can
+      # persist sticky feature toggles.
+      attr_dependency :session_store, Shamu::Sessions::SessionStore
+
+      # @!attribute
+      # @return [Shamu::Features::ToggleCodec]
+      #
+      # Used to pack and unpack sticky toggle overrides in a persistent user
+      # session.
+      attr_dependency :toggle_codec, Shamu::Features::ToggleCodec
+
+      # @!attribute
+      # @return [Shamu::Features::EnvStore]
+      #
+      # Read-only access to Rack and host ENV toggle overrides.
+      attr_dependency :env_store, Shamu::Features::EnvStore
+
+      #
+      # @!endgroup Dependencies
+
+      # @!method initialize( config_path )
+      # @param
+      # @return [FeaturesService]
+      initialize do |config_path = nil, **|
+        @config_path = config_path || self.class.default_config_path
+      end
+
+      # Indicates if the feature is enabled for the current request/session.
+      #
+      # @param [String] name of the feature.
+      # @return [Boolean] true if the feature is enabled.
+      def enabled?( name )
+        context = build_context
+
+        if toggle = toggles[name]
+          resolve_known( toggle, context )
+        else
+          resolve_unknown( name )
+        end
+      end
+
+      # List all the known toggles with the given prefix.
+      # @param [String] name prefix
+      # @return [Hash] the known toggles.
+      def list( prefix = nil )
+        if prefix.present?
+          toggles.each_with_object({}) do |(name, toggle), result|
+            next unless name.start_with?( prefix )
+            result[name] = toggle
+          end
+        else
+          toggles.dup
+        end
+      end
+
+      private
+
+        attr_reader :config_path
+
+        def toggles
+          @toggles ||= begin
+            if File.exist?( config_path )
+              listener = Listen.to File.dirname( config_path ), only: File.basename( config_path ) do
+                @toggles = Toggle.load( config_path )
+              end
+              listener.start
+
+              Toggle.load( config_path )
+            else
+              logger.warn "Feature configuration file does not exist: #{ config_path }"
+              {}
+            end
+          end
+        end
+
+        def resolve_unknown( name )
+          logger.info "The '#{ name }' feature toggle has not been configured. Add to #{ config_path }."
+          false
+        end
+
+        def resolve_known( toggle, context )
+          fail RetiredToggleError.new( toggle ) if toggle.retired?( context ) # rubocop:disable Style/RaiseArgs
+
+          store_value = resolve_store_toggle( toggle )
+          return store_value unless store_value.nil?
+
+          resolve_toggle( toggle, context )
+        end
+
+        def build_context
+          Features::Context.new self,
+                                scorpion: scorpion,
+                                user_id: security_principal.user_id,
+                                roles: roles_service.roles_for( security_principal.user_id )
+        end
+
+        def resolve_toggle( toggle, context )
+          toggle.enabled?( context ).tap do |result|
+            persist_sticky( toggle.name, result ) if context.sticky?
+          end
+        end
+
+        def resolve_store_toggle( toggle )
+          # session_store is for sticky overrides
+          sticky_overrides.fetch( toggle.name ) do
+            # env_store is for host and service header overrides
+            env_store.fetch( toggle.name )
+          end
+        end
+
+        def persist_sticky( name, result )
+          sticky_overrides[ name ] = result
+          session_store.set( SESSION_KEY, toggle_codec.pack( sticky_overrides ) )
+        end
+
+        def sticky_overrides
+          @sticky_overrides ||= begin
+            if token = session_store.fetch( SESSION_KEY )
+              toggle_codec.unpack( token )
+            else
+              {}
+            end
+          end
+        end
+
+
+      class << self
+        # Looks for a config/features.yml or features.yml in the current
+        # directory. Use {#ddefault_config_path=} to manually set the default
+        # config file.
+        #
+        # @return [String] the default path to load toggle information from.
+        def default_config_path
+          @default_config_path ||= begin
+            path = File.expand_path( "config/features.yml" )
+            path = File.expand_path( "features.yml" ) unless File.exist?( path )
+            path
+          end
+        end
+
+        # @param [String] path of the default config file.
+        # @return [String]
+        def default_config_path=( path ) # rubocop:disable Style/TrivialAccessors
+          @default_config_path = path
+        end
+      end
+
+    end
+  end
+end

data/lib/shamu/features/list_scope.rb

@@ -0,0 +1,30 @@
+module Shamu
+  module Features
+
+    # Select the features to be listed.
+    class ListScope < Entities::ListScope
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!attribute
+      # @return [Symbol] the desired type of toggle.
+      attribute :type, inclusion: { in: Features::Toggle::TYPES }
+
+      # @!attribute
+      # @return [Symbol] only include toggles that have retired but are still
+      #     configured.
+      attribute :retired, coerce: :to_bool
+
+      # @!attribute
+      # @return [String] include toggles with a name that is prefixed with the
+      #     given value.
+      attribute :prefix, coerce: :to_s
+
+      #
+      # @!endgroup Attributes
+
+    end
+  end
+end

data/lib/shamu/features/selector.rb

@@ -0,0 +1,50 @@
+module Shamu
+  module Features
+
+    # A selector used to match conditions against environment configuration.
+    class Selector
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!attribute
+      # @return [Array<Condition>] conditions that must match for the selector
+      #     to match.
+        attr_reader :conditions
+
+      # @!attribute
+      # @return [Boolean] true if the feature should not be enabled when the
+      #     selector matches.
+        attr_reader :reject
+
+      # @!attribute
+      # @return [Toggle] that owns the selector.
+        attr_reader :toggle
+
+      #
+      # @!endgroup Attributes
+
+      def initialize( toggle, config )
+        @conditions = []
+
+        config.each do |name, condition_config|
+          if name == "reject"
+            @reject = condition_config.to_bool
+          else
+            @conditions << Conditions::Condition.create( name, condition_config, toggle )
+          end
+        end
+
+        @conditions.freeze
+      end
+
+      # @param [Context] context the feature evaluation context.
+      # @return [Boolean] true if the selector matches the given environment.
+      def match?( context )
+        conditions.all? { |c| c.match?( context ) }
+      end
+
+    end
+  end
+end

data/lib/shamu/features/support.rb

@@ -0,0 +1,51 @@
+module Shamu
+  module Features
+
+    # Add feature togggle support to an object.
+    module Support
+      extend ActiveSupport::Concern
+
+      included do
+
+        # ============================================================================
+        # @!group Dependencies
+        #
+
+        # @!attribute
+        # @return [Features::FeaturesService] the service used to resolve
+        #     enabled features.
+        attr_dependency :features_service, Features::FeaturesService, lazy: true
+
+        #
+        # @!endgroup Dependencies
+
+      end
+
+      private
+
+        # @!visibility public
+        #
+        # Only execute the block if the current {Features::Context} has the
+        # named featue enabled.
+        #
+        # @param [String] feature name.
+        # @param [Boolean] override force the feature to be either on or off.
+        # @yield Yields if the feature is enabled.
+        # @yieldreturn the result of the block or nil if the feature wasn't
+        #     enabled.
+        def when_feature( feature, override: nil, &block )
+          yield if override.nil? ? feature_enabled?( feature ) : override
+        end
+
+        # @!visibility public
+        #
+        # Determines if the given feature has been toggled.
+        #
+        # @param [Symbol] feature name of the feature to check.
+        # @return [Boolean] true if the feature has been toggled on.
+        def feature_enabled?( feature )
+          features_service.enabled?( feature )
+        end
+    end
+  end
+end