roam_fdpass/lib.rs
1//! Cross-platform file descriptor / handle passing for roam.
2//!
3//! This crate provides a unified API for passing file descriptors (Unix) or
4//! socket handles (Windows) between processes over IPC channels.
5//!
6//! # Platform implementations
7//!
8//! - **Unix**: Uses SCM_RIGHTS to pass raw file descriptors over Unix domain sockets
9//! - **Windows**: Uses `WSADuplicateSocket` to serialize socket state, sends it over
10//! a named pipe, and recreates the socket with `WSASocket` on the receiving end
11//!
12//! # Usage
13//!
14//! ## Unix
15//!
16//! ```ignore
17//! use roam_fdpass::{send_fd, recv_fd};
18//! use tokio::net::UnixStream;
19//!
20//! // Sender
21//! let tcp_listener = std::net::TcpListener::bind("127.0.0.1:0")?;
22//! let fd = tcp_listener.into_raw_fd();
23//! send_fd(&unix_stream, fd).await?;
24//!
25//! // Receiver
26//! let fd = recv_fd(&unix_stream).await?;
27//! let listener = unsafe { std::net::TcpListener::from_raw_fd(fd) };
28//! ```
29//!
30//! ## Windows
31//!
32//! ```ignore
33//! use roam_fdpass::{send_socket, recv_socket};
34//! use tokio::net::windows::named_pipe::{NamedPipeServer, NamedPipeClient};
35//!
36//! // Sender (needs receiver's process ID)
37//! let tcp_listener = std::net::TcpListener::bind("127.0.0.1:0")?;
38//! send_socket(&pipe, &tcp_listener, receiver_pid).await?;
39//!
40//! // Receiver
41//! let listener: std::net::TcpListener = recv_socket(&pipe).await?;
42//! ```
43
44#[cfg(unix)]
45mod unix;
46
47#[cfg(windows)]
48mod windows;
49
50#[cfg(unix)]
51pub use unix::*;
52
53#[cfg(windows)]
54pub use windows::*;