Timeout Configuration and Error Handling

This page documents timeout configuration mechanisms, error types, retry logic, and error recovery patterns in the Bolt connection layer. It covers how timeouts are set and enforced across different connection implementations, the distinction between ConnectException and ConnectionTimeoutException, automatic retry mechanisms for transient errors, and strategies for recovering from timeout and connection failures.

For information about connection implementations and their capabilities, see Connection Implementations. For persistent connection-specific error handling and cache validation, see Persistent Connections with PStreamSocket.

Timeout Configuration

All connection implementations support configurable timeouts for connection establishment, read operations, and write operations. The timeout is specified in seconds and supports fractional values for millisecond precision.

Default Timeout Values

The default timeout is 15 seconds, defined in the IConnection interface constructor signature:

src/connection/IConnection.php16

This default applies to all three connection implementations: Socket, StreamSocket, and PStreamSocket.

Sources: src/connection/IConnection.php16 src/connection/AConnection.php14-26

Setting Timeout on Instantiation

Timeouts are configured during connection instantiation by passing the third constructor parameter:

Sources: src/connection/Socket.php28-34 tests/PerformanceTest.php23 tests/connection/ConnectionTest.php34-44

Runtime Timeout Adjustment

Timeouts can be modified after connection instantiation using the setTimeout() method. This is useful for adjusting timeouts based on query characteristics:

Sources: src/connection/AConnection.php57-60 tests/connection/ConnectionTest.php49-58 tests/packstream/v1/UnpackerTest.php32

Timeout Application Diagram

Sources: src/connection/Socket.php49-141 src/connection/StreamSocket.php127-144 src/connection/AConnection.php57-60

Error Types

The library defines two primary exception types for connection errors, both located in the Bolt\error namespace:

Exception Class	Base Class	Use Case
ConnectException	Exception	General connection failures: invalid host, port unreachable, SSL errors, socket creation failures
ConnectionTimeoutException	ConnectException	Timeout-specific failures: connection timeout, read timeout, write timeout

Sources: src/connection/Socket.php6-7 src/connection/StreamSocket.php7-8

ConnectException

Thrown for non-timeout connection failures. Common scenarios include:

• Connection refused: Server not listening on specified port
• DNS resolution failure: Invalid hostname
• SSL/TLS negotiation failure: Certificate validation errors
• Socket creation failure: Missing ext-sockets extension
• Remote host closed connection: Server terminated connection unexpectedly

src/connection/Socket.php36-45

Sources: src/connection/Socket.php30-106 tests/error/ErrorsTest.php16-22

ConnectionTimeoutException

A specialized subclass of ConnectException thrown when operations exceed configured timeout. The exception message includes the timeout value:

Connection timeout reached after {timeout} seconds.

Three distinct timeout scenarios exist:

1. Connection Establishment Timeout: Initial TCP handshake exceeds timeout
2. Read Timeout: No data received within timeout period
3. Write Timeout: Unable to send data within timeout period

Sources: src/connection/Socket.php152-156 src/connection/StreamSocket.php81-98

Error Type Decision Diagram

Sources: src/connection/Socket.php149-159 src/connection/StreamSocket.php80-103

Implementation Details by Connection Type

Socket Implementation

The Socket class uses PHP's ext-sockets extension with granular timeout control:

Timeout Configuration

src/connection/Socket.php131-141

The timeout is split into seconds and microseconds for precise control. Both receive (SO_RCVTIMEO) and send (SO_SNDTIMEO) timeouts are configured.

Manual Timeout Enforcement

In addition to socket-level timeouts, Socket::read() manually tracks elapsed time:

src/connection/Socket.php93-96

This dual-layer approach ensures timeout detection even if socket-level timeouts fail to trigger properly.

Sources: src/connection/Socket.php85-141

StreamSocket Implementation

The StreamSocket class uses PHP streams with stream_set_timeout():

src/connection/StreamSocket.php136-144

Stream Metadata Timeout Detection

StreamSocket::read() checks stream metadata for timeout status:

src/connection/StreamSocket.php102-103

Manual Timeout Check

Like Socket, StreamSocket also manually tracks elapsed time:

src/connection/StreamSocket.php96-98

Sources: src/connection/StreamSocket.php92-144

Timeout Enforcement Comparison

Mechanism	Socket	StreamSocket
Socket-level timeout	SO_RCVTIMEO / SO_SNDTIMEO	stream_set_timeout()
Manual elapsed time check	✓ (read/write)	✓ (read/write)
Metadata inspection	SOCKET_ETIMEDOUT error code	timed_out metadata flag
Precision	Microseconds	Microseconds

Sources: src/connection/Socket.php131-141 src/connection/StreamSocket.php136-144

Retry Logic for Transient Errors

The Socket implementation includes automatic retry logic for transient socket errors that may occur due to system-level interruptions or non-blocking operations.

Retryable Error Codes

src/connection/Socket.php23-26

Write Retry Logic

src/connection/Socket.php71-78

Read Retry Logic

src/connection/Socket.php97-103

Retry Flow Diagram

Sources: src/connection/Socket.php23-115

Note: StreamSocket does not implement explicit retry logic for transient errors. Operations either succeed or throw an exception immediately.

Sources: src/connection/StreamSocket.php69-114

Error Recovery Patterns

Timeout Recovery and Reset

When a timeout occurs during query execution, the connection may be in an inconsistent state. The recommended recovery pattern involves:

1. Catch the ConnectionTimeoutException
2. Increase the timeout
3. Send a reset() message to cancel the running query
4. Handle the expected FAILURE response
5. Reconnect if necessary

Example from Tests

tests/connection/ConnectionTest.php78-119

Sources: tests/connection/ConnectionTest.php78-119

Connection State After Timeout

After a timeout exception, the connection's state depends on when the timeout occurred:

Timeout Point	Connection State	Recovery Action
During connect()	Not established	Create new connection
During write()	Partial write possible	Reset or reconnect
During read()	Waiting for response	Reset to cancel, then reconnect
During long query	Server still processing	Reset, wait for FAILURE, reconnect

Sources: tests/connection/ConnectionTest.php78-119

Error Recovery Sequence Diagram

Sources: tests/connection/ConnectionTest.php78-119 src/connection/Socket.php149-159

Best Practices

1. Choose Appropriate Timeouts

Match timeout values to expected query durations:

Sources: tests/PerformanceTest.php23 tests/connection/ConnectionTest.php34-58

2. Use Millisecond Precision for Fast-Fail

For scenarios requiring quick failure detection:

Sources: tests/connection/ConnectionTest.php37-84

3. Adjust Timeouts Dynamically

Modify timeouts based on query characteristics:

Sources: tests/connection/ConnectionTest.php49-58

4. Implement Proper Error Recovery

Always handle timeouts with appropriate recovery:

Sources: tests/connection/ConnectionTest.php78-119

5. Consider Connection Type for Timeouts

Choose connection implementation based on timeout requirements:

Requirement	Recommended Implementation
Precise timeout control	Socket (dual-layer timeout enforcement)
SSL/TLS with timeouts	StreamSocket (built-in SSL, good timeout handling)
Persistent connections	PStreamSocket (inherits StreamSocket timeout behavior)

Sources: src/connection/Socket.php1-160 src/connection/StreamSocket.php1-145

6. Monitor Timeout Occurrences

Track timeout exceptions to identify slow queries:

7. Set Transaction-Level Timeouts

For V3+ protocols with explicit transaction support, use both connection and transaction timeouts:

Sources: tests/connection/ConnectionTest.php54-57

---

Page Sources:

• src/connection/Socket.php1-160
• src/connection/StreamSocket.php1-145
• src/connection/AConnection.php1-61
• src/connection/IConnection.php1-42
• tests/connection/ConnectionTest.php1-125
• tests/PerformanceTest.php1-64
• tests/error/ErrorsTest.php1-46
• tests/packstream/v1/UnpackerTest.php19-34