Crate holochain_websocket
source ·Expand description
Holochain utilities for websocket serving and connecting.
To establish an outgoing connection, use connect
which will return a tuple
(WebsocketSender
, WebsocketReceiver
)
To open a listening socket, use WebsocketListener::bind
which will give you a WebsocketListener
which is an async Stream whose items resolve to that same tuple (
WebsocketSender
,
WebsocketReceiver
).
If you want to be able to shutdown the stream use WebsocketListener::bind_with_handle
which will give you a tuple (ListenerHandle
, ListenerStream
).
You can use ListenerHandle::close
to close immediately or
ListenerHandle::close_on
to close on a future completing.
Example
use holochain_serialized_bytes::prelude::*;
use holochain_websocket::*;
use std::convert::TryInto;
use tokio_stream::StreamExt;
use url2::prelude::*;
#[derive(serde::Serialize, serde::Deserialize, SerializedBytes, Debug)]
struct TestMessage(pub String);
#[tokio::main]
async fn main() {
// Create a new server listening for connections
let mut server = WebsocketListener::bind(
url2!("ws://127.0.0.1:0"),
std::sync::Arc::new(WebsocketConfig::default()),
)
.await
.unwrap();
// Get the address of the server
let binding = server.local_addr().clone();
tokio::task::spawn(async move {
// Handle new connections
while let Some(Ok((_send, mut recv))) = server.next().await {
tokio::task::spawn(async move {
// Receive a message and echo it back
if let Some((msg, resp)) = recv.next().await {
// Deserialize the message
let msg: TestMessage = msg.try_into().unwrap();
// If this message is a request then we can respond
if resp.is_request() {
let msg = TestMessage(format!("echo: {}", msg.0));
resp.respond(msg.try_into().unwrap()).await.unwrap();
}
}
});
}
});
// Connect the client to the server
let (mut send, _recv) = connect(binding, std::sync::Arc::new(WebsocketConfig::default()))
.await
.unwrap();
let msg = TestMessage("test".to_string());
// Make a request and get the echoed response
let rsp: TestMessage = send.request(msg).await.unwrap();
assert_eq!("echo: test", &rsp.0,);
}
Structs
- Handle for shutting down a listener stream.
- Shuts down the receiver on drop or if you call close.
- A builder-style config struct for setting up websockets.
- Listens for connecting clients.
- Receive signals and requests from a connection.
- The sender half of an active connection.
Enums
- The response half to a
WebsocketMessage
. If this message is a requestRespond::is_request
you can respond withRespond::respond
. - The messages actually sent over the wire by this library. If you want to impliment your own server or client you will need this type or be able to serialize / deserialize it.
Functions
- Create a new external websocket connection.
Type Aliases
- New connection result returned from the
ListenerStream
. - Stream of new connections.
WebsocketSender
andWebsocketReceiver
for an active connection.- Closure for responding to a
Respond::Request