feat: Add testkit backend

Author: exaby73

.gitignore

@@ -14,3 +14,4 @@ composer.lock
 /docs/_build
 cachegrind.out.*
 .phpunit.cache/
+/testkit-backend/testkit/

.php-cs-fixer.dist.php

@@ -33,7 +33,8 @@
 try {
     $finder = PhpCsFixer\Finder::create()
         ->in(__DIR__.'/src')
-        ->in(__DIR__.'/tests');
+        ->in(__DIR__.'/tests')
+        ->in(__DIR__.'/testkit-backend');
 } catch (Throwable $e) {
     echo $e->getMessage()."\n";
 

Dockerfile

@@ -26,5 +26,7 @@ COPY src/ src/
 COPY tests/ tests/
 COPY .git/ .git/
 
+RUN git config --global --add safe.directory /opt/project
+
 
 

composer.json

@@ -57,7 +57,8 @@
         "cache/integration-tests": "dev-master",
         "kubawerlos/php-cs-fixer-custom-fixers": "3.13.*",
         "rector/rector": "^1.0",
-        "psr/log": "^3.0"
+        "psr/log": "^3.0",
+        "php-di/php-di": "^6.3"
     },
     "autoload": {
         "psr-4": {
@@ -66,7 +67,8 @@
     },
     "autoload-dev": {
         "psr-4": {
-            "Laudis\\Neo4j\\Tests\\": "tests/"
+            "Laudis\\Neo4j\\Tests\\": "tests/",
+            "Laudis\\Neo4j\\TestkitBackend\\": "testkit-backend/src"
         }
     },
     "minimum-stability": "stable",
@@ -78,5 +80,9 @@
         "platform": {
             "php": "8.1.17"
         }
+    },
+    "scripts": {
+        "fix-cs": "./vendor/bin/php-cs-fixer fix",
+        "check-cs": "./vendor/bin/php-cs-fixer fix --dry-run"
     }
 }

docker-compose.yml

@@ -115,3 +115,13 @@ services:
       NEO4J_initial_server_mode__constraint: 'SECONDARY'
       NEO4J_server_bolt_advertised__address: server4:7687
       NEO4J_server_http_advertised__address: server4:7474
+
+  testkit_backend:
+    <<: *common-php
+    command: php ./testkit-backend/index.php
+    networks:
+      - neo4j
+    depends_on:
+      - neo4j
+    ports:
+      - "9876:9876"

testkit-backend/blacklist.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Neo4j PHP Client and Driver package.
+ *
+ * (c) Nagels <https://nagels.tech>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+return [
+    'neo4j' => [
+        'datatypes' => [
+            'TestDataTypes' => [
+                'test_should_echo_very_long_map' => 'Work in progress on testkit frontend',
+            ],
+        ],
+        'sessionrun' => [
+            'TestSessionRun' => [
+                'test_autocommit_transactions_should_support_metadata' => 'Meta data isn\'t supported yet',
+                'test_autocommit_transactions_should_support_timeout' => 'Waiting on bookmarks isn\'t supported yet',
+            ],
+        ],
+        'test_direct_driver' => [
+            'TestDirectDriver' => [
+                'test_custom_resolver' => 'No custom resolver implemented',
+                'test_fail_nicely_when_using_http_port' => 'Not implemented yet',
+            ],
+        ],
+        'test_summary' => [
+            'TestDirectDriver' => [
+                'test_agent_string' => 'This is not an official driver yet',
+            ],
+        ],
+        'txrun' => [
+            'TestTxRun' => [
+                'test_should_fail_to_run_query_for_invalid_bookmark' => 'Waiting on bookmarks isn\'t supported yet',
+            ],
+        ],
+        'txfuncrun' => [
+            'TestTxFuncRun' => [
+                'test_iteration_nested' => 'Buffers not supported yet',
+                'test_updates_last_bookmark_on_commit' => 'Waiting on bookmarks isn\'t supported yet',
+            ],
+        ],
+    ],
+];

testkit-backend/features.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Neo4j PHP Client and Driver package.
+ *
+ * (c) Nagels <https://nagels.tech>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+return [
+    // === OPTIMIZATIONS ===
+    // On receiving Neo.ClientError.Security.AuthorizationExpired, the driver
+    // shouldn't reuse any open connections for anything other than finishing
+    // a started job. All other connections should be re-established before
+    // running the next job with them.
+    'AuthorizationExpiredTreatment' => false,
+
+    // Driver doesn't explicitly send message data that is the default value.
+    // This conserves bandwidth.
+    'Optimization:ImplicitDefaultArguments' => false,
+
+    // The driver sends no more than the strictly necessary RESET messages.
+    'Optimization:MinimalResets' => false,
+
+    // The driver caches connections (e.g., in a pool) and doesn't start a new
+    // one (with hand-shake, HELLO, etc.) for each query.
+    'Optimization:ConnectionReuse' => false,
+
+    // The driver doesn't wait for a SUCCESS after calling RUN but pipelines a
+    // PULL right afterwards and consumes two messages after that. This saves a
+    // full round-trip.
+    'Optimization:PullPipelining' => false,
+
+    // === CONFIGURATION HINTS (BOLT 4.3+) ===
+    // The driver understands and follow the connection hint
+    // connection.recv_timeout_seconds which tells it to close the connection
+    // after not receiving an answer on any request for longer than the given
+    // time period. On timout, the driver should remove the server from its
+    // routing table and assume all other connections to the server are dead
+    // as well.
+    'ConfHint:connection.recv_timeout_seconds' => false,
+
+    // Temporary driver feature that will be removed when all official drivers
+    // have been unified in their behaviour of when they return a Result object.
+    // We aim for drivers to not providing a Result until the server replied with
+    // SUCCESS so that the result keys are already known and attached to the
+    // Result object without further waiting or communication with the server.
+    'Temporary:ResultKeys' => false,
+
+    // Temporary driver feature that will be removed when all official driver
+    // backends have implemented all summary response fields.
+    'Temporary:FullSummary' => false,
+
+    // Temporary driver feature that will be removed when all official driver
+    // backends have implemented path and relationship types
+    'Temporary:CypherPathAndRelationship' => true,
+];

testkit-backend/index.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Neo4j PHP Client and Driver package.
+ *
+ * (c) Nagels <https://nagels.tech>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+require_once __DIR__.'/../vendor/autoload.php';
+
+use Laudis\Neo4j\TestkitBackend\Backend;
+
+$backend = Backend::boot();
+while (true) {
+    $backend->handle();
+}

testkit-backend/register.php

@@ -0,0 +1,49 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Neo4j PHP Client and Driver package.
+ *
+ * (c) Nagels <https://nagels.tech>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Laudis\Neo4j\TestkitBackend\Handlers\GetFeatures;
+use Laudis\Neo4j\TestkitBackend\Handlers\StartTest;
+use Laudis\Neo4j\TestkitBackend\MainRepository;
+use Monolog\Handler\StreamHandler;
+use Monolog\Logger;
+use Psr\Log\LoggerInterface;
+
+return [
+    LoggerInterface::class => static function () {
+        $logger = new Logger('testkit-backend');
+        $logger->pushHandler(new StreamHandler('php://stdout', Logger::DEBUG));
+
+        return $logger;
+    },
+
+    GetFeatures::class => static function () {
+        $featuresConfig = require __DIR__.'/features.php';
+
+        return new GetFeatures($featuresConfig);
+    },
+
+    StartTest::class => static function () {
+        $acceptedTests = require __DIR__.'/blacklist.php';
+
+        return new StartTest($acceptedTests);
+    },
+
+    MainRepository::class => static function () {
+        return new MainRepository(
+            [],
+            [],
+            [],
+            [],
+        );
+    },
+];

testkit-backend/src/Backend.php

@@ -0,0 +1,136 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Neo4j PHP Client and Driver package.
+ *
+ * (c) Nagels <https://nagels.tech>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Laudis\Neo4j\TestkitBackend;
+
+use DI\ContainerBuilder;
+use Exception;
+
+use function get_debug_type;
+use function json_decode;
+use function json_encode;
+
+use const JSON_THROW_ON_ERROR;
+
+use JsonException;
+use Laudis\Neo4j\TestkitBackend\Contracts\RequestHandlerInterface;
+use Laudis\Neo4j\TestkitBackend\Contracts\TestkitResponseInterface;
+use Laudis\Neo4j\TestkitBackend\Responses\BackendErrorResponse;
+
+use const PHP_EOL;
+
+use Psr\Container\ContainerInterface;
+use Psr\Log\LoggerInterface;
+use Throwable;
+use UnexpectedValueException;
+
+final class Backend
+{
+    private Socket $socket;
+    private LoggerInterface $logger;
+    private ContainerInterface $container;
+    private RequestFactory $factory;
+
+    public function __construct(
+        Socket $socket,
+        LoggerInterface $logger,
+        ContainerInterface $container,
+        RequestFactory $factory,
+    ) {
+        $this->socket = $socket;
+        $this->logger = $logger;
+        $this->container = $container;
+        $this->factory = $factory;
+    }
+
+    /**
+     * @throws Exception
+     */
+    public static function boot(): self
+    {
+        $builder = new ContainerBuilder();
+        $builder->addDefinitions(__DIR__.'/../register.php');
+        $builder->useAutowiring(true);
+        $container = $builder->build();
+
+        $logger = $container->get(LoggerInterface::class);
+        $logger->info('Booting testkit backend ...');
+        Socket::setupEnvironment();
+        $tbr = new self(Socket::fromEnvironment(), $logger, $container, new RequestFactory());
+        $logger->info('Testkit booted');
+
+        return $tbr;
+    }
+
+    /**
+     * @throws JsonException
+     */
+    public function handle(): void
+    {
+        while (true) {
+            $message = $this->socket->readMessage();
+            if ($message === null) {
+                $this->socket->reset();
+                continue;
+            }
+
+            try {
+                [$handler, $request] = $this->extractRequest($message);
+                $this->properSendoff($handler->handle($request));
+            } catch (Throwable $e) {
+                $this->logger->error($e->__toString());
+                $this->properSendoff(new BackendErrorResponse($e->getMessage()));
+            }
+        }
+    }
+
+    private function loadRequestHandler(string $name): RequestHandlerInterface
+    {
+        $action = $this->container->get('Laudis\\Neo4j\\TestkitBackend\\Handlers\\'.$name);
+        if (!$action instanceof RequestHandlerInterface) {
+            $str = printf(
+                'Expected action to be an instance of %s, received %s instead',
+                RequestHandlerInterface::class,
+                get_debug_type($action)
+            );
+            throw new UnexpectedValueException($str);
+        }
+
+        return $action;
+    }
+
+    private function properSendoff(TestkitResponseInterface $response): void
+    {
+        $message = json_encode($response, JSON_THROW_ON_ERROR);
+
+        $this->logger->debug('Sending: '.$message);
+        $this->socket->write('#response begin'.PHP_EOL);
+        $this->socket->write($message.PHP_EOL);
+        $this->socket->write('#response end'.PHP_EOL);
+    }
+
+    /**
+     * @return array{0: RequestHandlerInterface, 1: object}
+     */
+    private function extractRequest(string $message): array
+    {
+        $this->logger->debug('Received: '.$message);
+        /** @var array{name: string, data: iterable<array|scalar|null>} $response */
+        $response = json_decode($message, true, 512, JSON_THROW_ON_ERROR);
+
+        $handler = $this->loadRequestHandler($response['name']);
+        $request = $this->factory->create($response['name'], $response['data']);
+
+        return [$handler, $request];
+    }
+}