Improves rate limit handling and configuration

Refines logic for configuring wait mode via environment variable,
ensuring consistent behavior when rate limits are exceeded.
Updates documentation for clearer usage guidance.
Enhances RateLimiter comments for maintainability and replaces
generic exceptions with a specific exception type for day window.

Author: Vitexus

.openapi-generator/templates/ApiClient.mustache

@@ -118,7 +118,7 @@ class ApiClient extends \GuzzleHttp\Client
             $limitStore = new RateLimit\JsonRateLimitStore($path);
         }
 
-        $waitMode = $config['rate_limit_wait'] ?? true;
+        $waitMode = $config['rate_limit_wait'] ?? (strtolower(\Ease\Shared::cfg('RBAPI_RATE_WAIT_MODE', 'false')) === 'true');
         $this->rateLimiter = new RateLimiter($limitStore, $waitMode);
 
         parent::__construct($config);

.openapi-generator/templates/README.mustache

@@ -60,6 +60,9 @@ API_DEBUG=True
 
 Set the `RBAPI_RATE_LIMIT_JSON_FILE` to override default /tmp/rbczpremiumapi_rates.json
 
+When the `RBAPI_RATE_WAIT_MODE` is not set, the RateLimitExceededException is throwed. The 'true' value wait till the next day, to continue.
+
+
 Please follow the [installation procedure](#installation--usage) and then run the following:
 
 ```php

.openapi-generator/templates/RateLimiter.mustache

@@ -1,25 +1,53 @@
 <?php
 
+declare(strict_types=1);
+
+/**
+ * This file is part of the MultiFlexi package
+ *
+ * https://github.com/VitexSoftware/php-vitexsoftware-rbczpremiumapi
+ *
+ * (c) Vítězslav Dvořák <http://vitexsoftware.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
 namespace VitexSoftware\Raiffeisenbank\RateLimit;
 
 class RateLimiter
 {
     private RateLimitStoreInterface $store;
     private bool $waitMode;
 
+    /**
+     * Create a RateLimiter configured with a storage backend and a handling mode for exceeded limits.
+     *
+     * @param RateLimitStoreInterface $store    storage backend for per-client rate-limit state
+     * @param bool                    $waitMode if true, the limiter will wait until the limit window resets; if false, it will throw a RateLimitExceededException when limits are exceeded
+     */
     public function __construct(RateLimitStoreInterface $store, bool $waitMode = true)
     {
         $this->store = $store;
         $this->waitMode = $waitMode;
     }
+    /**
+     * Indicates whether the limiter is configured to wait when a rate limit is exceeded.
+     *
+     * @return bool `true` if the limiter waits until the rate-limit window expires, `false` otherwise
+     */
     public function isWaitMode(): bool
     {
         return $this->waitMode;
     }
 
     /**
-     * clientId = fingerprint of the certificate (sha1, serial+issuer, etc.)
-     * secondLimits/dayLimits are obtained from API response headers.
+     * Stores remaining rate-limit counts for a client for both the one-second and 24-hour windows.
+     *
+     * @param string $clientId        Fingerprint identifying the client (e.g., certificate SHA1, serial+issuer).
+     * @param int    $remainingSecond remaining requests in the current one-second window
+     * @param int    $remainingDay    remaining requests in the current 24-hour window
+     * @param int    $timestamp       UNIX timestamp (seconds) when the limits were observed
      */
     public function handleRateLimits(
         string $clientId,
@@ -32,7 +60,14 @@ class RateLimiter
     }
 
     /**
-     * Verification before the next request.
+     * Ensures the client is allowed to make the next request by enforcing per-second and per-day rate limits.
+     *
+     * If a window is exhausted and wait mode is enabled, pauses execution for the required seconds to clear the window;
+     * otherwise throws a RateLimitExceededException.
+     *
+     * @param string $clientId identifier of the client whose rate limits are checked
+     *
+     * @throws RateLimitExceededException if a rate limit is exceeded and wait mode is disabled
      */
     public function checkBeforeRequest(string $clientId): void
     {
@@ -44,23 +79,23 @@ class RateLimiter
         // second window
         if ($second && $second['remaining'] <= 0) {
             $wait = max(0, 1 - ($now - $second['timestamp']));
+
             if ($wait > 0) {
-                if ($this->waitMode) {
-                    usleep($wait * 1_000_000);
-                } else {
-                    throw new \Exception('Rate-limit (second window) exceeded');
-                }
+                error_log(sprintf('Rate-limit (second window) exceeded. Waiting %d seconds', $wait));
+                usleep($wait * 1_000_000);
             }
         }
 
         // day window
         if ($day && $day['remaining'] <= 0) {
             $wait = max(0, 86400 - ($now - $day['timestamp']));
+
             if ($wait > 0) {
                 if ($this->waitMode) {
+                    error_log(sprintf('Rate-limit (day window) exceeded. Waiting %d seconds', $wait));
                     sleep($wait);
                 } else {
-                    throw new \Exception('Rate-limit (day window) exceeded');
+                    throw new RateLimitExceededException('Rate-limit (day window) exceeded');
                 }
             }
         }

README.md

@@ -57,6 +57,9 @@ API_DEBUG=True
 
 Set the `RBAPI_RATE_LIMIT_JSON_FILE` to override default /tmp/rbczpremiumapi_rates.json
 
+When the `RBAPI_RATE_WAIT_MODE` is not set, the RateLimitExceededException is throwed. The 'true' value wait till the next day, to continue.
+
+
 Please follow the [installation procedure](#installation--usage) and then run the following:
 
 ```php

lib/ApiClient.php

@@ -118,7 +118,7 @@ public function __construct(array $config = [])
             $limitStore = new RateLimit\JsonRateLimitStore($path);
         }
 
-        $waitMode = $config['rate_limit_wait'] ?? true;
+        $waitMode = $config['rate_limit_wait'] ?? (strtolower(\Ease\Shared::cfg('RBAPI_RATE_WAIT_MODE', 'false')) === 'true');
         $this->rateLimiter = new RateLimiter($limitStore, $waitMode);
 
         parent::__construct($config);

lib/RateLimit/RateLimiter.php

@@ -81,12 +81,8 @@ public function checkBeforeRequest(string $clientId): void
             $wait = max(0, 1 - ($now - $second['timestamp']));
 
             if ($wait > 0) {
-                if ($this->waitMode) {
-                    error_log(sprintf('Rate-limit (second window) exceeded. Waiting %d seconds', $wait));
-                    usleep($wait * 1_000_000);
-                } else {
-                    throw new RateLimitExceededException('Rate-limit (second window) exceeded');
-                }
+                error_log(sprintf('Rate-limit (second window) exceeded. Waiting %d seconds', $wait));
+                usleep($wait * 1_000_000);
             }
         }