hypercore_protocol/lib.rs
1//! ## Introduction
2//!
3//! Hypercore protocol is a streaming, message based protocol. This is a rust port of the wire
4//! protocol implementation in [the original Javascript version][holepunch-hypercore] aiming
5//! for interoperability with LTS version.
6//!
7//! This crate is built on top of the [hypercore](https://crates.io/crates/hypercore) crate, which defines some structs used here.
8//!
9//! ## Design
10//!
11//! This crate expects to receive a pre-encrypted, message-framed connection (e.g., from hyperswarm).
12//! The underlying stream should implement `Stream<Item = Vec<u8>> + Sink<Vec<u8>>`.
13//!
14//! After construction, each side can request any number of channels on the protocol. A
15//! channel is opened with a [Key], a 32 byte buffer. Channels are only opened if both peers
16//! opened a channel for the same key. It is automatically verified that both parties know the
17//! key without transmitting the key itself using the handshake hash from the underlying connection.
18//!
19//! On a channel, the predefined messages, including a custom Extension message, of the Hypercore
20//! protocol can be sent and received.
21//!
22//! [holepunch-hypercore]: https://github.com/holepunchto/hypercore
23
24#![forbid(unsafe_code)]
25#![deny(missing_debug_implementations, nonstandard_style)]
26#![warn(missing_docs, clippy::needless_pass_by_ref_mut, unreachable_pub)]
27
28mod channels;
29mod constants;
30mod crypto;
31mod error;
32mod message;
33mod mqueue;
34mod protocol;
35mod stream;
36#[cfg(test)]
37mod test_utils;
38mod util;
39
40/// The wire messages used by the protocol.
41pub mod schema;
42pub use error::Error;
43
44pub use channels::Channel;
45// Export the needed types for Channel::take_receiver, and Channel::local_sender()
46pub use async_channel::{
47 Receiver as ChannelReceiver, SendError as ChannelSendError, Sender as ChannelSender,
48};
49pub use message::Message;
50pub use protocol::{Command, CommandTx, DiscoveryKey, Event, Key, Protocol};
51pub use stream::BoxedStream;
52pub use util::discovery_key;
53// Export handshake result for constructing Protocol
54pub use crypto::handshake::HandshakeResult;