Session Management Messages

Purpose and Scope

This page documents Bolt protocol messages for managing session state and lifecycle: RESET, ACK_FAILURE, and GOODBYE. These messages control connection cleanup, error recovery, and graceful termination. For server state transitions and the state machine, see Server State Management. For initial connection setup, see Handshake and Authentication Messages.

Session management messages serve three critical functions:

1. Error recovery - Return from FAILED state to operational state
2. Connection cleanup - Cancel outstanding operations and reset state
3. Graceful termination - Close connections cleanly (V3+)

---

Message Overview by Protocol Version

The availability and behavior of session management messages varies by protocol version:

Message	V1-V2	V3-V6	Purpose
RESET	✓	✓	Cancel operations, return to READY state
ACK_FAILURE	✓	✗	Acknowledge FAILURE response (replaced by RESET in V3+)
GOODBYE	✗	✓	Graceful connection termination

Sources: README.md108-116 src/protocol/v1/AckFailureMessage.php

---

RESET Message

Overview

The RESET message cancels all outstanding operations and returns the server to the READY state. It is available in all protocol versions and serves as the primary mechanism for error recovery and connection cleanup.

Message Format

RESET
 Signature: 0x0F
 Fields: none

Behavior

When the server receives RESET, it:

1. Cancels any running query
2. Rolls back any open transaction
3. Clears the result stream
4. Returns to READY state
5. Responds with SUCCESS if reset succeeds, or FAILURE if connection is in unrecoverable state

Implementation

The ResetMessage trait is implemented in src/protocol/v1/ResetMessage.php and is available across all protocol versions through trait composition:

Sources: README.md108 tests/BoltTest.php165-171

Usage Example

State Transitions

Sources: README.md279-280

Persistent Connection Handling

When using PStreamSocket (persistent connections), the RESET message is automatically sent when reusing a cached connection to ensure clean state. The connection is validated before reuse:

Sources: README.md231-233

---

ACK_FAILURE Message (V1-V2 Only)

Overview

ACK_FAILURE is specific to Bolt V1 and V2. It acknowledges a FAILURE response from the server and transitions from the FAILED state back to READY. In V3+, this functionality is replaced by the RESET message.

Message Format

ACK_FAILURE
 Signature: 0x0E
 Fields: none

V1-V2 Error Handling Pattern

In V1-V2, error recovery requires explicit acknowledgment:

Implementation

The AckFailureMessage trait is defined in src/protocol/v1/AckFailureMessage.php1-24:

Why ACK_FAILURE Was Removed in V3+

In V3 and later, RESET serves the same purpose but with enhanced semantics:

• Single message for both acknowledgment and state reset
• Works consistently across FAILED, STREAMING, and TX states
• Simplifies client implementation
• Clearer intent (reset vs acknowledge)

Sources: src/protocol/v1/AckFailureMessage.php1-24

---

GOODBYE Message (V3+)

Overview

GOODBYE is a polite termination message introduced in V3. It signals the client's intent to close the connection, allowing the server to clean up resources gracefully before disconnecting.

Message Format

GOODBYE
 Signature: 0x02
 Fields: none

Behavior

When the server receives GOODBYE:

1. Performs any necessary cleanup
2. May respond with SUCCESS (not required)
3. Closes the underlying TCP connection

The client should wait briefly for server acknowledgment before closing the socket to ensure graceful termination.

Implementation

The GoodbyeMessage trait is available in V3+ protocol versions. Usage is demonstrated in tests:

Connection Lifecycle

Usage Patterns

Simple termination:

With verification (recommended for production):

Cleanup in finally blocks:

Sources: tests/BoltTest.php35-36 tests/BoltTest.php55-56 README.md100

---

State Recovery Patterns

Recovery from FAILED State

All protocol versions use RESET to recover from the FAILED state:

Transaction Rollback on Reset

When RESET is sent during an open transaction, the server automatically rolls back the transaction:

Multiple Outstanding Operations

RESET cancels all pipelined operations, regardless of their state:

Sources: tests/BoltTest.php165-171 tests/NornicDBTest.php77-108

---

Version-Specific Differences

V1-V2 Session Management

V3+ Session Management

Feature Comparison Table

Feature	V1-V2	V3+
Error acknowledgment	ACK_FAILURE	RESET only
State reset	RESET	RESET
Graceful termination	None	GOODBYE
Transaction rollback on reset	✓ (V3+ only has transactions)	✓
Cancel streaming results	✓	✓
Multiple acknowledgment methods	✓ (ACK_FAILURE or RESET)	✗ (RESET only)

Sources: src/protocol/v1/AckFailureMessage.php1-24 README.md139-145

---

Integration with Server State Machine

Session management messages are critical to the server state machine documented in Server State Management:

ServerState Enum Values

The ServerState enum tracks current connection state:

Session management messages affect state transitions:

Message	From State	To State (SUCCESS)	To State (FAILURE)
RESET	FAILED	READY	DEFUNCT
RESET	STREAMING	READY	DEFUNCT
RESET	TX_READY	READY	DEFUNCT
RESET	TX_STREAMING	READY	DEFUNCT
ACK_FAILURE (V1-V2)	FAILED	READY	-
GOODBYE	READY	DEFUNCT	-

Sources: README.md279-280

---

Error Handling and Edge Cases

RESET During Streaming

When RESET is sent while the server is streaming results, all remaining records are discarded:

RESET During Transaction

RESET performs implicit rollback of any open transaction:

Failed RESET - DEFUNCT State

If RESET fails, the connection enters DEFUNCT state and must be reconnected:

Persistent Connection Reset Failure

With PStreamSocket, if the automatic reset on connection reuse fails, the system falls back to a fresh handshake:

Sources: README.md231-233

---

Testing Session Management

Test Coverage

The test suite validates session management across multiple scenarios:

Basic Reset Test - tests/BoltTest.php165-171

Transaction Rollback Test - tests/NornicDBTest.php77-108

Goodbye Test - tests/BoltTest.php35-36

Cross-Version Testing

Session management is tested across Neo4j versions 4.4 through 2025:

Test Matrix	PHP 8.2	PHP 8.3	PHP 8.4	PHP 8.5
Neo4j 4.4 (V4)	✓	✓	✓	✓
Neo4j 5.x (V5)	✓	✓	✓	✓
Neo4j 2025 (V6)	✓	✓	✓	✓
Memgraph	-	-	-	✓
NornicDB	-	-	-	✓

Sources: tests/BoltTest.php165-171 tests/NornicDBTest.php77-108 phpunit.xml1-27

---

Best Practices

Always Reset on Error

When handling errors, always send RESET to ensure clean state:

Use Goodbye for Clean Shutdown

Always use GOODBYE (V3+) for clean connection termination:

Handle DEFUNCT State

Always check for DEFUNCT state after RESET fails:

Persistent Connection Validation

Trust the automatic reset validation for persistent connections, but handle fallback to handshake:

Sources: README.md108 README.md231-233