Added monitorManager

Added metrics

Added prometheus response handling

Added response size toggle for speed vs memory optimalization of response decoding.

Author: LaravelFreelancerNL

README.md

@@ -70,6 +70,12 @@ The admin manager manages administrative functions and information retrieval for
 $client->admin()->version();
 ```
 
+### Monitor manager
+The monitor manager manages monitoring functions the server/cluster.
+``` 
+$client->monitor()->getMetrics();
+```
+
 ### Schema manager
 The schema manager manages all schema related operations.
 ``` 
@@ -86,15 +92,16 @@ $client->transactions()->begin(['write' => ['users', 'teams']]);
 1) [ArangoDB PHP client](docs/arangodb-client.md)
 2) [AQL query statements](docs/statements.md)
 3) [Admin manager](docs/admin-manager.md)
-4) Schema manager
+4) [Monitor manager](docs/monitor-manager.md)
+5Schema manager
     1) [Database schema](docs/schema-databases.md)
     2) [User schema](docs/schema-users.md)
     3) [Collection schema](docs/schema-collections.md)
     4) [Index schema](docs/schema-indexes.md)
     5) [Graph schema](docs/schema-graphs.md)
     6) [View schema](docs/schema-views.md)
     7) [Analyzer schema](docs/schema-analyzers.md)
-5) [Transaction manager](docs/transaction-manager.md)
+6[Transaction manager](docs/transaction-manager.md)
 
 ## Related packages
 * [AQL query builder](https://github.com/LaravelFreelancerNL/fluentaql)

docs/arangodb-client.md

@@ -13,6 +13,7 @@ Upon creation, you can alter the default configuration of the client. The follow
 * username = null
 * password = null
 * database = '_system'
+* responseSizeDecoderSwitch = 1 * 1024 * 1024
 
 ```
 $config = [
@@ -25,6 +26,15 @@ $config = [
 $arangoClient = new ArangoClient($config);
 ```
 
+### Speed vs response size
+JSON response decoding is normally done by the default json_decode method. This method
+is optimized for speed and can take a large amount of memory; up to ~ 20x of the JSON size.
+
+Therefor we use halaxa/json-machine to stream decode for responses larger than 1MB.
+You can alter this cutoff by setting the `responseSizeDecoderSwitch` to a different size in **Bytes**.
+
+This removed any memory issues at the cost of speed.
+
 ### Support Guzzle configuration
 In addition to the above mentioned options you can use the following Guzzle 7 specific options:
 * [version](https://docs.guzzlephp.org/en/stable/request-options.html#version)

docs/monitor-manager.md

@@ -0,0 +1,13 @@
+# Monitor manager
+
+Manages monitoring functions for the server/cluster.
+
+## Functions
+The monitor manager supports the following functions:
+
+### getMetrics(): Metrics
+Get Prometheus metrics of the server
+
+```
+$arangoClient->monitor()->getMetrics();
+```

phpstan.neon.dist

@@ -2,3 +2,5 @@ parameters:
     level: 8
     paths:
         - src
+    universalObjectCratesClasses:
+        - ArangoClient\Prometheus\Metrics

src/ArangoClient.php

@@ -25,6 +25,7 @@
  */
 class ArangoClient
 {
+    use HandlesResponses;
     use HandlesJson;
     use HasManagers;
     use SupportsTransactions;
@@ -88,7 +89,11 @@ public function request(string $method, string $uri, array|HttpRequestOptions $o
             $this->handleGuzzleException($e);
         }
 
-        return $this->cleanupResponse($response);
+        if ($response !== null) {
+            return $this->cleanupResponse($response);
+        }
+
+        return new stdClass();
     }
 
     /**
@@ -116,7 +121,7 @@ public function debugRequest(
         string $method,
         string $uri,
         array $options = [],
-        ?string $database = null,
+        ?string $database = null
     ): ResponseInterface {
         $uri = $this->prependDatabaseToUri($uri, $database);
         $options['debug'] = true;
@@ -142,23 +147,31 @@ protected function handleGuzzleException(Throwable $e): void
         $code = $e->getCode();
 
         if ($e instanceof RequestException && $e->hasResponse()) {
-            $decodedResponse = $this->decodeResponse($e->getResponse());
-            $message = (string) $decodedResponse->errorMessage;
-            $code = (int) $decodedResponse->code;
+            $response = $e->getResponse();
+            if ($response !== null) {
+                $decodedResponse = $this->decodeResponse($response);
+            }
+            if (isset($decodedResponse->errorMessage)) {
+                $message = (string) $decodedResponse->errorMessage;
+            }
+
+            if (isset($decodedResponse->code)) {
+                $code = (int) $decodedResponse->code;
+            }
         }
 
         throw(
-        new ArangoException(
-            $code . ' - ' . $message,
-            $code,
-        )
+            new ArangoException(
+                $code . ' - ' . $message,
+                $code
+            )
         );
     }
 
     /**
      * @SuppressWarnings(PHPMD.StaticAccess)
      */
-    protected function cleanupResponse(?ResponseInterface $response): stdClass
+    protected function cleanupResponse(ResponseInterface $response): stdClass
     {
         $response = $this->decodeResponse($response);
         unset($response->error);
@@ -175,16 +188,19 @@ protected function cleanupResponse(?ResponseInterface $response): stdClass
     public function prepare(
         string $query,
         array $bindVars = [],
-        array $options = [],
+        array $options = []
     ): Traversable {
         return new Statement($this, $query, $bindVars, $options);
     }
 
     /**
-     * @return array<array-key, mixed>
+     * @return mixed
      */
-    public function getConfig(): array
+    public function getConfig(string $value = null): mixed
     {
+        if ($value) {
+            return $this->config->$value;
+        }
         return $this->config->toArray();
     }
 

src/HandlesJson.php

@@ -35,15 +35,18 @@ public function jsonEncode(mixed $data): string
     /**
      * @SuppressWarnings(PHPMD.StaticAccess)
      */
-    protected function decodeResponse(?ResponseInterface $response): stdClass
+    protected function decodeJsonResponse(ResponseInterface $response): stdClass
     {
-        $decodedResponse = new stdClass();
-        if (!isset($response)) {
-            return $decodedResponse;
+        $contentLength = $response->getHeaderLine('Content-Length');
+        $sizeSwitch = $this->getConfig('responseSizeDecoderSwitch');
+        if ($contentLength < $sizeSwitch) {
+            return json_decode($response->getBody()->getContents(), false, 512, JSON_THROW_ON_ERROR);
         }
 
+        $decodedResponse = new stdClass();
+
         $phpStream = StreamWrapper::getResource($response->getBody());
-        $decoder = new ExtJsonDecoder(false);
+        $decoder = new ExtJsonDecoder(true);
         $decodedStream = Items::fromStream($phpStream, ['decoder' => $decoder]);
 
         foreach ($decodedStream as $key => $value) {

src/HandlesResponses.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArangoClient;
+
+use ArangoClient\Prometheus\Prometheus;
+use Psr\Http\Message\ResponseInterface;
+use stdClass;
+
+trait HandlesResponses
+{
+    use HandlesJson;
+
+    /**
+     * @SuppressWarnings(PHPMD.StaticAccess)
+     */
+    protected function decodeResponse(ResponseInterface $response): stdClass
+    {
+        $contentType = null;
+        $rawContentType = $response->getHeader('Content-type');
+        if (is_array($rawContentType) && sizeOf($rawContentType) > 0) {
+            $contentType = $rawContentType[0];
+        }
+
+        return match($contentType) {
+            "application/json; charset=utf-8" => $this->decodeJsonResponse($response),
+            "text/plain; charset=utf-8" => $this->decodeTextResponse($response),
+            default => (object) $response->getBody()->getContents(),
+        };
+    }
+
+    /**
+     * @SuppressWarnings(PHPMD.StaticAccess)
+     */
+    protected function decodeTextResponse(ResponseInterface $response): stdClass
+    {
+        $prometheus = new Prometheus();
+        return $prometheus->parseStream($response);
+    }
+}

src/HasManagers.php

@@ -5,12 +5,15 @@
 namespace ArangoClient;
 
 use ArangoClient\Admin\AdminManager;
+use ArangoClient\Monitor\MonitorManager;
 use ArangoClient\Schema\SchemaManager;
 
 trait HasManagers
 {
     protected ?AdminManager $adminManager = null;
 
+    protected ?MonitorManager $monitorManager = null;
+
     protected ?SchemaManager $schemaManager = null;
 
     public function admin(): AdminManager
@@ -22,6 +25,15 @@ public function admin(): AdminManager
         return $this->adminManager;
     }
 
+    public function monitor(): MonitorManager
+    {
+        if (!(property_exists($this, 'monitorManager') && $this->monitorManager !== null)) {
+            $this->monitorManager = new MonitorManager($this);
+        }
+
+        return $this->monitorManager;
+    }
+
     public function schema(): SchemaManager
     {
         if (!(property_exists($this, 'schemaManager') && $this->schemaManager !== null)) {

src/Http/HttpClientConfig.php

@@ -37,6 +37,15 @@ class HttpClientConfig extends DataTransferObject
 
     public string $database = '_system';
 
+    /**
+     * Small responses are decoded with json_decode. This is fast but memory intensive.
+     * Large responses are decoded with Halaxa/json-machine stream decoder.
+     * $responseSizeDecoderSwitch is the response length cutoff in bytes which determines which decoder is used.
+     *
+     * @var int
+     */
+    public int $responseSizeDecoderSwitch = 1 * 1024 * 1024; // Default 1 MB
+
     /**
      * @return array<array<mixed>|string|numeric|bool|null>
      */

src/Monitor/MonitorManager.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArangoClient\Monitor;
+
+use ArangoClient\ArangoClient;
+use ArangoClient\Manager;
+
+class MonitorManager extends Manager
+{
+    public function __construct(protected ArangoClient $arangoClient) {}
+
+    public function getMetrics(): \stdClass
+    {
+        $uri = '/_admin/metrics/v2';
+
+        return $this->arangoClient->request('get', $uri);
+    }
+}

src/Prometheus/Bucket.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArangoClient\Prometheus;
+
+class Bucket
+{
+    /**
+     * @param int|float|null $value
+     * @param array<string, mixed>|null $labels
+     */
+    public function __construct(
+        public int|float|null|string $value,
+        public array|null $labels,
+        public int|float|null|string $timestamp,
+    ) {}
+}

src/Prometheus/Metric.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArangoClient\Prometheus;
+
+class Metric
+{
+    /**
+     * @param string $name
+     * @param null|string $type
+     * @param string|null $help
+     * @param int|float|null $count
+     * @param int|float|null $sum
+     * @param int|float|null $value
+     * @param array<array-key, Bucket>|null $buckets
+     * @param array<string, float|int|string>|null $labels
+     */
+    public function __construct(
+        public string $name,
+        public null|string $type = null,
+        public null|string $help = null,
+        public int|float|null $count = null,
+        public int|float|null $sum = null,
+        public int|float|null $value = null,
+        public ?array $buckets = [],
+        public ?array $labels = [],
+    ) {}
+}

src/Prometheus/Metrics.php

@@ -0,0 +1,9 @@
+<?php
+
+declare(strict_types=1);
+
+namespace ArangoClient\Prometheus;
+
+use stdClass;
+
+class Metrics extends stdClass {}