libp2p_quic/
lib.rs

1// Copyright 2020 Parity Technologies (UK) Ltd.
2//
3// Permission is hereby granted, free of charge, to any person obtaining a
4// copy of this software and associated documentation files (the "Software"),
5// to deal in the Software without restriction, including without limitation
6// the rights to use, copy, modify, merge, publish, distribute, sublicense,
7// and/or sell copies of the Software, and to permit persons to whom the
8// Software is furnished to do so, subject to the following conditions:
9//
10// The above copyright notice and this permission notice shall be included in
11// all copies or substantial portions of the Software.
12//
13// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
14// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
18// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
19// DEALINGS IN THE SOFTWARE.
20
21//! Implementation of the QUIC transport protocol for libp2p.
22//!
23//! # Usage
24//!
25//! Example:
26//!
27//! ```
28//! # #[cfg(not(feature = "tokio"))]
29//! # fn main() {}
30//! #
31//! # #[cfg(feature = "tokio")]
32//! # #[tokio::main]
33//! # async fn main() -> std::io::Result<()> {
34//! #
35//! use libp2p_core::{transport::ListenerId, Multiaddr, Transport};
36//! use libp2p_quic as quic;
37//!
38//! let keypair = libp2p_identity::Keypair::generate_ed25519();
39//! let quic_config = quic::Config::new(&keypair);
40//! let mut quic_transport = quic::tokio::Transport::new(quic_config);
41//! let addr = "/ip4/127.0.0.1/udp/12345/quic-v1"
42//!     .parse()
43//!     .expect("address should be valid");
44//! quic_transport
45//!     .listen_on(ListenerId::next(), addr)
46//!     .expect("listen error.");
47//!
48//! #
49//! # Ok(())
50//! # }
51//! ```
52//!
53//! The [`GenTransport`] struct implements the [`libp2p_core::Transport`]. See the
54//! documentation of [`libp2p_core`] and of libp2p in general to learn how to use the
55//! [`Transport`][libp2p_core::Transport] trait.
56//!
57//! Note that QUIC provides transport, security, and multiplexing in a single protocol.  Therefore,
58//! QUIC connections do not need to be upgraded. You will get a compile-time error if you try.
59//! Instead, you must pass all needed configuration into the constructor.
60
61#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
62
63mod config;
64mod connection;
65mod hole_punching;
66mod provider;
67mod transport;
68
69use std::net::SocketAddr;
70
71pub use config::Config;
72pub use connection::{Connecting, Connection, Stream};
73#[cfg(feature = "tokio")]
74pub use provider::tokio;
75pub use provider::Provider;
76pub use transport::GenTransport;
77
78/// Errors that may happen on the [`GenTransport`] or a single [`Connection`].
79#[derive(Debug, thiserror::Error)]
80pub enum Error {
81    /// Error while trying to reach a remote.
82    #[error(transparent)]
83    Reach(#[from] ConnectError),
84
85    /// Error after the remote has been reached.
86    #[error(transparent)]
87    Connection(#[from] ConnectionError),
88
89    /// I/O Error on a socket.
90    #[error(transparent)]
91    Io(#[from] std::io::Error),
92
93    /// The [`Connecting`] future timed out.
94    #[error("Handshake with the remote timed out.")]
95    HandshakeTimedOut,
96
97    /// Error when `Transport::dial_as_listener` is called without an active listener.
98    #[error("Tried to dial as listener without an active listener.")]
99    NoActiveListenerForDialAsListener,
100
101    /// Error when holepunching for a remote is already in progress
102    #[error("Already punching hole for {0}).")]
103    HolePunchInProgress(SocketAddr),
104}
105
106/// Dialing a remote peer failed.
107#[derive(Debug, thiserror::Error)]
108#[error(transparent)]
109pub struct ConnectError(quinn::ConnectError);
110
111/// Error on an established [`Connection`].
112#[derive(Debug, thiserror::Error)]
113#[error(transparent)]
114pub struct ConnectionError(quinn::ConnectionError);
libp2p_quic/lib.rs

libp2p_quic/
lib.rs
