Last indexed: 14 February 2026 (a283bd)

Server State Management

Server state management tracks the lifecycle and current operational state of a Bolt protocol connection. The library maintains a state machine that transitions between states (such as READY, STREAMING, TX_READY, FAILED) based on the messages sent to the server and the signatures received in responses. This mechanism ensures that the client accurately reflects the server's state and can enforce valid message sequencing.

For information about the protocol message types and their meanings, see Message Reference. For details on how the protocol layer sends and receives messages, see AProtocol Base Class and Message Pipeline.

Overview

The Bolt protocol is stateful—the server maintains a session state that determines which operations are valid at any given moment. For example, you cannot execute a PULL message unless the server is in the STREAMING state following a successful RUN message. The client must track this state to validate operations and correctly interpret responses.

Sources: src/protocol/AProtocol.php29

ServerState Property

Each protocol instance maintains a public serverState property of type ServerState:

This property is directly accessible and is updated automatically by the protocol layer after processing each response. The initial state is set during protocol instantiation based on the protocol version.

Sources: src/protocol/AProtocol.php29 src/Bolt.php155-156 src/Bolt.php174

ServerState Values

The ServerState enum defines the following states:

State	Description	Protocol Version
`NEGOTIATION`	Initial state for V5.1+ after handshake, before authentication	V5.1+
`CONNECTED`	Initial state for V1-V5.0 after handshake, before authentication	V1-V5.0
`READY`	Authenticated and ready to execute queries or begin transactions	All
`STREAMING`	Currently streaming results from a query outside a transaction	All
`TX_READY`	Inside an explicit transaction, ready to execute queries or commit/rollback	V3+
`TX_STREAMING`	Inside an explicit transaction, currently streaming query results	V3+
`FAILED`	An error has occurred; requires `RESET` (V1-V2) or `ACK_FAILURE` (V1) to recover	V1-V2 primarily
`INTERRUPTED`	Connection was interrupted; used with persistent connections	Persistent
`DEFUNCT`	Connection is no longer usable; must disconnect and reconnect	All

Sources: src/Bolt.php155-156 src/Bolt.php174 tests/protocol/V1Test.php52-59

State Machine Diagram

Sources: src/protocol/AProtocol.php154-165 tests/protocol/V1Test.php tests/protocol/V3Test.php tests/protocol/V4Test.php

State Transition Mechanism

State transitions are managed by the serverStateTransition property, which is an array of transition rules defined in version-specific traits. Each rule is a tuple:

[currentState, message, responseSignature, newState]

The transition logic is executed in the getResponse() method:

Sources: src/protocol/AProtocol.php154-165

ServerStateTransition Traits

Different protocol versions implement state transitions through traits:

Trait	Used By	Key Features
V1 ServerStateTransition	V1, V2	Basic states: `CONNECTED`, `READY`, `STREAMING`, `FAILED`, `DEFUNCT`
V3 ServerStateTransition	V3	Adds transaction states: `TX_READY`, `TX_STREAMING`
V4 ServerStateTransition	V4, V4.1, V4.2, V4.3, V4.4	Enhanced streaming with `has_more` flag
V5.1 ServerStateTransition	V5.1, V5.2, V5.3, V5.4, V5.5, V5.6, V5.7, V5.8, V6	Adds `NEGOTIATION` state, separates authentication

These traits are composed into protocol classes using PHP's trait system, allowing for incremental evolution of state management across protocol versions.

Sources: src/protocol/AProtocol.php154

Streaming State Management

The `has_more` Flag

Starting with Protocol V4, the server includes a has_more flag in SUCCESS responses to PULL and DISCARD messages. When true, this indicates that more records are available and the state should remain STREAMING (or TX_STREAMING in a transaction):

Without the has_more flag, the state transitions back to READY (or TX_READY).

Sources: src/protocol/AProtocol.php157-160

The `openStreams` Counter

The openStreams property tracks the number of active result streams within a transaction:

When executing multiple RUN statements within a transaction before consuming their results, each creates a stream. The counter is incremented on each RUN SUCCESS and decremented on each PULL/DISCARD SUCCESS (when has_more is false). The state remains TX_STREAMING as long as openStreams > 0, even after completing one stream.

Sources: src/protocol/AProtocol.php33-39 src/protocol/AProtocol.php157-160

State Transition Examples

Persistent Connection State Recovery

When using PStreamSocket for persistent connections, the library caches the protocol version and attempts to reuse the connection. Upon reconnection, the state is set to INTERRUPTED:

The library then issues a RESET command to validate the connection. If the reset succeeds, the state transitions to READY. If it fails, the connection is closed and a fresh handshake is performed:

Sources: src/Bolt.php174 src/Bolt.php176-180

Protocol Version Differences

V1 and V2 State Management

V1/V2 use INIT for authentication and include a FAILED state that requires ACK_FAILURE to recover:

Sources: tests/protocol/V1Test.php93-96 tests/protocol/V1Test.php203-205

V3+ Transaction States

V3 introduced explicit transaction control with BEGIN, COMMIT, and ROLLBACK, requiring new states TX_READY and TX_STREAMING:

Sources: tests/protocol/V3Test.php128-130

V4+ Streaming Enhancements

V4 refined streaming with the has_more flag, allowing the server to control batching:

Sources: tests/protocol/V4Test.php45-49

V5.1+ Authentication Separation

V5.1 separates authentication into distinct LOGON/LOGOFF messages and introduces the NEGOTIATION state:

Sources: src/Bolt.php155-156

State Transition on Connection Loss

When a response signature indicates a terminal failure or when goodbye() is called, the state transitions to DEFUNCT and the connection is disconnected:

A DEFUNCT state requires creating a new connection instance; the existing connection cannot be recovered.

Sources: src/protocol/AProtocol.php161-162 tests/protocol/V3Test.php214-215

State Validation in Tests

The test suite extensively validates state transitions across all protocol versions. Each protocol version test class (e.g., V1Test, V3Test, V4Test) includes assertions that verify:

Initial state before message execution
Expected state after successful responses
Expected state after failure responses
Expected state after ignored responses (in INTERRUPTED state)

Example from V1 tests:

Sources: tests/protocol/V1Test.php89-91 tests/protocol/V3Test.php97-99 tests/protocol/V4Test.php45-49

Summary

Server state management is a critical component that:

Tracks session lifecycle from authentication through query execution to disconnection
Enforces valid message sequences by maintaining awareness of what operations are permissible
Handles transactions with dedicated states for transactional vs. non-transactional contexts
Manages streaming using the has_more flag and openStreams counter
Enables error recovery through state transitions like FAILED → READY
Supports persistent connections via the INTERRUPTED state and reset validation
Evolves across protocol versions using trait composition for version-specific state machines

The state machine ensures that the client accurately mirrors the server's operational state, preventing invalid operations and providing clear error recovery paths.

Sources: src/protocol/AProtocol.php29 src/protocol/AProtocol.php154-165 src/Bolt.php155-156

Refresh this wiki

URL: https://deepwiki.com/stefanak-michal/php-bolt-driver/3.3-server-state-management