Class Connection.ConnectionOptions

Inheritance

object

Connection.ConnectionOptions

XrplClient.ClientOptions

Namespace: Xrpl.Client

Assembly: Xrpl.dll

Syntax

public class Connection.ConnectionOptions

Properties

AdminPassword

Admin password for rippled's admin_password port-stanza setting. See AdminUser.

Declaration

public string AdminPassword { get; set; }

Property Value

Type	Description
string

AdminUser

Admin user for rippled's admin_user port-stanza setting.

Declaration

public string AdminUser { get; set; }

Property Value

Type	Description
string

Remarks

Unlike authorization, these credentials travel inside the JSON body of every request — that is the only mechanism rippled accepts for admin commands over ws/wss. Both AdminUser and AdminPassword must be set for them to be sent.

ConnectionAcquisitionTimeout

Maximum time to wait for connection when using WaitForConnection request policy. This is the total time allowed for multiple connection attempts, including retry delays. Must be >= ConnectionAttemptTimeout to allow at least one full connection attempt. Default: 30 seconds.

Declaration

public TimeSpan ConnectionAcquisitionTimeout { get; set; }

Property Value

Type	Description
TimeSpan

ConnectionAttemptTimeout

Timeout for a single WebSocket connection attempt. If the connection cannot be established within this time, it will fail and trigger reconnection logic. Should be shorter than ConnectionAcquisitionTimeout to allow multiple retry attempts. Default: 30 seconds.

Declaration

public TimeSpan ConnectionAttemptTimeout { get; set; }

Property Value

Type	Description
TimeSpan

HealthCheckInterval

Gets or sets how often the background health check runs — the timer that notices a socket which is no longer Open and hands the client to the fast-reconnect path.
Default: 20 seconds, the interval this check has always used.

Declaration

public TimeSpan HealthCheckInterval { get; set; }

Property Value

Type	Description
TimeSpan

Remarks

Exposed primarily so tests can exercise the ping and fast-reconnect paths without waiting out the default interval; those paths were previously unreachable from a unit test, which is why they went uncovered through several fixes. Lowering it in production only makes the state check more frequent — it sends no network requests of its own.

InactivityTimeout

Gets or sets how long a connection may go without any inbound activity before the health check treats it as dead and hands it to the fast-reconnect path.
Applies only when UseCustomPing is enabled.
Default: 60 seconds, the threshold this check has always used.

Declaration

public TimeSpan InactivityTimeout { get; set; }

Property Value

Type	Description
TimeSpan

Remarks

A socket whose peer vanished stays Open until the next I/O, so silence is the only signal that reaches the client - and it is a signal only while keepalive pings are being sent, because an idle connection with no subscriptions receives nothing by design. With UseCustomPing off this value is not consulted; see the remarks on UseCheckHealth. Exposed together with HealthCheckInterval so the fast-reconnect path is reachable from a test in under a second instead of over a minute.

MaxReconnectAttempts

Gets or sets the maximum number of times the system will attempt to reconnect after a disconnection.

Declaration

public int MaxReconnectAttempts { get; set; }

Property Value

Type	Description
int

Remarks

Set this property to limit how many reconnection attempts are made before giving up. A value of 0 disables automatic reconnection.

ReconnectBaseDelay

Gets or sets the base delay interval used between automatic reconnection attempts.

Declaration

public TimeSpan ReconnectBaseDelay { get; set; }

Property Value

Type	Description
TimeSpan

ReconnectMaxDelay

Gets or sets the maximum delay between automatic reconnection attempts after a disconnection.

Declaration

public TimeSpan ReconnectMaxDelay { get; set; }

Property Value

Type	Description
TimeSpan

Remarks

This value determines the upper bound for the time interval between reconnection attempts. If the connection is lost, the delay between retries will not exceed this value, even if a backoff strategy is used.

RequestPolicy

Gets or sets the policy that determines how failed requests are handled.

Declaration

public RequestFailurePolicy RequestPolicy { get; set; }

Property Value

Type	Description
RequestFailurePolicy

Remarks

Use this property to specify the strategy for handling request failures,
such as whether to retry, delay, or fail immediately.
The selected policy affects how the system responds to transient errors or network issues.

RequestTimeout

Timeout for individual API requests after connection is established. This controls how long to wait for a response to a single request (e.g., account_info, submit). Default: 40 seconds.

Declaration

public TimeSpan RequestTimeout { get; set; }

Property Value

Type	Description
TimeSpan

StopAfterMaxAttempts

Gets or sets a value indicating whether the operation should stop after reaching the maximum number of attempts.

Declaration

public bool StopAfterMaxAttempts { get; set; }

Property Value

Type	Description
bool

Remarks

Set this property to true to prevent further retries once the maximum attempt count is reached. If set to false, the operation may continue beyond the maximum attempts, depending on the retry policy.

StreamMessageQueueCapacity

How many stream messages may wait for the consumer before the oldest are discarded.

Declaration

public int StreamMessageQueueCapacity { get; set; }

Property Value

Type	Description
int

Remarks

Stream events are handed to a background reader through a bounded channel, so a slow handler never blocks the receive loop. What it does instead is fall behind, and past this many queued messages the oldest are dropped to make room - DroppedStreamMessages counts them.

Raise it for a consumer that must not miss events and can absorb the memory (each slot holds one frame); lower it to bound memory harder, accepting more loss. Default 10 000.

UseCheckHealth

Gets or sets a value indicating whether to enable periodic background health monitoring of the WebSocket connection.
When enabled, the local connection state is checked every HealthCheckInterval. If the WebSocket is detected as no longer Open, an automatic reconnection is triggered.
This check does not send any network requests — it only inspects the local connection state.
Automatically enabled when UseCustomPing is set to true.
Default: false.

Declaration

public bool UseCheckHealth { get; set; }

Property Value

Type	Description
bool

Remarks

On its own this detects only a socket the runtime already knows is gone. A peer that vanished without closing leaves the socket Open, and the only signal for that is silence - which is a signal only when something is expected to arrive. That is what UseCustomPing adds: keepalive pings whose answers keep the activity clock moving, so InactivityTimeout can mean "the node stopped answering". Without pings an idle connection - no subscriptions, no requests - receives nothing at all, and silence would declare a healthy socket dead every InactivityTimeout; so the inactivity check runs only when UseCustomPing is enabled.

UseCustomPing

Gets or sets a value indicating whether to use a custom ping
implementation instead of the default behavior.

Declaration

public bool UseCustomPing { get; set; }

Property Value

Type	Description
bool

authorization

Raw user:password pair sent as an HTTP Basic Authorization header on the WebSocket upgrade handshake. Matches the authorization option of xrpl.js.

Declaration

public string authorization { get; set; }

Property Value

Type	Description
string

Remarks

rippled itself does not check Basic auth on the ws/wss handshake — its user/password port-stanza settings only apply to plain HTTP JSON-RPC. This option is for reaching a node behind a reverse proxy or a provider that requires Basic auth. For admin commands over ws/wss use AdminUser/AdminPassword instead. Ignored under WebAssembly — the browser WebSocket API cannot set request headers.

headers

Extra HTTP headers to put on the WebSocket upgrade handshake.

Declaration

public Dictionary<string, string> headers { get; set; }

Property Value

Type	Description
Dictionary<string, string>

Remarks

Ignored under WebAssembly — the browser WebSocket API cannot set request headers.