feat(*): Update bouncer configurations. Replace live_mode by stream_mode everywhere

Author: julienloizelet

docs/api/ApiCache.md

@@ -75,7 +75,8 @@ The cache mecanism to store every decisions from LAPI/CAPI. Symfony Cache compon
 **Description**
 
 ```php
-public configure (bool $liveMode, string $apiUrl, int $timeout, string $userAgent, string $apiKey, int $cacheExpirationForCleanIp, int $cacheExpirationForBadIp, string $fallbackRemediation)
+public configure (bool $streamMode, string $apiUrl, int $timeout, string $userAgent, string $apiKey, int 
+$cacheExpirationForCleanIp, int $cacheExpirationForBadIp, string $fallbackRemediation)
 ```
 
 Configure this instance. 
@@ -84,8 +85,8 @@ Configure this instance.
 
 **Parameters**
 
-* `(bool) $liveMode`
-: If we use the live mode (else we use the stream mode)  
+* `(bool) $streamMode`
+: If we use the stream mode (else we use the live mode)  
 * `(string) $apiUrl`
 : The URL of the LAPI  
 * `(int) $timeout`

docs/configuration-reference.md

@@ -1,6 +1,6 @@
 # Full configuration reference
 
-```bash
+```php
    $config = [
        // Required. The bouncer api key to access LAPI or CAPI.
        'api_key'=> 'YOUR_BOUNCER_API_KEY',
@@ -11,25 +11,89 @@
        // Optional. HTTP user agent used to call CAPI or LAPI. Default to this library name/current version.
        'api_user_agent'=> 'CrowdSec PHP Library/x.x.x',
 
-       // Optional. In seconds. The timeout when calling CAPI/LAPI. Defaults to 2 sec.
-       'api_timeout'=> 2,
+       // Optional. In seconds. The timeout when calling CAPI/LAPI. Defaults to 1 sec.
+       'api_timeout'=> 1,
+       
+       // Optional. Select from 'bouncing_disabled', 'normal_bouncing' or 'flex_bouncing'. Default to 'normal_bouncing'
+       'bouncing_level' => 'normal_bouncing',
+       
+       // Optional. Absolute path to store log files.
+       'log_directory_path' => __DIR__.'/.logs',
+       
+       // Optional. Select from 'phpfs' (File system cache), 'redis' or 'memcached'. Default to 'phpcs'
+       'cache_system' => 'phpfs',
+       
+       // Optional. Will be used only if you choose File system as cache_system
+       'fs_cache_path' => __DIR__.'/.cache',
+       
+       // Optional. Will be used only if you choose Redis cache as cache_system
+       'redis_dsn' => 'redis://localhost:6379',
+       
+       // Optional. Will be used only if you choose Memcached as cache_system
+       'memcached_dsn' => 'memcached://localhost:11211',
+       
+       // Optional. If you use a CDN, a reverse proxy or a load balancer, set an array of IPs.
+       // For other IPs, the bouncer will not trust the X-Forwarded-For header.
+       'trust_ip_forward_array' => [],
 
-       // Optional. true to enable live mode, false to enable the stream mode. Default to true.
-       'live_mode'=> true,
+       // Optional. true to enable stream mode, true to enable the stream mode. Default to false.
+       'stream_mode'=> false,
 
-       // Optional. Cap the remediation to the selected one. Select from 'bypass' (minimum remediation), 'captcha' or 'ban' (maximum remediation). Defaults to 'ban'.
+       // Optional. true to enable verbose debug log. Default to false
+       'debug_mode' => false,
+       
+       // Optional. true to stop the process and display errors if any. Default to false.
+       'display_errors' => false,
+       
+       // Optional. true to hide CrowdSec mentions on ban and captcha walls. Default to false.
+       'hide_mentions' => false,
+       
+       // Optional. Only for test or debug purpose.
+       // If not empty, it will be used for all remediation and geolocation processes.
+       'forced_test_ip' => '1.2.3.4',
+       
+       // Optional. Cap the remediation to the selected one.
+       // Select from 'bypass' (minimum remediation),'captcha' or 'ban' (maximum remediation).
+       // Default to 'ban'.
        'max_remediation_level'=> 'ban',
 
-       // Optional. Handle unknown remediations as. Select from 'bypass' (minimum remediation), 'captcha' or 'ban' (maximum remediation). Defaults to 'captcha'.
+       // Optional. Handle unknown remediations as.
+       // Select from 'bypass' (minimum remediation), 'captcha' or 'ban' (maximum remediation).
+       // Default to 'captcha'.
        'fallback_remediation'=> 'captcha',
 
        // Optional. Set the duration we keep in cache the fact that an IP is clean. In seconds. Defaults to 5.
        'cache_expiration_for_clean_ip'=> '5',
 
        // Optional. Set the duration we keep in cache the fact that an IP is bad. In seconds. Defaults to 20.
        'cache_expiration_for_bad_ip'=> '20',
+       
+       // Optional
+       'hide_mentions' => false
+       
+       // Optional. Settings for geolocation remediation (i.e. country based remediation).
+       'geolocation' => [
+                     // Optional. true to enable remediation based on country.
+                     // Default to false.
+                     'enabled' => false,
+                     // Optional. Geolocation system. Only 'maxmind' is available for the moment. 
+                     // Default to 'maxmind'
+                     'type' => 'maxmind',
+                     // Optional. true to store the geolocalized country in session
+                     // Setting true will avoid multiple call to the geolocalized system (e.g. maxmind database)
+                     // Default to true.
+                     'save_in_session' => true,
+                     // Optional. MaxMind settings
+                     'maxmind' => [
+                               // Optional. Select from 'country' or 'city'.
+                               // These are the two available MaxMind database types.
+                               // Default to 'country'
+                               'database_type' => 'country',
+                               // Optional. Absolute path to the MaxMind database (mmdb file).
+                               'database_path' => '/some/path/GeoLite2-Country.mmdb',
+                     ]
+        ]       
    ]
-   $cacheAdapter = (...)
-   $bouncer = new Bouncer($cacheAdapter);
+   $bouncer = new Bouncer();
    $bouncer->configure($config);
 ```

examples/auto-prepend/scripts/bounce-via-auto-prepend.php

@@ -7,7 +7,5 @@
 
 $bounce = new StandAloneBounce();
 
-$bounce->setDebug($crowdSecStandaloneBouncerConfig['debug_mode']??false);
-$bounce->setDisplayErrors($crowdSecStandaloneBouncerConfig['display_errors'] ?? false);
 $bounce->init($crowdSecStandaloneBouncerConfig);
 $bounce->safelyBounce();

examples/auto-prepend/scripts/cache-actions.php

@@ -8,8 +8,6 @@
 if (isset($_GET['action']) && in_array($_GET['action'],['refresh', 'clear', 'prune', 'warm-up'])) {
     $action = $_GET['action'];
     $bounce = new StandAloneBounce();
-    $bounce->setDebug($crowdSecStandaloneBouncerConfig['debug_mode']??false);
-    $bounce->setDisplayErrors($crowdSecStandaloneBouncerConfig['display_errors'] ?? false);
     $bounce->init($crowdSecStandaloneBouncerConfig);
     $bouncer = $bounce->getBouncerInstance();
     switch ($action) {

examples/auto-prepend/settings.example.php

@@ -24,7 +24,6 @@
     'fallback_remediation' => Constants::REMEDIATION_CAPTCHA,
 
     'hide_mentions' => false,
-    'trust_ip_forward' => '',
     'trust_ip_forward_array' => [],
 
     'theme_color_text_primary' => 'black',

examples/live-mode/full-example-live-mode.php

@@ -47,7 +47,7 @@
     'api_url' => $apiUrl,
     'api_user_agent' => 'MyCMS CrowdSec Bouncer/1.0.0',
     'api_timeout' => 1,
-    'live_mode' => true,
+    'stream_mode' => false,
     'max_remediation_level' => 'ban',
     'cache_expiration_for_clean_ip' => 2,
     'cache_expiration_for_bad_ip' => 30,

src/AbstractBounce.php

@@ -6,13 +6,15 @@
 require_once __DIR__.'/templates/access-forbidden.php';
 
 use Bramus\Monolog\Formatter\ColoredLineFormatter;
+use ErrorException;
 use Exception;
 use IPLib\Factory;
 use Monolog\Formatter\LineFormatter;
 use Monolog\Handler\RotatingFileHandler;
 use Monolog\Logger;
 use Psr\Cache\InvalidArgumentException;
 use Psr\Log\LoggerInterface;
+use Symfony\Component\Cache\Exception\CacheException;
 
 /**
  * The class that apply a bounce.
@@ -41,14 +43,19 @@ abstract class AbstractBounce
     /** @var Bouncer */
     protected $bouncer;
 
+    protected function getBoolSettings(string $name): bool
+    {
+        return $this->settings[$name]??false;
+    }
+
     protected function getStringSettings(string $name): string
     {
-        return $this->settings[$name];
+        return $this->settings[$name] ?? '';
     }
 
     protected function getArraySettings(string $name): array
     {
-        return $this->settings[$name];
+        return $this->settings[$name] ?? [];
     }
 
     /**
@@ -193,6 +200,11 @@ protected function clearCaptchaSessionContext()
         $this->unsetSessionVariable('crowdsec_captcha_resolution_failed');
     }
 
+    /**
+     * @throws ErrorException
+     * @throws InvalidArgumentException
+     * @throws CacheException
+     */
     protected function handleCaptchaResolutionForm(string $ip)
     {
         // Early return if no captcha has to be resolved or if captcha already resolved.
@@ -237,6 +249,11 @@ protected function handleCaptchaResolutionForm(string $ip)
         }
     }
 
+    /**
+     * @throws ErrorException
+     * @throws InvalidArgumentException
+     * @throws CacheException
+     */
     protected function handleCaptchaRemediation($ip)
     {
         // Check captcha resolution form
@@ -259,6 +276,11 @@ protected function handleCaptchaRemediation($ip)
         }
     }
 
+    /**
+     * @throws CacheException
+     * @throws ErrorException
+     * @throws InvalidArgumentException
+     */
     protected function handleRemediation(string $remediation, string $ip)
     {
         if (Constants::REMEDIATION_CAPTCHA !== $remediation && null !== $this->getSessionVariable('crowdsec_captcha_has_to_be_resolved')) {

src/ApiCache.php

@@ -48,7 +48,7 @@ class ApiCache
     private $geolocation;
 
     /** @var bool */
-    private $liveMode = false;
+    private $streamMode = false;
 
     /**
      * @var int
@@ -101,7 +101,7 @@ public function __construct(LoggerInterface $logger, ApiClient $apiClient = null
     /**
      * Configure this instance.
      *
-     * @param bool   $liveMode                  If we use the live mode (else we use the stream mode)
+     * @param bool   $streamMode                If we use the stream mode (else we use the live mode)
      * @param string $apiUrl                    The URL of the LAPI
      * @param int    $timeout                   The timeout well calling LAPI
      * @param string $userAgent                 The user agent to use when calling LAPI
@@ -114,7 +114,7 @@ public function __construct(LoggerInterface $logger, ApiClient $apiClient = null
      * @throws InvalidArgumentException
      */
     public function configure(
-        bool $liveMode,
+        bool $streamMode,
         string $apiUrl,
         int $timeout,
         string $userAgent,
@@ -124,7 +124,7 @@ public function configure(
         string $fallbackRemediation,
         array $geolocConfig = []
     ): void {
-        $this->liveMode = $liveMode;
+        $this->streamMode = $streamMode;
         $this->cacheExpirationForCleanIp = $cacheExpirationForCleanIp;
         $this->cacheExpirationForBadIp = $cacheExpirationForBadIp;
         $this->fallbackRemediation = $fallbackRemediation;
@@ -136,7 +136,7 @@ public function configure(
         $this->logger->debug('', [
             'type' => 'API_CACHE_INIT',
             'adapter' => \get_class($this->adapter),
-            'mode' => ($liveMode ? 'live' : 'stream'),
+            'mode' => ($streamMode ? 'stream' : 'live'),
             'exp_clean_ips' => $cacheExpirationForCleanIp,
             'exp_bad_ips' => $cacheExpirationForBadIp,
             'warmed_up' => ($this->warmedUp ? 'true' : 'false'),
@@ -295,7 +295,7 @@ private function formatRemediationFromDecision(?array $decision): array
     {
         if (!$decision) {
             $duration = time() + $this->cacheExpirationForCleanIp;
-            if (!$this->liveMode) {
+            if ($this->streamMode) {
                 // In stream mode we consider a clean IP forever... until the next resync.
                 $duration = 315360000; // in this case, forever is 10 years as PHP_INT_MAX will cause trouble with the Memcached Adapter (int to float unwanted conversion)
             }
@@ -306,7 +306,7 @@ private function formatRemediationFromDecision(?array $decision): array
         $duration = self::parseDurationToSeconds($decision['duration']);
 
         // Don't set a max duration in stream mode to avoid bugs. Only the stream update has to change the cache state.
-        if ($this->liveMode) {
+        if (!$this->streamMode) {
             $duration = min($this->cacheExpirationForBadIp, $duration);
         }
 
@@ -659,7 +659,7 @@ private function miss(string $value, string $cacheScope): string
     {
         $decisions = [];
         $cacheKey = $this->getCacheKey($cacheScope, $value);
-        if ($this->liveMode) {
+        if (!$this->streamMode) {
             if (Constants::SCOPE_IP === $cacheScope) {
                 $this->logger->debug('', ['type' => 'DIRECT_API_CALL', 'ip' => $value]);
                 $decisions = $this->apiClient->getFilteredDecisions(['ip' => $value]);
@@ -694,8 +694,10 @@ private function hit(string $ip): string
     }
 
     /**
+     * @param string $cacheScope
      * @param $value
      *
+     * @return string
      * @throws InvalidArgumentException
      * @throws Exception
      */
@@ -738,7 +740,7 @@ public function get(AddressInterface $address): string
         $ip = $address->toString();
         $this->logger->debug('', ['type' => 'START_IP_CHECK', 'ip' => $ip]);
 
-        if (!$this->liveMode && !$this->warmedUp) {
+        if ($this->streamMode && !$this->warmedUp) {
             throw new BouncerException('CrowdSec Bouncer configured in "stream" mode. Please warm the cache up before trying to access it.');
         }
 

src/Bouncer.php

@@ -73,7 +73,7 @@ public function configure(array $config): void
 
         // Configure Api Cache.
         $this->apiCache->configure(
-            $this->config['live_mode'],
+            $this->config['stream_mode'],
             $this->config['api_url'],
             $this->config['api_timeout'],
             $this->config['api_user_agent'],

src/Configuration.php

@@ -32,8 +32,24 @@ public function getConfigTreeBuilder(): TreeBuilder
                 ->scalarNode('api_url')->defaultValue(Constants::CAPI_URL)->end()
                 ->scalarNode('api_user_agent')->defaultValue(Constants::BASE_USER_AGENT)->end()
                 ->integerNode('api_timeout')->defaultValue(Constants::API_TIMEOUT)->end()
-                ->booleanNode('live_mode')->defaultValue(true)->end()
+                ->booleanNode('stream_mode')->defaultValue(false)->end()
+                ->booleanNode('debug_mode')->defaultValue(false)->end()
+                ->booleanNode('display_errors')->defaultValue(false)->end()
+                ->booleanNode('hide_mentions')->defaultValue(false)->end()
                 ->scalarNode('forced_test_ip')->end()
+                ->scalarNode('log_directory_path')->end()
+                ->enumNode('bouncing_level')
+                    ->values([Constants::BOUNCING_LEVEL_DISABLED, Constants::BOUNCING_LEVEL_NORMAL, Constants::BOUNCING_LEVEL_FLEX])
+                    ->defaultValue(Constants::BOUNCING_LEVEL_NORMAL)
+                ->end()
+                ->enumNode('cache_system')
+                    ->values([Constants::CACHE_SYSTEM_PHPFS, Constants::CACHE_SYSTEM_REDIS, Constants::CACHE_SYSTEM_MEMCACHED])
+                    ->defaultValue(Constants::CACHE_SYSTEM_PHPFS)
+                ->end()
+                ->scalarNode('fs_cache_path')->end()
+                ->scalarNode('redis_dsn')->end()
+                ->scalarNode('memcached_dsn')->end()
+                ->arrayNode('trust_ip_forward_array')->end()
                 ->enumNode('max_remediation_level')
                     ->values(Constants::ORDERED_REMEDIATIONS)
                     ->defaultValue(Constants::REMEDIATION_BAN)