Introduce Bookmark Manager (#974)

Neo4j clusters are causally consistent, meaning that by default there is no guarantee a query will be able to read changes made by a previous query. For cases where such a guarantee is necessary, the server provides bookmarks to the client. A bookmark is an abstract token that represents some state of the database. By passing one or multiple bookmarks along with a query, the server will make sure that the query will not get executed before the represented state(s) (or a later state) have been established.

The bookmark manager is an interface used by the driver for keeping track of the bookmarks and this way keeping sessions automatically consistent.

### Usage in the session

Enabling it is done by supplying an BookmarkManager implementation instance to this param.
A default implementation could be acquired by calling the factory function `neo4j.bookmarkManager()`.

**Warning**: Share the same BookmarkManager instance across all session can have a negative impact
on performance since all the queries will wait for the latest changes being propagated across the cluster.
For keeping consistency between a group of queries, use `Session` for grouping them.
For keeping consistency between a group of sessions, use `BookmarkManager` instance for grouping them.

```javascript
const bookmarkManager = neo4j.bookmarkManager()
const linkedSession1 = driver.session({ database:'neo4j', bookmarkManager })
const linkedSession2 = driver.session({ database:'neo4j', bookmarkManager })
const unlinkedSession = driver.session({ database:'neo4j' })

// Creating Driver User
const createUserQueryResult = await linkedSession1.run('CREATE (p:Person {name: $name})', { name: 'Driver User'})

// Reading Driver User will *NOT* wait of the changes being propagated to the server before RUN the query
// So the 'Driver User' person might not exist in the Result
const unlinkedReadResult = await unlinkedSession.run('CREATE (p:Person {name: $name}) RETURN p', { name: 'Driver User'})

// Reading Driver User will wait of the changes being propagated to the server before RUN the query
// So the 'Driver User' person should exist in the Result, unless deleted.
const linkedSession2 = await linkedSession2.run('CREATE (p:Person {name: $name}) RETURN p', { name: 'Driver User'})

await linkedSession1.close()
await linkedSession2.close()
await unlinkedSession.close()
```


Co-authored-by: Robsdedude <[email protected]>

Author: bigmontz

packages/bolt-connection/src/connection-provider/connection-provider-routing.js

@@ -146,7 +146,7 @@ export default class RoutingConnectionProvider extends PooledConnectionProvider
     const routingTable = await this._freshRoutingTable({
       accessMode,
       database: context.database,
-      bookmarks: bookmarks,
+      bookmarks,
       impersonatedUser,
       onDatabaseNameResolved: (databaseName) => {
         context.database = context.database || databaseName

packages/core/src/bookmark-manager.ts

@@ -0,0 +1,187 @@
+/**
+ * Copyright (c) "Neo4j"
+ * Neo4j Sweden AB [http://neo4j.com]
+ *
+ * This file is part of Neo4j.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Interface for the piece of software responsible for keeping track of current active bookmarks accross the driver.
+ * @interface
+ * @since 5.0
+ * @experimental
+ */
+export default class BookmarkManager {
+  /**
+   * @constructor
+   * @private
+   */
+  private constructor () {
+    throw new Error('Not implemented')
+  }
+
+  /**
+   * Method called when the bookmarks get updated when a transaction finished.
+   *
+   * This method will be called when auto-commit queries finish and when explicit transactions
+   * get commited.
+   *
+   * @param {string} database The database which the bookmarks belongs to
+   * @param {Iterable<string>} previousBookmarks The bookmarks used when starting the transaction
+   * @param {Iterable<string>} newBookmarks The new bookmarks received at the end of the transaction.
+   * @returns {void}
+  */
+  async updateBookmarks (database: string, previousBookmarks: Iterable<string>, newBookmarks: Iterable<string>): Promise<void> {
+    throw new Error('Not implemented')
+  }
+
+  /**
+   * Method called by the driver to get the bookmarks for one specific database
+   *
+   * @param {string} database The database which the bookmarks belong to
+   * @returns {Iterable<string>} The set of bookmarks
+   */
+  async getBookmarks (database: string): Promise<Iterable<string>> {
+    throw new Error('Not implemented')
+  }
+
+  /**
+   * Method called by the driver for getting all the bookmarks.
+   *
+   * This method should return all bookmarks for all databases present in the BookmarkManager.
+   *
+   * @returns {Iterable<string>} The set of bookmarks
+   */
+  async getAllBookmarks (): Promise<Iterable<string>> {
+    throw new Error('Not implemented')
+  }
+
+  /**
+   * Forget the databases and its bookmarks
+   *
+   * This method is not called by the driver. Forgetting unused databases is the user's responsibility.
+   *
+   * @param {Iterable<string>} databases The databases which the bookmarks will be removed for.
+   */
+  async forget (databases: Iterable<string>): Promise<void> {
+    throw new Error('Not implemented')
+  }
+}
+
+export interface BookmarkManagerConfig {
+  initialBookmarks?: Map<string, Iterable<string>>
+  bookmarksSupplier?: (database?: string) => Promise<Iterable<string>>
+  bookmarksConsumer?: (database: string, bookmarks: Iterable<string>) => Promise<void>
+}
+
+/**
+ * @typedef {Object} BookmarkManagerConfig
+ *
+ * @since 5.0
+ * @experimental
+ * @property {Map<string,Iterable<string>>} [initialBookmarks@experimental] Defines the initial set of bookmarks. The key is the database name and the values are the bookmarks.
+ * @property {function([database]: string):Promise<Iterable<string>>} [bookmarksSupplier] Called for supplying extra bookmarks to the BookmarkManager
+ * 1. supplying bookmarks from the given database when the default BookmarkManager's `.getBookmarks(database)` gets called.
+ * 2. supplying all the bookmarks when the default BookmarkManager's `.getAllBookmarks()` gets called
+ * @property {function(database: string, bookmarks: Iterable<string>): Promise<void>} [bookmarksConsumer] Called when the set of bookmarks for database get updated
+ */
+/**
+ * Provides an configured {@link BookmarkManager} instance.
+ *
+ * @since 5.0
+ * @experimental
+ * @param {BookmarkManagerConfig} [config={}]
+ * @returns {BookmarkManager}
+ */
+export function bookmarkManager (config: BookmarkManagerConfig = {}): BookmarkManager {
+  const initialBookmarks = new Map<string, Set<string>>()
+
+  config.initialBookmarks?.forEach((v, k) => initialBookmarks.set(k, new Set(v)))
+
+  return new Neo4jBookmarkManager(
+    initialBookmarks,
+    config.bookmarksSupplier,
+    config.bookmarksConsumer
+  )
+}
+
+class Neo4jBookmarkManager implements BookmarkManager {
+  constructor (
+    private readonly _bookmarksPerDb: Map<string, Set<string>>,
+    private readonly _bookmarksSupplier?: (database?: string) => Promise<Iterable<string>>,
+    private readonly _bookmarksConsumer?: (database: string, bookmark: Iterable<string>) => Promise<void>
+  ) {
+
+  }
+
+  async updateBookmarks (database: string, previousBookmarks: Iterable<string>, newBookmarks: Iterable<string>): Promise<void> {
+    const bookmarks = this._getOrInitializeBookmarks(database)
+    for (const bm of previousBookmarks) {
+      bookmarks.delete(bm)
+    }
+    for (const bm of newBookmarks) {
+      bookmarks.add(bm)
+    }
+    if (typeof this._bookmarksConsumer === 'function') {
+      await this._bookmarksConsumer(database, [...bookmarks])
+    }
+  }
+
+  private _getOrInitializeBookmarks (database: string): Set<string> {
+    let maybeBookmarks = this._bookmarksPerDb.get(database)
+    if (maybeBookmarks === undefined) {
+      maybeBookmarks = new Set()
+      this._bookmarksPerDb.set(database, maybeBookmarks)
+    }
+    return maybeBookmarks
+  }
+
+  async getBookmarks (database: string): Promise<Iterable<string>> {
+    const bookmarks = new Set(this._bookmarksPerDb.get(database))
+
+    if (typeof this._bookmarksSupplier === 'function') {
+      const suppliedBookmarks = await this._bookmarksSupplier(database) ?? []
+      for (const bm of suppliedBookmarks) {
+        bookmarks.add(bm)
+      }
+    }
+
+    return [...bookmarks]
+  }
+
+  async getAllBookmarks (): Promise<Iterable<string>> {
+    const bookmarks = new Set<string>()
+
+    for (const [, dbBookmarks] of this._bookmarksPerDb) {
+      for (const bm of dbBookmarks) {
+        bookmarks.add(bm)
+      }
+    }
+    if (typeof this._bookmarksSupplier === 'function') {
+      const suppliedBookmarks = await this._bookmarksSupplier() ?? []
+      for (const bm of suppliedBookmarks) {
+        bookmarks.add(bm)
+      }
+    }
+
+    return bookmarks
+  }
+
+  async forget (databases: Iterable<string>): Promise<void> {
+    for (const database of databases) {
+      this._bookmarksPerDb.delete(database)
+    }
+  }
+}