feat: release 3.0.4 with background connections and service startup improvements

This commit is contained in:
Kevin Yue committed 2026-10-12 23:53:21 +08:00
1 parent 57322e3cf3
commit ff1ea259d9
42 files changed
+1040 -584

No files matched your search

+1
View File
@@ -17,6 +17,7 @@ clap.workspace = true
env_logger.workspace = true
inquire = "0.9"
log.workspace = true
nix = { version = "0.31", features = ["fs", "signal", "process"] }
tokio = { workspace = true, features = ["rt-multi-thread"] }
tokio-util.workspace = true
sysinfo.workspace = true
+302
View File
@@ -0,0 +1,302 @@
//! Re-exec a worker in the foreground for sign-in, then detach only after tunnel setup.
//! No process is forked after authentication or OpenConnect has started its threads.
use std::{
ffi::OsString,
fs::{File, OpenOptions},
io::{self, Write},
os::{
fd::{AsRawFd, FromRawFd, OwnedFd},
unix::{
fs::{MetadataExt, OpenOptionsExt, PermissionsExt},
net::UnixStream,
},
},
path::Path,
process::{ExitStatus, Stdio},
};
use anyhow::{Context, bail};
use nix::{
fcntl::{FcntlArg, FdFlag, OFlag, fcntl},
sys::signal::{Signal, kill},
unistd::{Pid, dup2_stderr, dup2_stdin, dup2_stdout, setsid},
};
use tokio::{io::AsyncReadExt, process::Command};
const READY: u8 = 1;
pub(crate) struct BackgroundWorker {
ready: UnixStream,
log: File,
input: File,
}
// Keep sign-in interactive again if a tunnel attempt fails before detachment.
pub(crate) struct BackgroundStdio {
saved: Option<[OwnedFd; 3]>,
}
impl Drop for BackgroundStdio {
fn drop(&mut self) {
if let Some([input, output, error]) = &self.saved {
let _ = io::stdout().flush();
let _ = io::stderr().flush();
let result = dup2_stdin(input)
.and_then(|_| dup2_stdout(output))
.and_then(|_| dup2_stderr(error));
if let Err(error) = result {
log::warn!("Cannot restore foreground standard streams: {error}");
}
}
}
}
impl BackgroundWorker {
pub(crate) fn new(fd: i32, log_path: &Path) -> anyhow::Result<Self> {
anyhow::ensure!(fd >= 3, "Invalid background readiness descriptor");
// Validate the raw descriptor before taking ownership; malformed internal args
// must return an error rather than violate OwnedFd's validity requirement.
if unsafe { nix::libc::fcntl(fd, nix::libc::F_GETFD) } == -1 {
return Err(io::Error::last_os_error().into());
}
// The launcher passes its own readiness socket across exec, without authentication state.
let ready = unsafe { UnixStream::from_raw_fd(fd) };
ready.peer_addr().context("Invalid background readiness socket")?;
fcntl(&ready, FcntlArg::F_SETFD(FdFlag::FD_CLOEXEC))?;
let log = OpenOptions::new()
.create(true)
.append(true)
.mode(0o600)
.custom_flags(OFlag::O_NOFOLLOW.bits() | OFlag::O_NONBLOCK.bits())
.open(log_path)
.with_context(|| format!("Cannot open background log {}", log_path.display()))?;
let metadata = log.metadata()?;
anyhow::ensure!(metadata.is_file(), "Background log must be a regular file");
anyhow::ensure!(
metadata.uid() == uzers::get_effective_uid(),
"Background log must be owned by the user running gpclient"
);
anyhow::ensure!(
metadata.permissions().mode() & 0o077 == 0,
"Background log must not be readable or writable by other users"
);
let input = File::open("/dev/null")?;
Ok(Self { ready, log, input })
}
pub(crate) fn redirect_stdio(&self) -> anyhow::Result<BackgroundStdio> {
io::stdout().flush()?;
io::stderr().flush()?;
let save = |fd| -> anyhow::Result<OwnedFd> {
// Duplicate atomically with close-on-exec so helpers never inherit the terminal copies.
let saved = unsafe { nix::libc::fcntl(fd, nix::libc::F_DUPFD_CLOEXEC, 3) };
if saved == -1 {
return Err(io::Error::last_os_error().into());
}
Ok(unsafe { OwnedFd::from_raw_fd(saved) })
};
let stdio = BackgroundStdio {
saved: Some([save(0)?, save(1)?, save(2)?]),
};
// Redirect before tunnel setup, which can start a persistent --script-tun helper.
dup2_stdin(&self.input)?;
dup2_stdout(&self.log)?;
dup2_stderr(&self.log)?;
Ok(stdio)
}
pub(crate) fn detach(&self, stdio: &mut BackgroundStdio) -> anyhow::Result<()> {
// The worker inherited the launcher's foreground group, so it can prompt normally.
// It becomes a session leader only when sign-in and tunnel configuration are done.
setsid().context("Cannot detach the VPN session from the terminal")?;
(&self.ready)
.write_all(&[READY])
.context("Background launcher exited before tunnel setup")?;
stdio.saved.take();
Ok(())
}
}
pub(crate) async fn start(log_path: &Path, format: gpapi::log_format::LogFormat) -> anyhow::Result<()> {
let command = Command::new(std::env::current_exe()?);
let arguments = std::env::args_os().skip(1).collect::<Vec<_>>();
launch(command, &arguments)
.await
.with_context(|| format!("Background VPN startup failed; log file: {}", log_path.display()))?;
gpapi::clap::report(
format,
log::Level::Info,
&format!("VPN is running in the background. Logs: {}", log_path.display()),
);
Ok(())
}
async fn launch(mut command: Command, arguments: &[OsString]) -> anyhow::Result<()> {
let (parent, worker) = UnixStream::pair()?;
parent.set_nonblocking(true)?;
let mut ready = tokio::net::UnixStream::from_std(parent)?;
let fd = worker.as_raw_fd();
command.arg("--background-worker-fd").arg(fd.to_string());
// Internal options precede user arguments, which can include the `--` terminator.
command.args(arguments);
command
.stdin(Stdio::inherit())
.stdout(Stdio::inherit())
.stderr(Stdio::inherit());
// Only async-signal-safe descriptor setup runs between spawn's fork and exec.
unsafe {
command.pre_exec(move || {
fcntl(&worker, FcntlArg::F_SETFD(FdFlag::empty())).map_err(io::Error::from)?;
Ok(())
});
}
let mut child = command.spawn().context("Cannot start background VPN worker")?;
// Release our copy of the worker's socket so EOF reports startup failure.
drop(command);
let pid = Pid::from_raw(child.id().context("Background worker has no PID")? as i32);
let outcome = tokio::select! {
result = ready.read_u8() => result.map_err(anyhow::Error::from),
status = child.wait() => return startup_exit(status?),
_ = gpapi::utils::shutdown_signal() => {
let _ = kill(pid, Signal::SIGINT);
child.wait().await?;
bail!("Background connection cancelled");
}
};
match outcome {
Ok(READY) => Ok(()),
_ => {
let _ = kill(pid, Signal::SIGINT);
startup_exit(child.wait().await?)
}
}
}
fn startup_exit(status: ExitStatus) -> anyhow::Result<()> {
bail!("Background VPN exited before the tunnel was established ({status})")
}
#[cfg(test)]
mod tests {
use super::*;
use nix::unistd::{getpid, getsid};
use std::time::Duration;
// Re-exec the test binary so the test exercises real process/session/descriptor setup.
// The shell consumes launch's internal FD argument instead of giving it to libtest.
fn fixture(directory: &Path) -> Command {
let mut command = Command::new("sh");
command.args(["-c", "export GPCLIENT_TEST_FD=\"$2\"; exec \"$GPCLIENT_TEST_EXE\" --exact background::tests::worker_fixture --nocapture", "fixture"])
.env("GPCLIENT_TEST_EXE", std::env::current_exe().unwrap())
.env("GPCLIENT_TEST_DIR", directory);
command
}
#[tokio::test]
async fn startup_failure_is_not_reported_as_a_background_connection() {
let mut command = Command::new("sh");
command.args(["-c", "exit 7"]);
let error = tokio::time::timeout(Duration::from_secs(5), launch(command, &[]))
.await
.unwrap()
.unwrap_err();
assert!(error.to_string().contains("before the tunnel was established"));
}
#[tokio::test]
async fn detached_worker_survives_launcher_and_disconnects_by_pid() {
let directory = tempfile::tempdir().unwrap();
tokio::time::timeout(Duration::from_secs(5), launch(fixture(directory.path()), &[]))
.await
.unwrap()
.unwrap();
let pid = std::fs::read_to_string(directory.path().join("pid"))
.unwrap()
.parse::<i32>()
.unwrap();
let pid = Pid::from_raw(pid);
assert_eq!(
getsid(Some(pid)).unwrap(),
pid,
"Worker must own a terminal-independent session"
);
kill(pid, None).unwrap();
tokio::time::timeout(Duration::from_secs(5), async {
while !std::fs::read_to_string(directory.path().join("worker.log"))
.unwrap()
.contains("helper-output")
{
tokio::time::sleep(Duration::from_millis(10)).await;
}
})
.await
.unwrap();
let log = std::fs::read_to_string(directory.path().join("worker.log")).unwrap();
assert!(log.contains("failed-attempt-output"));
assert!(!log.contains("restored-foreground-output"));
#[derive(clap::Parser)]
struct Disconnect {
#[command(flatten)]
args: crate::disconnect::DisconnectArgs,
}
let args = <Disconnect as clap::Parser>::parse_from(["test"]);
crate::disconnect::DisconnectHandler::new(&args.args, &directory.path().join("pid"))
.handle()
.await
.unwrap();
tokio::time::timeout(Duration::from_secs(5), async {
while !directory.path().join("stopped").exists() {
tokio::time::sleep(Duration::from_millis(10)).await;
}
})
.await
.unwrap();
}
#[tokio::test]
async fn unsafe_log_path_fails_before_detaching() {
let directory = tempfile::tempdir().unwrap();
std::os::unix::fs::symlink(directory.path().join("target"), directory.path().join("worker.log")).unwrap();
let result = tokio::time::timeout(Duration::from_secs(5), launch(fixture(directory.path()), &[]))
.await
.unwrap();
assert!(result.is_err());
assert!(!directory.path().join("target").exists());
}
#[tokio::test]
async fn worker_fixture() {
let Ok(fd) = std::env::var("GPCLIENT_TEST_FD") else {
return;
};
let directory = std::path::PathBuf::from(std::env::var_os("GPCLIENT_TEST_DIR").unwrap());
let worker = match BackgroundWorker::new(fd.parse().unwrap(), &directory.join("worker.log")) {
Ok(worker) => worker,
Err(error) => {
eprintln!("{error:#}");
std::process::exit(1);
}
};
let mut interrupt = tokio::signal::unix::signal(tokio::signal::unix::SignalKind::interrupt()).unwrap();
std::fs::write(directory.join("pid"), getpid().to_string()).unwrap();
// A failed attempt must restore foreground streams before another sign-in.
{
let _stdio = worker.redirect_stdio().unwrap();
println!("failed-attempt-output");
}
println!("restored-foreground-output");
let mut stdio = worker.redirect_stdio().unwrap();
// Like OpenConnect's script-tun helper, this child starts before readiness.
let mut helper = std::process::Command::new("sh")
.args(["-c", "sleep 0.1; echo helper-output"])
.spawn()
.unwrap();
worker.detach(&mut stdio).unwrap();
println!("detached-output");
io::stdout().flush().unwrap();
interrupt.recv().await;
helper.wait().unwrap();
std::fs::write(directory.join("stopped"), "stopped").unwrap();
}
}
+70 -1
View File
@@ -107,6 +107,9 @@ struct Cli {
)]
lock_file: PathBuf,
#[arg(long, hide = true, global = true)]
background_worker_fd: Option<i32>,
#[arg(
long,
value_enum,
@@ -171,6 +174,9 @@ impl Cli {
}
async fn run(&self) -> anyhow::Result<()> {
if self.background_worker_fd.is_some() && !matches!(&self.command, CliCommand::Connect(args) if args.background) {
bail!("Background worker requires connect --background");
}
if let CliCommand::Diagnostics(args) = &self.command {
return args.run(VERSION).await;
}
@@ -180,6 +186,23 @@ impl Cli {
bail!("Another instance of the client is already running");
}
let background_worker = if let CliCommand::Connect(args) = &self.command {
if args.background {
let log_file = args
.log_file
.as_deref()
.unwrap_or_else(|| Path::new("/var/log/gpclient.log"));
match self.background_worker_fd {
Some(fd) => Some(crate::background::BackgroundWorker::new(fd, log_file)?),
None => return crate::background::start(log_file, self.log_format).await,
}
} else {
None
}
} else {
None
};
// The temp file will be dropped automatically when the file handle is dropped
// So, declare it here to ensure it's not dropped
let _file = self.fix_openssl()?;
@@ -196,7 +219,12 @@ impl Cli {
}
match &self.command {
CliCommand::Connect(args) => ConnectHandler::new(args, &shared_args).handle().await,
CliCommand::Connect(args) => {
ConnectHandler::new(args, &shared_args)
.with_background(background_worker)
.handle()
.await
}
CliCommand::Disconnect(args) => DisconnectHandler::new(args, shared_args.lock_file).handle().await,
CliCommand::LaunchGui(args) => LaunchGuiHandler::new(args).handle().await,
CliCommand::Hip(args) => HipHandler::new(args).handle().await,
@@ -256,6 +284,47 @@ mod tests {
use super::*;
#[test]
fn background_worker_option_precedes_user_option_terminator() {
let cli = Cli::try_parse_from([
"gpclient",
"--background-worker-fd",
"3",
"connect",
"--background",
"--",
"portal.example.com",
])
.unwrap();
assert_eq!(cli.background_worker_fd, Some(3));
assert!(matches!(cli.command, CliCommand::Connect(args) if args.background));
}
#[test]
fn background_mode_rejects_cookie_only_and_requires_background_for_log_file() {
assert!(
Cli::try_parse_from([
"gpclient",
"connect",
"portal.example.com",
"--background",
"--cookie-only"
])
.is_err()
);
assert!(Cli::try_parse_from(["gpclient", "connect", "portal.example.com", "--log-file", "/tmp/gp.log"]).is_err());
assert!(
Cli::try_parse_from([
"gpclient",
"connect",
"portal.example.com",
"--background",
"--passwd-on-stdin"
])
.is_ok()
);
}
#[test]
fn diagnostics_accepts_output_options_and_runs_alongside_the_client() {
let cli = Cli::try_parse_from([
+14
View File
@@ -13,6 +13,20 @@ pub(crate) struct ConnectArgs {
#[arg(help = "The portal server to connect to")]
pub(super) server: String,
#[arg(
long,
conflicts_with = "cookie_only",
help = "Complete sign-in, then keep the VPN running after this command exits"
)]
pub(crate) background: bool,
#[arg(
long,
requires = "background",
help = "Background log file (default: /var/log/gpclient.log)"
)]
pub(crate) log_file: Option<PathBuf>,
#[arg(short, long, help = "The gateway to connect to, it will prompt if not specified")]
pub(super) gateway: Option<String>,
+118 -6
View File
@@ -484,6 +484,13 @@ impl ConnectHandler<'_> {
let disconnect_requested_on_signal = Arc::clone(&disconnect_requested);
let cancellation = self.cancellation.clone();
let mut background_stdio = self
.background
.as_ref()
.map(|background| background.redirect_stdio())
.transpose()
.map_err(GatewayConnectError::before_establishment)?;
let disconnect_task = tokio::spawn(async move {
cancellation.cancelled().await;
info!("Received the interrupt signal, disconnecting...");
@@ -497,7 +504,7 @@ impl ConnectHandler<'_> {
let session_cancellation = self.cancellation.clone();
let (established_tx, established_rx) = tokio::sync::oneshot::channel();
self.sessions.borrow_mut().relinquish_gateway(gateway);
let worker = tokio::task::spawn_blocking(move || {
let mut worker = tokio::task::spawn_blocking(move || {
vpn.connect(move |vpn_session_info| {
if session_cancellation.is_cancelled() {
return;
@@ -516,7 +523,7 @@ impl ConnectHandler<'_> {
session_task_on_connect.lock().unwrap().replace(task);
})
});
tokio::pin!(worker);
let mut background_error = None;
let connect_result = tokio::select! {
result = &mut worker => result,
established = established_rx => {
@@ -525,11 +532,26 @@ impl ConnectHandler<'_> {
.filter(|session| session.gateway.server() != gateway)
.map(|session| session.gateway.server().to_owned())
.collect::<Vec<_>>();
for server in unused {
self.logout_gateway(&server).await;
}
wait_for_tunnel_exit(&mut worker, async {
for server in unused {
self.logout_gateway(&server).await;
}
}, || {
if let (Some(background), Some(stdio)) = (&self.background, &mut background_stdio) {
let detach = if self.pid_written.load(Ordering::SeqCst) {
background.detach(stdio)
} else {
Err(anyhow::anyhow!("Cannot detach without a writable PID lock file"))
};
if let Err(error) = detach {
self.cancellation.cancel();
background_error = Some(error);
}
}
}).await
} else {
(&mut worker).await
}
(&mut worker).await
}
};
let tunnel_established = tunnel_established.load(Ordering::SeqCst);
@@ -542,6 +564,10 @@ impl ConnectHandler<'_> {
let _ = task.await;
}
if let Some(error) = background_error {
return Err(GatewayConnectError::after_establishment(error));
}
let disconnect_requested = disconnect_requested.load(Ordering::SeqCst);
let connect_result = connect_result.map_err(|error| GatewayConnectError::after_establishment(error.into()))?;
classify_openconnect_result(connect_result, tunnel_established, disconnect_requested)
@@ -584,6 +610,28 @@ impl ConnectHandler<'_> {
}
}
async fn wait_for_tunnel_exit(
worker: &mut JoinHandle<i32>,
cleanup: impl std::future::Future<Output = ()>,
on_ready: impl FnOnce(),
) -> Result<i32, tokio::task::JoinError> {
tokio::pin!(cleanup);
tokio::select! {
// A finished tunnel must not publish readiness, including when cleanup is
// also ready in the same poll.
biased;
result = &mut *worker => {
// Logout temporarily owns the session registry. Complete it even when
// the tunnel exits, so cancelling this future cannot discard sessions.
cleanup.await;
return result;
},
_ = &mut cleanup => {},
}
on_ready();
worker.await
}
fn classify_openconnect_result(
exit_code: i32,
tunnel_established: bool,
@@ -641,6 +689,70 @@ fn apply_os_profile(builder: VpnBuilder, profile: &OsProfile) -> VpnBuilder {
mod tests {
use super::*;
#[tokio::test]
async fn tunnel_exit_during_startup_cleanup_does_not_publish_readiness() {
let (cleanup_started_tx, cleanup_started_rx) = tokio::sync::oneshot::channel();
let (worker_exited_tx, worker_exited_rx) = tokio::sync::oneshot::channel();
let mut worker = tokio::spawn(async move {
cleanup_started_rx.await.unwrap();
worker_exited_tx.send(()).unwrap();
7
});
let mut ready = false;
let result = tokio::time::timeout(
std::time::Duration::from_secs(5),
wait_for_tunnel_exit(
&mut worker,
async {
cleanup_started_tx.send(()).unwrap();
worker_exited_rx.await.unwrap();
tokio::time::sleep(std::time::Duration::from_millis(10)).await;
},
|| ready = true,
),
)
.await
.expect("Tunnel exit must preserve completed cleanup")
.unwrap();
assert_eq!(result, 7);
assert!(!ready, "An exited tunnel must not report background startup success");
}
#[tokio::test]
async fn finished_tunnel_takes_priority_over_finished_startup_cleanup() {
let mut worker = tokio::spawn(async { 7 });
while !worker.is_finished() {
tokio::task::yield_now().await;
}
let mut ready = false;
let result = wait_for_tunnel_exit(&mut worker, async {}, || ready = true)
.await
.unwrap();
assert_eq!(result, 7);
assert!(!ready, "A ready cleanup must not conceal a finished tunnel");
}
#[tokio::test]
async fn running_tunnel_publishes_readiness_after_startup_cleanup() {
let (ready_tx, ready_rx) = tokio::sync::oneshot::channel();
let mut worker = tokio::spawn(async move {
ready_rx.await.unwrap();
0
});
let cleanup_complete = AtomicBool::new(false);
let result = wait_for_tunnel_exit(
&mut worker,
async { cleanup_complete.store(true, Ordering::SeqCst) },
|| {
assert!(cleanup_complete.load(Ordering::SeqCst));
ready_tx.send(()).unwrap();
},
)
.await
.unwrap();
assert_eq!(result, 0);
}
#[test]
fn hip_script_defaults_to_inherited_process_identity() {
assert_eq!(get_uid(&None).unwrap(), None);
+4
View File
@@ -26,6 +26,10 @@ impl ConnectHandler<'_> {
first_session: super::gateway::GatewayLoginSession,
remaining: &[&Gateway],
) -> anyhow::Result<()> {
ensure!(
self.background.is_none(),
"--background requires a VPN tunnel; internal non-tunnel sessions must run in the foreground"
);
ensure!(remaining.len() < 64, "Too many internal non-tunnel candidates");
let mut hosts = std::collections::HashSet::new();
for gateway in std::iter::once(first_gateway).chain(remaining.iter().copied()) {
+7
View File
@@ -46,6 +46,7 @@ pub(crate) struct ConnectHandler<'a> {
auth_recovery: RefCell<gpapi::process::rendering_recovery::RecoveryState>,
sessions: RefCell<GatewaySessions>,
pid_written: Arc<AtomicBool>,
background: Option<crate::background::BackgroundWorker>,
}
impl<'a> ConnectHandler<'a> {
@@ -71,9 +72,15 @@ impl<'a> ConnectHandler<'a> {
auth_recovery: RefCell::default(),
sessions: RefCell::default(),
pid_written: Arc::default(),
background: None,
}
}
pub(crate) fn with_background(mut self, background: Option<crate::background::BackgroundWorker>) -> Self {
self.background = background;
self
}
fn build_gp_params(&self) -> GpParams {
let mut builder = GpParams::builder(self.os_profile.borrow().clone());
builder
+10 -9
View File
@@ -26,16 +26,19 @@ impl<'a> DisconnectHandler<'a> {
pub async fn handle(&self) -> anyhow::Result<()> {
// Try to disconnect the CLI client
if let Ok(c) = fs::read_to_string(self.lock_file) {
send_signal(c.trim(), Signal::Interrupt).unwrap_or_else(|err| {
let cli_signalled = match fs::read_to_string(self.lock_file) {
Ok(c) => send_signal(c.trim(), Signal::Interrupt).unwrap_or_else(|err| {
warn!("Failed to send signal to client: {}", err);
});
false
}),
Err(_) => false,
};
// Try to disconnect the GUI service
if let Ok(c) = gpservice_lock_info().await {
if !cli_signalled && let Ok(c) = gpservice_lock_info().await {
send_signal(&c.pid.to_string(), Signal::User1).unwrap_or_else(|err| {
warn!("Failed to send signal to service: {}", err);
false
});
};
@@ -48,16 +51,14 @@ impl<'a> DisconnectHandler<'a> {
}
}
fn send_signal(pid: &str, signal: Signal) -> anyhow::Result<()> {
fn send_signal(pid: &str, signal: Signal) -> anyhow::Result<bool> {
let s = System::new_all();
let pid = Pid::from_str(pid)?;
if let Some(process) = s.process(pid) {
info!("Found process {}, sending signal...", pid);
if process.kill_with(signal).is_none() {
warn!("Failed to kill process {}", pid);
}
return Ok(process.kill_with(signal).unwrap_or(false));
}
Ok(())
Ok(false)
}
+1
View File
@@ -1,3 +1,4 @@
mod background;
mod cli;
mod connect;
mod diagnostics;