quic_reverse/
lib.rs

1// Copyright 2024-2026 Farlight Networks, LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! Reverse-initiated, multiplexed services over QUIC.
16//!
17//! `quic-reverse` is a library that enables servers to initiate streams back to clients
18//! over an existing QUIC connection. This is useful for scenarios where:
19//!
20//! - Clients are behind NAT and cannot accept incoming connections
21//! - Edge devices need to expose services to a central server
22//! - Reverse tunneling is required without opening inbound ports
23//!
24//! # Architecture
25//!
26//! The library sits atop an existing QUIC connection and adds:
27//!
28//! - An explicit control plane for stream lifecycle management
29//! - Reverse-initiated stream semantics
30//! - Service multiplexing via service identifiers
31//! - Well-defined negotiation, backpressure, and error handling
32//!
33//! # Example
34//!
35//! ```ignore
36//! use quic_reverse::{Session, Config, Role};
37//!
38//! // Wrap an existing QUIC connection
39//! let session = Session::new(connection, Role::Client, Config::default());
40//!
41//! // Start the session (performs negotiation)
42//! let mut handle = session.start().await?;
43//!
44//! // Open a reverse stream to a service
45//! let (send, recv) = handle.open("ssh", Metadata::Empty).await?;
46//! ```
47
48pub use quic_reverse_control::{
49    CloseCode, Features, Metadata, OpenFlags, RejectCode, ServiceId, StreamBind,
50};
51pub use quic_reverse_transport::{Connection, RecvStream, SendStream};
52
53#[cfg(feature = "quinn")]
54pub use quic_reverse_transport::{QuinnConnection, QuinnRecvStream, QuinnSendStream};
55
56mod client;
57mod config;
58mod control;
59mod error;
60mod negotiation;
61mod registry;
62mod session;
63mod state;
64
65pub use client::{ClientEvent, SessionClient};
66pub use config::Config;
67pub use error::Error;
68pub use negotiation::NegotiatedParams;
69pub use session::{ControlEvent, Session, SessionHandle};
70pub use state::State;
71
72/// Role in a quic-reverse session.
73///
74/// The role primarily affects example code and documentation.
75/// The protocol itself is largely symmetrical.
76#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
77pub enum Role {
78    /// The client role (typically the QUIC connection initiator).
79    Client,
80    /// The server role (typically the QUIC connection acceptor).
81    Server,
82}
83
84impl std::fmt::Display for Role {
85    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
86        match self {
87            Self::Client => write!(f, "client"),
88            Self::Server => write!(f, "server"),
89        }
90    }
91}
quic_reverse/lib.rs

quic_reverse/
lib.rs
