System XLS: Peer to Peer Disconnect Handshake

[Tapanito]

title: Peer Disconnection Handshake
description: Adds diagnostic headers to the peer protocol's connection termination message to aid in debugging disconnections.
author: Vito Tumas (vtumas@ripple.com)
status: Discussion
category: System
created: 2025-08-28

Abstract

This specification proposes an enhancement to the XRP Ledger peer-to-peer protocol to include diagnostic headers in connection termination messages. Currently, when a peer closes a connection, it provides no reason, making it difficult to differentiate between network failures and application-level issues like resource exhaustion. By adding headers that specify the reason for closure and the peer's last known ledger state, this proposal aims to provide crucial data for debugging and improving network stability.

Motivation

Network operators frequently observe peer disconnections, with a leading hypothesis being that remote peers drop connections due to high resource usage on the local server. Verifying this is challenging because peer servers act as black boxes; without access to their debug logs, it's nearly impossible to determine the root cause of a disconnection.

This proposal introduces a simple, non-intrusive mechanism for peers to communicate the reason for termination. By sending a small set of diagnostic headers when closing a connection—similar to the handshake performed when opening one—peers can provide valuable context. This data will enable operators to more effectively diagnose and resolve issues related to resource limits, idle timeouts, and ledger synchronization problems.

Specification

When a rippled server decides to terminate a p2p connection, it should send a final message containing a set of HTTP-style headers before closing the underlying TCP socket. This message is intended for diagnostic purposes and helps the remote peer understand the reason for the disconnection.

The following headers are included in the termination message:

Header	Value Type	Description
Connection	string	Must be set to Close. Explicitly indicates that the server is closing the connection.
X-Reason	string	A string specifying the reason for closure. See the list of predefined reason codes below.
Closed-Ledger	string (uint)	The sequence number of the last ledger the server has closed. This aids in diagnosing synchronization issues.
Previous-Ledger	string (uint)	The sequence number of the last fully validated ledger known to the server.
Network-Time	string (uint)	The network-adjusted time as seen by the peer, in seconds since the Ripple epoch.

X-Reason Codes

To standardize reporting, the following initial values for the X-Reason header are proposed:

• resource_limit_exceeded: The connection was terminated because the remote peer was consuming excessive resources (e.g., CPU, memory, I/O) or sending too many messages.
• idle_timeout: The connection was closed after a period of inactivity.
• protocol_violation: The remote peer violated the p2p protocol.
• shutdown: The server is shutting down cleanly.
• unspecified: The server is closing the connection for a reason not covered by other codes.

Rationale

The design of this feature mirrors the existing handshake process for new peer connections, which already uses HTTP-style headers. Reusing this format simplifies implementation and maintains consistency within the peer protocol. The chosen headers provide a balance between delivering valuable diagnostic information and minimizing the amount of data transmitted upon disconnection. The inclusion of ledger and time information, already sent during the initial handshake, is critical for correlating disconnection events with potential ledger state or sync-related problems.

Backwards Compatibility

This change is fully backwards compatible.

• When a server implementing this specification closes a connection to an older peer, the older peer will ignore the unrecognized termination headers and proceed with its standard connection closure logic.
• When an older peer closes a connection to a newer server, the newer server will simply not receive any termination headers and will handle the disconnection as it does today.

No protocol breakage or adverse effects are anticipated.

Test Plan

An implementation of this specification requires the following tests:

1. Unit Tests: Verify that the termination message is correctly formatted with all required and optional headers.
2. Integration Tests:
   • Set up two peers that support this specification. Induce a disconnection (e.g., by exceeding a resource limit) on Peer A and verify that Peer B receives and correctly parses the termination headers.
   • Test a scenario where a peer supporting this specification disconnects from a peer that does not. Confirm that the older peer closes the connection gracefully.
   • Verify the behavior for each of the defined X-Reason codes.

Security Considerations

The primary security consideration for this feature is the potential for minor information disclosure. The X-Reason header reveals a peer's internal state (e.g., resource_limit_exceeded implies the server is under high load). An attacker could potentially use this information to identify and target stressed nodes in the network.

To mitigate this risk, the provided reasons are generic and do not expose specific metrics. The other headers (Closed-Ledger, Previous-Ledger, Network-Time) expose information that is already publicly available or exchanged during the initial handshake. The overall security risk is assessed as low.