Merge pull request #25 from VitexSoftware/5-support-rate-limiting-headers

Adds rate limiting mechanism with configurable storage

Author: Vitexus

.openapi-generator/config.yaml

@@ -26,3 +26,33 @@ files:
       destinationFilename: Transactor.php
   bootstrap.php:
       folder: test
+  RateLimiter.mustache:
+    folder: lib/RateLimit
+    destinationFilename: RateLimiter.php
+  RateLimitStoreInterface.mustache:
+    folder: lib/RateLimit
+    destinationFilename: RateLimitStoreInterface.php
+  SqlDialect.mustache:
+    folder: lib/RateLimit
+    destinationFilename: SqlDialect.php
+  RateLimitMode.mustache:
+    folder: lib/RateLimit
+    destinationFilename: RateLimitMode.php
+  RateLimitExceededException.mustache:
+    folder: lib/RateLimit
+    destinationFilename: RateLimitExceededException.php
+  PdoRateLimitStore.mustache:
+    folder: lib/RateLimit
+    destinationFilename: PdoRateLimitStore.php
+  JsonRateLimitStore.mustache:
+    folder: lib/RateLimit
+    destinationFilename: JsonRateLimitStore.php
+  RateLimiterTest.mustache:
+    folder: test/RateLimit
+    destinationFilename: RateLimiterTest.php
+  RateLimitStoreInterfaceTest.mustache:
+    folder: test/RateLimit
+    destinationFilename: RateLimitStoreInterfaceTest.php
+  SqlDialectTest.mustache:
+    folder: test/RateLimit
+    destinationFilename: SqlDialectTest.php

.openapi-generator/templates/ApiClient.mustache

@@ -1,95 +1,120 @@
 <?php
 
+declare(strict_types=1);
+
 /**
- * 
+ * This file is part of the MultiFlexi package
+ *
+ * https://github.com/VitexSoftware/php-vitexsoftware-rbczpremiumapi
  *
- * @author    Vitex <vitex@hippy.cz>
- * @copyright 2023 Vitex@hippy.cz (G)
- * 
- * PHP 8
+ * (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;
 
+use VitexSoftware\Raiffeisenbank\RateLimit\RateLimiter;
+use VitexSoftware\Raiffeisenbank\RateLimit\RateLimitExceededException;
+
 /**
- * Description of ApiClient
+ * Description of ApiClient.
  *
  * @author vitex
  */
 class ApiClient extends \GuzzleHttp\Client
 {
-
     /**
      * ClientID obtained from Developer Portal - when you registered your app with us.
-     * @var string
      */
     protected string $xIBMClientId = '';
 
     /**
-     * the end IP address of the client application (no server) in IPv4 or IPv6 
-     * format. If the bank client (your user) uses a browser by which he 
-     * accesses your server app, we need to know the IP address of his browser. 
-     * Always provide the closest IP address to the real end-user possible. 
-     * (optional)
-     * 
-     * @var string
+     * the end IP address of the client application (no server) in IPv4 or IPv6
+     * format. If the bank client (your user) uses a browser by which he
+     * accesses your server app, we need to know the IP address of his browser.
+     * Always provide the closest IP address to the real end-user possible.
+     * (optional).
      */
     protected string $pSUIPAddress = '';
 
     /**
      * Use mocking for api calls ?
-     * @var boolean
      */
     protected bool $mockMode = false;
+    private RateLimiter $rateLimiter;
 
     /**
-     * @inheritDoc
-     * 
-     * $config['clientid'] - obtained from Developer Portal - when you registered your app with us.
-     * $config['cert'] = ['/path/to/cert.p12','certificat password']
-     * $config['clientpubip'] = the closest IP address to the real end-user
-     * $config['mocking'] = true to use /rbcz/premium/mock/* endpoints
-     * 
-     * @param array $config 
-     * @throws \Exception CERT_FILE is not set
-     * @throws \Exception CERT_PASS is not set
+     * Initialize the API client with configuration, certificate validation, and a rate limiter.
+     *
+     * Accepted $config keys:
+     * - 'clientid': client ID from the Developer Portal.
+     * - 'cert': array with [pathToP12, password]; when omitted, CERT_FILE and CERT_PASS configuration values are used.
+     * - 'clientpubip': client public IP (nearest to the end user).
+     * - 'mocking': bool to enable mock endpoints.
+     * - 'debug': debug flag.
+     *
+     * @param array $config client configuration
+     *                      - 'clientid': client ID from Developer Portal
+     *                      - 'cert': [path, password]
+     *                      - 'clientpubip': client public IP
+     *                      - 'mocking': bool
+     *                      - 'debug': bool
+     *                      - 'rate_limit_store': RateLimitStoreInterface instance (optional)
+     *                      - 'rate_limit_wait': bool - wait when limited (default true)
+     *
+     * @throws \Exception if certificate file path (CERT_FILE) is not provided
+     * @throws \Exception if certificate password (CERT_PASS) is not provided
      */
     public function __construct(array $config = [])
     {
-        if (array_key_exists('clientid', $config) === false) {
+        if (\array_key_exists('clientid', $config) === false) {
             $this->xIBMClientId = \Ease\Shared::cfg('XIBMCLIENTID');
         } else {
             $this->xIBMClientId = $config['clientid'];
         }
 
-        if (array_key_exists('cert', $config) === false) {
+        if (\array_key_exists('cert', $config) === false) {
             $config['cert'] = [\Ease\Shared::cfg('CERT_FILE'), \Ease\Shared::cfg('CERT_PASS')];
+
             if (empty($config['cert'][0])) {
                 throw new \Exception('Certificate (CERT_FILE) not specified');
             }
+
             if (empty($config['cert'][1])) {
                 throw new \Exception('Certificate password (CERT_PASS) not specified');
             }
         }
 
-        if (array_key_exists('debug', $config) === false) {
+        if (\array_key_exists('debug', $config) === false) {
             $config['debug'] = \Ease\Shared::cfg('API_DEBUG', false);
-        } 
-        
-        if (array_key_exists('clientpubip', $config)){
+        }
+
+        if (\array_key_exists('clientpubip', $config)) {
             $this->pSUIPAddress = $config['clientpubip'];
         }
 
-        if (array_key_exists('mocking', $config)){
-            $this->mockMode = boolval($config['mocking']);
+        if (\array_key_exists('mocking', $config)) {
+            $this->mockMode = (bool) $config['mocking'];
+        }
+
+        if (isset($config['rate_limit_store'])) {
+            $limitStore = $config['rate_limit_store'];
+        } else {
+            $path = $config['rate_limit_path'] ?? sys_get_temp_dir().'/rbczpremiumapi_rates.json';
+            $limitStore = new RateLimit\JsonRateLimitStore($path);
         }
-        
+
+        $waitMode = $config['rate_limit_wait'] ?? true;
+        $this->rateLimiter = new RateLimiter($limitStore, $waitMode);
+
         parent::__construct($config);
     }
 
     /**
-     * ClientID obtained from Developer Portal
-     * 
+     * ClientID obtained from Developer Portal.
+     *
      * @return string
      */
     public function getXIBMClientId()
@@ -98,102 +123,158 @@ class ApiClient extends \GuzzleHttp\Client
     }
 
     /**
-     * Keep user public IP here
-     * 
+     * Keep user public IP here.
+     *
      * @return string
      */
     public function getpSUIPAddress()
     {
         return $this->pSUIPAddress;
-    } 
+    }
 
     /**
      * Use mocking uri for api calls ?
-     * 
-     * @return boolean
+     *
+     * @return bool
      */
     public function getMockMode()
     {
         return $this->mockMode;
     }
-    
+
     /**
-     * Obtain Your current Public IP
-     * 
+     * Obtain Your current Public IP.
+     *
      * @deprecated since version 0.1 - Do not use in production Environment!
-     * 
+     *
      * @return string
      */
     public static function getPublicIP()
     {
         $curl = curl_init();
-        curl_setopt($curl, CURLOPT_URL, "http://httpbin.org/ip");
-        curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
+        curl_setopt($curl, \CURLOPT_URL, 'http://httpbin.org/ip');
+        curl_setopt($curl, \CURLOPT_RETURNTRANSFER, 1);
         $output = curl_exec($curl);
         curl_close($curl);
         $ip = json_decode($output, true);
+
         return $ip['origin'];
     }
-    
+
     /**
-     * Source Identifier
-     * 
+     * Source Identifier.
+     *
      * @deprecated since version 0.1 - Do not use in production Environment!
-     * 
+     *
      * @return string
      */
     public static function sourceString()
     {
-        return substr(__FILE__ . '@' . gethostname(), -50);
+        return substr(__FILE__.'@'.gethostname(), -50);
     }
 
     /**
-     * Try to check certificate readibilty
-     * 
-     * @throws Exception - Certificate file not found
-     * 
-     * @param string  $certFile path to certificate
-     * @param boolean $die      throw exception or return false ?
-     * 
-     * @return boolean certificate file
+     * Try to check certificate readibilty.
+     *
+     * @param string $certFile path to certificate
+     * @param bool   $die      throw exception or return false ?
+     *
+     * @throws \Exception - Certificate file not found
+     *
+     * @return bool certificate file
      */
     public static function checkCertificatePresence(string $certFile, bool $die = false): bool
     {
         $found = false;
+
         if ((file_exists($certFile) === false) || (is_readable($certFile) === false)) {
-            $errMsg = 'Cannot read specified certificate file: ' . $certFile;
-            fwrite(STDERR, $errMsg . PHP_EOL);
-            if ($die){
+            $errMsg = 'Cannot read specified certificate file: '.$certFile;
+            fwrite(\STDERR, $errMsg.\PHP_EOL);
+
+            if ($die) {
                 throw new \Exception($errMsg);
             }
         } else {
             $found = true;
         }
-        return  $found;
+
+        return $found;
     }
-    
-    public static function checkCertificate($certFile,$password): bool {
-        return  self::checkCertificatePresence($certFile) && self::checkCertificatePassword($certFile,$password);
+
+    public static function checkCertificate(string $certFile, string $password): bool
+    {
+        return self::checkCertificatePresence($certFile) && self::checkCertificatePassword($certFile, $password);
     }
-    
-    public static function checkCertificatePassword(string $certFile, string $password): bool {
+
+    public static function checkCertificatePassword(string $certFile, string $password): bool
+    {
         $certContent = file_get_contents($certFile);
+
         if (openssl_pkcs12_read($certContent, $certs, $password) === false) {
             fwrite(\STDERR, 'Cannot read PKCS12 certificate file: '.$certFile.\PHP_EOL);
-            exit(1);
+
+            throw new \Exception('Cannot read PKCS12 certificate file: '.$certFile);
         }
+
         return true;
     }
-    
-    
+
     /**
-     * Request Identifier
-     * 
-     * @deprecated since version 0.1 - Do not use in production Environment!
-     * 
-     * @return string
+     * Produce a short request identifier used for diagnostics and testing.
+     *
+     * @deprecated since version 0.1 — Do not use in production environments.
+     *
+     * @return string the generated request identifier composed from a source token and the current timestamp, truncated to at most 59 characters
      */
-    public static function getxRequestId() {
-        return substr(self::sourceString() . '#' . time(),-59);
+    public static function getxRequestId()
+    {
+        return substr(self::sourceString().'#'.time(), -59);
+    }
+
+    /**
+     * Send an HTTP request while enforcing and updating client rate limits.
+     *
+     * @param \Psr\Http\Message\RequestInterface $request the HTTP request to send
+     * @param array                              $options Request options to apply to the transfer. See \GuzzleHttp\RequestOptions.
+     *
+     * @throws \GuzzleHttp\Exception\GuzzleException
+     * @throws RateLimitExceededException            if the client is rate limited and wait mode is disabled
+     *
+     * @return \Psr\Http\Message\ResponseInterface the HTTP response
+     */
+    public function send(\Psr\Http\Message\RequestInterface $request, array $options = []): \Psr\Http\Message\ResponseInterface
+    {
+        $this->rateLimiter->checkBeforeRequest($this->xIBMClientId);
+
+        $response = parent::send($request, $options);
+
+        $this->updateRateLimitsFromResponse($response);
+
+        $statusCode = $response->getStatusCode();
+
+        if ($statusCode === 429) { // 429 Too Many Requests
+            if ($this->rateLimiter->isWaitMode()) {
+                $this->rateLimiter->checkBeforeRequest($this->xIBMClientId);
+                $response = parent::send($request, $options);
+
+                $this->updateRateLimitsFromResponse($response);
+
+                $statusCode = $response->getStatusCode();
+            } else {
+                throw new RateLimitExceededException('Rate limit exceeded (HTTP 429)');
+            }
+        }
+
+        return $response;
+    }
+
+    private function updateRateLimitsFromResponse(\Psr\Http\Message\ResponseInterface $response): void
+    {
+        if ($response->hasHeader('x-ratelimit-remaining-second') && $response->hasHeader('x-ratelimit-remaining-day')) {
+            $remainingSecond = (int) $response->getHeaderLine('x-ratelimit-remaining-second');
+            $remainingDay = (int) $response->getHeaderLine('x-ratelimit-remaining-day');
+            $timestamp = time();
+            $this->rateLimiter->handleRateLimits($this->xIBMClientId, $remainingSecond, $remainingDay, $timestamp);
+        }
     }
 }