Advanced Messages

Purpose and Scope

This document covers specialized Bolt protocol messages introduced in later protocol versions for advanced database operations. These messages are not required for basic query execution but provide essential functionality for production deployments in clustered environments and monitoring scenarios.

Two advanced messages are covered here:

• ROUTE (V4.3+): Retrieves routing tables from the server for cluster topology discovery
• TELEMETRY (V5.4+): Sends client-side telemetry data to the server for monitoring

For basic query execution messages, see Query Execution Messages. For transaction control, see Transaction Control Messages.

---

ROUTE Message (V4.3+)

Overview

The ROUTE message instructs the server to return the current routing table for a clustered Neo4j deployment. Prior to V4.3, clients had to invoke routing procedures using Cypher through RUN and PULL messages. The ROUTE message provides a dedicated, efficient mechanism for topology discovery.

Availability:

• Introduced in Bolt V4.3
• Enhanced in V4.4 with database-specific routing
• Available in V5.x and V6

Method Signature

The ROUTE message is implemented via the route() method:

Parameters:

Parameter	Type	Description	Required
$routing	array	Routing context (converted to object)	Yes
$bookmarks	array	Transaction bookmarks for consistency	No (default: [])
$extra	array	Additional metadata (converted to object)	No (default: [])

Extra Fields (V4.4+):

Field	Type	Description
db	String	Database name for routing table
imp_user	String	Impersonated user for routing context

Message Structure

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

Implementation Details

The RouteMessage trait is used by V4.3, V4.4, V5.x, and V6 protocols:

src/protocol/v4_4/RouteMessage.php8-24

Key implementation points:

1. Signature byte: 0x66 identifies this as a ROUTE message
2. Array-to-object conversion: The $routing and $extra parameters are explicitly cast to objects via (object) to ensure proper PackStream encoding as dictionaries
3. Bookmarks: Passed as a list for causal consistency across cluster members
4. Pipelining: The message is added to pipelinedMessages[] for response correlation

Protocol Version Differences

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

Response Handling

The ROUTE message expects a SUCCESS response containing routing table metadata:

Expected Response Structure:

{
 "rt": {
 "ttl": <Integer>, // Time-to-live in seconds
 "servers": [
 {
 "role": "WRITE" | "READ" | "ROUTE",
 "addresses": ["host:port", ...]
 },
 ...
 ]
 }
}

The response must be consumed via getResponse() or getResponses() to process the routing table data.

Usage Example Pattern

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

---

TELEMETRY Message (V5.4+)

Overview

The TELEMETRY message allows clients to send telemetry data to the server for monitoring and analytics purposes. This enables the database to collect information about client behavior, performance metrics, and usage patterns.

Availability:

• Introduced in Bolt V5.4
• Available in V5.4+, V6

Message Integration

The TELEMETRY message is implemented via the TelemetryMessage trait, which is used by V5.4+ and V6 protocols:

Sources: src/protocol/V6.php36

Method Signature Pattern

Based on the trait usage pattern in V6, the TELEMETRY message follows the standard message implementation pattern:

The method:

1. Packs telemetry data with a specific signature byte
2. Adds the message to the pipeline via $this->pipelinedMessages[] = Message::TELEMETRY
3. Returns $this for method chaining

Telemetry Data Structure

Telemetry messages typically include:

• Client information: User agent, client version, language runtime
• Performance metrics: Query execution times, connection pool statistics
• Usage patterns: Message frequency, protocol feature usage
• Error metrics: Failure rates, retry counts

Protocol Version Timeline

Sources: src/protocol/V6.php36

Pipelining Behavior

Like other Bolt messages, TELEMETRY supports pipelining:

The TELEMETRY message is added to the pipelinedMessages[] array and responses are correlated in order.

Sources: src/protocol/AProtocol.php (inherited pattern)

Response Handling

The TELEMETRY message expects a SUCCESS or IGNORED response:

• SUCCESS: Telemetry data was accepted and recorded
• IGNORED: Server does not support or is not collecting telemetry

Clients should gracefully handle IGNORED responses and may disable telemetry for subsequent connections to avoid overhead.

---

Protocol Version Support Matrix

The following table summarizes which protocol versions support each advanced message:

Message	V4.0	V4.1	V4.2	V4.3	V4.4	V5.0-V5.3	V5.4+	V6
ROUTE	❌	❌	❌	✅	✅*	✅*	✅*	✅*
TELEMETRY	❌	❌	❌	❌	❌	❌	✅	✅

* Enhanced version with additional parameters

Trait Composition Architecture

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

---

Advanced Message Pipeline

Both advanced messages integrate seamlessly with the Bolt message pipeline architecture:

Sources: src/protocol/v4_4/RouteMessage.php8-24 src/protocol/V6.php1-37 src/protocol/AProtocol.php (message pipeline pattern)

---

Implementation Notes

ROUTE Message Considerations

1. Object Casting: Always use (object) cast for routing context and extra parameters to ensure proper dictionary encoding in PackStream
2. Bookmark Consistency: Include relevant bookmarks to maintain causal consistency when routing queries across cluster members
3. Database Targeting: Use the db parameter in $extra (V4.4+) to retrieve routing tables for specific databases in multi-database deployments
4. TTL Handling: Cache routing tables based on the ttl field in the response to minimize routing overhead

TELEMETRY Message Considerations

1. Optional Nature: TELEMETRY is optional; the server may respond with IGNORED
2. Performance Impact: Avoid sending telemetry on every operation; batch or sample metrics
3. Privacy: Be aware that telemetry data is sent to the server; ensure compliance with privacy policies
4. Error Handling: Gracefully handle telemetry failures without affecting query execution

Message Pipeline Integration

Both messages follow the standard Bolt message pipeline pattern:

1. Call the message method (e.g., route(), telemetry())
2. Message signature is added to pipelinedMessages[] array
3. Binary data is written to the connection
4. Response is consumed via getResponse() or getResponses()
5. Server state is updated based on response signature

Sources: src/protocol/v4_4/RouteMessage.php1-24 src/protocol/V6.php1-37 src/protocol/AProtocol.php (base message handling)

---

Testing Advanced Messages

The test infrastructure validates advanced message functionality across protocol versions:

Sources: tests/protocol/V6Test.php1-22 tests/TestLayer.php1-114