TestKit driver_parameter - Neo4j bookmark manager and Bolt user agent

README.md

@@ -207,6 +207,8 @@ foreach ($results as $result) {
 }
 ```
 
+`peek()` returns the next row without moving the cursor (or `null` if there is none). It can pull the next record from the server into the buffer if needed, but does not advance past it—unlike `next()` in a `foreach`, which always consumes. Repeated calls to `peek()` return the same value until you advance the iterator (for example with `next()` or by continuing a `foreach`).
+
 Cypher values and types map to these php types and classes:
 
 | Cypher         | Php                                           |

src/Authentication/BasicAuth.php

@@ -35,7 +35,7 @@
     /**
      * @throws Exception
      *
      * @return array{server: string, connection_id: string, hints: list}
      */
     public function authenticateBolt(BoltConnection $connection, string $userAgent): array
     {
@@ -55,21 +55,21 @@
 
             $response = $factory->createLogonMessage($credentials)->send()->getResponse();
 
-            /** @var array{server: string, connection_id: string, hints: list} */
+            /** @var array{server: string, connection_id: string, hints: list, patch_bolt?: list<string>} */
             return array_merge($responseHello->content, $response->content);
         }
 
-        $helloMetadata = [
+        $helloMetadata = BoltHelloMetadata::withUtcPatchIfSupported($connection, [
             'user_agent' => $userAgent,
             'scheme' => 'basic',
             'principal' => $this->username,
             'credentials' => $this->password,
-        ];
+        ]);
 
         $response = $factory->createHelloMessage($helloMetadata)->send()->getResponse();
 
-        /** @var array{server: string, connection_id: string, hints: list} */
+        /** @var array{server: string, connection_id: string, hints: list, patch_bolt?: list<string>} */
         return $response->content;
     }
 
     /**

src/Authentication/KerberosAuth.php

@@ -37,15 +37,17 @@ public function __construct(
     /**
      * @throws Exception
      *
-     * @return array{server: string, connection_id: string, hints: list}
+     * @return array{server: string, connection_id: string, hints: list, patch_bolt?: list<string>}
      */
     public function authenticateBolt(BoltConnection $connection, string $userAgent): array
     {
         $factory = $this->createMessageFactory($connection);
 
         $this->logger?->log(LogLevel::DEBUG, 'HELLO', ['user_agent' => $userAgent]);
 
-        $factory->createHelloMessage(['user_agent' => $userAgent])->send()->getResponse();
+        $helloMetadata = BoltHelloMetadata::withUtcPatchIfSupported($connection, ['user_agent' => $userAgent]);
+
+        $factory->createHelloMessage($helloMetadata)->send()->getResponse();
 
         $this->logger?->log(LogLevel::DEBUG, 'LOGON', ['scheme' => 'kerberos', 'principal' => '']);
 
@@ -56,7 +58,7 @@ public function authenticateBolt(BoltConnection $connection, string $userAgent):
         ])->send()->getResponse();
 
         /**
-         * @var array{server: string, connection_id: string, hints: list}
+         * @var array{server: string, connection_id: string, hints: list, patch_bolt?: list<string>}
          */
         return $response->content;
     }

src/Authentication/NoAuth.php

@@ -33,31 +33,31 @@ public function __construct(
     /**
      * @throws Exception
      *
-     * @return array{server: string, connection_id: string, hints: list}
+     * @return array{server: string, connection_id: string, hints: list, patch_bolt?: list<string>}
      */
     public function authenticateBolt(BoltConnection $connection, string $userAgent): array
     {
         $factory = $this->createMessageFactory($connection);
 
         if ($connection->getProtocol()->compare(ConnectionProtocol::BOLT_V5_1()) >= 0) {
-            $helloMetadata = ['user_agent' => $userAgent];
+            $helloMetadata = BoltHelloMetadata::withUtcPatchIfSupported($connection, ['user_agent' => $userAgent]);
 
             $factory->createHelloMessage($helloMetadata)->send()->getResponse();
 
             $response = $factory->createLogonMessage(['scheme' => 'none'])->send()->getResponse();
 
-            /** @var array{server: string, connection_id: string, hints: list} */
+            /** @var array{server: string, connection_id: string, hints: list, patch_bolt?: list<string>} */
             return $response->content;
         }
 
-        $helloMetadata = [
+        $helloMetadata = BoltHelloMetadata::withUtcPatchIfSupported($connection, [
             'user_agent' => $userAgent,
             'scheme' => 'none',
-        ];
+        ]);
 
         $response = $factory->createHelloMessage($helloMetadata)->send()->getResponse();
 
-        /** @var array{server: string, connection_id: string, hints: list} */
+        /** @var array{server: string, connection_id: string, hints: list, patch_bolt?: list<string>} */
         return $response->content;
     }
 

src/Authentication/OpenIDConnectAuth.php

@@ -43,15 +43,17 @@ public function authenticateHttp(RequestInterface $request, UriInterface $uri, s
     /**
      * @throws Exception
      *
-     * @return array{server: string, connection_id: string, hints: list}
+     * @return array{server: string, connection_id: string, hints: list, patch_bolt?: list<string>}
      */
     public function authenticateBolt(BoltConnection $connection, string $userAgent): array
     {
         $factory = $this->createMessageFactory($connection);
 
         $this->logger?->log(LogLevel::DEBUG, 'HELLO', ['user_agent' => $userAgent]);
 
-        $factory->createHelloMessage(['user_agent' => $userAgent])->send()->getResponse();
+        $helloMetadata = BoltHelloMetadata::withUtcPatchIfSupported($connection, ['user_agent' => $userAgent]);
+
+        $factory->createHelloMessage($helloMetadata)->send()->getResponse();
 
         $this->logger?->log(LogLevel::DEBUG, 'LOGON', ['scheme' => 'bearer']);
 
@@ -61,7 +63,7 @@ public function authenticateBolt(BoltConnection $connection, string $userAgent):
         ])->send()->getResponse();
 
         /**
-         * @var array{server: string, connection_id: string, hints: list}
+         * @var array{server: string, connection_id: string, hints: list, patch_bolt?: list<string>}
          */
         return $response->content;
     }

src/Bolt/BoltConnection.php

@@ -18,6 +18,8 @@
 use Bolt\error\BoltException;
 use Bolt\error\ConnectException as BoltConnectException;
 use Bolt\protocol\Response;
+use Bolt\protocol\V4_2;
+use Bolt\protocol\V4_3;
 use Bolt\protocol\V4_4;
 use Bolt\protocol\V5;
 use Bolt\protocol\V5_1;
@@ -45,7 +47,7 @@
 use WeakReference;
 
 /**
- * @implements ConnectionInterface<array{0: V4_4|V5|V5_1|V5_2|V5_3|V5_4|null, 1: Connection}>
+ * @implements ConnectionInterface<array{0: V4_2|V4_3|V4_4|V5|V5_1|V5_2|V5_3|V5_4|null, 1: Connection}>
  *
  * @psalm-import-type BoltMeta from SummarizedResultFormatter
  */
@@ -81,8 +83,12 @@
 
     private int $messagesInPipeline = 0;
 
+    private bool $boltUtcPatchNegotiated = false;
+
+    private bool $boltUtcPatchNegotiated = false;
+
     /**
-     * @return array{0: V4_4|V5|V5_1|V5_2|V5_3|V5_4|null, 1: Connection}
+     * @return array{0: V4_2|V4_3|V4_4|V5|V5_1|V5_2|V5_3|V5_4|null, 1: Connection}
      */
     public function getImplementation(): array
     {
@@ -93,7 +99,7 @@
      * @psalm-mutation-free
      */
     public function __construct(
-        private V4_4|V5|V5_1|V5_2|V5_3|V5_4|null $boltProtocol,
+        private V4_2|V4_3|V4_4|V5|V5_1|V5_2|V5_3|V5_4|null $boltProtocol,
         private readonly Connection $connection,
         private readonly AuthenticateInterface $auth,
         private readonly string $userAgent,
@@ -142,10 +148,20 @@
         return $this->config->getProtocol();
     }
 
+    public function setBoltUtcPatchNegotiated(bool $negotiated): void
+    {
+        $this->boltUtcPatchNegotiated = $negotiated;
+    }
+
+    public function isBoltUtcPatchNegotiated(): bool
+    {
+        return $this->boltUtcPatchNegotiated;
+    }
+
     /**
      * @psalm-mutation-free
      */
     public function isBoltUtcPatchNegotiated(): bool
     {
         return $this->config->isBoltUtcPatchNegotiated();
     }
@@ -323,7 +339,7 @@
         $this->assertNoFailure($response);
     }
 
-    public function protocol(): V4_4|V5|V5_1|V5_2|V5_3|V5_4
+    public function protocol(): V4_2|V4_3|V4_4|V5|V5_1|V5_2|V5_3|V5_4
     {
         if (!isset($this->boltProtocol)) {
             throw new Exception('Connection is closed');

src/Bolt/BoltMessageFactory.php

@@ -26,6 +26,7 @@
 use Laudis\Neo4j\Bolt\Messages\BoltRollbackMessage;
 use Laudis\Neo4j\Bolt\Messages\BoltRunMessage;
 use Laudis\Neo4j\Common\Neo4jLogger;
+use Laudis\Neo4j\Contracts\Neo4jBookmarkManagerHooksInterface;
 use Laudis\Neo4j\Databags\BookmarkHolder;
 
 /**
@@ -59,9 +60,9 @@ public function createRunMessage(string $text, array $parameters, array $extra):
         return new BoltRunMessage($this->connection, $text, $parameters, $extra, $this->logger);
     }
 
-    public function createCommitMessage(BookmarkHolder $bookmarkHolder): BoltCommitMessage
+    public function createCommitMessage(BookmarkHolder $bookmarkHolder, ?Neo4jBookmarkManagerHooksInterface $bookmarkManagerHooks = null, bool $neo4jSharedManagedBookmarks = false): BoltCommitMessage
     {
-        return new BoltCommitMessage($this->connection, $this->logger, $bookmarkHolder);
+        return new BoltCommitMessage($this->connection, $this->logger, $bookmarkHolder, $bookmarkManagerHooks, $neo4jSharedManagedBookmarks);
     }
 
     public function createRollbackMessage(): BoltRollbackMessage

src/Bolt/BoltResult.php

@@ -145,6 +145,11 @@
     {
         $this->networkPullOccurred = true;
 
+        $deferred = $this->connection->takeDeferredPullFailure();
+        if ($deferred !== null) {
+            throw $deferred;
+        }
+
         try {
             $meta = $this->connection->pull($this->qid, $this->effectivePullSize());
         } catch (BoltConnectException|BoltException $e) {

src/Bolt/Messages/BoltCommitMessage.php

@@ -18,6 +18,7 @@
 use Laudis\Neo4j\Bolt\BoltConnection;
 use Laudis\Neo4j\Common\Neo4jLogger;
 use Laudis\Neo4j\Contracts\BoltMessage;
+use Laudis\Neo4j\Contracts\Neo4jBookmarkManagerHooksInterface;
 use Laudis\Neo4j\Databags\Bookmark;
 use Laudis\Neo4j\Databags\BookmarkHolder;
 use Psr\Log\LogLevel;
@@ -28,6 +29,8 @@ public function __construct(
         BoltConnection $connection,
         private readonly ?Neo4jLogger $logger,
         private readonly BookmarkHolder $bookmarks,
+        private readonly ?Neo4jBookmarkManagerHooksInterface $bookmarkManagerHooks = null,
+        private readonly bool $neo4jSharedManagedBookmarks = false,
     ) {
         parent::__construct($connection);
     }
@@ -54,9 +57,15 @@ public function getResponse(): Response
         /** @var array{bookmark?: string} $content */
         $content = $response->content;
         $bookmark = $content['bookmark'] ?? '';
-
-        if (trim($bookmark) !== '') {
-            $this->bookmarks->setBookmark(new Bookmark([$bookmark]));
+        $trimmed = trim($bookmark);
+        if ($trimmed !== '') {
+            $incoming = new Bookmark([$trimmed]);
+            if ($this->neo4jSharedManagedBookmarks) {
+                $this->bookmarks->neo4jApplyCommittedServerBookmark($incoming);
+            } else {
+                $this->bookmarks->setBookmark($incoming);
+            }
+            $this->bookmarkManagerHooks?->notifyBookmarksUpdated([$trimmed]);
         }
 
         $this->connection->protocol()->serverState = ServerState::READY;

src/Bolt/ProtocolFactory.php

@@ -15,6 +15,8 @@
 
 use Bolt\Bolt;
 use Bolt\connection\IConnection;
+use Bolt\protocol\V4_2;
+use Bolt\protocol\V4_3;
 use Bolt\protocol\V4_4;
 use Bolt\protocol\V5;
 use Bolt\protocol\V5_1;
@@ -25,20 +27,20 @@
 
 class ProtocolFactory
 {
-    public function createProtocol(IConnection $connection): V4_4|V5|V5_1|V5_2|V5_3|V5_4
+    public function createProtocol(IConnection $connection): V4_2|V4_3|V4_4|V5|V5_1|V5_2|V5_3|V5_4
     {
         $boltOptoutEnv = getenv('BOLT_ANALYTICS_OPTOUT');
         if ($boltOptoutEnv === false) {
             putenv('BOLT_ANALYTICS_OPTOUT=1');
         }
 
         $bolt = new Bolt($connection);
-        // Offer protocol versions from newest to oldest (only 4.4 and above are supported)
-        $bolt->setProtocolVersions('5.4.4', 4.4);
+        // Four Bolt version suggestions (library maximum); include 4.2/4.3 for TestKit stubs and older servers.
+        $bolt->setProtocolVersions('5.4.4', '4.4.4', '4.3.3', '4.2.2');
         $protocol = $bolt->build();
 
-        if (!($protocol instanceof V4_4 || $protocol instanceof V5 || $protocol instanceof V5_1 || $protocol instanceof V5_2 || $protocol instanceof V5_3 || $protocol instanceof V5_4)) {
-            throw new RuntimeException('Client only supports bolt version 4.4 to 5.4');
+        if (!($protocol instanceof V4_2 || $protocol instanceof V4_3 || $protocol instanceof V4_4 || $protocol instanceof V5 || $protocol instanceof V5_1 || $protocol instanceof V5_2 || $protocol instanceof V5_3 || $protocol instanceof V5_4)) {
+            throw new RuntimeException('Client only supports Bolt protocol 4.2 through 5.4');
         }
 
         return $protocol;

src/Bolt/Session.php

@@ -62,7 +62,8 @@
          */
         private readonly SummarizedResultFormatter $formatter,
     ) {
-        $this->bookmarkHolder = new BookmarkHolder(Bookmark::from($config->getBookmarks()));
+        $this->bookmarkHolder = $config->getBookmarkHolder()
+            ?? new BookmarkHolder(Bookmark::from($config->getBookmarks()));
     }
 
     /**

src/BoltFactory.php

@@ -30,7 +30,7 @@
 use Laudis\Neo4j\Enum\SocketType;
 
 /**
- * Small wrapper around the bolt library to easily guarantee only bolt version 3 and up will be created and authenticated.
+ * Small wrapper around the bolt library to create and authenticate Bolt connections (protocol 4.2+).
  */
 class BoltFactory
 {
@@ -83,6 +83,11 @@ public function createConnection(ConnectionRequestData $data, SessionConfigurati
 
         $response = $data->getAuth()->authenticateBolt($connection, $data->getUserAgent());
 
+        $patchBolt = $response['patch_bolt'] ?? null;
+        $connection->setBoltUtcPatchNegotiated(
+            is_array($patchBolt) && in_array('utc', $patchBolt, true)
+        );
+
         $config->setServerAgent($response['server'] ?? '');
 
         // Timeout precedence: 1) driver config, 2) server hint, 3) default 30s.

src/Contracts/Neo4jBookmarkManagerHooksInterface.php

@@ -0,0 +1,35 @@
+<?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\Contracts;
+
+/**
+ * Optional hooks used when a session is tied to a Neo4j-style bookmark manager
+ * (supplier / consumer callbacks).
+ */
+interface Neo4jBookmarkManagerHooksInterface
+{
+    /**
+     * Additional bookmarks merged only for the next wire message (RUN / BEGIN / ROUTE).
+     *
+     * @return list<string>
+     */
+    public function getSupplierBookmarks(): array;
+
+    /**
+     * Called after the server reports new bookmark(s) for the session bookmark store.
+     *
+     * @param list<string> $bookmarks
+     */
+    public function notifyBookmarksUpdated(array $bookmarks): void;
+}