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();
}
}