Respect rate limits (#63)

The NitrAPI has a rate limit in place. This metadata will be stored in
the header of each response. To access that, getters can be used. If a
user reaches the rate limit, the NitrAPI refuses all requests. To handle
that, a NitrapiRateLimitException will be thrown, so the client can
handle that case properly.

Author: f0086

lib/Nitrapi/Common/Exceptions/NitrapiRateLimitException.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace Nitrapi\Common\Exceptions;
+
+/**
+ * NitrapiRateLimitException
+ *
+ * The NitrAPI has some rate limits in place, which limits the number of requests
+ * the user can perform in one hour. This limit will be reset every hour, so if
+ * the user ran into a rate limit, it will be released by no later than one hour.
+ * The rate limit besides the reset time and the remaining tasks will be sent as
+ * a header with every response.
+ *
+ * If the rate limit is reached, the NitrAPI refuses all request. If that happen,
+ * we throw this exception, so the client can handle this case properly.
+ *
+ * @package Nitrapi\Common\Exceptions
+ */
+class NitrapiRateLimitException extends NitrapiException {
+    private $rateLimit;
+    private $resetTime;
+
+    public function __construct($rateLimit, $resetTime) {
+        $this->rateLimit = $rateLimit;
+        $this->resetTime = $resetTime;
+
+        parent::__construct("The rate limit ($rateLimit requests in one hour) is exceeded. You need to wait until $resetTime make another request.");
+    }
+
+    public function getRateLimit() {
+        return $this->rateLimit;
+    }
+
+    public function getResetTime() {
+        return $this->resetTime;
+    }
+}

lib/Nitrapi/Common/Http/Client.php

@@ -2,13 +2,15 @@
 
 namespace Nitrapi\Common\Http;
 
+use DateTime;
 use GuzzleHttp\Client as GuzzleClient;
 use GuzzleHttp\Exception\RequestException;
 use GuzzleHttp\Psr7\Response;
 use Nitrapi\Common\Exceptions\NitrapiConcurrencyException;
 use Nitrapi\Common\Exceptions\NitrapiException;
 use Nitrapi\Common\Exceptions\NitrapiHttpErrorException;
 use Nitrapi\Common\Exceptions\NitrapiMaintenanceException;
+use Nitrapi\Common\Exceptions\NitrapiRateLimitException;
 
 class Client extends GuzzleClient
 {
@@ -18,6 +20,14 @@ class Client extends GuzzleClient
 
     protected $accessToken = null;
 
+    // Rate Limit metadata
+    /** @var integer */
+    protected $rateLimit;
+    /** @var integer */
+    protected $remainingRequests;
+    /** @var DateTime */
+    protected $rateLimitResetTime;
+
     protected $clientCertificate;
     protected $clientCertificateKey;
 
@@ -82,7 +92,70 @@ public function fillOptions(&$options) {
         }
     }
 
+    /**
+     * Rate limit
+     *
+     * @return int The number of requests which are allowed in one hour.
+     */
+    public function getRateLimit() {
+        return $this->rateLimit;
+    }
+
+    /**
+     * Check for rate limit
+     *
+     * @return bool if there is a rate limit in place
+     */
+    public function hasRateLimit() {
+        return $this->rateLimit !== false;
+    }
+
+    /**
+     * Remaining requests
+     *
+     * @return int The number of requests remaining until the rate limit is exceeded.
+     */
+    public function getRemainingRequests() {
+        return $this->remainingRequests;
+    }
+
+    /**
+     * Rate limit reset time
+     *
+     * @return DateTime The time the rate limit will be reset
+     */
+    public function getRateLimitResetTime() {
+        return $this->rateLimitResetTime;
+    }
+
+    /**
+     * Parse the NitrAPI response
+     *
+     * @param Response $response
+     * @return bool|mixed true if response is fine but without message, data or message otherwise.
+     * @throws NitrapiHttpErrorException when the API responds with an error message.
+     * @throws NitrapiRateLimitException when the user ran into the rate limit.
+     */
     public function parseResponse(Response $response) {
+        // Rate limit metadata
+        if ($response->hasHeader('X-RateLimit-Limit')) {
+            $this->rateLimit = $response->getHeader('X-RateLimit-Limit')[0];
+            $this->remainingRequests = $response->getHeader('X-RateLimit-Remaining')[0];
+            $resetDateTime = new DateTime();
+            $resetDateTime->setTimestamp($response->getHeader('X-RateLimit-Reset')[0]);
+            $this->rateLimitResetTime = $resetDateTime;
+
+            // We ran into the rate limit, so we throw an exception with all needed information.
+            // This gives the client the option to handle that error. To access the rate limit
+            // metadata, the getRateLimit(), getRemainingRequests() and getRateLimitResetTime()
+            // method can be used at any time.
+            if ($response->getStatusCode() === 429) {
+                throw new NitrapiRateLimitException($this->getRateLimit(), $this->getRateLimitResetTime());
+            }
+        } else {
+            $this->rateLimit = false;
+        }
+
         $contentType = $response->getHeader('Content-Type')[0];
 
         // Return plain text