Luigit
repositories / smith

smith

There are many coding harnesses - but this one is fast

owned by admin

smith-harness/src/plugin_control.rs

Raw
//! 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<smith::id::SessionId>) -> 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<Vec<PathBuf>> {
    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<smith::id::SessionId>) -> 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<ReloadRequest>,
    shutdown: std::sync::Arc<std::sync::atomic::AtomicBool>,
    socket: PathBuf,
    socket_identity: SocketIdentity,
    thread: Option<std::thread::JoinHandle<()>>,
}

/// 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> {
        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<Self> {
        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<Self> {
        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> {
        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<ReloadRequest>,
    shutdown: &std::sync::Arc<std::sync::atomic::AtomicBool>,
) {
    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<String>) -> 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();
    }
}