return result for cache update methods

Author: mobula9

docs/api/ApiCache.md

@@ -16,6 +16,7 @@ The cache mecanism to store every decisions from LAPI/CAPI. Symfony Cache compon
 |[get](#apicacheget)|Request the cache for the specified IP.|
 |[prune](#apicacheprune)||
 |[pullUpdates](#apicachepullupdates)|Used in stream mode only.|
+|[warmUp](#apicachewarmup)|Used in stream mode only.|
 
 
 
@@ -163,7 +164,36 @@ TODO P2 test for overlapping decisions strategy (ex: max expires)
 
 **Return Values**
 
-`void`
+`array`
+
+> number of deleted and new decisions.
+
+
+<hr />
+
+
+### ApiCache::warmUp  
+
+**Description**
+
+```php
+public warmUp (void)
+```
+
+Used in stream mode only. 
+
+Warm the cache up.  
+Used when the stream mode has just been activated. 
+
+**Parameters**
+
+`This function has no parameters.`
+
+**Return Values**
+
+`int`
+
+> number of decisions added.
 
 
 <hr />

docs/api/Bouncer.md

@@ -11,14 +11,19 @@ The main Class of this package. This is the first entry point of any PHP Bouncer
 | Name | Description |
 |------|-------------|
 |[__construct](#bouncer__construct)||
+|[buildCaptchaCouple](#bouncerbuildcaptchacouple)||
+|[checkCaptcha](#bouncercheckcaptcha)||
 |[clearCache](#bouncerclearcache)|This method clear the full data in cache.|
 |[configure](#bouncerconfigure)|Configure this instance.|
-|[getAccessForbiddenHtmlTemplate](#getAccessForbiddenHtmlTemplate)|Returns a default "CrowdSec 403" HTML template to display to a web browser using a banned IP.|
+|[getAccessForbiddenHtmlTemplate](#bouncergetaccessforbiddenhtmltemplate)|Returns a default "CrowdSec 403" HTML template to display to a web browser using a banned IP.|
+|[getCaptchaHtmlTemplate](#bouncergetcaptchahtmltemplate)|Returns a default "CrowdSec Captcha" HTML template to display to a web browser using a captchable IP.|
+|[getLogger](#bouncergetlogger)|Returns the logger instance.|
 |[getRemediationForIp](#bouncergetremediationforip)|Get the remediation for the specified IP. This method use the cache layer.|
 |[loadPaginatedBlocklistFromCache](#bouncerloadpaginatedblocklistfromcache)|Browse the remediations cache.|
 |[loadPaginatedLogs](#bouncerloadpaginatedlogs)|Browse the bouncer technical logs.|
 |[pruneCache](#bouncerprunecache)|This method prune the cache: it removes all the expired cache items.|
 |[refreshBlocklistCache](#bouncerrefreshblocklistcache)|Used in stream mode only.|
+|[warmBlocklistCacheUp](#bouncerwarmblocklistcacheup)|Used in stream mode only.|
 
 
 
@@ -35,6 +40,54 @@ The main Class of this package. This is the first entry point of any PHP Bouncer
 
 
 
+**Parameters**
+
+`This function has no parameters.`
+
+**Return Values**
+
+`void`
+
+
+<hr />
+
+
+### Bouncer::buildCaptchaCouple  
+
+**Description**
+
+```php
+ buildCaptchaCouple (void)
+```
+
+ 
+
+ 
+
+**Parameters**
+
+`This function has no parameters.`
+
+**Return Values**
+
+`void`
+
+
+<hr />
+
+
+### Bouncer::checkCaptcha  
+
+**Description**
+
+```php
+ checkCaptcha (void)
+```
+
+ 
+
+ 
+
 **Parameters**
 
 `This function has no parameters.`
@@ -95,18 +148,66 @@ Configure this instance.
 <hr />
 
 
-### Bouncer::get403Template  
+### Bouncer::getAccessForbiddenHtmlTemplate  
 
 **Description**
 
 ```php
-public getAccessForbiddenHtmlTemplate (void)
+public static getAccessForbiddenHtmlTemplate (void)
 ```
 
 Returns a default "CrowdSec 403" HTML template to display to a web browser using a banned IP. 
 
 
 
+**Parameters**
+
+`This function has no parameters.`
+
+**Return Values**
+
+`void`
+
+
+<hr />
+
+
+### Bouncer::getCaptchaHtmlTemplate  
+
+**Description**
+
+```php
+public static getCaptchaHtmlTemplate (void)
+```
+
+Returns a default "CrowdSec Captcha" HTML template to display to a web browser using a captchable IP. 
+
+ 
+
+**Parameters**
+
+`This function has no parameters.`
+
+**Return Values**
+
+`void`
+
+
+<hr />
+
+
+### Bouncer::getLogger  
+
+**Description**
+
+```php
+public getLogger (void)
+```
+
+Returns the logger instance. 
+
+ 
+
 **Parameters**
 
 `This function has no parameters.`
@@ -236,7 +337,35 @@ This method should be called periodically (ex: crontab) in a asynchronous way to
 
 **Return Values**
 
-`void`
+`array`
+
+> number of deleted and new decisions.
+
+
+<hr />
+
+
+### Bouncer::warmBlocklistCacheUp  
+
+**Description**
+
+```php
+public warmBlocklistCacheUp (void)
+```
+
+Used in stream mode only. 
+
+This method should be called only to force a cache warm up. 
+
+**Parameters**
+
+`This function has no parameters.`
+
+**Return Values**
+
+`int`
+
+> number of decisions added.
 
 
 <hr />

src/ApiCache.php

@@ -313,6 +313,8 @@ public function clear(): bool
     {
         $cleared = $this->adapter->clear();
         $this->warmedUp = false;
+        $this->defferUpdateCacheConfig(['warmed_up' => $this->warmedUp]);
+        $this->adapter->commit();
         $this->logger->info(null, ['type' => 'CACHE_CLEARED']);
         return $cleared;
     }
@@ -321,10 +323,15 @@ public function clear(): bool
      * Used in stream mode only.
      * Warm the cache up.
      * Used when the stream mode has just been activated.
+     * 
+     * @return int number of decisions added.
      *
      */
-    public function warmUp(): void
+    public function warmUp(): int
     {
+        if ($this->warmedUp) {
+            $this->clear();
+        }
         $this->logger->debug(null, ['type' => 'START_CACHE_WARMUP']);
         $startup = true;
         $decisionsDiff = $this->apiClient->getStreamedDecisions($startup);
@@ -333,16 +340,20 @@ public function warmUp(): void
         $nbNew = 0;
         if ($newDecisions) {
             $this->warmedUp = $this->saveRemediations($newDecisions);
+            $this->defferUpdateCacheConfig(['warmed_up' => $this->warmedUp]);
+            $this->adapter->commit();
             if (!$this->warmedUp) {
                 throw new BouncerException("Unable to warm the cache up");
             }
             $nbNew = count($newDecisions);
         }
 
         // Store the fact that the cache has been warmed up.
-        $this->logger->info(null, ['type' => 'CACHE_WARMED_UP', 'added_decisions' => $nbNew]);
         $this->defferUpdateCacheConfig(['warmed_up' => true]);
+
         $this->adapter->commit();
+        $this->logger->info(null, ['type' => 'CACHE_WARMED_UP', 'added_decisions' => $nbNew]);
+        return $nbNew;
     }
 
     /**
@@ -351,12 +362,14 @@ public function warmUp(): void
      * Used for the stream mode when we have to update the remediations list.
      * 
      * TODO P2 test for overlapping decisions strategy (ex: max expires)
+     * 
+     * @return array number of deleted and new decisions.
+     * 
      */
-    public function pullUpdates(): void
+    public function pullUpdates(): array
     {
         if (!$this->warmedUp) {
-            $this->warmUp();
-            return;
+            return ['deleted' => 0, 'new' => $this->warmUp()];
         }
 
         $this->logger->debug(null, ['type' => 'START_CACHE_UPDATE']);
@@ -376,7 +389,8 @@ public function pullUpdates(): void
             $nbNew = count($newDecisions);
         }
 
-        $this->logger->debug(null, ['type' => 'CACHE_UPDATED', 'old' => $nbDeleted, 'new' => $nbNew]);
+        $this->logger->debug(null, ['type' => 'CACHE_UPDATED', 'deleted' => $nbDeleted, 'new' => $nbNew]);
+        return ['deleted' => $nbDeleted, 'new' => $nbNew];
     }
 
     /**

src/Bouncer.php

@@ -142,19 +142,23 @@ public static function getCaptchaHtmlTemplate(bool $error, string $captchaImageS
     /**
      * Used in stream mode only.
      * This method should be called only to force a cache warm up.
+     * 
+     * @return int number of decisions added.
      */
-    public function warmBlocklistCacheUp(): void
+    public function warmBlocklistCacheUp(): int
     {
-        $this->apiCache->warmUp();
+        return $this->apiCache->warmUp();
     }
 
     /**
      * Used in stream mode only.
      * This method should be called periodically (ex: crontab) in a asynchronous way to update the bouncer cache.
+     * 
+     * @return array number of deleted and new decisions.
      */
-    public function refreshBlocklistCache(): void
+    public function refreshBlocklistCache(): array
     {
-        $this->apiCache->pullUpdates();
+        return $this->apiCache->pullUpdates();
     }
 
     /**
@@ -170,7 +174,7 @@ public function clearCache(): bool
      */
     public function pruneCache(): bool
     {
-        return $this->apiCache->clear();
+        return $this->apiCache->prune();
     }
 
     /**