tokio_quiche/socket/
connected.rs

1// Copyright (C) 2025, Cloudflare, Inc.
2// All rights reserved.
3//
4// Redistribution and use in source and binary forms, with or without
5// modification, are permitted provided that the following conditions are
6// met:
7//
8//     * Redistributions of source code must retain the above copyright notice,
9//       this list of conditions and the following disclaimer.
10//
11//     * Redistributions in binary form must reproduce the above copyright
12//       notice, this list of conditions and the following disclaimer in the
13//       documentation and/or other materials provided with the distribution.
14//
15// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
16// IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
17// THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
18// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
19// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
22// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
23// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
24// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26
27use datagram_socket::DatagramSocketRecv;
28use datagram_socket::DatagramSocketSend;
29use std::io;
30use std::net::SocketAddr;
31use std::sync::Arc;
32use tokio::net::UdpSocket;
33
34use super::SocketCapabilities;
35
36/// A connected datagram socket with separate `send` and `recv` halves.
37///
38/// [`Socket`] abstracts over both real UDP-based connections and in-process
39/// tunneled flows like (multi-hop) MASQUE flows. It uses the
40/// [`datagram_socket`] traits for this purpose.
41#[derive(Debug)]
42pub struct Socket<Tx, Rx> {
43    /// The sending half of the connection. This generally supports concurrent
44    /// senders.
45    pub send: Tx,
46    /// The receiving half of the connection. This is generally owned by a
47    /// single caller.
48    pub recv: Rx,
49    /// The address of the local endpoint.
50    pub local_addr: SocketAddr,
51    /// The address of the remote endpoint.
52    pub peer_addr: SocketAddr,
53    /// The [`SocketCapabilities`] to use for this socket.
54    ///
55    /// By default, [`Socket`]s are constructed with all capabilities
56    /// disabled. On Linux, you can use `apply_max_capabilities()` to (try
57    /// to) enable all supported capabilities.
58    pub capabilities: SocketCapabilities,
59}
60
61/// A type-erased variant of [`Socket`] with boxed `Tx` and `Rx` halves.
62pub type BoxedSocket = Socket<
63    Box<dyn DatagramSocketSend + Send + 'static>,
64    Box<dyn DatagramSocketRecv + Sync + 'static>,
65>;
66
67impl<Tx, Rx> Socket<Tx, Rx> {
68    /// Creates a [`Socket`] from a [`UdpSocket`] by wrapping the file
69    /// descriptor in an [`Arc`].
70    pub fn from_udp(
71        socket: UdpSocket,
72    ) -> io::Result<Socket<Arc<UdpSocket>, Arc<UdpSocket>>> {
73        let local_addr = socket.local_addr()?;
74        let peer_addr = socket.peer_addr()?;
75
76        let send = Arc::new(socket);
77        let recv = Arc::clone(&send);
78
79        Ok(Socket {
80            send,
81            recv,
82            local_addr,
83            peer_addr,
84            capabilities: SocketCapabilities::default(),
85        })
86    }
87}
88
89impl<Tx, Rx> Socket<Tx, Rx>
90where
91    Tx: DatagramSocketSend,
92    Rx: DatagramSocketRecv,
93{
94    /// Checks whether both `send` and `recv` refer to the same underlying
95    /// UDP socket FD and returns a reference to that socket.
96    ///
97    /// # Note
98    /// The file descriptor _numbers_ have to be identical. A pair of FDs
99    /// created by [`dup(2)`](https://man7.org/linux/man-pages/man2/dup.2.html) will
100    /// return `None`.
101    #[cfg(unix)]
102    pub fn as_udp_socket(&self) -> Option<&UdpSocket> {
103        use std::os::fd::AsRawFd;
104
105        let send = self.send.as_udp_socket()?;
106        let recv = self.recv.as_udp_socket()?;
107        (send.as_raw_fd() == recv.as_raw_fd()).then_some(send)
108    }
109
110    /// Tries to enable all sockopts supported by the crate for this socket.
111    ///
112    /// This does nothing unless `send` and `recv` refer to the same UDP socket
113    /// FD. See `SocketCapabilities::apply_all_and_get_compatibility` for
114    /// details.
115    #[cfg(target_os = "linux")]
116    pub fn apply_max_capabilities(&mut self, max_send_udp_payload_size: usize) {
117        let Some(socket) = self.as_udp_socket() else {
118            return;
119        };
120
121        let capabilities = SocketCapabilities::apply_all_and_get_compatibility(
122            socket,
123            max_send_udp_payload_size,
124        );
125        self.capabilities = capabilities;
126    }
127}
128
129impl TryFrom<UdpSocket> for Socket<Arc<UdpSocket>, Arc<UdpSocket>> {
130    type Error = io::Error;
131
132    fn try_from(socket: UdpSocket) -> Result<Self, Self::Error> {
133        Self::from_udp(socket)
134    }
135}
tokio_quiche/socket/connected.rs

tokio_quiche/socket/
connected.rs
