VOOZH about

URL: https://deepwiki.com/stefanak-michal/php-bolt-driver/5.3-protocol-v4.x-series-streaming-and-routing

⇱ Protocol V4.x Series - Streaming and Routing | stefanak-michal/php-bolt-driver | DeepWiki

Loading...
Loading...
Last indexed: 14 February 2026 (a283bd)
Menu

Protocol V4.x Series - Streaming and Routing

Purpose and Scope

This document covers the Bolt Protocol V4.x series (versions 4.0 through 4.4), which introduced two major capabilities: parameterized streaming and cluster routing. The V4.0 protocol replaced the monolithic PULL_ALL and DISCARD_ALL messages from V1/V2 with parameterized PULL and DISCARD messages, enabling clients to request specific batch sizes rather than forcing complete result set retrieval. Starting with V4.3, the ROUTE message was added to support efficient cluster topology discovery without executing Cypher procedures.

For foundational V1/V2 messages, see Protocol V1 and V2 - Foundation. For transaction control messages used across V3/V4, see Protocol V3 - Transaction Support. For newer features in V5/V6, see Protocol V5.x and V6 - Modern Features.

Sources: src/protocol/V4.php src/protocol/V4_3.php src/protocol/v4/PullMessage.php src/protocol/v4_3/RouteMessage.php

Version Evolution Matrix

VersionKey ChangesImplementation ClassNew MessagesNew Message Traits
V4.0Parameterized streaming: PULL(n) and DISCARD(n) replace PULL_ALL and DISCARD_ALLV4PULL, DISCARDv4\PullMessage, v4\DiscardMessage
V4.1Updated HELLO message formatV4_1-v4_1\HelloMessage
V4.2No protocol changes (internal Neo4j improvements)V4_2--
V4.3Cluster routing via ROUTE messageV4_3ROUTEv4_3\RouteMessage
V4.4Enhanced ROUTE with database and impersonation supportV4_4-v4_4\RouteMessage

Sources: src/protocol/V4.php src/protocol/V4_1.php src/protocol/V4_2.php src/protocol/V4_3.php src/protocol/V4_4.php

Protocol Class Hierarchy

The V4.x series demonstrates the trait composition pattern used throughout this library. Each version extends AProtocol and composes features from multiple trait namespaces, reusing implementations from earlier protocol versions.



Key Observations:


    

  • V4.0 introduces the critical v4\PullMessage and v4\DiscardMessage traits
    • 

  • V4.1+ switches from v3\HelloMessage to v4_1\HelloMessage
    • 

  • V4.3+ adds v4_3\AvailableStructures for new structure types
    • 

  • V4.3 and V4.4 differ only in their RouteMessage trait implementation
    • 

  • All V4.x versions use v4\ServerStateTransition for state management
    • 



Sources: src/protocol/V4.php1-29 src/protocol/V4_1.php1-30 src/protocol/V4_3.php1-32 src/protocol/V4_4.php1-32


Parameterized Streaming (V4.0)


Conceptual Improvement Over V1/V2


In V1 and V2, clients had only two options after executing a query:


    

  • PULL_ALL: Retrieve all remaining records (memory-intensive for large result sets)
    • 

  • DISCARD_ALL: Discard all remaining records
    • 



V4.0 introduced parameterized streaming where clients specify exactly how many records to fetch or discard in each request:


    

  • PULL(n): Retrieve n records from the result stream
    • 

  • DISCARD(n): Discard n records from the result stream
    • 

  • n = -1: Process all remaining records (equivalent to V1's _ALL variants)
    • 



This enables memory-efficient processing of large result sets by fetching records in manageable batches.


PULL Message Implementation


The PullMessage trait implements parameterized record retrieval:




Implementation Details:


src/protocol/v4/PullMessage.php19-26




Key parameters in $extra:


    

  • n (integer): Number of records to pull. Default: -1 (all records)
    • 

  • qid (integer): Query ID for multi-query scenarios. Default: -1 (current query)
    • 



src/protocol/v4/PullMessage.php33-45




The response iterator:


    

  1. Yields RECORD responses containing data rows
    2. 

  2. Yields a final SUCCESS or FAILURE response
    3. 

  3. Tracks openStreams counter to manage concurrent query state
    4. 

  4. Stops when has_more is false in the metadata
    5. 



Sources: src/protocol/v4/PullMessage.php9-46


DISCARD Message Implementation


The DiscardMessage trait implements parameterized record discarding:


src/protocol/v4/DiscardMessage.php20-27




The response handling is simpler than PULL since no records are returned:


src/protocol/v4/DiscardMessage.php34-40




Unlike PULL, DISCARD yields only a single response since no intermediate records need to be returned.


Sources: src/protocol/v4/DiscardMessage.php10-41


Batch Processing Pattern




Sources: src/protocol/v4/PullMessage.php src/protocol/v4/DiscardMessage.php


Test Coverage Examples


tests/protocol/V4Test.php27-60 demonstrates PULL with multiple scenarios:


    

  • Success case: Fetching records and reaching READY state
    • 

  • Failure case: Error during pull transitions to FAILED state
    • 

  • Interrupted case: Returns IGNORED response
    • 



tests/protocol/V4Test.php65-95 demonstrates DISCARD with similar scenarios.


The test mocks show the binary protocol format:




Sources: tests/protocol/V4Test.php1-96


Cluster Routing (V4.3+)


ROUTE Message (V4.3)


V4.3 introduced the ROUTE message to enable efficient cluster topology discovery. Prior to V4.3, clients had to execute a Cypher procedure (dbms.cluster.routing.getRoutingTable()) using RUN and PULL messages, which was inefficient and required Cypher parsing overhead.


src/protocol/v4_3/RouteMessage.php (referenced but not provided) implements the basic ROUTE message.


The V4.3 implementation signature:




Parameters:


    

  • $routing: Dictionary containing routing context (e.g., ['address' => 'localhost:7687'])
    • 

  • $bookmarks: Array of transaction bookmarks for consistency
    • 



Sources: src/protocol/V4_3.php31


Enhanced ROUTE Message (V4.4)


V4.4 enhanced the ROUTE message with additional parameters for database selection and user impersonation:


src/protocol/v4_4/RouteMessage.php18-23




Message Structure:


    

  • Signature: 0x66
    • 

  • Field 1: Routing context (dictionary cast to object)
    • 

  • Field 2: Bookmarks array
    • 

  • Field 3: Extra parameters (dictionary cast to object)
    • 



Extra parameters ($extra):


    

  • db (string): Target database name for multi-database scenarios
    • 

  • imp_user (string): Impersonated user for authorization context
    • 



Sources: src/protocol/v4_4/RouteMessage.php1-24


ROUTE Message Flow




Typical Response Structure:




Sources: src/protocol/v4_4/RouteMessage.php tests/protocol/V4_3Test.php27-57


Test Coverage for ROUTE


tests/protocol/V4_3Test.php27-57 verifies basic ROUTE functionality:




tests/protocol/V4_4Test.php27-59 verifies enhanced ROUTE with extra parameters:




The test mock shows the binary encoding includes the db parameter:




Sources: tests/protocol/V4_3Test.php1-59 tests/protocol/V4_4Test.php1-61


State Management in V4


The V4 series introduces enhanced state transitions to support streaming operations. The v4\ServerStateTransition trait (referenced in src/protocol/V4.php16) manages state changes specific to parameterized streaming:


Key State Transitions:


    

  • READY → STREAMING: After successful RUN
    • 

  • STREAMING → READY: After PULL completes without has_more
    • 

  • STREAMING → STREAMING: After PULL with has_more=true
    • 

  • TX_READY → TX_STREAMING: After RUN within transaction
    • 

  • TX_STREAMING → TX_READY: After streaming completes within transaction
    • 



The openStreams counter tracks concurrent result streams. When multiple queries are pipelined:


    

  • Incremented when RUN succeeds
    • 

  • Decremented when PULL/DISCARD completes without has_more
    • 

  • Reset to 0 on FAILURE
    • 



Sources: src/protocol/v4/PullMessage.php35-42 src/protocol/v4/DiscardMessage.php36-38 src/protocol/V4.php16


Version-Specific Compatibility





































VersionNeo4j CompatibilityKey Use Cases
V4.0Neo4j 4.0+Memory-efficient result processing, batch fetching
V4.1Neo4j 4.1+Updated authentication metadata format
V4.2Neo4j 4.2+Internal improvements (no protocol changes)
V4.3Neo4j 4.3+Cluster topology discovery without Cypher procedures
V4.4Neo4j 4.4+Multi-database routing, user impersonation in clusters


All V4.x versions maintain backward compatibility with V3 transaction messages (BEGIN, COMMIT, ROLLBACK) and connection lifecycle messages (HELLO, GOODBYE, RESET).


Sources: src/protocol/V4.php src/protocol/V4_1.php src/protocol/V4_2.php src/protocol/V4_3.php src/protocol/V4_4.php


Comparison: V1 vs V4 Streaming










































AspectV1/V2 (PULL_ALL)V4.x (PULL with n)
Memory footprintMust buffer entire result setConfigurable batch sizes
Network efficiencySingle round-tripMultiple round-trips for batching
Partial resultsNot supportedFetch first N records, discard rest
State complexitySimple (STREAMING → READY)Complex (has_more tracking, openStreams)
Multi-query supportSequential onlyqid parameter enables multiplexing
Message signatures0x3F (PULL_ALL), 0x2F (DISCARD_ALL)0x3F (PULL), 0x2F (DISCARD)


Sources: src/protocol/v1/PullAllMessage.php (not provided), src/protocol/v4/PullMessage.php src/protocol/v4/DiscardMessage.php


Usage Examples


Example 1: Batch Processing Large Result Set




Example 2: Cluster Routing Discovery




Example 3: Discard Unwanted Records




Sources: src/protocol/v4/PullMessage.php src/protocol/v4/DiscardMessage.php src/protocol/v4_4/RouteMessage.php