use std::fs;
use std::io;
#[cfg(unix)]
use std::os::fd::{AsRawFd, OwnedFd, RawFd};
#[cfg(unix)]
use std::os::unix::process::ExitStatusExt as _;
use std::path::Path;
use std::process::Stdio;
#[cfg(unix)]
use std::sync::Arc;
#[cfg(unix)]
use command_fds::{CommandFdExt, FdMapping};
#[cfg(unix)]
use nix::sys::signal::{self, Signal};
#[cfg(unix)]
use nix::unistd::Pid;
use shep_core::signals::OperatorSignal;
#[cfg(unix)]
use tokio::net::UnixStream;
use tokio::process::{Child, Command};
use tokio::sync::mpsc;
use crate::channel::CHANNEL_VERSION;
#[cfg(unix)]
use crate::runner::{AdoptSpec, AdoptedReaper};
use crate::runner::{
ExitOutcome, Preflight, ProcIo, ProcessRunner, RunnerError, RunningProcess, SpawnSpec,
StopSignal,
};
use super::CHANNEL_CAPACITY;
#[cfg(unix)]
use super::log_file::carried_sink;
use super::log_file::{LogSink, PipeFds};
use super::pump::{spawn_channel_pumps, spawn_log_pump, spawn_stdin_pump};
#[derive(Debug, Default)]
pub struct TokioRunner;
#[cfg(windows)]
const KILL_TREE_EXIT_CODE: u32 = 137;
#[cfg(windows)]
static NEXT_CHANNEL_ID: core::sync::atomic::AtomicU64 = core::sync::atomic::AtomicU64::new(0);
impl TokioRunner {
#[must_use]
pub fn new() -> Self {
Self
}
}
#[derive(Debug)]
pub struct TokioProc {
pid: u32,
proc: Supervised,
#[cfg(windows)]
job: crate::sys_windows::Job,
}
#[derive(Debug)]
enum Supervised {
Spawned(Child),
#[cfg(unix)]
Adopted(Arc<AdoptedReaper>),
}
impl RunningProcess for TokioProc {
fn pid(&self) -> u32 {
self.pid
}
async fn wait(&mut self) -> ExitOutcome {
let child = match &mut self.proc {
Supervised::Spawned(child) => child,
#[cfg(unix)]
Supervised::Adopted(reaper) => {
return match reaper.wait(self.pid).await {
Ok(outcome) => outcome,
Err(error) => {
tracing::error!(pid = self.pid, %error, "adopted process wait failed");
ExitOutcome {
code: None,
signal: None,
}
}
};
}
};
match child.wait().await {
Ok(status) => ExitOutcome {
code: status.code(),
#[cfg(windows)]
signal: None,
#[cfg(unix)]
signal: status.signal(),
},
Err(error) => {
tracing::error!(pid = self.pid, %error, "process wait() failed");
ExitOutcome {
code: None,
signal: None,
}
}
}
}
#[cfg(unix)]
fn signal(&mut self, sig: StopSignal) -> Result<(), RunnerError> {
signal_group(self.pid, to_nix_signal(sig))
}
#[cfg(windows)]
fn signal(&mut self, sig: StopSignal) -> Result<(), RunnerError> {
Err(RunnerError::SignalFailed(format!(
"Windows cannot deliver {sig:?} to another process; \
an app that needs a graceful stop must opt into the shepherd \
channel (shutdown_with_message), otherwise the stop escalates \
to a forced termination after kill_timeout"
)))
}
#[cfg(unix)]
fn kill_tree(&mut self) -> Result<(), RunnerError> {
signal_group(self.pid, Signal::SIGKILL)
}
#[cfg(windows)]
fn kill_tree(&mut self) -> Result<(), RunnerError> {
self.job
.terminate(KILL_TREE_EXIT_CODE)
.map_err(|error| RunnerError::SignalFailed(error.to_string()))
}
#[cfg(windows)]
fn signal_process(&mut self, sig: OperatorSignal) -> Result<(), RunnerError> {
let Supervised::Spawned(child) = &mut self.proc;
match sig {
OperatorSignal::Kill => child
.start_kill()
.map_err(|error| RunnerError::SignalFailed(error.to_string())),
other => Err(RunnerError::SignalFailed(format!(
"Windows has no way to deliver {other:?} to another process; \
only SIGKILL is available here"
))),
}
}
#[cfg(unix)]
fn signal_process(&mut self, sig: OperatorSignal) -> Result<(), RunnerError> {
let pid = signallable_pid(self.pid)?;
signal::kill(Pid::from_raw(pid), to_nix_operator_signal(sig))
.map_err(|error| RunnerError::SignalFailed(error.to_string()))
}
}
#[cfg(unix)]
pub(super) fn signallable_pid(pid: u32) -> Result<i32, RunnerError> {
i32::try_from(pid)
.ok()
.filter(|pid| *pid > 0)
.ok_or_else(|| {
RunnerError::SignalFailed(format!("pid {pid} is not a signallable process id"))
})
}
#[cfg(unix)]
pub(crate) fn signal_group(pid: u32, sig: Signal) -> Result<(), RunnerError> {
let pid = signallable_pid(pid)?;
signal::kill(Pid::from_raw(-pid), sig)
.map_err(|error| RunnerError::SignalFailed(error.to_string()))
}
#[cfg(unix)]
fn to_nix_signal(sig: StopSignal) -> Signal {
match sig {
StopSignal::Term => Signal::SIGTERM,
StopSignal::Int => Signal::SIGINT,
StopSignal::Quit => Signal::SIGQUIT,
StopSignal::Usr2 => Signal::SIGUSR2,
StopSignal::Kill => Signal::SIGKILL,
}
}
#[cfg(unix)]
fn to_nix_operator_signal(sig: OperatorSignal) -> Signal {
match sig {
OperatorSignal::Hup => Signal::SIGHUP,
OperatorSignal::Int => Signal::SIGINT,
OperatorSignal::Quit => Signal::SIGQUIT,
OperatorSignal::Term => Signal::SIGTERM,
OperatorSignal::Usr1 => Signal::SIGUSR1,
OperatorSignal::Usr2 => Signal::SIGUSR2,
OperatorSignal::Winch => Signal::SIGWINCH,
OperatorSignal::Cont => Signal::SIGCONT,
OperatorSignal::Kill => Signal::SIGKILL,
}
}
pub(super) fn what_exec_will_find(spec: &SpawnSpec) -> Preflight {
if spec.program.is_empty() {
return Preflight::Unknown;
}
let program = Path::new(&spec.program);
if spec.program.contains('/') || spec.program.contains(std::path::MAIN_SEPARATOR) {
let full = if program.is_absolute() {
program.to_path_buf()
} else {
match &spec.cwd {
Some(cwd) => cwd.join(program),
None => return Preflight::Unknown,
}
};
if !definitely_absent(&full) {
return Preflight::Unknown;
}
return Preflight::Impossible(format!("no such file: {}", full.display()));
}
let Some(path) = spec.env.get("PATH").filter(|value| !value.is_empty()) else {
return Preflight::Unknown;
};
for dir in std::env::split_paths(path).filter(|dir| !dir.as_os_str().is_empty()) {
match fs::metadata(dir.join(program)) {
Ok(_) => return Preflight::Unknown,
Err(err) if err.kind() == io::ErrorKind::NotFound => {}
Err(_) => return Preflight::Unknown,
}
}
Preflight::Doubtful(format!(
"`{}` is not on the shepherd's PATH ({})",
spec.program,
summarise_path(path)
))
}
const PATH_ENTRIES_IN_MESSAGE: usize = 4;
pub(super) const PATH_LIST_SEPARATOR: char = if cfg!(windows) { ';' } else { ':' };
pub(super) fn summarise_path(path: &str) -> String {
let entries: Vec<&str> = path
.split(PATH_LIST_SEPARATOR)
.filter(|dir| !dir.is_empty())
.collect();
if entries.len() <= PATH_ENTRIES_IN_MESSAGE {
return path.to_string();
}
format!(
"{} and {} more entries",
entries[..PATH_ENTRIES_IN_MESSAGE].join(&PATH_LIST_SEPARATOR.to_string()),
entries.len() - PATH_ENTRIES_IN_MESSAGE,
)
}
fn definitely_absent(path: &Path) -> bool {
matches!(fs::metadata(path), Err(err) if err.kind() == io::ErrorKind::NotFound)
}
impl ProcessRunner for TokioRunner {
type Proc = TokioProc;
fn preflight(&self, spec: &SpawnSpec) -> Preflight {
what_exec_will_find(spec)
}
#[cfg(unix)]
fn adopt(&self, spec: AdoptSpec) -> Result<(Self::Proc, ProcIo), RunnerError> {
let AdoptSpec {
pid,
out_file,
err_file,
out_pipe,
err_pipe,
out_log,
err_log,
log_timestamps,
stdin_pipe,
channel,
reaper,
} = spec;
let (logs_tx, logs_rx) = mpsc::channel(CHANNEL_CAPACITY);
let (log_ctl_tx, log_ctl_rx) = mpsc::channel(CHANNEL_CAPACITY);
let pipes = PipeFds {
out: out_pipe.as_ref().map(AsRawFd::as_raw_fd),
err: err_pipe.as_ref().map(AsRawFd::as_raw_fd),
stdin: stdin_pipe.as_ref().map(AsRawFd::as_raw_fd),
channel: channel.as_ref().map(AsRawFd::as_raw_fd),
};
spawn_log_pump(
out_pipe,
err_pipe,
carried_sink(out_file, out_log),
carried_sink(err_file, err_log),
log_timestamps,
logs_tx,
log_ctl_rx,
pipes,
);
let (from_child_tx, from_child) = mpsc::channel(CHANNEL_CAPACITY);
let (to_child, to_child_rx) = mpsc::channel(CHANNEL_CAPACITY);
if let Some(channel) = channel {
spawn_channel_pumps(channel, from_child_tx, to_child_rx);
} else {
drop(from_child_tx);
drop(to_child_rx);
}
let (to_stdin, to_stdin_rx) = mpsc::channel(CHANNEL_CAPACITY);
if let Some(stdin_pipe) = stdin_pipe {
spawn_stdin_pump(Some(stdin_pipe), to_stdin_rx);
} else {
drop(to_stdin_rx);
}
Ok((
TokioProc {
pid,
proc: Supervised::Adopted(reaper),
},
ProcIo {
logs: logs_rx,
from_child,
to_child,
log_ctl: log_ctl_tx,
to_stdin,
},
))
}
fn spawn(&self, spec: &SpawnSpec) -> Result<(Self::Proc, ProcIo), RunnerError> {
let mut command = Command::new(&spec.program);
command.args(&spec.args);
if let Some(cwd) = &spec.cwd {
command.current_dir(cwd);
}
command.env_clear();
command.envs(&spec.env);
command.stdin(if spec.stdin {
Stdio::piped()
} else {
Stdio::null()
});
command.stdout(Stdio::piped());
command.stderr(Stdio::piped());
#[cfg(unix)]
command.process_group(0);
#[cfg(windows)]
{
const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
const CREATE_NO_WINDOW: u32 = 0x0800_0000;
command.creation_flags(CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW);
}
#[cfg(unix)]
if let Some(creds) = spec.credentials {
if let Some(gid) = creds.gid {
command.gid(gid);
}
command.uid(creds.uid);
}
#[cfg(windows)]
debug_assert!(
spec.credentials.is_none(),
"privilege::resolve must refuse user/group on Windows before a spawn is reached"
);
let (from_child_tx, from_child_rx) = mpsc::channel(CHANNEL_CAPACITY);
let (to_child_tx, to_child_rx) = mpsc::channel(CHANNEL_CAPACITY);
#[cfg(windows)]
if spec.channel {
use shep_core::transport;
let mut nonce = [0_u8; 16];
getrandom::fill(&mut nonce).map_err(|error| {
RunnerError::SpawnFailed(format!("shepherd channel pipe name: {error}"))
})?;
let pipe = std::path::PathBuf::from(format!(
r"\\.\pipe\shep-channel-{}-{}-{:032x}",
std::process::id(),
NEXT_CHANNEL_ID.fetch_add(1, core::sync::atomic::Ordering::Relaxed),
u128::from_ne_bytes(nonce)
));
let mut listener = transport::Listener::bind(&pipe).map_err(|error| {
RunnerError::SpawnFailed(format!("shepherd channel pipe: {error}"))
})?;
command.env("SHEP_CHANNEL_PIPE", &pipe);
command.env("SHEP_CHANNEL_VERSION", CHANNEL_VERSION);
let from_child_tx = from_child_tx.clone();
tokio::spawn(async move {
let watcher = from_child_tx.clone();
tokio::select! {
accepted = listener.accept() => match accepted {
Ok(daemon_end) => {
spawn_channel_pumps(daemon_end, from_child_tx, to_child_rx);
}
Err(error) => {
tracing::warn!(%error, "shepherd channel accept failed");
}
},
() = watcher.closed() => {}
}
});
} else {
drop(to_child_rx);
}
#[cfg(unix)]
let mut channel_fd: Option<RawFd> = None;
#[cfg(unix)]
if spec.channel {
command.env("SHEP_CHANNEL_FD", "3");
command.env("SHEP_CHANNEL_VERSION", CHANNEL_VERSION);
let (daemon_end, child_end) = UnixStream::pair().map_err(|error| {
RunnerError::SpawnFailed(format!("shepherd channel socketpair: {error}"))
})?;
let std_child_end = child_end.into_std().map_err(|error| {
RunnerError::SpawnFailed(format!("shepherd channel into_std: {error}"))
})?;
std_child_end.set_nonblocking(false).map_err(|error| {
RunnerError::SpawnFailed(format!("shepherd channel set_nonblocking: {error}"))
})?;
let child_fd = OwnedFd::from(std_child_end);
command
.as_std_mut()
.fd_mappings(vec![FdMapping {
parent_fd: child_fd,
child_fd: 3,
}])
.map_err(|error| {
RunnerError::SpawnFailed(format!("shepherd channel fd mapping: {error}"))
})?;
channel_fd = Some(daemon_end.as_raw_fd());
spawn_channel_pumps(daemon_end, from_child_tx, to_child_rx);
} else {
drop(from_child_tx);
drop(to_child_rx);
}
let mut child = command
.spawn()
.map_err(|error| RunnerError::SpawnFailed(error.to_string()))?;
drop(command);
let pid = child.id().ok_or_else(|| {
RunnerError::SpawnFailed("child exited before its pid could be read".to_string())
})?;
#[cfg(windows)]
let job = {
let job = crate::sys_windows::Job::create().map_err(|error| {
RunnerError::SpawnFailed(format!("job object for {}: {error}", spec.name))
})?;
let handle = child.raw_handle().ok_or_else(|| {
RunnerError::SpawnFailed("child exited before it could be contained".to_string())
})?;
if let Err(error) = job.assign(handle) {
let _ = child.start_kill();
return Err(RunnerError::SpawnFailed(format!(
"could not contain {} in a job object: {error}",
spec.name
)));
}
job
};
let (logs_tx, logs_rx) = mpsc::channel(CHANNEL_CAPACITY);
let (log_ctl_tx, log_ctl_rx) = mpsc::channel(CHANNEL_CAPACITY);
#[cfg(unix)]
let pipes = PipeFds {
out: child.stdout.as_ref().map(AsRawFd::as_raw_fd),
err: child.stderr.as_ref().map(AsRawFd::as_raw_fd),
stdin: child.stdin.as_ref().map(AsRawFd::as_raw_fd),
channel: channel_fd,
};
#[cfg(not(unix))]
let pipes = PipeFds;
spawn_log_pump(
child.stdout.take(),
child.stderr.take(),
LogSink::Path(spec.out_file.clone()),
LogSink::Path(spec.err_file.clone()),
spec.log_timestamps,
logs_tx,
log_ctl_rx,
pipes,
);
let (to_stdin_tx, to_stdin_rx) = mpsc::channel(CHANNEL_CAPACITY);
if spec.stdin {
spawn_stdin_pump(child.stdin.take(), to_stdin_rx);
} else {
drop(to_stdin_rx);
}
let io = ProcIo {
logs: logs_rx,
from_child: from_child_rx,
to_child: to_child_tx,
log_ctl: log_ctl_tx,
to_stdin: to_stdin_tx,
};
Ok((
TokioProc {
pid,
proc: Supervised::Spawned(child),
#[cfg(windows)]
job,
},
io,
))
}
}