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 = "async-std"))]
29//! # fn main() {}
30//! #
31//! # #[cfg(feature = "async-std")]
32//! # fn main() -> std::io::Result<()> {
33//! #
34//! use libp2p_core::{transport::ListenerId, Multiaddr, Transport};
35//! use libp2p_quic as quic;
36//!
37//! let keypair = libp2p_identity::Keypair::generate_ed25519();
38//! let quic_config = quic::Config::new(&keypair);
39//!
40//! let mut quic_transport = quic::async_std::Transport::new(quic_config);
41//!
42//! let addr = "/ip4/127.0.0.1/udp/12345/quic-v1"
43//!     .parse()
44//!     .expect("address should be valid");
45//! quic_transport
46//!     .listen_on(ListenerId::next(), addr)
47//!     .expect("listen error.");
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 = "async-std")]
74pub use provider::async_std;
75#[cfg(feature = "tokio")]
76pub use provider::tokio;
77pub use provider::Provider;
78pub use transport::GenTransport;
79
80/// Errors that may happen on the [`GenTransport`] or a single [`Connection`].
81#[derive(Debug, thiserror::Error)]
82pub enum Error {
83    /// Error while trying to reach a remote.
84    #[error(transparent)]
85    Reach(#[from] ConnectError),
86
87    /// Error after the remote has been reached.
88    #[error(transparent)]
89    Connection(#[from] ConnectionError),
90
91    /// I/O Error on a socket.
92    #[error(transparent)]
93    Io(#[from] std::io::Error),
94
95    /// The [`Connecting`] future timed out.
96    #[error("Handshake with the remote timed out.")]
97    HandshakeTimedOut,
98
99    /// Error when `Transport::dial_as_listener` is called without an active listener.
100    #[error("Tried to dial as listener without an active listener.")]
101    NoActiveListenerForDialAsListener,
102
103    /// Error when holepunching for a remote is already in progress
104    #[error("Already punching hole for {0}).")]
105    HolePunchInProgress(SocketAddr),
106}
107
108/// Dialing a remote peer failed.
109#[derive(Debug, thiserror::Error)]
110#[error(transparent)]
111pub struct ConnectError(quinn::ConnectError);
112
113/// Error on an established [`Connection`].
114#[derive(Debug, thiserror::Error)]
115#[error(transparent)]
116pub struct ConnectionError(quinn::ConnectionError);
libp2p_quic/lib.rs

libp2p_quic/
lib.rs
