Class Connection

Inheritance

object

Connection

Namespace: Xrpl.Client

Assembly: Xrpl.dll

Syntax

public class Connection

Constructors

Connection(string, ConnectionOptions?)

Declaration

public Connection(string server, Connection.ConnectionOptions? options = null)

Parameters

Type	Name	Description
string	server
Connection.ConnectionOptions	options

Fields

connectionManager

Declaration

public ConnectionManager connectionManager

Field Value

Type	Description
ConnectionManager

requestManager

Declaration

public RequestManager requestManager

Field Value

Type	Description
RequestManager

timer

Declaration

public Timer timer

Field Value

Type	Description
Timer

ws

Declaration

public volatile WebSocketClient ws

Field Value

Type	Description
WebSocketClient

Properties

CurrentConnectionState

Declaration

public XrpConnectionState CurrentConnectionState { get; }

Property Value

Type	Description
XrpConnectionState

DroppedStreamMessages

How many stream messages have been discarded because the consumer fell behind.

Declaration

public long DroppedStreamMessages { get; }

Property Value

Type	Description
long

Remarks

The queue feeding stream handlers is bounded (see StreamMessageQueueCapacity) and discards the oldest message when full, so a slow handler costs events rather than stalling the socket. That discard used to be entirely silent: nothing threw, nothing logged, and a consumer building state from the stream simply drifted from the ledger with no way to notice. This counter is the way to notice - non-zero and rising means handlers are not keeping up.

Counts across the lifetime of this connection, including across reconnects and ChangeServer, since the same object serves them all.

FallbackDispatchedStreamMessages

How many stream frames were dispatched outside the queue.

Declaration

public long FallbackDispatchedStreamMessages { get; }

Property Value

Type	Description
long

Remarks

The fallback path holds none of the queue's guarantees: no capacity bound, no eviction counting, no single-reader ordering. Three things send a frame down it - the processor not being up yet, the processor having been stopped, and the channel refusing a write because its writer is already completed - and none of them were visible from outside until this counter existed.

Cumulative over the life of the connection, and a non-zero value is not by itself a fault: a client that was driven before it connected, or after it disconnected, legitimately has frames here. What means something is an increase across a connect: the startup window this counter was added to measure is closed, so the number should not move while a connection is being established.

StaleSessionFramesDropped

How many stream frames were discarded because they came from a session that is no longer active.

Declaration

public long StaleSessionFramesDropped { get; }

Property Value

Type	Description
long

Remarks

A socket being retired keeps delivering until its graceful close finishes, so a handful of frames can arrive after a reconnect or ChangeServer has already moved on. They are dropped rather than delivered: after a change of network they would otherwise describe a different chain entirely. Counted separately from DroppedStreamMessages, which is about consumers falling behind - these two mean different things and a non-zero value here is normal right after a reconnect.

config

Declaration

public Connection.ConnectionOptions config { get; }

Property Value

Type	Description
Connection.ConnectionOptions

url

Declaration

public string url { get; }

Property Value

Type	Description
string

Methods

Base64Decode(string)

Declaration

public static string Base64Decode(string base64EncodedData)

Parameters

Type	Name	Description
string	base64EncodedData

Returns

Type	Description
string

Base64Encode(string)

Declaration

public static string Base64Encode(string plainText)

Parameters

Type	Name	Description
string	plainText

Returns

Type	Description
string

ChangeServer(string, ConnectionOptions?, CancellationToken)

Moves the client to another server: retires the current session and connects to server.

Declaration

public Task ChangeServer(string server, Connection.ConnectionOptions? options = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
string	server
Connection.ConnectionOptions	options
CancellationToken	cancellationToken

Returns

Type	Description
Task

Remarks

This is a transition of the connection and it can be superseded by a later one - a Disconnect(), another ChangeServer, a Connect() - issued while it is still under way, from another thread or from a consumer callback it runs. It then stops where it is, leaves the rest to the operation that took over, and tells the caller: NotConnectedException when a Disconnect() won, because the client is down; System.OperationCanceledException when anything else won, because the client is connecting, or connected, somewhere this call did not ask for. It used to reset the disconnect and connect anyway - the client online after the consumer took it down.

The old session is retired in the background whatever happens, and the switch is announced through OnSessionEnded before the new connection is opened.

Connect(CancellationToken)

Declaration

public Task Connect(CancellationToken cancellationToken)

Parameters

Type	Name	Description
CancellationToken	cancellationToken

Returns

Type	Description
Task

Disconnect()

Declaration

public Task<int> Disconnect()

Returns

Type	Description
Task<int>

DisconnectAndWaitAsync(TimeSpan, CancellationToken)

Disconnects and waits for the WebSocket to be fully closed and cleaned up.

Declaration

public Task DisconnectAndWaitAsync(TimeSpan timeout, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
TimeSpan	timeout	Maximum time to wait for cleanup.
CancellationToken	cancellationToken	Cancellation token.

Returns

Type	Description
Task

GRequest<T, R>(R, TimeSpan?, RequestFailurePolicy?, CancellationToken)

Declaration

public Task<XrplResponse<T>> GRequest<T, R>(R request, TimeSpan? timeout = null, RequestFailurePolicy? policyOverride = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
R	request
TimeSpan?	timeout
RequestFailurePolicy?	policyOverride
CancellationToken	cancellationToken

Returns

Type	Description
Task<XrplResponse<T>>

Type Parameters

Name	Description
T
R

GetUrl()

Declaration

public string GetUrl()

Returns

Type	Description
string

HasConnectionAsync(TimeSpan?)

Declaration

public Task<bool> HasConnectionAsync(TimeSpan? timeout = null)

Parameters

Type	Name	Description
TimeSpan?	timeout

Returns

Type	Description
Task<bool>

IsConnected()

Declaration

public bool IsConnected()

Returns

Type	Description
bool

OnMessage(string)

Declaration

public Task OnMessage(string message)

Parameters

Type	Name	Description
string	message

Returns

Type	Description
Task

Request(Dictionary<string, object>, TimeSpan?, RequestFailurePolicy?, CancellationToken)

Declaration

public Task<XrplResponse<Dictionary<string, object>>> Request(Dictionary<string, object> request, TimeSpan? timeout = null, RequestFailurePolicy? policyOverride = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
Dictionary<string, object>	request
TimeSpan?	timeout
RequestFailurePolicy?	policyOverride
CancellationToken	cancellationToken

Returns

Type	Description
Task<XrplResponse<Dictionary<string, object>>>

State()

Declaration

public WebSocketState State()

Returns

Type	Description
WebSocketState

WaitForConnectionAsync(TimeSpan?, CancellationToken)

Declaration

public Task WaitForConnectionAsync(TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
TimeSpan?	timeout
CancellationToken	cancellationToken

Returns

Type	Description
Task

WaitForConnectionOutcomeAsync(TimeSpan?, CancellationToken)

How a wait for the connection ended.

Declaration

public Task<ConnectionWaitOutcome> WaitForConnectionOutcomeAsync(TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

Type	Name	Description
TimeSpan?	timeout
CancellationToken	cancellationToken

Returns

Type	Description
Task<ConnectionWaitOutcome>

Remarks

The same events NotConnectedException and its subtypes report, for callers who would rather read an answer than catch one: "it did not come back in time" is something a caller has to act on, not an exceptional event.

A bool would fold "timed out", "gave up" and "nothing is running" into one false, which is the confusion this whole family of types exists to remove. Two things stay exceptions: cancellation through the caller's own token, which is the .NET convention, and an invalid timeout, which is a mistake by the caller rather than an outcome of the connection.

WebsocketSendAsync(WebSocketClient, string)

Sends a message through the WebSocket connection, fire-and-forget.

Declaration

public void WebsocketSendAsync(WebSocketClient ws, string message)

Parameters

Type	Name	Description
WebSocketClient	ws	The WebSocket client to send through.
string	message	The message to send.

Remarks

Kept for callers outside this class. Request(Dictionary<string, object>, TimeSpan?, RequestFailurePolicy?, CancellationToken) and GRequest<T, R>(R, TimeSpan?, RequestFailurePolicy?, CancellationToken) use Xrpl.Client.Connection.SendRequestAsync(string) instead, which pairs the socket read with the send under the retirement lock and observes the send.

Exceptions

Type	Condition
DisconnectedException	Thrown when the WebSocket connection is null or closed.

Events

OnBookChanges

Declaration

public event OnBookChanges OnBookChanges

Event Type

Type	Description
OnBookChanges

OnConnected

Declaration

public event OnConnected OnConnected

Event Type

Type	Description
OnConnected

OnConnectionStatus

Declaration

public event Action<ConnectionStatusInfo> OnConnectionStatus

Event Type

Type	Description
Action<ConnectionStatusInfo>

OnConsensusPhase

Declaration

public event OnConsensusPhase OnConsensusPhase

Event Type

Type	Description
OnConsensusPhase

OnDisconnect

Declaration

public event OnDisconnect OnDisconnect

Event Type

Type	Description
OnDisconnect

OnError

Declaration

public event OnError OnError

Event Type

Type	Description
OnError

OnLedgerClosed

Declaration

public event OnLedgerClosed OnLedgerClosed

Event Type

Type	Description
OnLedgerClosed

OnManifestReceived

Declaration

public event OnManifestReceived OnManifestReceived

Event Type

Type	Description
OnManifestReceived

OnPathFind

Declaration

public event OnPathFind OnPathFind

Event Type

Type	Description
OnPathFind

OnPeerStatusChange

Declaration

public event OnPeerStatusChange OnPeerStatusChange

Event Type

Type	Description
OnPeerStatusChange

OnPing

Declaration

public event OnPing OnPing

Event Type

Type	Description
OnPing

OnServerStatus

Declaration

public event OnServerStatus OnServerStatus

Event Type

Type	Description
OnServerStatus

OnServerWarning

Declaration

public event OnServerWarning OnServerWarning

Event Type

Type	Description
OnServerWarning

OnSessionEnded

The connection that carried the subscriptions has ended - by any route.

Declaration

public event OnSessionEnded OnSessionEnded

Event Type

Type	Description
OnSessionEnded

Remarks

Subscriptions live on the node against one connection. When that connection goes, so do they, and a consumer has to resubscribe. Knowing when to is the hard part, because the connection can end in three different ways and until this event only the first was announced:

• the socket closes on its own, or the caller closes it with Disconnect - OnDisconnect fires;
• a ping timeout or a network drop makes the SDK retire the session and reconnect at once - only a RestoringConnection status went out;
• ChangeServer retires the session to move to another server - nothing went out at all, and the client reported Connected throughout, so a consumer had no way to notice its stream had gone quiet for good.

This event fires exactly once per session in all three cases, which makes it the single thing to subscribe to in order to know that a resubscribe is due. OnDisconnect keeps its own meaning - a socket closed - and still fires alongside it where it always did.

It reports a loss, not a readiness: on a server switch and on a fast reconnect it fires before the replacement connection is open, so the handler cannot resubscribe from where it stands. Note that the subscriptions are gone and send them again from OnConnected - which is also why the loss is announced first, so a consumer is never told to resubscribe after it has already seen the new connection come up.

Handlers are awaited before the SDK carries on, so a slow one holds up the very reconnect or server switch it is reporting. Keep the work short.

It does not fire for a connection attempt that never succeeded: there was no session, and so no subscription, to lose. It does fire when the client is disposed, since System.IDisposable.Dispose() closes the connection - and, because that close is not awaited, possibly after Dispose has returned. A handler that touches the client should be detached before disposing it.

OnTransaction

Declaration

public event OnTransaction OnTransaction

Event Type

Type	Description
OnTransaction

OnValidationReceived

Declaration

public event OnValidationReceived OnValidationReceived

Event Type

Type	Description
OnValidationReceived

OnWarning

Declaration

public event OnWarning OnWarning

Event Type

Type	Description
OnWarning