Struct TestBroker

Source

pub struct TestBroker { /* private fields */ }

Expand description

Broker for use in tests.

This type is a simple wrapper around aldrin_broker::Broker and aldrin_broker::BrokerHandle. All method of BrokerHandle can be called on this type as well due to its Deref implementation.

The underlying Broker is not automatically started. Users must take the broker and run it manually.

See the crate-level documentation for usage examples.

Implementations§

Source §

impl TestBroker

Source

pub fn new() -> Self

Creates a new broker.

Source

pub fn handle(&self) -> &BrokerHandle

Returns a handle to the broker.

Source

pub fn take_broker(&mut self) -> Broker

Takes the broker out of this struct.

After creating a TestBroker, the actual Broker must be taken out and run.

§Panics

This function panics when the Broker has already been taken out. It must be called only once.

Source

pub async fn add_client(&mut self) -> TestClient

Add a new client to the broker.

Methods from Deref<Target = BrokerHandle>§

Source

pub async fn connect<T>( &mut self, t: T, ) -> Result<Connection<T>, EstablishError<<T as AsyncTransport>::Error>>
where T: AsyncTransport + Unpin,

Establishes a new connection.

This method performs the initial connection setup and Aldrin handshake between broker and client. If successful, the resulting Connection must be run and polled to completion, much like the Broker itself.

The Aldrin protocol allows client and broker to exchange custom user data during the handshake. This function will ignore the client’s user data. If you need to inspect the data and possibly reject some clients, then use begin_connect.

§Examples

// Create an AsyncTransport to a new incoming connection:
// let t = ...

// Establish a connection to the client:
let connection = broker_handle.connect(t).await?;

// Run the connection:
tokio::spawn(connection.run());

// The connection is now active and the client is fully connected.

Source

pub async fn begin_connect<T>( &mut self, t: T, ) -> Result<PendingConnection<T>, EstablishError<<T as AsyncTransport>::Error>>
where T: AsyncTransport + Unpin,

Begins establishing a new connection.

Unlike connect, this function will not automatically establish a connection. It will only receive the client’s initial connection message. This allows you to inspect the client’s user data and accept or reject the client.

Source

pub async fn shutdown(&mut self)

Shuts down the broker.

This method informs the Broker that it should initiate shutdown, but doesn’t block until Broker has done so. The Broker will cleanly shut down all connections, before the Broker::run returns.

§Examples

use aldrin_broker::Broker;

let broker = Broker::new();
let mut handle = broker.handle().clone();
let join = tokio::spawn(broker.run());

// Tell the broker to shutdown:
handle.shutdown().await;

// `run` will return as soon as all connections have been shut down:
join.await?;

Source

pub async fn shutdown_idle(&mut self)

Shuts down the broker when the last client disconnects.

This method informs the Broker that it should shutdown as soon as there are no active clients left.

Calling this method does not prevent new connections. It also doesn’t actively tell the connected clients to shut down.

§Examples

use aldrin_broker::Broker;

let broker = Broker::new();
let mut handle = broker.handle().clone();
let join = tokio::spawn(broker.run());

// Tell the broker to shutdown when it becomes idle:
handle.shutdown_idle().await;

// `run` will return as soon as the last client disconnects:
join.await?;

Source

pub async fn shutdown_connection( &mut self, conn: &ConnectionHandle, ) -> Result<(), BrokerShutdown>

Shuts down a specific connection.

Similar to the other shutdown methods, this method will only initiate shutdown of the Connection specified by conn and then return before it has actually shut down.

§Examples

// Create an AsyncTransport to a new incoming connection:
// let t = ...

// Establish a connection to the client:
let connection = broker_handle.connect(t).await?;

// Get a handle to the connection:
let connection_handle = connection.handle().clone();

// Run the connection:
let connection_join = tokio::spawn(connection.run());

// Tell the broker to shut down the connection again:
broker_handle.shutdown_connection(&connection_handle).await?;
connection_join.await??;