proxystore.p2p.relay.client¶
Client interface to a relay server.
RelayClient
¶
RelayClient(
address: str,
*,
client_name: str | None = None,
client_uuid: UUID | None = None,
extra_headers: dict[str, str] | None = None,
reconnect_task: bool = True,
ssl_context: SSLContext | None = None,
timeout: float = 10,
verify_certificate: bool = True
)
Client interface to a relay server.
This interface abstracts the low-level WebSocket connection to a relay server to provide automatic reconnection.
Tip
This class can be used as an async context manager!
Note
WebSocket connections are not opened until a message is sent,
a message is received, or
connect()
is called. Initializing the client with await
will call
connect()
.
Parameters:
-
address
(str
) –Address of the relay server. Should start with
ws://
orwss://
. -
client_name
(str | None
, default:None
) –Optional name of the client to use when registering with the relay server. If
None
, the hostname will be used. -
client_uuid
(UUID | None
, default:None
) –Optional UUID of the client to use when registering with the relay server. If
None
, one will be generated. -
extra_headers
(dict[str, str] | None
, default:None
) –Arbitrary HTTP headers to add to the handshake request. If connecting to a relay server with authentication, such as one using the
GlobusAuthenticator
, the headers should include theAuthorization
header containing the bearer token. -
reconnect_task
(bool
, default:True
) –Spawn a background task which will automatically reconnect to the relay server when the websocket client closes. Otherwise, reconnections will only be attempted when sending or receiving a message.
-
ssl_context
(SSLContext | None
, default:None
) –Custom SSL context to pass to
websockets.connect()
. A TLS context is created withssl.create_default_context()
when connecting to awss://
URI andssl_context
is not provided. -
timeout
(float
, default:10
) –Time to wait in seconds on relay server connection.
-
verify_certificate
(bool
, default:True
) –Verify the relay server's SSL certificate. Only used if
ssl_context
isNone
and connecting to awss://
URI.
Raises:
-
RelayRegistrationError
–If the connection to the relay server is closed, does not reply to the registration request within the timeout, or replies with an error.
-
ValueError
–If address does not start with
ws://
orwss://
.
Source code in proxystore/p2p/relay/client.py
websocket
property
¶
Websocket connection to the relay server.
Raises:
-
RelayNotConnectedError
–if the websocket connection to the relay server is not open. This usually indicates that
connect()
needs to be called.
connect
async
¶
connect(retry: bool = True) -> None
Connect to the relay server.
Note
Typically this does not need to be called because the send and receive methods will automatically call this.
Note
This method is a no-op if a connection is already established.
Otherwise, a new connection will be attempted with
exponential backoff when retry
is True for connection failures.
Parameters:
-
retry
(bool
, default:True
) –Retry the connection with exponential backoff starting at one second and increasing to a max of 60 seconds. Retrying is only performed for certain connection error types:
ConnectionRefusedError
,TimeoutError
, and certainConnectionClosed
types. Specifically, retrying will not be performed if the connection closed status code indicates forbidden or unauthorized errors. These typically cannot be recovered from and must be addressed by the user.
Source code in proxystore/p2p/relay/client.py
close
async
¶
Close the connection to the relay server.
Source code in proxystore/p2p/relay/client.py
recv
async
¶
recv() -> RelayMessage
Receive the next message.
Returns:
-
RelayMessage
–The message received from the relay server.
Raises:
-
RelayMessageDecodeError
–If the message received cannot be decoded into the appropriate message type.
Source code in proxystore/p2p/relay/client.py
send
async
¶
send(message: RelayMessage) -> None
Send a message.
Parameters:
-
message
(RelayMessage
) –The message to send to the relay server.