shamu 0.0.1 → 0.0.2

data/lib/shamu/features/toggle.rb

@@ -0,0 +1,149 @@
+module Shamu
+  module Features
+
+    # A configured feature toggle.
+    class Toggle < Entities::Entity
+
+      TYPES = [
+        "release",    # Feature is expected to become permanent and is used to
+                      #  decouple deployment from production release. Relatively
+                      #  short lived.
+        "ops",        # Controlled by operations as a kill-switch or tuning
+                      #   option. Cohorts are typically not dynamic and apply to
+                      #   all users.
+        "experiment", # Used to explore the efficacy of an option by testing it
+                      #   on a subset of the total users.
+        "segment",    # Long-lived toggle used to control access to a feature
+                      #   based on some sort of user segmentation (e.g. dogfood,
+                      #   internal, premium, etc.).
+      ].freeze
+
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!attribute
+      # @return [String] name of the toggle, namespaced using paths.
+      attribute :name
+
+      # @!attribute
+      # @return [String] human friendly description of the toggle.
+      attribute :description
+
+      # @!attribute
+      # @return [String] type of the toggle. Offers a hint at acceptable caching
+      #     strategies.
+      attribute :type
+
+      # @!attribute
+      # @return [Time] When the feature toggle should be at 100% and removed
+      #     from the code base.
+      #
+      # Toggles, and the code selected by them should be removed as soon as
+      # possible so that you don't have to maintain unused code. By explicitly
+      # setting a date when the toggle is no longer to be used, the system can
+      # help inform you when the code is no longer needed and can safely be
+      # removed.
+      attribute :retire_at
+
+      # @!attribute
+      # @return [Array<Selector>] selectors used to match environment conditions
+      #     to determine if the flag should be enabled.
+      attribute :selectors do
+        Array( select ).map do |config|
+          Selector.new( self, config )
+        end
+      end
+
+      # The raw Hash read from the YAML file
+      model :select
+
+      #
+      # @!endgroup Attributes
+
+      # @param [Context] context the feature evaluation context.
+      # @return [Boolean] true if the toggle should be enabled.
+      def enabled?( context )
+        if selector = matching_selector( context )
+          !selector.reject
+        end
+      end
+
+      # @param [Context] context the feature evaluation context.
+      # @return [Boolean] true if the toggle is retired and should be always on.
+      def retired?( context )
+        !retire_at || context.time > retire_at
+      end
+
+
+      def initialize( attributes )
+        fail ArgumentError, "Must provide a retire_at attribute for '#{ attributes[ 'name' ] }' toggle." unless attributes["retire_at"] # rubocop:disable Metrics/LineLength
+        fail ArgumentError, "Type must be one of #{ TYPES } for '#{ attributes[ 'name' ] }' toggle." unless TYPES.include?( attributes["type"] ) # rubocop:disable Metrics/LineLength
+        super
+      end
+
+      private
+
+        def matching_selector( context )
+          selectors.find { |s| s.match?( context ) }
+        end
+
+      class << self
+
+        # Loads all the toggles from the YAML file at the given path.
+        #
+        # @param [String] path.
+        # @return [Hash<String,Toggle>] of toggles by name.
+        def load( path )
+          toggles = {}
+          load_from_path( path, toggles, ParsingState.new( nil, nil ) )
+
+          toggles
+        end
+
+        private
+
+          def load_from_path( path, toggles, state )
+            path = File.expand_path( path, state.file_path )
+            File.open( path, "r" ) do |file|
+              yaml = YAML.load( file.read )
+              parse_node( yaml, toggles, ParsingState.new( state.name, File.dirname( path ) ) )
+            end
+          end
+
+          def parse_node( node, toggles, state )
+            if toggle?( node )
+              params = node.merge!( "name" => state.name )
+              toggles[state.name] = Toggle.new( params )
+            else
+              parse_child_nodes( node, toggles, state )
+            end
+          end
+
+          def parse_child_nodes( node, toggles, state )
+            node.each do |key, child|
+              if key == "import"
+                load_from_path( child, toggles, state )
+              else
+                child_state = ParsingState.new( [ state.name, key ].compact.join( "/" ), state.file_path )
+                parse_node( child, toggles, child_state )
+              end
+            end
+          end
+
+          TOGGLE_KEYS = %w( description retire_at type select ).freeze
+
+          # Determines if the yaml entry with the given key is a toggle, or if
+          # it's children themselves may be toggles.
+          def toggle?( node )
+            return unless node.is_a? Hash
+            node.keys.all? { |k| TOGGLE_KEYS.include?( k ) }
+          end
+
+      end
+
+      ParsingState = Struct.new( :name, :file_path )
+    end
+  end
+end

data/lib/shamu/features/toggle_codec.rb

@@ -0,0 +1,69 @@
+module Shamu
+  module Features
+
+    # Packs and unpacks sticky toggle settings in a securely verifiable way. The
+    # data is not encrypted so it should not be relied on for security. It only
+    # guarantees that the packed data was created by calling
+    # {ToggleCode#pack}.
+    class ToggleCodec
+      include Shamu::Security::HashedValue
+
+      # @param [String] private_key the private key used to verify the packed toggles.
+      def initialize( private_key = Shamu::Security.private_key )
+        @private_key = private_key
+      end
+
+      # Packs a hash of configured features into a string that can be sent
+      # from a client at a later date to override those features. Use
+      # {#unpack} to restore the features hash.
+      #
+      # @param [Hash<String,Boolean>] featues hash of name to enabled state.
+      # @return [String] the packed string.
+      def pack( toggles )
+        hash_value( insecure_pack( toggles ) )
+      end
+
+      # Packs a hash of configured features without any authentication
+      # guarantees. Useful for working with trusted sources such as ENV
+      # variables.
+      #
+      # @param [Hash<String,Boolean>] featues hash of name to enabled state.
+      # @return [String] the packed string.
+      def insecure_pack( toggles )
+        toggles.each_with_object("") do |(key, state), packed|
+          packed << "," unless packed.blank?
+          packed << "!" unless state
+          packed << key
+        end
+      end
+
+      # Unpack a {#pack packed} token into its original hash of configured
+      # toggles. If the token is invalid or unauthenticated an empty result is
+      # returned.
+      #
+      # @param [String] token the packed toggles
+      # @return [Hash<String,Boolean>] the configured toggles.
+      def unpack( token )
+        insecure_unpack( verify_hash( token ) )
+      end
+
+      # Unpack a {#insecure_pack insecure packed} token into its original hash
+      # of configured toggles. If the token is invalid an empty result is
+      # returned.
+      #
+      # @param [String] token the packed toggles
+      # @return [Hash<String,Boolean>] the configured toggles.
+      def insecure_unpack( token )
+        return {} unless token
+
+        token.split( "," ).each_with_object( {} ) do |toggle, hash|
+          bang = toggle[0] == "!"
+          key  = bang ? toggle[1..-1] : toggle
+
+          hash[key] = !bang
+        end
+      end
+
+    end
+  end
+end

data/lib/shamu/features.rb

@@ -0,0 +1,16 @@
+module Shamu
+  # {include:file:lib/shamu/features/README.md}
+  module Features
+    require "shamu/features/context"
+    require "shamu/features/toggle"
+    require "shamu/features/conditions"
+    require "shamu/features/selector"
+    require "shamu/features/toggle_codec"
+    require "shamu/features/env_store"
+    require "shamu/features/features_service"
+    require "shamu/features/config_service"
+    require "shamu/features/list_scope"
+    require "shamu/features/support"
+    require "shamu/features/errors"
+  end
+end

data/lib/shamu/locale/en.yml

@@ -1,7 +1,27 @@
 en:
   shamu:
     errors:
-      messages:
+        not_found: The resource was not found.
+        not_implemented: The method has not been implemented.
 
     warnings:
-      messages:
+
+    services:
+      errors:
+        active_record_crud_missing_resource: The resource has not been defined. Add `resource entity_class, model_class` to {%service}.
+        incomplete_setup: The service has not been setup. See included modules documentation for details.
+
+
+    security:
+      errors:
+        access_denied: You are not permitted to do that.
+        incomplete_setup: Security has been enabled but is not yet configured.
+        no_actiev_record_policy_checks: Don't check for policy on ActiveRecord resources. Check their projected Entity instead.
+
+    events:
+      errors:
+        unknown_runner: Unknown runner. Each process should offer a consitent but unique runner_id.
+
+    features:
+      errors:
+        retired_toggle_checked: "The `%{name}` toggle retired at `%{retire_at}` and cannot be checked anymore."

data/lib/shamu/logger.rb

@@ -0,0 +1,13 @@
+module Shamu
+
+  # Logging class for shamu {Services}.
+  class Logger < ::Logger
+
+    # Set up a default logger.
+    def self.create( scorpion, *args, **dependencies, &block )
+      args = [STDOUT] unless args.present?
+      ::Logger.new( *args )
+    end
+
+  end
+end

data/lib/shamu/rack/cookies.rb

@@ -0,0 +1,115 @@
+module Shamu
+  module Rack
+
+    # Expose the request cookies as a hash.
+    class Cookies
+
+      # @return [Cookies]
+      def self.create( * )
+        fail "Add Shamu::Rack::CookiesMiddleware to use Shamu::Rack::Cookies"
+      end
+
+      # @param [Hash] env the Rack environment
+      def initialize( env )
+        @env = env
+        @cookies = {}
+        @deleted_cookies = []
+      end
+
+      # Apply the cookies {#set} or {#delete deleted} to the actual rack
+      # response headers.
+      #
+      # Modifies the `headers` hash!
+      #
+      # @param [Hash] headers from rack response
+      # @return [Hash] the modified headers with cookie values.
+      def apply!( headers )
+        cookies.each do |key, value|
+          ::Rack::Utils.set_cookie_header! headers, key, value
+        end
+
+        deleted_cookies.each do |key|
+          ::Rack::Utils.delete_cookie_header! headers, key
+        end
+
+        headers
+      end
+
+      # Get a cookie value from the browser.
+      # @param [String] key or name of the cookie
+      # @return [String] cookie value
+      def get( key )
+        key = key.to_s
+
+        if cookie = cookies[ key ]
+          cookie[:value]
+        else
+          env_cookies[ key ]
+        end
+      end
+      alias_method :[], :get
+
+      # @param [String] name
+      # @return [Boolean] true if the cookie has been set.
+      def key?( name )
+        cookies.key?( name ) || env_cookies.key?( name )
+      end
+
+      # Set or update a cookie in the headers.
+      #
+      # @overload set( key, value )
+      #   @param [String] key or name of the cookie
+      #   @param [String] value to assign
+      #
+      # @overload set( key, hash )
+      #   @param [String] key or name of the cookie
+      #   @option hash [String] :value
+      #   @option hash [String] :domain
+      #   @option hash [String] :path
+      #   @option hash [Integer] :max_age
+      #   @option hash [Time] :expires
+      #   @option hash [Boolean] :secure
+      #   @option hash [Boolean] :http_only
+      #
+      # @return [self]
+      def set( key, value )
+        key = key.to_s
+        deleted_cookies.delete( key )
+
+        value = { value: value } unless value.is_a? Hash
+        cookies[key] = value
+
+        self
+      end
+      alias_method :[]=, :set
+
+      # Delete a cookie from the browser.
+      # @param [String] key or name of the cookie.
+      # @return [self]
+      def delete( key )
+        cookies.delete( key )
+        @deleted_cookies << key if env_cookies.key?( key )
+        self
+      end
+
+      private
+
+        attr_reader :env
+        attr_reader :cookies
+        attr_reader :deleted_cookies
+
+        def env_cookies
+          @env_cookies ||= begin
+            @env_cookies = {}
+            string = env[ "HTTP_COOKIE" ]
+
+            # Cribbed from Rack::Request#cookies
+            parsed = ::Rack::Utils.parse_query( string, ";," ) { |s| ::Rack::Utils.unescape( s ) rescue s } # rubocop:disable Style/RescueModifier, Metrics/LineLength
+            parsed.each do |k, v|
+              @env_cookies[ k ] = Array === v ? v.first : v
+            end
+          end
+        end
+    end
+  end
+end

data/lib/shamu/rack/cookies_middleware.rb

@@ -0,0 +1,26 @@
+require "scorpion/rack"
+
+module Shamu
+  module Rack
+
+    # Expose a {Cookies} hash to any service that wants to use session specific
+    # storage.
+    class CookiesMiddleware
+      include Scorpion::Rack
+
+      def initialize( app )
+        @app = app
+      end
+
+      def call( env )
+        cookies = Shamu::Rack::Cookies.new( env )
+        scorpion( env ).hunt_for Shamu::Rack::Cookies, return: cookies
+
+        status, headers, body = @app.call( env )
+
+        [ status, cookies.apply!( headers ), body ]
+      end
+
+    end
+  end
+end

data/lib/shamu/rack/query_params.rb

@@ -0,0 +1,41 @@
+module Shamu
+  module Rack
+
+    # Expose the query string and post data parameters as a hash.
+    class QueryParams
+
+      # @return [QueryParams]
+      def self.create( * )
+        fail "Add Shamu::Rack::QueryParamsMiddleware to use Shamu::Rack::QueryParams"
+      end
+
+      # @param [Hash] env the Rack environment
+      def initialize( env )
+        @env = env
+      end
+
+      # Get a cookie value from the browser.
+      # @param [String] key or name of the cookie
+      # @return [String] cookie value
+      def get( key )
+        key = key.to_s
+        env_query_params[ key ]
+      end
+      alias_method :[], :get
+
+      # @param [String] name
+      # @return [Boolean] true if the cookie has been set.
+      def key?( name )
+        env_query_params.key?( name.to_s )
+      end
+
+      private
+
+        attr_reader :env
+
+        def env_query_params
+          @env_query_params ||= ::Rack::Request.new( env ).params
+        end
+    end
+  end
+end

data/lib/shamu/rack/query_params_middleware.rb

@@ -0,0 +1,24 @@
+require "scorpion/rack"
+
+module Shamu
+  module Rack
+
+    # Expose a {QueryParams} hash to any service that wants to toggle behavior
+    # based on query parameters.
+    class QueryParamsMiddleware
+      include Scorpion::Rack
+
+      def initialize( app )
+        @app = app
+      end
+
+      def call( env )
+        query_params = Shamu::Rack::QueryParams.new( env )
+        scorpion( env ).hunt_for Shamu::Rack::QueryParams, return: query_params
+
+        @app.call( env )
+      end
+
+    end
+  end
+end

data/lib/shamu/rack.rb

@@ -0,0 +1,12 @@
+require "scorpion/rack/middleware"
+
+module Shamu
+
+  # {include:file:lib/shamu/rack/README.md}
+  module Rack
+    require "shamu/rack/cookies"
+    require "shamu/rack/cookies_middleware"
+    require "shamu/rack/query_params"
+    require "shamu/rack/query_params_middleware"
+  end
+end

data/lib/shamu/rails/controller.rb

@@ -0,0 +1,131 @@
+module Shamu
+  module Rails
+
+    # Adds convenience methods to a controller to access services and process
+    # entities in response to common requests. The mixin is automatically added
+    # to all controllers.
+    #
+    # ```
+    # class UsersController < ApplicationController
+    #   service :users_service, Users::UsersService
+    # end
+    # ```
+    module Controller
+      extend ActiveSupport::Concern
+
+      included do
+        include Scorpion::Rails::Controller
+
+        helper_method :permit?
+        helper_method :current_user
+      end
+
+      private
+
+        # The currently logged in user. Must respond to #id when logged in.
+        def current_user
+        end
+
+        # @!visibility public
+        #
+        # @return [Array<Services::Service>] the list of services available to the
+        #     controller.
+        def services
+          @services ||= self.class.services.map { |n| send n }
+        end
+
+        # @!visibility public
+        #
+        # @return [Array<Services::Service>] the list of services that can
+        #     determine permissions for the controller.
+        def secure_services
+          @services ||= services.select { |s| s.respond_to?( :permit? ) }
+        end
+
+        # @!visibility public
+        #
+        # Checks if the requested behavior is permitted by any one of the
+        # {#secure_services}.
+        #
+        # See {Security::Policy#permit?} for details.
+        #
+        # @overload permit?( action, resource, additional_context = nil )
+        # @param (see Security::Policy#permit?)
+        # @return (see Security::Policy#permit?)
+        def permit?( *args )
+          secure_services.any? { |s| s.permit?( *args ) }
+        end
+
+
+        # @!visibility public
+        #
+        # Gets the security principal for the current request.
+        #
+        # @return [Shamu::Security::Principal]
+        def security_principal
+          @security_principal ||= begin
+            Shamu::Security::Principal.new \
+              user_id: current_user && current_user.id,
+              remote_ip: remote_ip,
+              elevated: session_elevated?
+          end
+        end
+
+        # @!visibility public
+        #
+        # @return [String] the IP address that the request originated from.
+        def remote_ip
+          request.env["HTTP_X_REAL_IP"] || request.remote_ip
+        end
+
+        # @!visibility public
+        #
+        # Override to indicate if the user has offerred their credentials this
+        # session rather than just using a 'remember me' style token
+        #
+        # @return [Boolean] true if the session has been elevated.
+        def session_elevated?
+        end
+
+        def prepare_scorpion( scorpion )
+          super
+
+          scorpion.prepare do |s|
+            s.hunt_for Shamu::Security::Principal do
+              security_principal
+            end
+          end
+        end
+
+      class_methods do
+
+        # @return [Array<Symbol>] the list of service names on the controller.
+        def services
+          @services ||= begin
+            superclass.respond_to?( :services ) ? superclass.services.dup : []
+          end
+        end
+
+        # Define a service dependency on the controller. Each request will get
+        # its own instance of the service.
+        #
+        # @param [Symbol] name of the attribute the service should be accessible
+        #     through.
+        # @param [Class] contract the class of the service that should be
+        #     resolved at runtime.
+        # @param [Hash] options additional dependency options. See Scorpion
+        #     attr_dependency for details.
+        # @option options [Boolean] :lazy true if the service should be resolved
+        #     the first time it's used instead of when the controller is
+        #     initialized.
+        # @return [name]
+        def service( name, contract, **options, &block )
+          services << name
+          attr_dependency name, contract, options.merge( private: true )
+          name
+        end
+      end
+
+    end
+  end
+end