Properly close TUN device from C lib

Signed-off-by: Lee Smet <lee.smet@hotmail.com>

Author: LeeSmet

CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- When the mycelium library is used, the TUN device is now properly
+  cleaned up after the node is stopped
+
 ## [0.7.8] - 2026-05-19
 
 ### Added

mycelium/src/ffi/exports.rs

@@ -237,9 +237,12 @@ pub unsafe extern "C" fn mycelium_start(
     }
 }
 
-/// Halt the node and release its internal resources. The handle remains
-/// valid for `mycelium_is_running` queries (which will return false) until
-/// `mycelium_node_free` is called. No-op on an already-stopped node.
+/// Halt the node and release its internal resources. This call blocks until
+/// the node's background runtime has fully shut down (typically well under a
+/// second; bounded at a few seconds) and any network interface it created has
+/// been removed. The handle remains valid for `mycelium_is_running` queries
+/// (which will return false) until `mycelium_node_free` is called. No-op on an
+/// already-stopped node.
 ///
 /// # Safety
 ///
@@ -255,15 +258,17 @@ pub unsafe extern "C" fn mycelium_stop(node: *mut mycelium_node_t) -> i32 {
         Ok(g) => g,
         Err(_) => return error::set_and_return("node lock poisoned", MYCELIUM_ERR_INTERNAL),
     };
-    match &mut *guard {
-        NodeState::Running(h) => {
-            info!("stopping mycelium node");
-            h.stop();
-            *guard = NodeState::Stopped;
-        }
-        NodeState::Stopped => {
-            warn!("mycelium_stop called on a stopped node");
-        }
+    if matches!(&*guard, NodeState::Running(_)) {
+        info!("stopping mycelium node");
+        // Swap the handle out under the lock, then release the lock before
+        // dropping the handle: `NodeHandle`'s `Drop` blocks until the
+        // background runtime is fully torn down, and we must not hold the
+        // `state` mutex while that happens.
+        let old = std::mem::replace(&mut *guard, NodeState::Stopped);
+        drop(guard);
+        drop(old);
+    } else {
+        warn!("mycelium_stop called on a stopped node");
     }
     MYCELIUM_OK
 }

mycelium/src/node_handle.rs

@@ -9,7 +9,7 @@ use std::net::SocketAddr;
 use std::sync::Arc;
 
 use tokio::sync::Mutex;
-use tracing::{error, info};
+use tracing::{debug, error, info};
 
 use crate::metrics::NoMetrics;
 use crate::{Config, Node};
@@ -72,13 +72,32 @@ pub fn create_tun_fd(tun_name: &str) -> Result<i32, std::io::Error> {
 
 // ── NodeHandle ──────────────────────────────────────────────────────────────
 
+/// Upper bound on how long node teardown waits for the background Tokio
+/// runtime to shut down. Asynchronous tasks (including the TUN reader/writer)
+/// are cancelled immediately when the runtime is dropped; this timeout only
+/// bounds the wait on any outstanding `spawn_blocking` work so a stuck
+/// blocking task cannot hang teardown forever.
+const SHUTDOWN_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(5);
+
 /// Handle to a running mycelium node. Holds a reference to the node for direct
 /// method calls and the Tokio runtime handle to drive them from non-async
 /// threads (e.g. Binder threads, C FFI callbacks).
 pub struct NodeHandle {
     node: Arc<Mutex<Node<NoMetrics>>>,
     rt_handle: tokio::runtime::Handle,
     shutdown_tx: Option<tokio::sync::oneshot::Sender<()>>,
+    /// Background OS thread that owns the Tokio runtime. Joined on drop so
+    /// teardown is synchronous: once the join completes the runtime is gone
+    /// and any TUN interface the node created has been removed.
+    thread: Option<std::thread::JoinHandle<()>>,
+    /// On Android the `tun` crate does not close the TUN file descriptor on
+    /// drop (it assumes the fd is owned by Android's `VpnService`). Mycelium
+    /// opens this fd itself via [`create_tun_fd`], so it owns it and must
+    /// close it during teardown — otherwise the kernel keeps the
+    /// non-persistent TUN interface alive. Closed in [`Drop`], after the
+    /// background runtime has been joined.
+    #[cfg(target_os = "android")]
+    tun_fd: Option<i32>,
 }
 
 impl NodeHandle {
@@ -87,10 +106,15 @@ impl NodeHandle {
     /// Blocks the calling thread until the node is ready (or fails to start).
     /// The caller provides a fully constructed [`Config`].
     pub fn start(config: Config<NoMetrics>) -> Result<Self, NodeError> {
+        // On Android mycelium opens the TUN fd itself (see `create_tun_fd`),
+        // so the handle owns it and is responsible for closing it on drop.
+        #[cfg(target_os = "android")]
+        let tun_fd = config.tun_fd;
+
         let (result_tx, result_rx) = std::sync::mpsc::sync_channel(1);
         let (shutdown_tx, shutdown_rx) = tokio::sync::oneshot::channel::<()>();
 
-        std::thread::spawn(move || {
+        let thread = std::thread::spawn(move || {
             let rt = match tokio::runtime::Builder::new_multi_thread()
                 .worker_threads(2)
                 .enable_all()
@@ -121,14 +145,44 @@ impl NodeHandle {
                     }
                 }
             });
+
+            // Explicit, bounded teardown. Dropping the runtime cancels every
+            // asynchronous task and drops the TUN device, then waits up to
+            // SHUTDOWN_TIMEOUT for any `spawn_blocking` work to finish.
+            debug!("shutting down node runtime");
+            rt.shutdown_timeout(SHUTDOWN_TIMEOUT);
+            debug!("node runtime shut down");
         });
 
-        let (node, rt_handle) = result_rx.recv().map_err(|_| NodeError::ThreadPanic)??;
+        let (node, rt_handle) = match result_rx.recv() {
+            Ok(Ok(pair)) => pair,
+            other => {
+                // The node failed to start. Wait for the background runtime
+                // to finish tearing down, then release the TUN fd we opened
+                // (on Android nothing else will close it).
+                let _ = thread.join();
+                #[cfg(target_os = "android")]
+                if let Some(fd) = tun_fd {
+                    if fd >= 0 {
+                        // SAFETY: `fd` came from `create_tun_fd`; the runtime
+                        // that used it has been joined, so it is unreferenced.
+                        unsafe { libc::close(fd) };
+                    }
+                }
+                return Err(match other {
+                    Ok(Err(e)) => e,
+                    _ => NodeError::ThreadPanic,
+                });
+            }
+        };
 
         Ok(NodeHandle {
             node,
             rt_handle,
             shutdown_tx: Some(shutdown_tx),
+            thread: Some(thread),
+            #[cfg(target_os = "android")]
+            tun_fd,
         })
     }
 
@@ -158,6 +212,44 @@ impl NodeHandle {
     }
 }
 
+impl Drop for NodeHandle {
+    /// Shut the node down and block until its background runtime — and any
+    /// network interface it created — has been fully torn down.
+    ///
+    /// NOTE: this joins the background OS thread, so it must not be invoked
+    /// from within the node's own Tokio runtime (a thread cannot join
+    /// itself). Calling it from an external thread — as the C FFI layer
+    /// does — is safe.
+    fn drop(&mut self) {
+        // Signal shutdown if `stop()` has not already done so.
+        if let Some(tx) = self.shutdown_tx.take() {
+            let _ = tx.send(());
+        }
+        // Block until the background thread has finished tearing down the
+        // runtime. Dropping the runtime cancels every task, including the
+        // TUN reader/writer that owns the tun device.
+        if let Some(thread) = self.thread.take() {
+            if let Err(e) = thread.join() {
+                error!("node background thread panicked during shutdown: {e:?}");
+            }
+        }
+        // On Android the `tun` crate does not close the TUN fd on drop (it
+        // assumes Android's `VpnService` owns it). Mycelium opened this fd
+        // itself via `create_tun_fd`, so it must close it here — after the
+        // join above guarantees the runtime, and the tun device using the
+        // fd, are gone. The interface is non-persistent, so closing the last
+        // fd makes the kernel remove it.
+        #[cfg(target_os = "android")]
+        if let Some(fd) = self.tun_fd.take() {
+            if fd >= 0 {
+                // SAFETY: `fd` came from `create_tun_fd`; the runtime that
+                // used it has been joined, so nothing else references it.
+                unsafe { libc::close(fd) };
+            }
+        }
+    }
+}
+
 // ── Helpers ─────────────────────────────────────────────────────────────────
 
 /// Parse a proxy address string (`"ip:port"`) into a [`SocketAddr`].