shamu 0.0.1 → 0.0.2

data/lib/shamu/events/error.rb

@@ -0,0 +1,24 @@
+require "i18n"
+
+module Shamu
+
+  module Events
+    # A generic error class for problems with shamu services.
+    class Error < Shamu::Error
+      private
+
+        def translation_scope
+          super.dup.insert( 1, :events )
+        end
+    end
+
+    # A an event runner did not provide a valid runner_id.
+    class UnknownRunnnerError < Error
+
+      def initialize( message = :unknown_runner )
+        super
+      end
+
+    end
+  end
+end

data/lib/shamu/events/events_service.rb

@@ -0,0 +1,136 @@
+require "multi_json"
+
+module Shamu
+  module Events
+
+    # The {EventsService} handles receiving messages ({#publish}) and
+    # dispatching them to all registered subscribers ({#subscriber}). The actual
+    # delivery and message transport is defined by the concrete implementations
+    # of the {EventService}. See "Included Event Systems" below.
+    #
+    # Use `.` or `/` to namespace and group channels. Channels are not related
+    # to each other but namespacing can help organize and group channels in
+    # reports and back-end tools.
+    #
+    # > Events are not guaranteed to be delivered and may be delivered more than
+    # > once. Event processing should be idempotent and resilient to message
+    # > loss.
+    #
+    # ## Included Event Systems
+    #
+    # - {InMemory In Memory} intended for decoupling services all running
+    #   withing the same process. This is the default.
+    # - {ActiveRecord} for low volume high-latency communications in a smaller
+    #   system.
+    #
+    # ## Selecting an Event System
+    #
+    # Shamu relies on {https://github.com/phallguy/scorpion Scorpion} to resolve
+    # dependencies. To select which event system to use, prepare the scorpion
+    # with specific hunting instructions.
+    #
+    # ```
+    # Scorpion.prepare do
+    #   capture Shamu::Events::ActiveRecord::Service
+    # end
+    # ```
+    class EventsService < Services::Service
+
+      # Prepare the default event service implementation to use. The default
+      # event service can be overridden when setting up the scorpion.
+      #
+      # @example
+      #   Scorpion.prepare do
+      #     capture Shamu::Events::EventsService do |scorpion, *args|
+      #       scorpion.fetch Shamu::Events::InMemory::AsyncService, *args
+      #     end
+      #   end
+      #
+      # @return [EventsService]
+      def self.create( scorpion, *args, &block )
+        @events_service ||= scorpion.fetch InMemory::Service
+      end
+
+      # Publish a well-defined {Message} to a known channel so that any client
+      # that has {#subscribe subscribed} will receive a copy of the message to
+      # process.
+      #
+      # Events are delivered asynchronously. There is no guarantee that a
+      # subscriber has received or processed a message.
+      #
+      # @param [String] channel to publish to.
+      # @param [Message] message to publish.
+      # @return [void]
+      def publish( channel, message )
+        fail NotImplementedError
+      end
+
+      # Subscribe to receive notifications of events on the named channel. Any
+      # time a publisher pushes a message `callback` will be invoked with a copy
+      # of the message.
+      #
+      # @param [String] channel to listen to.
+      # @yield (message)
+      # @yieldparam [Message] message
+      # @return [void]
+      def subscribe( channel, &callback )
+        fail NotImplementedError
+      end
+
+      # Subscribe to the given channels from one service and forward them to
+      # another service.
+      #
+      # @param [EventsService] from the service to subscribe to.
+      # @param [EventsService] to the service to forward to.
+      # @param [Array<String>] the channels to forwar.
+      # @return [void]
+      def self.bridge( from, to, *channels )
+        Array( channels ).each do |channel|
+          from.subscribe( channel ) do |message|
+            to.publish channel, message
+          end
+        end
+      end
+
+      private
+
+        # @!visibility public
+        #
+        # Serialize a message so that it can be transfered from publisher to
+        # subsriber.
+        #
+        # @param [Message] message to serializer.
+        # @return [String] the serialized message.
+        def serialize( message )
+          MultiJson.dump \
+            class: message.class.name,
+            attributes: message.to_attributes
+        end
+
+        # @!visibility public
+        #
+        # Deserialize a message back to a {Message} instance.
+        #
+        # @param [String] raw data.
+        # @return [Message] the deserialized message.
+        def deserialize( raw )
+          hash = MultiJson.load( raw )
+          message_class = hash["class"].constantize
+          scorpion.fetch message_class, hash["attributes"], {}
+        end
+
+        def fetch_channel( name )
+          channels[name] || begin
+            mutex.synchronize do
+              channels[ name ] ||= create_channel( name )
+            end
+          end
+        end
+
+        def create_channel( name )
+          fail NotImplementedError, "Implement `def create_channel( name )` in #{ self.class.name }"
+        end
+
+    end
+  end
+end

data/lib/shamu/events/in_memory/async_service.rb

@@ -0,0 +1,48 @@
+require "thread"
+require "thwait"
+
+module Shamu
+  module Events
+    module InMemory
+
+      # An asynchronous version of {Service}. Event subscribers should be able
+      # to handle events coming in on a separate thread.
+      class AsyncService < InMemory::Service
+
+        initialize do
+          ObjectSpace.define_finalizer self do
+            threads = mutex.synchronize do
+              channels.map do |_, state|
+                state[:queue].close
+                state[:thread]
+              end
+            end
+
+            ThreadsWait.all_waits( *threads )
+          end
+        end
+
+        # (see Service#dispatch)
+        def dispatch
+          # No-op since messages are immediately dispatched on background threads.
+        end
+
+        private
+
+          def create_channel( _ )
+            state = super
+            state[:thread] = channel_thread( state )
+            state[:queue]  = Queue.new
+            state
+          end
+
+          def channel_thread( state )
+            Thread.new do
+              dispatch_channel( state )
+            end
+          end
+
+      end
+    end
+  end
+end

data/lib/shamu/events/in_memory/service.rb

@@ -0,0 +1,97 @@
+require "thread"
+require "thwait"
+
+module Shamu
+  module Events
+    module InMemory
+
+      # Provides an in-memory {EventsService} that dispatches {Message messages}
+      # to subscribers within the same process.
+      #
+      # Messages are volitale and will be lost if the process crashes.
+      class Service < EventsService
+        include ChannelStats
+
+        initialize do
+          @mutex    = Thread::Mutex.new
+          @channels = {}
+        end
+
+        # (see EventsService#publish)
+        def publish( channel, message )
+          state = fetch_channel( channel )
+          queue = state[ :queue ]
+          queue.push serialize( message )
+        end
+
+        # (see EventsService#subscribe)
+        def subscribe( channel, &callback )
+          subscribers = fetch_channel( channel )[ :subscribers ]
+          mutex.synchronize do
+            subscribers << callback
+          end
+        end
+
+        # Dispatch all pending mssages in the given named channels.
+        # @param [Array<String>] names of the channels to dispatch. Dispatches
+        #     to all queues if empty.
+        # @return [void]
+        def dispatch( *names )
+          names = channels.keys if names.empty?
+
+          names.each do |name|
+            dispatch_channel( fetch_channel( name ) )
+          end
+        end
+
+        # (see ChannelStats#chanel_stats)
+        def channel_stats( name )
+          channel = fetch_channel( name )
+
+          {
+            name: name,
+            subscribers_count: channel[ :subscribers ].count,
+            queue_size: channel[ :queue ].size,
+            dispatching: channel[ :dispatching ]
+          }
+        end
+
+        private
+
+          attr_reader :channels
+          attr_reader :mutex
+
+          def create_channel( _ )
+            {
+              queue: [],
+              subscribers: [],
+            }
+          end
+
+          def dispatch_channel( state )
+            mutex.synchronize do
+              return if state[:dispatching]
+              state[ :dispatching ] = true
+            end
+
+            dispatch_messages( state )
+
+          ensure
+            mutex.synchronize do
+              state[ :dispatching ] = false
+            end
+          end
+
+          def dispatch_messages( state )
+            while raw_message = state[:queue].shift
+              message = deserialize( raw_message )
+              state[ :subscribers ].each do |subscriber|
+                subscriber.call( message )
+              end
+            end
+          end
+
+      end
+    end
+  end
+end

data/lib/shamu/events/in_memory.rb

@@ -0,0 +1,10 @@
+module Shamu
+  module Events
+
+    # See {Service}.
+    module InMemory
+      require "shamu/events/in_memory/service"
+      require "shamu/events/in_memory/async_service"
+    end
+  end
+end

data/lib/shamu/events/message.rb

@@ -0,0 +1,38 @@
+module Shamu
+  module Events
+
+    # The event {Message} consists of a set of well-defined attributes
+    # describing a single discrete event in the system and associated meta-data
+    # needed by subscribers to process the message.
+    #
+    # Messages should attempt to forward the state available at the time the
+    # event was published so that subscribers can process the message without
+    # contacting additional services.
+    #
+    # Event messages are  serialized for network or IPC transimission and must
+    # limit attributes to primitive types (Strings, Numbers, Arrays and Hashes)
+    # so they can be round tripped with `Message.new( message.to_attributes )`.
+    class Message
+      include Shamu::Attributes
+      include Shamu::Attributes::Equality
+
+      # ============================================================================
+      # @!group Attributes
+      #
+
+      # @!attribute
+      # @return [String] the ID for the message. Automatically generated UUID
+        attribute :id
+
+      #
+      # @!endgroup Attributes
+
+
+      def initialize( * )
+        super
+
+        @id ||= SecureRandom.uuid
+      end
+    end
+  end
+end

data/lib/shamu/events/support.rb

@@ -0,0 +1,60 @@
+module Shamu
+  module Events
+
+    # Add event dispatching support to a {Services::Service}
+    module Support
+      extend ActiveSupport::Concern
+
+      included do
+
+        # ============================================================================
+        # @!group Dependencies
+        #
+
+        # @!attribute
+        # @return [Events::EventsService] the events service to publish messages
+        #     to.
+        attr_dependency :events_service, Events::EventsService
+
+        #
+        # @!endgroup Dependencies
+
+      end
+
+      private
+
+        # @!visibility public
+        #
+        # Publish the given `message` to the {#events_service}.
+        #
+        # @param [Events::Message] message the custom event specific message to
+        #     publish.
+        # @param [String] channel to publish to.
+        # @return [void]
+        def event!( message, channel: event_channel )
+          events_service.publish channel, message
+        end
+
+        # @!visibility public
+        #
+        # The channel to {#publish_event publish events} to. Defaults to the
+        # transformed name of the service class.
+        #
+        #     Users::UsersService              => users
+        #     Users::ProfileService            => users/profile
+        #     Users::Profiles::ProfilesService => users/profiles
+        #
+        # @return [String] the name of the channel.
+        def event_channel
+          @event_channel ||= begin
+            base_name = self.class.name || "Events"
+            parts     = base_name.split( "::" )
+            parts[-1].sub!( /Service$/, "" )
+            parts.pop if parts[-1] == parts[-2] || ( parts.length > 1 && parts[-1].blank? )
+            parts.join( "/" ).underscore
+          end
+        end
+
+    end
+  end
+end

data/lib/shamu/events.rb

@@ -0,0 +1,12 @@
+module Shamu
+  # {include:file:lib/shamu/events/README.md}
+  module Security
+    require "shamu/events/error"
+    require "shamu/events/message"
+    require "shamu/events/events_service"
+    require "shamu/events/channel_stats"
+    require "shamu/events/support"
+
+    require "shamu/events/in_memory"
+  end
+end

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

@@ -0,0 +1,39 @@
+module Shamu
+  module Features
+    module Conditions
+
+      # A condition that must be met for a {Selector} to match and enable a
+      # {Toggle}.
+      class Condition
+
+        # @param [String] name of the condition.
+        # @param [Object] config settings for the condition.
+        def self.create( name, config, toggle )
+          @condition_class ||= Hash.new do |hash, key|
+            hash[key] = "Shamu::Features::Conditions::#{ key.to_s.camelize }".constantize
+          end
+
+          @condition_class[name].new config, toggle
+        end
+
+        # @param [Object] config options selected for the condition.
+        def initialize( config, toggle )
+          @config = config
+          @toggle = toggle
+        end
+
+        # @param [Context] context the feature evaluation context.
+        # @return [Boolean] true if the condition matches the given environment.
+        def match?( context )
+          fail NotImplementedError
+        end
+
+        private
+
+          attr_reader :config
+          attr_reader :toggle
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+module Shamu
+  module Features
+    module Conditions
+
+      # Match against an environment variable.
+      class Env < Conditions::Condition
+
+        # (see Condition#match?)
+        def match?( context )
+          variables.any? { |name, matcher| matcher.call( context.env( name ) ) }
+        end
+
+        private
+
+          def variables
+            @variables ||= hash_variables || array_variables
+          end
+
+          def hash_variables
+            return unless config.is_a?( Hash )
+
+            config.each_with_object( {} ) do |(name, value), hash|
+              hash[name] = ->(v) { v == value }
+            end
+          end
+
+          def array_variables
+            Array( config ).each_with_object( {} ) do |name, hash|
+              hash[name] = ->(v) { v.to_bool }
+            end
+          end
+
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+module Shamu
+  module Features
+    module Conditions
+
+      # Match against the current host machine's name.
+      class Hosts < Conditions::Condition
+
+        # (see Condition#match?)
+        def match?( context )
+          hosts.any? { |h| h.match( context.host ) }
+        end
+
+        private
+
+          def hosts
+            @hosts ||= Array( config ).map do |entry|
+              Regexp.new( entry, true )
+            end
+          end
+
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Shamu
+  module Features
+    module Conditions
+
+      # Match if another feature is also enabled.
+      class Matching < Conditions::Condition
+
+        # (see Condition#match?)
+        def match?( context )
+          context.enabled?( config )
+        end
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Shamu
+  module Features
+    module Conditions
+
+      # Match if another feature is also enabled.
+      class NotMatching < Conditions::Matching
+
+        # (see Condition#match?)
+        def match?( context )
+          !super
+        end
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+require "crc32"
+
+module Shamu
+  module Features
+    module Conditions
+
+      # Match against a limited percentage of total users.
+      class Percentage < Conditions::Condition
+
+        # (see Condition#match?)
+        def match?( context )
+          if context.user_id
+            ( user_id_hash( context.user_id ) ^ toggle_crc ) % 100 < percentage
+          else
+            context.sticky!
+            Random.rand( 100 ) < percentage
+          end
+        end
+
+        private
+
+          def percentage
+            @percentage ||= [ config.to_i, 100 ].min
+          end
+
+          def user_id_hash( user_id )
+            if user_id.is_a?( Numeric )
+              return user_id
+            else
+              return user_id.sub( "-", "" ).to_i( 16 )
+            end
+          end
+
+          def toggle_crc
+            # Use the name of the toggle to provide consistent semi-random noise
+            # into the user selection process.
+            @toggle_crc ||= Crc32.calculate( toggle.name, toggle.name.length, 0 )
+          end
+
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+module Shamu
+  module Features
+    module Conditions
+
+      # Match against a custom method. Due to their dynamic nature, proc
+      # conditions are much slower and should be reserved for only a few
+      # features.
+      #
+      # The proc is specified in the configuration by class and method name like
+      #
+      # ```yaml
+      # # features.yml
+      # commerce:
+      #   buy_now:
+      #     select:
+      #     - proc: Commerce::BuyNow#match?
+      # ```
+      #
+      # Shamu will instantiate a new instance of the `Commerce::BuyNow` class
+      # and invoke the `match?` method passing the current {Features::Context}.
+      #
+      # The custom proj will also have access to the current {Scorpion} if it
+      # includes the {Scorpion::Object} mixin.
+      class Proc < Conditions::Condition
+        include Scorpion::Object
+
+        # (see Condition#match?)
+        def match?( context )
+          instance( context ).send( proc_method, context, toggle )
+        end
+
+        private
+
+          def instance( context )
+            context.scorpion.fetch( proc_class )
+          end
+
+          def proc_class
+            @proc_class ||= proc_config.first.constantize
+          end
+
+          def proc_method
+            proc_config.last
+          end
+
+          def proc_config
+            @proc_config ||= config.split( "#" )
+          end
+
+      end
+
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+module Shamu
+  module Features
+    module Conditions
+
+      # Match against the current user's roles.
+      class Roles < Conditions::Condition
+
+        # (see Condition#match?)
+        def match?( context )
+          ( context.roles && roles ).any?
+        end
+
+        private
+
+          def roles
+            @roles ||= Array( config )
+          end
+
+      end
+
+    end
+  end
+end