Additional throttler types

.travis.yml

@@ -3,6 +3,7 @@ language: php
 php:
   - 5.5
   - 5.6
+  - 7.0
 
 before_script:
   - composer self-update

README.md

@@ -37,7 +37,8 @@ compatible autoloader.
 ```php
 // 1. Make a rate limiter with limit 3 attempts in 10 minutes
 $cacheAdapter = new DesarrollaCacheAdapter((new DesarrollaCacheFactory())->make());
-$ratelimiter = new RateLimiter(new ThrottlerFactory(), new HydratorFactory(), $cacheAdapter, 3, 600);
+$settings = new ElasticWindowSettings(3, 600);
+$ratelimiter = new RateLimiter(new ThrottlerFactory($cacheAdapter), new HydratorFactory(), $settings);
 
 // 2. Get a throttler for path /login 
 $loginThrottler = $ratelimiter->get('/login');
@@ -145,6 +146,67 @@ class MyHydratorFactory implements FactoryInterface
 }
 ```
 
+## Throttler types
+
+### Elastic Window
+An elastic window throttler will allow X requests in Y seconds. Any further access attempts will be counted, but return false as status. Note that the window will be extended with Y seconds on every hit. This means there need to be no hits during Y seconds for the counter to be reset to 0. 
+
+See [Overview example](#overview) for instantiation.
+
+### Time-based throttlers
+All the following throttlers use time functions, thus needing a different factory for construction:
+
+```php
+$cacheAdapter = new DesarrollaCacheAdapter((new DesarrollaCacheFactory())->make());
+$timeAdapter = new PhpTimeAdapter();
+
+$throttlerFactory = new TimeAwareThrottlerFactory($cacheAdapter, $timeAdapter);
+$hydratorFactory = new HydratorFactory();
+
+//$settings = ...
+$ratelimiter = new RateLimiter($throttlerFactory, $hydratorFactory, $settings);
+```
+
+#### Fixed Window
+A fixed window throttler will allow X requests in the Y seconds since the first request. Any further access attempts will be counted, but return false as status. The window will not be extended at all. 
+
+```php
+// Make a rate limiter with limit 120 attempts per minute
+$settings = new FixedWindowSettings(120, 60);
+```
+
+#### Moving Window
+A moving window throttler will allow X requests during the previous Y seconds. Any further access attempts will be counted, but return false as status. The window is never extended beyond Y seconds. 
+
+```php
+// Make a rate limiter with limit 120 attempts per minute
+$settings = new MovingWindowSettings(120, 60);
+```
+
+#### Leaky Bucket
+A [leaky bucket](https://en.wikipedia.org/wiki/Leaky_bucket) throttler will allow X requests divided over time Y.
+
+Any access attempts past the threshold T (default: 0) will be delayed by Y / (X - T)
+
+`access()` will return false if delayed, `hit()` will return the number of milliseconds waited
+
+__Note: Time limit for this throttler is in milliseconds, where it is seconds for the other throttler types!__
+
+```php
+// Make a rate limiter with limit 120 attempts per minute, start delaying after 30 requests
+$settings = new LeakyBucketSettings(120, 60000, 30);
+```
+
+#### Retrial Queue
+The retrial queue encapsulates another throttler.
+When this throttler receives a hit which would fail on the internal throttler, 
+the request is delayed until the internal throttler has capacity again.   
+
+```php
+// Make a leaky bucket ratelimiter which delays any overflow
+$settings = new RetrialQueueSettings(new LeakyBucketSettings(120, 60000, 120));
+```
+
 ## Author
 
 Krishnaprasad MG [@sunspikes]

phpunit.xml

@@ -14,4 +14,7 @@
             <directory suffix=".php">./tests/</directory>
         </testsuite>
     </testsuites>
+    <listeners>
+        <listener class="\Mockery\Adapter\Phpunit\TestListener"/>
+    </listeners>
 </phpunit>

src/Cache/Factory/DesarrollaCacheFactory.php

@@ -199,10 +199,10 @@ protected function createMemcacheDriver()
     {
         $server = null;
 
-        if (isset($this->config['servers'])) {
+        if (isset($this->config['memcache']['servers'])) {
             $server = new \Memcache();
 
-            foreach ($this->config['servers'] as $host) {
+            foreach ($this->config['memcache']['servers'] as $host) {
                 $server->addserver($host);
             }
         }

src/RateLimiter.php

@@ -25,33 +25,19 @@
 
 namespace Sunspikes\Ratelimit;
 
-use Sunspikes\Ratelimit\Cache\Adapter\CacheAdapterInterface;
+use Sunspikes\Ratelimit\Throttle\Entity\Data;
+use Sunspikes\Ratelimit\Throttle\Settings\ThrottleSettingsInterface;
 use Sunspikes\Ratelimit\Throttle\Throttler\ThrottlerInterface;
 use Sunspikes\Ratelimit\Throttle\Factory\FactoryInterface as ThrottlerFactoryInterface;
 use Sunspikes\Ratelimit\Throttle\Hydrator\FactoryInterface as HydratorFactoryInterface;
 
-class RateLimiter
+class RateLimiter implements RateLimiterInterface
 {
-    /**
-     * @var CacheAdapterInterface
-     */
-    protected $adapter;
-
     /**
      * @var ThrottlerInterface[]
      */
     protected $throttlers;
 
-    /**
-     * @var int
-     */
-    protected $limit;
-
-    /**
-     * @var int
-     */
-    protected $ttl;
-
     /**
      * @var ThrottlerFactoryInterface
      */
@@ -62,54 +48,61 @@ class RateLimiter
      */
     protected $hydratorFactory;
 
+    /**
+     * @var ThrottleSettingsInterface
+     */
+    private $defaultSettings;
+
     /**
      * @param ThrottlerFactoryInterface $throttlerFactory
      * @param HydratorFactoryInterface  $hydratorFactory
-     * @param CacheAdapterInterface     $cacheAdapter
-     * @param int                       $limit
-     * @param int                       $ttl
+     * @param ThrottleSettingsInterface $defaultSettings
      */
     public function __construct(
         ThrottlerFactoryInterface $throttlerFactory,
         HydratorFactoryInterface $hydratorFactory,
-        CacheAdapterInterface $cacheAdapter,
-        $limit,
-        $ttl
+        ThrottleSettingsInterface $defaultSettings
     ) {
         $this->throttlerFactory = $throttlerFactory;
         $this->hydratorFactory = $hydratorFactory;
-        $this->adapter = $cacheAdapter;
-        $this->limit = $limit;
-        $this->ttl = $ttl;
+        $this->defaultSettings = $defaultSettings;
     }
 
     /**
-     * Build the throttler for given data
-     *
-     * @param mixed    $data
-     * @param int|null $limit
-     * @param int|null $ttl
-     *
-     * @return mixed
-     *
-     * @throws \InvalidArgumentException
+     * @inheritdoc
      */
-    public function get($data, $limit = null, $ttl = null)
+    public function get($data, ThrottleSettingsInterface $settings = null)
     {
         if (empty($data)) {
             throw new \InvalidArgumentException('Invalid data, please check the data.');
         }
 
-        $limit = null === $limit ? $this->limit : $limit;
-        $ttl = null === $ttl ? $this->ttl : $ttl;
+        $object = $this->hydratorFactory->make($data)->hydrate($data);
 
-        // Create the data object
-        $dataObject = $this->hydratorFactory->make($data)->hydrate($data, $limit, $ttl);
+        if (!isset($this->throttlers[$object->getKey()])) {
+            $this->throttlers[$object->getKey()] = $this->createThrottler($object, $settings);
+        }
 
-        if (!isset($this->throttlers[$dataObject->getKey()])) {
-            $this->throttlers[$dataObject->getKey()] = $this->throttlerFactory->make($dataObject, $this->adapter);
+        return $this->throttlers[$object->getKey()];
+    }
+
+    /**
+     * @param Data                           $object
+     * @param ThrottleSettingsInterface|null $settings
+     *
+     * @return ThrottlerInterface
+     */
+    private function createThrottler(Data $object, ThrottleSettingsInterface $settings = null)
+    {
+        if (null === $settings) {
+            $settings = $this->defaultSettings;
+        } else {
+            try {
+                $settings = $this->defaultSettings->merge($settings);
+            } catch (\InvalidArgumentException $exception) {
+            }
         }
 
-        return $this->throttlers[$dataObject->getKey()];
+        return $this->throttlerFactory->make($object, $settings);
     }
 }

src/RateLimiterInterface.php

@@ -0,0 +1,44 @@
+<?php
+/**
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2015 Krishnaprasad MG <[email protected]>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+namespace Sunspikes\Ratelimit;
+
+use Sunspikes\Ratelimit\Throttle\Settings\ThrottleSettingsInterface;
+use Sunspikes\Ratelimit\Throttle\Throttler\ThrottlerInterface;
+
+interface RateLimiterInterface
+{
+    /**
+     * Return a throttler for given data and settings
+     *
+     * @param mixed                          $data
+     * @param ThrottleSettingsInterface|null $throttlerSettings
+     *
+     * @return ThrottlerInterface
+     *
+     * @throws \InvalidArgumentException
+     */
+    public function get($data, ThrottleSettingsInterface $throttlerSettings = null);
+}

src/Throttle/Entity/Data.php

@@ -25,27 +25,24 @@
 
 namespace Sunspikes\Ratelimit\Throttle\Entity;
 
-class Data
+final class Data
 {
-    /* @var string */
-    protected $data;
-    /* @var int */
-    protected $limit;
-    /* @var int */
-    protected $ttl;
-    /* @var string */
-    protected $key;
+    /**
+     * @var string
+     */
+    private $data;
+
+    /**
+     * @var string
+     */
+    private $key;
 
     /**
      * @param string $data
-     * @param int $limit
-     * @param int $ttl
      */
-    public function __construct($data, $limit, $ttl)
+    public function __construct($data)
     {
         $this->data = $data;
-        $this->limit = $limit;
-        $this->ttl = $ttl;
     }
 
     /**
@@ -58,26 +55,6 @@ public function getData()
         return $this->data;
     }
 
-    /**
-     * Get limit
-     *
-     * @return int
-     */
-    public function getLimit()
-    {
-        return $this->limit;
-    }
-
-    /**
-     * Get TTL
-     *
-     * @return int
-     */
-    public function getTtl()
-    {
-        return $this->ttl;
-    }
-
     /**
      * Get key
      *

src/Throttle/Factory/FactoryInterface.php

@@ -25,18 +25,20 @@
 
 namespace Sunspikes\Ratelimit\Throttle\Factory;
 
-use Sunspikes\Ratelimit\Cache\Adapter\CacheAdapterInterface;
 use Sunspikes\Ratelimit\Throttle\Entity\Data;
+use Sunspikes\Ratelimit\Throttle\Settings\ThrottleSettingsInterface;
+use Sunspikes\Ratelimit\Throttle\Throttler\ThrottlerInterface;
 
 interface FactoryInterface
 {
     /**
      * Create the throttler
      *
-     * @param Data $data
-     * @param CacheAdapterInterface $cache
+     * @param Data                      $data
+     * @param ThrottleSettingsInterface $settings
      *
-     * @return \Sunspikes\Ratelimit\Throttle\Throttler\ThrottlerInterface
+     * @return ThrottlerInterface
+     * @throws \InvalidArgumentException
      */
-    public function make(Data $data, CacheAdapterInterface $cache);
+    public function make(Data $data, ThrottleSettingsInterface $settings);
 }