neo4j-ruby-driver 6.0.3.alpha.0 → 6.2.1.beta.2

data/lib/neo4j/driver/bolt/pool.rb

@@ -0,0 +1,255 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      # Hardened connection pool. Wraps ConnectionPool::TimedStack and
+      # layers the three guarantees production callers care about:
+      #
+      #   max_connection_lifetime  → connections older than this are
+      #                              dropped on acquire (caps server-side
+      #                              resource growth for long-running
+      #                              processes).
+      #   connection_liveness_check_timeout → if a connection has been
+      #                              idle longer than this, RESET-probe
+      #                              before handing it out (catches
+      #                              "server reaped me, client didn't
+      #                              notice yet").
+      #   connection_acquisition_timeout → bounded wait when the pool
+      #                              is at its size cap (raises
+      #                              ClientException, not a hang).
+      #
+      # Mirrors org.neo4j.driver.internal.async.pool.NettyChannelPool
+      # in the Java reference. The acquisition-timeout slice was already
+      # in place via TimedStack; this class adds the lifetime + liveness
+      # gates and centralises the construction across the two providers.
+      class Pool
+        DEFAULT_ACQUISITION_TIMEOUT = 60
+
+        # `connect_factory` is a callable returning a freshly-opened
+        # Bolt::Connection. Wrapped, not inherited, because TimedStack
+        # owns the threading + size-cap primitive and doesn't expose
+        # hooks for "decide whether to hand out the popped item".
+        def initialize(size:, options:, connect_factory:, clock: Internal::Clock.new)
+          @options = options
+          @clock = clock
+          # connect_factory takes the auth token a fresh connection should
+          # authenticate with. pop hands it to the create block via a
+          # thread-local: the create block runs synchronously inside
+          # @stack.pop on the *calling* thread, so a thread-local is read
+          # back by the same thread that set it and can't be clobbered by a
+          # concurrent pop on another thread (a shared ivar could — this
+          # pool is shared across sessions). Keyed by object_id so distinct
+          # pools don't collide on the same thread. This lets a session
+          # create a fresh connection with its own identity (per-session
+          # auth) or the manager's current token in a single get_token call,
+          # instead of connecting as the manager and re-authing.
+          @connect_factory = connect_factory
+          @auth_key = :"bolt_pool_next_auth_#{object_id}"
+          # Companion thread-local (same pattern as @auth_key) carrying the
+          # acquisition deadline a freshly-built connection's handshake must
+          # honour — so one budget spans the home-db guess + fallback.
+          @deadline_key = :"bolt_pool_next_deadline_#{object_id}"
+          # Metrics counters (driver.metrics / testkit GetConnectionPoolMetrics):
+          # @created = live connections this pool has built (idle + in use),
+          # @leased = currently checked out. idle = created - leased. Guarded by
+          # @metrics_lock since pop/push/discard run on many session threads.
+          # @created is bumped inside the create block (only on a successful
+          # factory call — TimedStack rolls back its own count if it raises).
+          @metrics_lock = Mutex.new
+          @created = 0
+          @leased = 0
+          @stack = ConnectionPool::TimedStack.new(size: size) do
+            @connect_factory.call(Thread.current[@auth_key], Thread.current[@deadline_key]).tap { bump(created: 1) }
+          end
+        end
+
+        # A consistent [in_use, idle] snapshot read under one lock — both
+        # counters move together on discard, so reading them separately could
+        # observe an intermediate (e.g. negative idle) state.
+        def metrics_snapshot
+          @metrics_lock.synchronize { [@leased, @created - @leased] }
+        end
+
+        # Pop a connection that's young enough and confirmed alive.
+        # Loops until a usable one is found or the acquisition-timeout
+        # budget runs out — every discarded slot opens room for the
+        # factory to make a fresh one.
+        def pop(auth: nil, deadline: nil)
+          # The token a freshly-built connection should authenticate with,
+          # handed to the create block via a thread-local that lives only
+          # for this pop (see #initialize). Cleared in `ensure` so it never
+          # leaks into a later create on the same thread.
+          Thread.current[@auth_key] = auth
+          # A caller-supplied deadline lets one acquisition-timeout budget span
+          # several pops (the home-db optimistic acquire + its fallback), and
+          # bounds a freshly-built connection's handshake via the create block.
+          deadline ||= current_monotonic + acquisition_timeout
+          Thread.current[@deadline_key] = deadline
+          loop do
+            timeout = [deadline - current_monotonic, 0].max
+            conn = @stack.pop(timeout: timeout)
+            return prepare(conn) if usable?(conn)
+
+            discard_on_pop(conn)
+            # Loop with whatever budget remains. A flapping server
+            # would otherwise burn the whole pool in one acquire.
+          end
+        rescue ::Timeout::Error
+          raise Exceptions::ClientException,
+                "Unable to acquire connection from the pool within configured maximum time of #{format_acquisition_timeout}"
+        ensure
+          Thread.current[@auth_key] = nil
+          Thread.current[@deadline_key] = nil
+        end
+
+        def push(connection)
+          return unless connection
+
+          # RESET on return to the pool, clearing any residual server-side state
+          # so the next lessee gets a clean connection. Reference drivers do this
+          # unless they advertise Optimization:MinimalResets (MRI doesn't), and
+          # testkit's scripts encode the expectation (#RESET_ON_POOL_RETURN#).
+          # It also keeps the liveness probe distinct from the return-RESET, so a
+          # silently-dead connection is actually detected on re-acquire
+          # (test_should_drop_connections_failing_liveness_check).
+          #
+          # If that RESET fails the connection is dead — discard it (closing the
+          # socket) rather than pooling a broken connection (test_fail_on_reset).
+          begin
+            connection.reset!(propagate: true)
+          rescue StandardError
+            discard(connection)
+            return
+          end
+          connection.idle_since = current_monotonic
+          @stack.push(connection)
+          bump(leased: -1) # returned to the pool, now idle
+        end
+
+        # Close a checked-out connection without putting it back.
+        # Mirrors Java's pool-discard: used when the connection is in
+        # a known-bad state (server FAILED, write-failure on a
+        # NotALeader, etc.) so we don't poison the pool. Frees the
+        # TimedStack slot so the next pop can lazily build a fresh
+        # one.
+        def discard(connection)
+          close_quietly(connection)
+          @stack.decrement_created
+          # A checked-out connection removed for good: no longer created, no
+          # longer leased.
+          bump(created: -1, leased: -1)
+        end
+
+        def shutdown(&)
+          @stack.shutdown(&)
+          # Every connection is closed now — keep the metrics truthful so a
+          # post-close snapshot reports nothing live.
+          @metrics_lock.synchronize { @created = @leased = 0 }
+        end
+
+        private
+
+        # Both gates: too old OR known dead. We probe only when the
+        # connection has been idle past the liveness threshold so the
+        # hot path stays single-pop / no-extra-roundtrip.
+        def usable?(conn)
+          return false if conn.nil?
+          return false if conn.closed?
+          return false if expired?(conn)
+          # A reused connection (idle_since set when it was pushed back) may have
+          # been closed by the server while parked — a cheap non-blocking
+          # peer-close check, no round-trip, catches that so we don't hand out a
+          # dead connection (and the replacement re-resolves the address). Fresh
+          # connections (idle_since nil) skip it.
+          return false if conn.idle_since && conn.broken?
+          return false if needs_liveness_check?(conn) && !conn.alive?
+
+          true
+        end
+
+        def prepare(conn)
+          conn.idle_since = nil
+          bump(leased: 1) # checked out of the pool
+          conn
+        end
+
+        # Move both counters under a single lock so a concurrent
+        # metrics_snapshot never sees a half-applied discard (created < leased).
+        def bump(created: 0, leased: 0)
+          @metrics_lock.synchronize do
+            @created += created
+            @leased += leased
+          end
+        end
+
+        # Replacement-on-acquire close: TimedStack already counted
+        # this connection as "created" (whether it came from the stack
+        # or the factory), so we must decrement_created to free the
+        # slot — otherwise a saturated pool that keeps producing
+        # unusable connections deadlocks: the next pop sees @created
+        # == size, has nothing on the stack, and blocks until timeout.
+        def discard_on_pop(conn)
+          close_quietly(conn)
+          @stack.decrement_created
+          # Popped but never handed out (unusable) — drop from created; it was
+          # never counted as leased.
+          bump(created: -1)
+        end
+
+        def close_quietly(conn)
+          conn&.close
+        rescue StandardError
+          # Caller already has a fresh connection coming. A failure
+          # during close is noise.
+        end
+
+        def expired?(conn)
+          return false unless max_lifetime
+          return false unless conn.created_at
+
+          current_monotonic - conn.created_at > max_lifetime
+        end
+
+        def needs_liveness_check?(conn)
+          return false unless liveness_check_timeout
+          return false unless conn.idle_since
+
+          current_monotonic - conn.idle_since > liveness_check_timeout
+        end
+
+        def max_lifetime
+          @max_lifetime ||= seconds(@options[:max_connection_lifetime])
+        end
+
+        def liveness_check_timeout
+          # Memoise the sentinel separately from the value so a configured
+          # 0 (probe-every-time) still bypasses the recompute.
+          return @liveness_check_timeout if defined?(@liveness_check_timeout)
+
+          @liveness_check_timeout = seconds(@options[:connection_liveness_check_timeout])
+        end
+
+        def acquisition_timeout
+          @acquisition_timeout ||=
+            seconds(@options[:connection_acquisition_timeout]) || DEFAULT_ACQUISITION_TIMEOUT
+        end
+
+        # Accept Numeric seconds or ActiveSupport::Duration (which
+        # responds to #to_f). nil stays nil — callers gate on it to
+        # decide whether the feature is configured at all.
+        def seconds(value)
+          value&.to_f
+        end
+
+        def format_acquisition_timeout
+          "#{(acquisition_timeout * 1000).to_i}ms"
+        end
+
+        def current_monotonic
+          @clock.monotonic
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/base.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Base of the per-minor protocol class hierarchy. Mirrors Java's
+        # BoltProtocolVxY family in `neo4j-bolt-connection-java` — each
+        # minor version is its own subclass and only overrides what
+        # changed at that version, instead of carrying a swarm of
+        # `version >= V5_X` checks inside one big class.
+        class Base
+          attr_reader :version, :connection
+
+          def initialize(connection, version)
+            @connection = connection
+            @version = version
+          end
+
+          # Top-level HELLO builder. The shape is fixed (one map argument);
+          # subclasses override `hello_extra` to change which keys it
+          # carries at their version. `notification_config` (the driver's
+          # NotificationsConfig, a `{minimum_severity:, disabled_categories:}`
+          # hash or nil) only lands on the wire from V52 on — older versions
+          # return an empty map from `notification_config_extra`.
+          def build_hello_message(user_agent:, auth:, routing: nil, notification_config: nil)
+            extra = hello_extra(user_agent:, auth:, routing:)
+                    .merge(notification_config_extra(notification_config))
+            PackStream::Structure.new(Message::HELLO, [extra.compact])
+          end
+
+          # The HELLO map. Auth lives inside HELLO through Bolt 5.0;
+          # `routing` is the routing context (nil for a direct bolt://
+          # connection, compacted away by build_hello_message). V51
+          # overrides this to drop `**auth` once auth splits out into a
+          # separate LOGON message.
+          def hello_extra(user_agent:, auth:, routing:)
+            { user_agent:, routing:, **auth }
+          end
+
+          # Notification-filtering keys for the HELLO map. Empty until V52,
+          # the first version whose server honours them (V52 overrides this).
+          def notification_config_extra(_notification_config) = {}
+
+          # Hook for V51+ (HELLO/LOGON split): the LOGON message the connection
+          # pipelines right after HELLO. nil here — older versions carry auth in
+          # the HELLO map and send no separate LOGON.
+          def build_logon_message(_auth) = nil
+
+          # Hook for V5+: lets the protocol flip the packer's UTC
+          # datetime flag (0x49 / 0x69 vs legacy 0x46 / 0x66).
+          def configure_packer(_packer); end
+
+          # Hook for per-version unpacker customisation — re-registering
+          # handlers for messages whose shape changed at this version
+          # (V57 FAILURE) or adding handlers for new struct types
+          # (V6 VECTOR / UNSUPPORTED). Called after Connection
+          # registers the common ones, so an override here wins.
+          def customize_hydration(_unpacker); end
+
+          # PackStream V2 (Bolt 6.1+) UUID codec. UUID is a version-specific
+          # type: only Protocol::V61 packs/unpacks it — every earlier version
+          # rejects it. Packing raises a ClientException naming the type;
+          # unpacking treats the 0xE0 marker as unknown.
+          def pack_uuid(_packer, value)
+            Exceptions::ClientException.unable_to_convert(value)
+          end
+
+          def unpack_uuid(unpacker)
+            unpacker.raise_unknown_marker(PackStream::Markers::UUID)
+          end
+
+          # --- Message builders -------------------------------------------
+          # The protocol handler owns the wire shape of the streaming /
+          # transaction messages, mirroring Java's BoltProtocolVxY. The
+          # defaults here are the Bolt 4.0+ forms; V3 overrides the three
+          # that changed: PULL/DISCARD carry no fields, and RUN/BEGIN have
+          # no `db` (3.0 is single-database). The `db` strip is keyed on
+          # supports_multiple_databases? so it is automatic for V3.
+
+          # `notification_config` is the SESSION's NotificationsConfig (the
+          # driver's rides on HELLO). It reaches the wire only on V5_2+, where
+          # notification_config_extra emits the keys; `.compact` there drops an
+          # unset severity while keeping an explicit `disabled_categories: []`.
+          def build_run(query, parameters, extra, notification_config: nil)
+            enforce_impersonation_support!(extra[:imp_user])
+            Message.run(query, parameters,
+                        strip_db(extra).merge(notification_config_extra(notification_config).compact))
+          end
+
+          def build_begin(extra, notification_config: nil)
+            enforce_impersonation_support!(extra[:imp_user])
+            Message.begin_transaction(strip_db(extra).merge(notification_config_extra(notification_config).compact))
+          end
+
+          # 4.0+ PULL carries `{n, qid}`. V3 overrides to the
+          # parameterless PULL_ALL.
+          def build_pull(extra)
+            Message.pull(extra)
+          end
+
+          # 4.0+ DISCARD carries `{n, qid}`. V3 overrides to DISCARD_ALL.
+          def build_discard(extra)
+            Message.discard(extra)
+          end
+
+          def build_telemetry(api)
+            Message.telemetry(api)
+          end
+
+          def supports_re_auth? = false
+          def supports_multiple_databases? = false
+          def supports_notification_filtering? = false
+          # TELEMETRY (driver-API usage reporting) arrived with Bolt 5.4;
+          # V54 flips this to true.
+          def supports_telemetry? = false
+          # Impersonation (imp_user on RUN/BEGIN/ROUTE) arrived with Bolt 4.4;
+          # V44 flips this to true.
+          def supports_impersonation? = false
+
+          # Fail fast when a caller asks to impersonate over a protocol
+          # that can't carry imp_user (Bolt < 4.4) — otherwise the field
+          # is silently dropped and the query runs as the authenticated
+          # user. Matches Java, which raises ClientException here. Public
+          # so Connection#route can enforce the same rule on the discovery
+          # path (a routed session impersonating against a 4.3 cluster
+          # must fail before sending ROUTE, not silently lose imp_user).
+          def enforce_impersonation_support!(imp_user)
+            return if imp_user.nil? || supports_impersonation?
+
+            raise Exceptions::ClientException,
+                  "Impersonation (impersonated_user) is not supported on Bolt #{version}; requires Bolt 4.4+"
+          end
+
+          private
+
+          def strip_db(extra)
+            return extra if supports_multiple_databases?
+
+            extra.reject { |key, _| key.to_sym == :db }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v3.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 3.0 protocol handler — the oldest version the driver
+        # speaks (matches the Java driver's matrix, which starts at 3.0).
+        #
+        # Differences from V4 that this class encodes:
+        #   * Routing is the `dbms.cluster.routing.getRoutingTable`
+        #     procedure (RUN), not a server ROUTE message — but the HELLO
+        #     still carries the routing context, matching the Java driver
+        #     (and so JRuby): testkit gates `routing` in the 3.0 HELLO on
+        #     driver name java/ruby specifically.
+        #   * Single-database: no `db` field on RUN / BEGIN. Inherits
+        #     supports_multiple_databases? = false from Base, so the
+        #     strip_db in build_run / build_begin happens automatically.
+        #   * Streaming is all-or-nothing: PULL_ALL (0x3F) and
+        #     DISCARD_ALL (0x2F) take no fields, unlike the 4.0+
+        #     PULL / DISCARD which carry `{n, qid}`.
+        class V3 < Base
+          # HELLO is the inherited auth-in-HELLO form. On 3.0, `routing`
+          # is the context for a neo4j:// driver and nil for bolt://
+          # (compacted away), so a direct 3.0 connection sends no routing
+          # key — matching the Java driver, which testkit gates on driver
+          # name for the 3.0 HELLO.
+
+          # PULL_ALL: no metadata map. The caller still passes `{n:}` for
+          # the 4.0+ path; on 3.0 we discard it and send the bare struct.
+          def build_pull(_extra)
+            PackStream::Structure.new(Message::PULL, [])
+          end
+
+          # DISCARD_ALL: no metadata map.
+          def build_discard(_extra)
+            PackStream::Structure.new(Message::DISCARD, [])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v4.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 4.x handler for the pre-4.4 wire form. The driver
+        # negotiates it for 4.2 and 4.3 (see ProtocolVersionHandler);
+        # 4.4's wire additions (imp_user, the ROUTE map form) live in
+        # the V44 subclass, which every 5.x handler descends from.
+        class V4 < Base
+          def supports_multiple_databases? = true
+
+          # ROUTE's third field is the target database as a bare string
+          # (or null for the home db). 4.4 changed it to a `{db, imp_user}`
+          # map — V44 overrides this; imp_user is unused here.
+          def build_route(routing_context, bookmarks, database, _imp_user)
+            Message.route(routing_context, bookmarks, database)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v43.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 4.3. First version to offer the "utc" datetime patch
+        # (HELLO `patch_bolt: ["utc"]`, opting into UTC-seconds encoding
+        # 0x49/0x69). Otherwise identical to V4 — 4.2 does not support the
+        # patch. V44 and every 5.x descend from here and inherit the
+        # capability; V5 turns it back off since 5.0+ makes UTC native. The
+        # packer only switches once the server confirms the patch in the
+        # HELLO SUCCESS (Connection#perform_hello).
+        class V43 < V4
+          # Advertise the "utc" patch in HELLO. Inherited by V44 (and thus the
+          # 5.x ladder); V5 resets patch_bolt_extra to {} since 5.0+ makes UTC
+          # native. The packer only switches once the server confirms the patch
+          # in the HELLO SUCCESS (Connection#perform_hello).
+          def hello_extra(user_agent:, auth:, routing:)
+            super.merge(patch_bolt_extra)
+          end
+
+          def patch_bolt_extra = { patch_bolt: ['utc'] }
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v44.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 4.4. Adds impersonation (imp_user on RUN/BEGIN/ROUTE) and
+        # changes ROUTE's third field from a bare database string to a
+        # `{db, imp_user}` map. Descends from V43 so it inherits the "utc"
+        # patch capability; every 5.x handler descends from this class, so
+        # they inherit impersonation, the ROUTE map form, and (until V5
+        # turns it off) the patch.
+        class V44 < V43
+          def supports_impersonation? = true
+
+          def build_route(routing_context, bookmarks, database, imp_user)
+            Message.route(routing_context, bookmarks, { db: database, imp_user: }.compact)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v5.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 5.0. HELLO shape is unchanged from V44 (auth still lives
+        # inside HELLO; 5.1 is where it splits out). The visible delta is
+        # on the wire: 5.0+ mandates UTC-seconds datetime encoding
+        # (structures 0x49 / 0x69) for both pack and hydrate. The 0x46 /
+        # 0x66 hydration handlers stay registered for back-compat reads
+        # from older sources. Extends V44 so it keeps impersonation and
+        # the ROUTE map form.
+        class V5 < V44
+          def configure_packer(packer)
+            packer.use_utc_datetime = true
+          end
+
+          # 5.0+ makes UTC-seconds datetimes native, so drop the "utc" HELLO
+          # patch V43 added — V43#hello_extra (inherited via V44) merges this
+          # empty map, so 5.0 sends no patch_bolt.
+          def patch_bolt_extra = {}
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v51.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 5.1. HELLO no longer carries auth — a separate LOGON
+        # (signature 0x6A) follows immediately. This also unlocks
+        # re-authentication on a live connection (`LOGOFF` + `LOGON`),
+        # which the public driver doesn't expose yet but the protocol
+        # supports from here on.
+        class V51 < V5
+          def hello_extra(user_agent:, auth:, routing:)
+            { user_agent:, routing: }
+          end
+
+          def build_logon_message(auth) = Message.logon(auth)
+
+          def supports_re_auth? = true
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v52.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 5.2. Server now honours notification-filtering fields in
+        # HELLO (`notifications_minimum_severity`,
+        # `notifications_disabled_categories`). The driver's
+        # NotificationsConfig (a `{minimum_severity:, disabled_categories:}`
+        # hash, or nil) is mapped straight onto those keys here; the outer
+        # `build_hello_message.compact` drops an unset severity while keeping
+        # an explicit empty `disabled_categories: []` (which the server reads
+        # as "re-enable every category").
+        class V52 < V51
+          def supports_notification_filtering? = true
+
+          def notification_config_extra(config)
+            return {} unless config
+
+            { notifications_minimum_severity: config[:minimum_severity],
+              notifications_disabled_categories: config[:disabled_categories] }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v53.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 5.3. HELLO grows a required `bolt_agent` map identifying
+        # the driver (product is required; the rest is informational).
+        class V53 < V52
+          def hello_extra(user_agent:, auth:, routing:)
+            super.merge(bolt_agent: bolt_agent)
+          end
+
+          private
+
+          def bolt_agent
+            {
+              product: "neo4j-ruby-driver/#{Neo4j::Driver::VERSION}",
+              language: "Ruby/#{RUBY_VERSION}",
+              platform: RUBY_PLATFORM
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v54.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 5.4. Adds the TELEMETRY request (signature 0x54).
+        class V54 < V53
+          def supports_telemetry? = true
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v55.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 5.5. Server stops emitting the legacy `notifications`
+        # list in SUCCESS metadata and switches to GQL status objects
+        # (`statuses`). Hydration-side: ResultSummary#notifications
+        # already falls back to `statuses` when the legacy key is
+        # absent, so there's nothing version-specific to override here.
+        class V55 < V54
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/driver/bolt/protocol/v56.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Driver
+    module Bolt
+      module Protocol
+        # Bolt 5.6. No client-visible wire change vs 5.5 — server-side
+        # capability bump only (vector type availability on the server).
+        class V56 < V55
+        end
+      end
+    end
+  end
+end