Writing a custom dnet transport
A dnet transport must implement the transport contract described in the transport contract.
What your transport must do
- Implement
futures::Sink<Outgoing, Error = dnet::Error<Other>>. - Implement
futures::Stream<Item = Result<Incoming, Other>>. - Preferably implement
futures::stream::FusedStreamas well. - Conditionally implement
dnet_base::Loggingbehind a “logging” feature in your crate.
The Other type is your transport-specific error type.
Sink
The outgoing side of a transport always uses dnet::Error<Other> as the Sink error type.
Example:
impl<Codec, Incoming, Outgoing> Sink<Outgoing> for MyTransport<Codec, Incoming, Outgoing> {
type Error = dnet::Error<MyError>;
// ... poll_ready, start_send, poll_flush, poll_close ...
}
Stream
The incoming side is a Stream of Result<Incoming, Other>, where the same Other error type is used directly in the stream item.
Note
Do not wrap stream item errors in
dnet::Error.
Example:
impl<Codec, Incoming, Outgoing> Stream for MyTransport<Codec, Incoming, Outgoing> {
type Item = Result<Incoming, MyError>;
// ... poll_next ...
}
The stream must return None to signal that the transport is closed (regardless of cause).
FusedStream
Implementing FusedStream is not strictly required but recommended.
impl<Codec, Incoming, Outgoing> FusedStream for MyTransport<Codec, Incoming, Outgoing> {
fn is_terminated(&self) -> bool {
// todo
}
}
Logging support
Conditionally implement dnet_base::Logging behind a “logging” feature in your crate.
See dnet transport implementations for reference of what to log, how and where.
Example:
pub struct MyTransport<Codec, Incoming, Outgoing> {
// ...
#[cfg(feature = "logging")]
logger: dnet::Logger,
}
impl<Codec, Incoming, Outgoing> MyTransport<Codec, Incoming, Outgoing> {
pub fn new(/* ... */) -> Self {
WebSocketTransport {
// ...
#[cfg(feature = "logging")]
logger: dnet::Logger::new::<Self>(),
}
}
}
// ... todo: remember to log in your poll methods
#[cfg(feature = "logging")]
impl<Codec, Incoming, Outgoing> dnet_base::Logging for MyTransport<Codec, Incoming, Outgoing> {
const KIND: &'static str = "MyTransport";
fn with_logger<F, R>(&self, f: F) -> R
where
F: FnOnce(&dnet_base::Logger) -> R,
{
f(&self.logger)
}
fn with_logger_mut<F, R>(&mut self, f: F) -> R
where
F: FnOnce(&mut dnet_base::Logger) -> R,
{
f(&mut self.logger)
}
}
Testing transports
Transports may be tested using the dnet-tests crate.
It provides helpers such as dnet_tests::test_transport, dnet_tests::test_unit_message, and dnet_tests::test_stream for validating that your transport correctly sends, receives, and closes.
You can use dnet_tests::dtest_configure!() and #[dtest] attribute macro to mark your tests in your test modules when your transport supports both: native and WASM targets.
Common mistakes
- Transport not closing on drop. Some underlying transports require an explicit
Dropimplementation to flush or close resources correctly. - Returning
Result<Incoming, dnet::Error<TransportError>>from the stream. The stream item should beResult<Incoming, TransportError>and the closing of the transport is notified by returningNone. - Returning
Poll::Pendingtoo early. If the underlying transport returnedPoll::Ready, but you can’t construct (and return) a message yet, keep polling in a loop until you can construct a concrete return value - returnPoll::Pendingonly when underlying transport returnsPoll::Pending(or you track waking with some other mechanism). - Forgetting to implement
Logging. When theloggingfeature is enabled, the transport should implementdnet_base::Loggingor it may not work correctly with otherdnetfeatures. - Implementing
Loggingtrait but forgetting to actually log anything.