excess_flow 1.0.0

data/lib/excess_flow/configuration.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Copyright 2019 ConvertKit, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module ExcessFlow
+  # == ExcessFlow::Configuration
+  #
+  # Holds configuration for rate limiter with writeable attributes allowing
+  # dynamic change of configuration during runtime
+  class Configuration
+    attr_accessor(
+      :connection_pool,
+      :connection_timeout,
+      :redis_url,
+      :sentinels
+    )
+
+    def initialize
+      @connection_pool = extract_connection_pool
+      @connection_timeout = extract_connection_timeout
+      @redis_url = extract_redis_url
+      @sentinels = process_sentinels
+    end
+
+    private
+
+    def extract_connection_pool
+      ENV.fetch(
+        'EXCESS_FLOW_CONNECTION_POOL',
+        ExcessFlow::DEFAULT_CONNECTION_POOL
+      ).to_i
+    end
+
+    def extract_connection_timeout
+      ENV.fetch(
+        'EXCESS_FLOW_CONNECTION_TIMEOUT',
+        ExcessFlow::DEFAULT_CONNECTION_TIMEOUT
+      ).to_i
+    end
+
+    def extract_redis_url
+      ENV.fetch(
+        'EXCESS_FLOW_REDIS_URL',
+        ExcessFlow::DEFAULT_REDIS_URL
+      )
+    end
+
+    def process_sentinels
+      ENV.fetch('EXCESS_FLOW_REDIS_SENTINELS', '').split(',').map do |sentinel|
+        host, port = sentinel.split(':')
+        { host: host, port: port.to_i }
+      end
+    end
+  end
+end

data/lib/excess_flow/configuration_error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Copyright 2019 ConvertKit, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module ExcessFlow
+  # == ExcessFlow::ConfigurationError
+  #
+  # Error used in ThrottleConfiguration class
+  class ConfigurationError < StandardError; end
+end

data/lib/excess_flow/constants.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# Copyright 2019 ConvertKit, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module ExcessFlow
+  CONFIGURATION_ERROR_MESSAGE = 'Invalid arguments provided. Please refer to README.md'
+  COUNTER_PREFIX = 'excess_flow::counter::'
+  DEFAULT_CONNECTION_POOL = 100
+  DEFAULT_CONNECTION_TIMEOUT = 3
+  DEFAULT_REDIS_URL = 'redis://localhost:6379/1'
+  LOCK_PREFIX = 'excess_flow::lock::'
+  MUTEX_LOCK_TIME = 1
+  MUTEX_SLEEP_TIME = 1 / 100_000
+  VERSION = '1.0.0'
+end

data/lib/excess_flow/failed_execution.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Copyright 2019 ConvertKit, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module ExcessFlow
+  class FailedExecution; end
+end

data/lib/excess_flow/fixed_window_strategy.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Copyright 2019 ConvertKit, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module ExcessFlow
+  # == ExcessFlow::FixedWindowStrategy
+  #
+  # Definition of fixed window rate limiting strategy and it's behaviour
+  # implementations. Fixed window allows only N requests for a given key to be
+  # done in a O time window where O start is defined at the time of first
+  # request. Window expiration starts with the first request for a given key.
+  # Once expired it will reset back to 0.
+  class FixedWindowStrategy < ExcessFlow::Strategy
+    def within_rate_limit?
+      ExcessFlow::GlobalMutex.locked(lock_key: configuration.lock_key) do
+        if current_requests < configuration.limit
+          bump_counter
+          start_expiration_window
+
+          true
+        else
+          false
+        end
+      end
+    end
+
+    private
+
+    def bump_counter
+      ExcessFlow.redis { |r| r.incr(configuration.counter_key) }
+    end
+
+    def current_requests
+      @current_requests ||= ExcessFlow.redis { |r| r.get(configuration.counter_key) }.to_i
+    end
+
+    def start_expiration_window
+      return if current_requests.zero?
+
+      ExcessFlow.redis { |r| r.expire(configuration.counter_key, configuration.ttl) }
+    end
+  end
+end

data/lib/excess_flow/global_mutex.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Copyright 2019 ConvertKit, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module ExcessFlow
+  # == ExcessFlow::GlobalMutex
+  #
+  # Attempts to set up exclusive lock to execute a block of code. If another
+  # lock is in place then GlobalMutex will wait till lock is available. Always
+  # returns result of execution. GlobalMutex does not guarantee order of execution;
+  # it will only guarantee that only one thread for a given lock_key is running to
+  # avoid race conditions.
+  class GlobalMutex
+    attr_reader :lock_key
+
+    def self.locked(lock_key:, &block)
+      new(lock_key).locked(&block)
+    end
+
+    def initialize(lock_key)
+      @lock_key = lock_key
+    end
+
+    def locked(&block)
+      sleep(ExcessFlow::MUTEX_SLEEP_TIME) until lock
+      result = block.call
+      unlock
+
+      result
+    end
+
+    private
+
+    def lock
+      ExcessFlow.redis { |r| r.set(lock_key, 1, nx: true, ex: ExcessFlow::MUTEX_LOCK_TIME) }
+    end
+
+    def unlock
+      ExcessFlow.redis { |r| r.expire(lock_key, 0) }
+    end
+  end
+end

data/lib/excess_flow/rate_limited_execution_result.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Copyright 2019 ConvertKit, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module ExcessFlow
+  # == ExcessFlow::RateLimitedExecutionResult
+  #
+  # Wrapper containing result of rate limited execution
+  class RateLimitedExecutionResult
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+    end
+
+    def success?
+      !result.is_a?(FailedExecution)
+    end
+  end
+end

data/lib/excess_flow/redis_connection.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Copyright 2019 ConvertKit, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module ExcessFlow
+  # == ExcessFlow::RedisConnection
+  #
+  # Wrapper around ConnectionPool and Redis to provide connectivity
+  # to Redis with desired configuration and sane connection pool
+  module RedisConnection
+    module_function
+
+    def connection_pool
+      @connection_pool = ConnectionPool.new(connection_pool_options) do
+        Redis.new(connection_options)
+      end
+    end
+
+    def connection_options
+      {
+        url: redis_url,
+        sentinels: sentinels
+      }.delete_if { |_k, v| v.nil? || v.empty? }
+    end
+
+    def connection_pool_options
+      {
+        size: pool_size,
+        timeout: connection_timeout
+      }
+    end
+
+    def connection_timeout
+      ExcessFlow.configuration.connection_timeout
+    end
+
+    def pool_size
+      ExcessFlow.configuration.connection_pool
+    end
+
+    def redis_url
+      ExcessFlow.configuration.redis_url
+    end
+
+    def sentinels
+      ExcessFlow.configuration.sentinels
+    end
+  end
+end

data/lib/excess_flow/sliding_window_strategy.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Copyright 2019 ConvertKit, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module ExcessFlow
+  # == ExcessFlow::SlidingWindowStrategy
+  #
+  # Definition of sliging window rate limiting strategy and it's behaviour
+  # implementations. Sliding window allows only N requests for a given key to
+  # be done in a trailing O time window where O start is defined as `now` -
+  # `window_size`. Window expiration starts with the first request for a given
+  # key. Once expired it will reset back to 0.
+  class SlidingWindowStrategy < ExcessFlow::Strategy
+    def within_rate_limit?
+      ExcessFlow::GlobalMutex.locked(lock_key: configuration.lock_key) do
+        cleanup_stale_counters
+
+        if current_requests < configuration.limit
+          bump_counter
+          start_expiration_window
+
+          true
+        else
+          false
+        end
+      end
+    end
+
+    private
+
+    def bump_counter
+      ExcessFlow.redis do |r|
+        r.zadd(
+          configuration.counter_key,
+          current_timestamp,
+          current_timestamp
+        )
+      end
+    end
+
+    def cleanup_stale_counters
+      ExcessFlow.redis do |r|
+        r.zremrangebyscore(configuration.counter_key, 0, "(#{window_start}")
+      end
+    end
+
+    def current_requests
+      @current_requests ||= ExcessFlow.redis { |r| r.zcount(configuration.counter_key, '-inf', '+inf') }
+    end
+
+    def current_timestamp
+      @current_timestamp ||= (Time.now.to_f * 100_000).to_i
+    end
+
+    def start_expiration_window
+      return if current_requests.zero?
+
+      ExcessFlow.redis { |r| r.expire(configuration.counter_key, configuration.ttl) }
+    end
+
+    def window_start
+      @window_start ||= current_timestamp - (configuration.ttl * 100_000)
+    end
+  end
+end

data/lib/excess_flow/strategy.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# Copyright 2019 ConvertKit, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module ExcessFlow
+  # == ExcessFlow::Strategy
+  #
+  # Base class for implementing different strategies for rate limiting.
+  class Strategy
+    attr_reader :configuration
+
+    def self.execute(configuration:, &block)
+      new(configuration).execute(&block)
+    end
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def execute
+      result = if within_rate_limit?
+                 yield
+               else
+                 FailedExecution.new
+               end
+
+      RateLimitedExecutionResult.new(result)
+    end
+
+    def within_rate_limit?
+      true
+    end
+  end
+end

data/lib/excess_flow/throttle_configuration.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+# Copyright 2019 ConvertKit, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module ExcessFlow
+  # == ExcessFlow::ThrottleConfiguration
+  #
+  # Wrapper class for throttle execution result that does provide some basic
+  # transformation of provided values.
+  class ThrottleConfiguration
+    MANDATORY_KEYS = %i[
+      key
+      limit
+      ttl
+    ].freeze
+
+    OPTIONAL_KEYS = %i[
+      strategy
+    ].freeze
+
+    attr_reader :key, :limit, :ttl
+
+    def initialize(args)
+      @raw_args = args
+      validate_args
+
+      args.each do |key, value|
+        instance_variable_set("@#{key}", value) unless value.nil?
+      end
+    end
+
+    def counter_key
+      ExcessFlow::COUNTER_PREFIX + key
+    end
+
+    def lock_key
+      ExcessFlow::LOCK_PREFIX + key
+    end
+
+    def strategy
+      case @strategy
+      when :fixed_window then ExcessFlow::FixedWindowStrategy
+      when :sliding_window then ExcessFlow::SlidingWindowStrategy
+      else ExcessFlow::FixedWindowStrategy
+      end
+    end
+
+    private
+
+    def allowed_keys_passed_in?
+      (@raw_args.keys - (MANDATORY_KEYS + OPTIONAL_KEYS)).empty?
+    end
+
+    def mandatory_keys_are_present?
+      (MANDATORY_KEYS - @raw_args.keys).empty?
+    end
+
+    def validate_args
+      return if allowed_keys_passed_in? && mandatory_keys_are_present?
+
+      raise ExcessFlow::ConfigurationError, CONFIGURATION_ERROR_MESSAGE
+    end
+  end
+end

data/lib/excess_flow/throttled_executor.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Copyright 2019 ConvertKit, LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module ExcessFlow
+  # == ExcessFlow::ThrottledExecutor
+  #
+  # Wrapper service class that will take care of initialization of configuration
+  # object and will execute on correct throttling strategy.
+  class ThrottledExecutor
+    attr_reader :args
+
+    def self.select_strategy_and_execute(args, &block)
+      new(args).select_strategy_and_execute(&block)
+    end
+
+    def initialize(args)
+      @args = args
+    end
+
+    def select_strategy_and_execute(&block)
+      strategy.execute(configuration: configuration, &block)
+    end
+
+    private
+
+    def configuration
+      @configuration ||= ExcessFlow::ThrottleConfiguration.new(args)
+    end
+
+    def strategy
+      configuration.strategy
+    end
+  end
+end