Skip to main content

hyprstream_rpc/transport/
uds_server.rs

1//! UDS RPC server — the same-host `ipc` serve path, post-ZMQ.
2//!
3//! Mirrors [`QuinnRpcServer`](super::quinn_transport::QuinnRpcServer): a
4//! `UnixListener` accept loop that hands each accepted connection to the
5//! transport-generic [`serve_rpc_connection`] over a
6//! [`UdsSession`](super::uds_session::UdsSession). Same DoS discipline — a
7//! server-wide concurrent-stream semaphore (drained on shutdown), a
8//! per-connection cap, a bounded handshake, and the per-stream read timeout —
9//! and the same `process_request` dispatch core, so the ipc plane is identical
10//! to the quinn/iroh planes save for the socket underneath.
11//!
12//! The daemon binds the `UnixListener` (choosing the path + file mode; peer
13//! creds are #207) and runs one of these per spawn-path service. A
14//! `!Send` service is bridged to the `Send`-bound processor via
15//! [`LocalServiceBridge`](super::iroh_rpc::LocalServiceBridge), exactly as the
16//! quinn/iroh serve paths do.
17
18use std::sync::Arc;
19use std::time::Duration;
20
21use anyhow::Result;
22use ed25519_dalek::SigningKey;
23use tokio::net::UnixListener;
24use tokio::sync::Semaphore;
25use tokio_util::sync::CancellationToken;
26
27use super::rpc_session::{
28    serve_rpc_connection, IrohRequestProcessor, DEFAULT_CONNECTION_LIMIT, DEFAULT_STREAM_LIMIT,
29    DRAIN_TIMEOUT, REQUEST_READ_TIMEOUT,
30};
31use super::uds_session::{accept_uds, PLANE_MOQ, PLANE_RPC};
32
33/// A `UnixListener`-backed RPC server for the same-host `ipc` plane.
34pub struct UdsRpcServer {
35    listener: UnixListener,
36    processor: Arc<dyn IrohRequestProcessor>,
37    signing_key: SigningKey,
38    /// Server-wide concurrent-stream cap, shared across all connections; one
39    /// permit per in-flight bidi stream. `shutdown` drains it via `acquire_many`.
40    stream_limit: Arc<Semaphore>,
41    stream_limit_capacity: u32,
42    /// Cap on concurrent accepted connections (#162). Connections beyond the cap
43    /// are rejected (dropped), not queued.
44    connection_limit: Arc<Semaphore>,
45    /// Per-stream request-read timeout (#159 slowloris bound).
46    read_timeout: Duration,
47    shutdown: CancellationToken,
48}
49
50impl UdsRpcServer {
51    /// Build a server over an already-bound [`UnixListener`].
52    pub fn new<P: IrohRequestProcessor>(
53        listener: UnixListener,
54        processor: P,
55        signing_key: SigningKey,
56    ) -> Self {
57        Self::with_capacity(
58            listener,
59            Arc::new(processor),
60            signing_key,
61            DEFAULT_STREAM_LIMIT,
62        )
63    }
64
65    /// Build a server with an explicit server-wide concurrent-stream cap.
66    pub fn with_capacity(
67        listener: UnixListener,
68        processor: Arc<dyn IrohRequestProcessor>,
69        signing_key: SigningKey,
70        stream_limit: usize,
71    ) -> Self {
72        Self {
73            listener,
74            processor,
75            signing_key,
76            stream_limit: Arc::new(Semaphore::new(stream_limit)),
77            stream_limit_capacity: u32::try_from(stream_limit).unwrap_or(u32::MAX),
78            connection_limit: Arc::new(Semaphore::new(DEFAULT_CONNECTION_LIMIT)),
79            read_timeout: REQUEST_READ_TIMEOUT,
80            shutdown: CancellationToken::new(),
81        }
82    }
83
84    /// Override the concurrent-connection cap (builder style).
85    pub fn with_connection_limit(mut self, limit: usize) -> Self {
86        self.connection_limit = Arc::new(Semaphore::new(limit));
87        self
88    }
89
90    /// Override the server-wide concurrent-stream cap (builder style).
91    pub fn with_stream_limit(mut self, limit: usize) -> Self {
92        self.stream_limit = Arc::new(Semaphore::new(limit));
93        self.stream_limit_capacity = u32::try_from(limit).unwrap_or(u32::MAX);
94        self
95    }
96
97    /// Override the per-stream request-read timeout (#159). Primarily for tests.
98    pub fn with_read_timeout(mut self, read_timeout: Duration) -> Self {
99        self.read_timeout = read_timeout;
100        self
101    }
102
103    /// Apply all tunables from an [`super::rpc_session::RpcConfig`] in one call (#197).
104    pub fn with_rpc_config(self, cfg: &super::rpc_session::RpcConfig) -> Self {
105        self.with_stream_limit(cfg.stream_limit)
106            .with_connection_limit(cfg.connection_limit)
107            .with_read_timeout(cfg.request_read_timeout)
108    }
109
110    /// A handle that, when cancelled, stops the accept loop and per-connection
111    /// serve loops. Does not by itself drain in-flight streams — use
112    /// [`UdsRpcServer::shutdown`] for a graceful drain.
113    pub fn shutdown_token(&self) -> CancellationToken {
114        self.shutdown.clone()
115    }
116
117    /// The shared concurrent-stream semaphore (pair with [`UdsRpcServer::capacity`]
118    /// + [`UdsRpcServer::shutdown_token`] to drain while `run` owns `self`).
119    pub fn stream_limit(&self) -> Arc<Semaphore> {
120        Arc::clone(&self.stream_limit)
121    }
122
123    /// The configured server-wide concurrent-stream capacity.
124    pub fn capacity(&self) -> u32 {
125        self.stream_limit_capacity
126    }
127
128    /// Graceful shutdown: cancel the accept loop, then wait (bounded by
129    /// [`DRAIN_TIMEOUT`]) for every in-flight stream to release its permit, then
130    /// close the semaphore. Mirrors [`QuinnRpcServer::shutdown`](super::quinn_transport::QuinnRpcServer::shutdown).
131    pub async fn shutdown(stream_limit: &Arc<Semaphore>, capacity: u32, token: &CancellationToken) {
132        Self::shutdown_until(
133            stream_limit,
134            capacity,
135            token,
136            tokio::time::Instant::now() + super::rpc_session::DRAIN_TIMEOUT,
137        )
138        .await;
139    }
140
141    /// Drain against the owner's shared deadline, without starting a new grace.
142    pub async fn shutdown_until(
143        stream_limit: &Arc<Semaphore>,
144        capacity: u32,
145        token: &CancellationToken,
146        deadline: tokio::time::Instant,
147    ) {
148        token.cancel();
149        match tokio::time::timeout_at(deadline, stream_limit.acquire_many(capacity)).await {
150            Ok(Ok(permits)) => {
151                permits.forget();
152                stream_limit.close();
153            }
154            Ok(Err(_)) => { /* already closed */ }
155            Err(_) => {
156                tracing::warn!(timeout = ?DRAIN_TIMEOUT, "uds-rpc: drain timed out, forcing teardown");
157                stream_limit.close();
158            }
159        }
160    }
161
162    /// Run the accept loop until `shutdown` is cancelled. Each accepted
163    /// connection is served on its own task by [`serve_rpc_connection`], sharing
164    /// the server-wide [`Semaphore`] so [`UdsRpcServer::shutdown`] can drain
165    /// every in-flight stream regardless of which connection it belongs to.
166    pub async fn run(self) -> Result<()> {
167        loop {
168            tokio::select! {
169                biased;
170                _ = self.shutdown.cancelled() => {
171                    tracing::debug!("uds-rpc: accept loop cancelled");
172                    return Ok(());
173                }
174                accepted = self.listener.accept() => {
175                    let stream = match accepted {
176                        Ok((stream, _addr)) => {
177                            // SECURITY (#207): enforce same-uid-only access via
178                            // SO_PEERCRED. The socket is already 0o700 so only the
179                            // daemon's user can connect, but kernel-level peer-cred
180                            // verification adds defense-in-depth against fd-passing
181                            // or capability tricks that bypass filesystem permissions.
182                            #[cfg(target_os = "linux")]
183                            {
184                                use nix::sys::socket::{getsockopt, sockopt::PeerCredentials};
185                                let daemon_uid = nix::unistd::getuid();
186                                match getsockopt(&stream, PeerCredentials) {
187                                    Ok(cred) if cred.uid() == daemon_uid.as_raw() => {}
188                                    Ok(cred) => {
189                                        tracing::warn!(
190                                            peer_uid = cred.uid(),
191                                            daemon_uid = daemon_uid.as_raw(),
192                                            "uds-rpc: peer uid mismatch, rejecting connection"
193                                        );
194                                        continue;
195                                    }
196                                    Err(e) => {
197                                        tracing::warn!(
198                                            error = %e,
199                                            "uds-rpc: SO_PEERCRED failed, rejecting connection"
200                                        );
201                                        continue;
202                                    }
203                                }
204                            }
205                            // TODO: add getpeereid() check for macOS/FreeBSD via nix crate
206                            stream
207                        }
208                        Err(e) => {
209                            tracing::debug!(error = %e, "uds-rpc: listener accept error");
210                            continue;
211                        }
212                    };
213
214                    // Connection cap (#162): reject (drop) at cap rather than queue.
215                    let conn_permit = match Arc::clone(&self.connection_limit).try_acquire_owned() {
216                        Ok(p) => p,
217                        Err(_) => {
218                            tracing::warn!("uds-rpc: connection cap reached, rejecting connection");
219                            drop(stream);
220                            continue;
221                        }
222                    };
223
224                    let processor = Arc::clone(&self.processor);
225                    let signing_key = self.signing_key.clone();
226                    let stream_limit = Arc::clone(&self.stream_limit);
227                    let read_timeout = self.read_timeout;
228                    let shutdown = self.shutdown.clone();
229                    tokio::spawn(async move {
230                        let _conn_permit = conn_permit; // released when this connection ends
231
232                        // Read the plane byte + spin up the yamux session, bounded
233                        // so a stalled handshake never pins a connection permit.
234                        let (plane, session) = match tokio::time::timeout(
235                            super::rpc_session::HANDSHAKE_TIMEOUT,
236                            accept_uds(stream),
237                        )
238                        .await
239                        {
240                            Ok(Ok(pair)) => pair,
241                            Ok(Err(e)) => {
242                                tracing::debug!(error = %e, "uds-rpc: accept_uds failed");
243                                return;
244                            }
245                            Err(_) => {
246                                tracing::warn!("uds-rpc: plane handshake timed out");
247                                return;
248                            }
249                        };
250
251                        match plane {
252                            PLANE_RPC => {
253                                // INV-2 (#1042): this accept boundary terminates a
254                                // same-host UDS connection (incl. systemd socket
255                                // activation) — the explicitly trusted local class.
256                                if let Err(e) = serve_rpc_connection(
257                                    session, processor, signing_key, stream_limit, read_timeout, shutdown,
258                                    crate::transport::carrier::CarrierContext::trusted_uds(),
259                                )
260                                .await
261                                {
262                                    tracing::debug!(error = ?e, "uds-rpc: serve connection ended with error");
263                                }
264                            }
265                            PLANE_MOQ => {
266                                // moq streaming over UDS is a later increment; the
267                                // same UdsSession is moq-capable, but the daemon
268                                // does not yet wire a moq Server on this listener.
269                                tracing::warn!("uds-rpc: PLANE_MOQ on the RPC listener — not yet served, closing");
270                            }
271                            other => {
272                                tracing::warn!(plane = other, "uds-rpc: unknown plane, closing");
273                            }
274                        }
275                    });
276                }
277            }
278        }
279    }
280}
281
282#[cfg(test)]
283#[allow(clippy::unwrap_used, clippy::expect_used)]
284mod tests {
285    use super::*;
286    use crate::transport::lazy_uds::LazyUdsTransport;
287    use crate::transport::rpc_session::from_fn;
288    use crate::transport_traits::Transport;
289    use bytes::Bytes;
290
291    fn temp_sock(tag: &str) -> std::path::PathBuf {
292        let dir = std::env::temp_dir().join(format!("uds-server-{}-{}", tag, std::process::id()));
293        let _ = std::fs::create_dir_all(&dir);
294        dir.join("rpc.sock")
295    }
296
297    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
298    async fn uds_server_round_trips_via_lazy_client() {
299        let path = temp_sock("rt");
300        let _ = std::fs::remove_file(&path);
301        let listener = UnixListener::bind(&path).unwrap();
302
303        let (sk, _vk) = crate::generate_signing_keypair();
304        let processor = from_fn(|req: Bytes| async move { Ok(req) }); // echo
305        let server = UdsRpcServer::new(listener, processor, sk);
306        let token = server.shutdown_token();
307        let srv = tokio::spawn(server.run());
308
309        let client = LazyUdsTransport::new(path.clone());
310        let r1 = client.send(b"ping".to_vec(), Some(4_000)).await.unwrap();
311        assert_eq!(r1, b"ping");
312        // Reuse the cached session over a second multiplexed stream.
313        let r2 = client.send(b"pong".to_vec(), Some(4_000)).await.unwrap();
314        assert_eq!(r2, b"pong");
315
316        token.cancel();
317        let _ = srv.await;
318        let _ = std::fs::remove_file(&path);
319    }
320
321    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
322    async fn uds_server_shutdown_drains() {
323        let path = temp_sock("drain");
324        let _ = std::fs::remove_file(&path);
325        let listener = UnixListener::bind(&path).unwrap();
326
327        let (sk, _vk) = crate::generate_signing_keypair();
328        let processor = from_fn(|req: Bytes| async move { Ok(req) });
329        let server = UdsRpcServer::new(listener, processor, sk);
330        let token = server.shutdown_token();
331        let stream_limit = server.stream_limit();
332        let capacity = server.capacity();
333        let srv = tokio::spawn(server.run());
334
335        let client = LazyUdsTransport::new(path.clone());
336        assert_eq!(client.send(b"x".to_vec(), Some(4_000)).await.unwrap(), b"x");
337
338        // Graceful drain completes promptly with no in-flight streams.
339        UdsRpcServer::shutdown(&stream_limit, capacity, &token).await;
340        let _ = srv.await;
341        let _ = std::fs::remove_file(&path);
342    }
343}