Bolt Factory and Protocol Negotiation

Purpose and Scope

This document explains the Bolt factory class and the protocol negotiation mechanism that occurs during connection establishment. The factory is responsible for:

• Establishing TCP connections to Neo4j/Memgraph databases
• Performing the Bolt protocol handshake
• Negotiating protocol versions with the server
• Instantiating the appropriate AProtocol subclass based on negotiated version
• Managing persistent connection recovery via cache

For details on individual protocol versions and their features, see Protocol Versions. For connection implementations, see Connection Management. For server state transitions after negotiation, see Server State Management.

Sources: src/Bolt.php1-262

---

Factory Pattern Overview

The Bolt class implements the factory pattern to abstract protocol version selection from the client application. It accepts an IConnection implementation and returns a configured AProtocol instance after successful negotiation.

Key Responsibilities

Responsibility	Implementation
Connection establishment	Delegates to IConnection::connect()
Protocol handshake	Sends magic bytes and version preferences
Version negotiation	Reads server's selected version from handshake response
Protocol instantiation	Creates V1, V3, V4, V4_3, V5, or V6 instance
Persistent connection recovery	Uses FileCache to restore interrupted sessions
Analytics tracking	Optional usage telemetry (opt-out via BOLT_ANALYTICS_OPTOUT)

Sources: src/Bolt.php12-39

---

Protocol Negotiation Sequence

Sources: src/Bolt.php120-143 src/Bolt.php145-157 src/Bolt.php159-185 src/Bolt.php205-220

---

Handshake Protocol

The handshake follows the Bolt specification with a fixed structure:

Magic Bytes and Version Packing

The client sends 20 bytes total:

• Bytes 0-3: Magic bytes 0x6060B017 (identifies Bolt protocol)
• Bytes 4-19: Four 4-byte protocol version specifications (in preference order)

Version Encoding

Protocol versions are encoded as 4 bytes in little-endian order:

Version String	Byte 3	Byte 2	Byte 1	Byte 0	Example Hex
1	0	0	0	1	00 00 00 01
3	0	0	0	3	00 00 00 03
4.4	0	0	4	4	00 00 04 04
5.8	0	0	5	8	00 00 05 08
6	0	0	0	6	00 00 00 06

Sources: src/Bolt.php240-261 src/Bolt.php223-238

---

Core Factory Methods

Building Protocol Instances

The build() method orchestrates the entire negotiation process:

Sources: src/Bolt.php120-143

Protocol Version Configuration

The setProtocolVersions() method accepts up to 4 version specifications:

The method ensures exactly 4 versions are sent (padding with 0 for unused slots):

Sources: src/Bolt.php37 src/Bolt.php187-193

Class Naming Convention

Protocol classes follow the naming pattern \Bolt\protocol\V{version} where dots in version numbers are replaced with underscores:

Server Response	Protocol Class	File Path
1	\Bolt\protocol\V1	src/protocol/V1.php
3	\Bolt\protocol\V3	src/protocol/V3.php
4.3	\Bolt\protocol\V4_3	src/protocol/V4_3.php
5.2	\Bolt\protocol\V5_2	src/protocol/V5_2.php
6	\Bolt\protocol\V6	src/protocol/V6.php

Sources: src/Bolt.php149-154 src/Bolt.php167-171

---

Initial Server State Assignment

After instantiation, the factory sets the initial serverState based on protocol version:

The determination logic:

• V5.1+: ServerState::NEGOTIATION (requires separate LOGON message after HELLO)
• V1-V4: ServerState::CONNECTED (authentication included in INIT or HELLO)
• Persistent connections: ServerState::INTERRUPTED (requires RESET to resume)

Sources: src/Bolt.php155-156 src/Bolt.php174

---

Persistent Connection Recovery

For PStreamSocket connections, the factory implements an optimized path that avoids full handshake:

Cache-Based Recovery Flow

The cache key is the connection identifier from PStreamSocket::getIdentifier(), and the cached value is the protocol version string (e.g., "5.2"). The TTL is 15 minutes from last successful use.

Sources: src/Bolt.php138-140 src/Bolt.php159-185 src/connection/PStreamSocket.php1-50

---

Error Handling

The factory handles several error conditions during negotiation:

Connection Failures

All exceptions trigger disconnection via $this->connection->disconnect() before rethrowing.

Sources: src/Bolt.php124-136 src/Bolt.php213-217 src/Bolt.php216-218 src/Bolt.php150-152

---

Debug Mode

When Bolt::$debug is enabled, the factory outputs handshake diagnostics:

This static property affects all Bolt instances and can be used for troubleshooting connection issues.

Sources: src/Bolt.php26 src/Bolt.php207-208

---

Analytics Tracking Integration

The factory optionally tracks usage metrics unless opted out via the BOLT_ANALYTICS_OPTOUT environment variable:

Analytics Data Structure

The factory interacts with analytics in two places:

1. Constructor: Triggers track() method to send pending analytics
2. Cache updates: Reads/writes to analytics cache key

The cached analytics structure:

Analytics are transmitted to Mixpanel when data from previous days exists. The factory cleans transmitted data from the cache.

Sources: src/Bolt.php30-36 src/Bolt.php40-114

---

Usage Example

Sources: src/Bolt.php28 src/Bolt.php187-193 src/Bolt.php195-199 src/Bolt.php120

---

Related Components

Dependencies

The Bolt factory depends on:

Component	Purpose	Reference
IConnection	TCP transport abstraction	Connection Management
AProtocol	Protocol message handling	AProtocol Base Class
CacheProvider	Persistent connection cache	Caching and Analytics
ServerState	State machine enum	Server State Management
Signature	Message signature enum	Message Reference

Protocol Implementations

After negotiation, one of these classes is instantiated:

• V1 - Bolt protocol 1 and 2 (Protocol V1 and V2)
• V3 - Bolt protocol 3 (Protocol V3)
• V4 through V4_4 - Bolt protocol 4.x series (Protocol V4.x)
• V5 through V5_8 - Bolt protocol 5.x series (Protocol V5.x and V6)
• V6 - Bolt protocol 6 (Protocol V5.x and V6)

Sources: src/Bolt.php1-11 src/protocol/V1.php1-23 src/protocol/V3.php1-28 src/protocol/V4.php1-29 src/protocol/V4_3.php1-32