//! Local, user-private plugin reload control (`SMH-SPEC-PLUG0001`). //! //! The socket accepts one fixed command only. It carries no path, grants, or //! artifact data: the runtime re-reads its already trusted package registry at //! its next provider boundary. use smith::error::{ProviderFault, Result, SmithError}; #[cfg(unix)] use std::path::Path; use std::path::PathBuf; const RELOAD_REQUEST: &[u8] = b"reload\n"; const RELOAD_RESPONSE: &[u8] = b"ok\n"; #[cfg(unix)] const CONTROL_ENDPOINTS_MAX: usize = 64; /// Tell one selected runtime, or every live runtime using this registry, to /// load the next complete plugin candidate. /// /// # Errors /// /// Returns a plugin fault when no selected or authorized local runtime /// acknowledges the bounded request. #[cfg(unix)] pub fn request_reload(session: Option) -> Result<()> { let paths = match session { Some(session) => vec![smith::config::plugin_control_socket_path(session)], None => runtime_socket_paths()?, }; let mut acknowledged = false; let mut last_error = None; for path in paths { match request_reload_at_path(&path) { Ok(()) => acknowledged = true, Err(error) => last_error = Some(error), } } if acknowledged { Ok(()) } else { Err(last_error.unwrap_or_else(|| control_fault("plugin reload runtime is unavailable"))) } } #[cfg(unix)] fn request_reload_at_path(path: &Path) -> Result<()> { use std::io::{Read, Write}; use std::os::unix::net::UnixStream; use std::time::Duration; let mut stream = UnixStream::connect(path) .map_err(|error| control_fault(format!("plugin reload runtime is unavailable: {error}")))?; stream .set_read_timeout(Some(Duration::from_secs(1))) .map_err(|error| control_fault(format!("plugin reload timeout setup failed: {error}")))?; stream .set_write_timeout(Some(Duration::from_secs(1))) .map_err(|error| control_fault(format!("plugin reload timeout setup failed: {error}")))?; stream .write_all(RELOAD_REQUEST) .map_err(|error| control_fault(format!("plugin reload request failed: {error}")))?; let mut response = [0; RELOAD_RESPONSE.len()]; stream .read_exact(&mut response) .map_err(|error| control_fault(format!("plugin reload acknowledgement failed: {error}")))?; if response != RELOAD_RESPONSE { return Err(control_fault("plugin reload runtime rejected the request")); } Ok(()) } #[cfg(unix)] fn runtime_socket_paths() -> Result> { use std::os::unix::fs::{FileTypeExt, PermissionsExt}; let directory = smith::config::plugin_control_dir(); ensure_private_directory(&directory)?; let entries = match std::fs::read_dir(&directory) { Ok(entries) => entries, Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(Vec::new()), Err(error) => { return Err(control_fault(format!( "plugin reload runtime directory is unavailable: {error}" ))); } }; let mut paths = Vec::new(); for entry in entries { let entry = entry.map_err(|error| { control_fault(format!( "plugin reload runtime directory read failed: {error}" )) })?; let path = entry.path(); let Some(stem) = path.file_stem().and_then(std::ffi::OsStr::to_str) else { continue; }; if path.extension() != Some(std::ffi::OsStr::new("sock")) || stem.len() != 22 || !stem .bytes() .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_')) { continue; } let metadata = std::fs::symlink_metadata(&path).map_err(|error| { control_fault(format!( "plugin reload runtime endpoint metadata failed: {error}" )) })?; if !metadata.file_type().is_socket() || metadata.permissions().mode() & 0o077 != 0 { continue; } paths.push(path); if paths.len() > CONTROL_ENDPOINTS_MAX { return Err(control_fault(format!( "plugin reload runtime endpoint count exceeds {CONTROL_ENDPOINTS_MAX}" ))); } } Ok(paths) } /// Local reload control is currently implemented with Unix-domain sockets. /// /// # Errors /// /// Returns a plugin fault on platforms without a user-private local socket. #[cfg(not(unix))] pub fn request_reload(_session: Option) -> Result<()> { Err(control_fault( "plugin reload control requires a user-private local socket on this platform", )) } /// Runtime-owned endpoint whose receiver is drained only at provider boundaries. #[cfg(unix)] pub struct ReloadControl { receiver: std::sync::mpsc::Receiver, shutdown: std::sync::Arc, socket: PathBuf, socket_identity: SocketIdentity, thread: Option>, } /// Runtime-owned endpoint placeholder for platforms without local sockets. #[cfg(not(unix))] pub struct ReloadControl; #[cfg(unix)] #[derive(Clone, Copy)] struct SocketIdentity { device: u64, inode: u64, } #[cfg(unix)] #[derive(Clone, Copy)] enum ReloadRequest { Reload, } impl ReloadControl { #[cfg(all(test, unix))] pub(crate) fn test_notifications() -> (Self, impl Fn() + Send) { let (sender, receiver) = std::sync::mpsc::sync_channel(1); let control = Self { receiver, shutdown: std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)), socket: PathBuf::new(), socket_identity: SocketIdentity { device: 0, inode: 0, }, thread: None, }; (control, move || sender.send(ReloadRequest::Reload).unwrap()) } /// Bind the one runtime endpoint beneath the caller's XDG private area. /// /// # Errors /// /// Returns before runtime startup if the private directory is unsafe, a /// previous endpoint exists, or socket setup fails. #[cfg(unix)] pub fn bind(session: smith::id::SessionId) -> Result { Self::bind_at_path(smith::config::plugin_control_socket_path(session)) } /// Bind an explicitly selected private socket path. /// /// # Errors /// /// Returns when its parent is not private or its path is occupied. #[cfg(unix)] pub fn bind_at_path(socket: PathBuf) -> Result { use std::os::unix::fs::{FileTypeExt, MetadataExt, PermissionsExt}; use std::os::unix::net::UnixListener; let directory = socket .parent() .ok_or_else(|| control_fault("plugin reload socket has no parent"))?; ensure_private_directory(directory)?; if socket.exists() { return Err(control_fault(format!( "plugin reload control path is already occupied: {}", socket.display() ))); } let listener = UnixListener::bind(&socket).map_err(|error| { if error.kind() == std::io::ErrorKind::InvalidInput { control_fault(format!( "plugin reload control path is too long for a Unix socket; set XDG_RUNTIME_DIR to a shorter private directory: {}", socket.display() )) } else { control_fault(format!("plugin reload control bind failed: {error}")) } })?; listener.set_nonblocking(true).map_err(|error| { control_fault(format!( "plugin reload control nonblocking setup failed: {error}" )) })?; std::fs::set_permissions(&socket, std::fs::Permissions::from_mode(0o600)).map_err( |error| { control_fault(format!( "plugin reload control permission setup failed: {error}" )) }, )?; let metadata = std::fs::symlink_metadata(&socket).map_err(|error| { control_fault(format!("plugin reload control metadata failed: {error}")) })?; if !metadata.file_type().is_socket() { return Err(control_fault( "plugin reload control endpoint is not a socket", )); } let socket_identity = SocketIdentity { device: metadata.dev(), inode: metadata.ino(), }; let (sender, receiver) = std::sync::mpsc::sync_channel(1); let shutdown = std::sync::Arc::new(std::sync::atomic::AtomicBool::new(false)); let thread_shutdown = std::sync::Arc::clone(&shutdown); let thread = std::thread::Builder::new() .name("smith-plugin-control".to_string()) .spawn(move || receive_reload_requests(&listener, &sender, &thread_shutdown)) .map_err(|error| { control_fault(format!("plugin reload control thread failed: {error}")) })?; Ok(Self { receiver, shutdown, socket, socket_identity, thread: Some(thread), }) } /// Construct no endpoint where the platform has no private local socket. #[cfg(not(unix))] pub fn bind() -> Result { Err(control_fault( "plugin reload control requires a user-private local socket on this platform", )) } /// Reject a local socket endpoint on platforms without this transport. #[cfg(not(unix))] pub fn bind_at_path(_socket: PathBuf) -> Result { Self::bind() } /// Coalesce all pending reload requests at a provider safe boundary. #[cfg(unix)] #[must_use] pub fn take_reload_request(&self) -> bool { let mut requested = false; while matches!(self.receiver.try_recv(), Ok(ReloadRequest::Reload)) { requested = true; } requested } /// No local endpoint exists on this platform. #[cfg(not(unix))] #[must_use] pub const fn take_reload_request(&self) -> bool { false } } #[cfg(unix)] impl Drop for ReloadControl { fn drop(&mut self) { use std::os::unix::fs::{FileTypeExt, MetadataExt}; use std::os::unix::net::UnixStream; use std::sync::atomic::Ordering; self.shutdown.store(true, Ordering::Release); if let Some(thread) = self.thread.take() { let _ignored = UnixStream::connect(&self.socket); let _ignored = thread.join(); } let removable = std::fs::symlink_metadata(&self.socket).is_ok_and(|metadata| { metadata.file_type().is_socket() && metadata.dev() == self.socket_identity.device && metadata.ino() == self.socket_identity.inode }); if removable { let _ignored = std::fs::remove_file(&self.socket); } } } #[cfg(unix)] fn receive_reload_requests( listener: &std::os::unix::net::UnixListener, sender: &std::sync::mpsc::SyncSender, shutdown: &std::sync::Arc, ) { use std::io::{Read, Write}; use std::sync::atomic::Ordering; use std::time::Duration; while !shutdown.load(Ordering::Acquire) { let (mut stream, _address) = match listener.accept() { Ok(connection) => connection, Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => { std::thread::sleep(Duration::from_millis(10)); continue; } Err(_) => break, }; if shutdown.load(Ordering::Acquire) { break; } let _ignored = stream.set_read_timeout(Some(Duration::from_secs(1))); let _ignored = stream.set_write_timeout(Some(Duration::from_secs(1))); let mut request = [0; RELOAD_REQUEST.len()]; if stream.read_exact(&mut request).is_ok() && request == RELOAD_REQUEST { let _coalesced = sender.try_send(ReloadRequest::Reload); let _ignored = stream.write_all(RELOAD_RESPONSE); } } } #[cfg(unix)] fn ensure_private_directory(directory: &Path) -> Result<()> { use std::os::unix::fs::{MetadataExt, PermissionsExt}; let parent = directory .parent() .ok_or_else(|| control_fault("plugin reload directory has no parent"))?; std::fs::create_dir_all(parent) .map_err(|error| control_fault(format!("plugin reload parent creation failed: {error}")))?; match std::fs::create_dir(directory) { Ok(()) => std::fs::set_permissions(directory, std::fs::Permissions::from_mode(0o700)) .map_err(|error| { control_fault(format!( "plugin reload directory permission setup failed: {error}" )) })?, Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => {} Err(error) => { return Err(control_fault(format!( "plugin reload directory creation failed: {error}" ))); } } let metadata = std::fs::symlink_metadata(directory).map_err(|error| { control_fault(format!("plugin reload directory metadata failed: {error}")) })?; if !metadata.is_dir() || metadata.file_type().is_symlink() { return Err(control_fault( "plugin reload directory is not a real directory", )); } if metadata.mode() & 0o077 != 0 { return Err(control_fault( "plugin reload directory must not be group or world accessible", )); } Ok(()) } fn control_fault(message: impl Into) -> SmithError { SmithError::Provider { fault: ProviderFault::Plugin { message: message.into(), }, } } #[cfg(all(test, unix))] mod tests { //! Local socket tests (`SMH-SPEC-PLUG0001`, Generations). use super::*; use std::io::{Read, Write}; use std::os::unix::net::UnixStream; #[test] fn longer_runtime_directory_binds_within_unix_socket_path_limit() { let session = smith::id::SessionId::new(); let socket_name = smith::config::plugin_control_socket_path(session) .file_name() .unwrap() .to_owned(); let prefix = std::env::temp_dir().join(format!("spc-long-{}-", std::process::id())); let fixed_bytes = prefix.as_os_str().as_encoded_bytes().len() + 1 + socket_name.as_encoded_bytes().len(); let padding = 107_usize.checked_sub(fixed_bytes).expect( "controlled TMPDIR must leave room for the fixture directory and socket basename", ); let root = prefix.with_file_name(format!( "{}{}", prefix.file_name().unwrap().to_str().unwrap(), "x".repeat(padding) )); let _ignored = std::fs::remove_dir_all(&root); std::fs::create_dir_all(&root).unwrap(); use std::os::unix::fs::PermissionsExt; std::fs::set_permissions(&root, std::fs::Permissions::from_mode(0o700)).unwrap(); let socket = root.join(socket_name); let control = ReloadControl::bind_at_path(socket.clone()).unwrap(); assert_eq!(socket.as_os_str().as_encoded_bytes().len(), 107); assert_eq!( std::fs::symlink_metadata(&socket) .unwrap() .permissions() .mode() & 0o777, 0o600 ); drop(control); assert!(!socket.exists()); std::fs::remove_dir_all(root).unwrap(); } #[test] fn session_runtime_endpoints_are_distinct_and_concurrent() { let root = std::env::temp_dir().join(format!("spc-concurrent-{}", std::process::id())); let _ignored = std::fs::remove_dir_all(&root); std::fs::create_dir_all(&root).unwrap(); use std::os::unix::fs::PermissionsExt; std::fs::set_permissions(&root, std::fs::Permissions::from_mode(0o700)).unwrap(); let first_session = smith::id::SessionId::new(); let second_session = smith::id::SessionId::new(); let first_path = smith::config::plugin_control_socket_path(first_session); let second_path = smith::config::plugin_control_socket_path(second_session); assert_ne!(first_path, second_path); let first = ReloadControl::bind_at_path(root.join(first_path.file_name().unwrap())).unwrap(); let second = ReloadControl::bind_at_path(root.join(second_path.file_name().unwrap())).unwrap(); assert!(first.socket.exists()); assert!(second.socket.exists()); request_reload_at_path(&first.socket).unwrap(); request_reload_at_path(&second.socket).unwrap(); assert!(first.take_reload_request()); assert!(second.take_reload_request()); drop(first); drop(second); std::fs::remove_dir_all(root).unwrap(); } #[test] fn failed_bind_preserves_a_foreign_socket() { let root = std::env::temp_dir().join(format!("spc-foreign-{}", std::process::id())); let _ignored = std::fs::remove_dir_all(&root); std::fs::create_dir_all(&root).unwrap(); use std::os::unix::fs::PermissionsExt; std::fs::set_permissions(&root, std::fs::Permissions::from_mode(0o700)).unwrap(); let socket = root.join("foreign.sock"); let foreign = std::os::unix::net::UnixListener::bind(&socket).unwrap(); assert!(ReloadControl::bind_at_path(socket.clone()).is_err()); assert!(socket.exists()); drop(foreign); std::fs::remove_file(&socket).unwrap(); std::fs::remove_dir_all(root).unwrap(); } #[test] fn drop_preserves_a_socket_replaced_after_binding() { let root = std::env::temp_dir().join(format!("spc-replaced-{}", std::process::id())); let _ignored = std::fs::remove_dir_all(&root); std::fs::create_dir_all(&root).unwrap(); use std::os::unix::fs::PermissionsExt; std::fs::set_permissions(&root, std::fs::Permissions::from_mode(0o700)).unwrap(); let socket = root.join("replaced.sock"); let control = ReloadControl::bind_at_path(socket.clone()).unwrap(); std::fs::remove_file(&socket).unwrap(); let foreign = std::os::unix::net::UnixListener::bind(&socket).unwrap(); drop(control); assert!(socket.exists()); drop(foreign); std::fs::remove_file(&socket).unwrap(); std::fs::remove_dir_all(root).unwrap(); } #[test] fn reload_request_is_acknowledged_and_coalesced_at_the_safe_boundary() { let root = std::env::temp_dir().join(format!("spc-{}", std::process::id())); let _ignored = std::fs::remove_dir_all(&root); std::fs::create_dir_all(&root).unwrap(); use std::os::unix::fs::PermissionsExt; std::fs::set_permissions(&root, std::fs::Permissions::from_mode(0o700)).unwrap(); let socket = root.join("plugin-reload.sock"); let control = ReloadControl::bind_at_path(socket.clone()).unwrap(); let client = std::thread::spawn(move || { let mut stream = UnixStream::connect(socket).unwrap(); stream.write_all(RELOAD_REQUEST).unwrap(); let mut response = [0; RELOAD_RESPONSE.len()]; stream.read_exact(&mut response).unwrap(); response }); assert_eq!(client.join().unwrap(), RELOAD_RESPONSE); assert!(control.take_reload_request()); assert!(!control.take_reload_request()); drop(control); assert!(!root.join("plugin-reload.sock").exists()); std::fs::remove_dir_all(root).unwrap(); } }