linux system adapter: InstallShutdownHook for SIGTERM/SIGINT

.github/workflows/roundtrip.yml

@@ -126,6 +126,40 @@ jobs:
         # without a session bus; single-instance, autostart, and the crash
         # hook always run.
         run: '"$RIVET_LINUX_ROUNDTRIP_STAGE/RivetIntegration" --system ci ci'
+      - name: Exercise Linux graceful shutdown hook
+        timeout-minutes: 2
+        shell: bash
+        run: |
+          set -euo pipefail
+          marker="$RUNNER_TEMP/rivet-shutdown-marker"
+          ready="$RUNNER_TEMP/rivet-shutdown-ready"
+          rm -f "$marker" "$ready"
+          "$RIVET_LINUX_ROUNDTRIP_STAGE/RivetIntegration" \
+            --shutdown-probe "$marker" >"$ready" &
+          probe_pid=$!
+          for _ in $(seq 1 100); do
+            grep -qx ready "$ready" 2>/dev/null && break
+            kill -0 "$probe_pid" 2>/dev/null || {
+              wait "$probe_pid"
+              exit 1
+            }
+            sleep 0.05
+          done
+          grep -qx ready "$ready"
+          kill -0 "$probe_pid"
+          kill -TERM "$probe_pid"
+          for _ in $(seq 1 100); do
+            kill -0 "$probe_pid" 2>/dev/null || break
+            sleep 0.05
+          done
+          if kill -0 "$probe_pid" 2>/dev/null; then
+            kill -KILL "$probe_pid"
+            wait "$probe_pid" || true
+            echo "shutdown hook did not terminate the process" >&2
+            exit 1
+          fi
+          wait "$probe_pid"
+          grep -qx shutdown "$marker"
       - name: Build, package, and verify a generated GTK4 app
         shell: bash
         run: |

CHANGELOG.md

@@ -4,6 +4,9 @@
 
 - Prefer native 64-bit MSBuild when discovering Visual Studio, preventing the
   32-bit host compiler from exhausting its address space on WinUI ARM64 builds.
+- Add an opt-in Linux `InstallShutdownHook` for SIGTERM/SIGINT. Its
+  async-signal-safe self-pipe hands graceful state flushing to a normal watcher
+  thread, while a repeated signal still terminates a stuck shutdown.
 - Add the Linux tray contract: `rivet::system::TrayIcon` hosts an
   org.kde.StatusNotifierItem with a com.canonical.dbusmenu menu over the
   session bus (GDBus), the pairing every desktop watcher serves (GNOME via

platform/linux/Integration/main.cpp

@@ -9,8 +9,10 @@
 #include <memory>
 #include <mutex>
 #include <optional>
+#include <signal.h>
 #include <stdexcept>
 #include <string>
+#include <unistd.h>
 #include <vector>
 
 #include <gio/gio.h>
@@ -195,6 +197,17 @@ int run_system_self_check(std::vector<std::string> const& arguments) {
   return 0;
 }
 
+int run_shutdown_probe(std::filesystem::path marker) {
+  rivet::system::InstallShutdownHook([marker = std::move(marker)] {
+    std::ofstream output(marker);
+    output << "shutdown\n";
+    output.close();
+    if (!output) throw std::runtime_error("shutdown marker write failed");
+  });
+  std::cout << "ready\n" << std::flush;
+  while (true) ::pause();
+}
+
 }  // namespace
 
 int main(int argc, char** argv) {
@@ -207,6 +220,14 @@ int main(int argc, char** argv) {
       return 1;
     }
   }
+  if (arguments.size() == 2 && arguments.front() == "--shutdown-probe") {
+    try {
+      return run_shutdown_probe(arguments[1]);
+    } catch (std::exception const& error) {
+      std::cerr << "Rivet Linux shutdown probe failure: " << error.what() << "\n";
+      return 1;
+    }
+  }
   try {
     auto const exe = executable_path();
     auto const root = exe.parent_path();

platform/linux/system/system_services.cpp

@@ -11,9 +11,12 @@
 #include <atomic>
 #include <cctype>
 #include <cerrno>
+#include <cstdlib>
 #include <cstring>
+#include <functional>
 #include <mutex>
 #include <stdexcept>
+#include <thread>
 #include <unordered_map>
 
 #include <gio/gio.h>
@@ -1328,4 +1331,133 @@ void InstallCrashHook(CrashCallback callback,
   }
 }
 
+// ---------------------------------------------------------- shutdown hook
+
+namespace {
+
+int shutdown_pipe_read = -1;
+volatile sig_atomic_t shutdown_pipe_write = -1;
+volatile sig_atomic_t shutdown_signal_received = 0;
+std::function<void()> shutdown_callback;
+
+extern "C" void rivet_shutdown_signal_handler(int signal_number) noexcept {
+  // Async-signal-safe: a single write into the self-pipe is all the handler
+  // does; everything else happens on the watcher thread. The write end is
+  // non-blocking, so a full pipe can never wedge signal delivery (a queued
+  // byte already represents the pending shutdown).
+  int const saved_errno = errno;
+  if (shutdown_signal_received != 0) {
+    ::_exit(128 + signal_number);
+  }
+  shutdown_signal_received = 1;
+  sig_atomic_t const write_fd = shutdown_pipe_write;
+  if (write_fd >= 0) {
+    char const byte = 's';
+    ssize_t ignored = ::write(static_cast<int>(write_fd), &byte, 1);
+    (void)ignored;
+  }
+  errno = saved_errno;
+}
+
+void rivet_shutdown_watch_loop() {
+  char byte = 0;
+  while (true) {
+    ssize_t const read_bytes = ::read(shutdown_pipe_read, &byte, 1);
+    if (read_bytes == 1) break;
+    if (read_bytes < 0 && errno == EINTR) continue;
+    std::_Exit(EXIT_FAILURE);
+  }
+
+  // A second signal must hard-kill even if the callback hangs: restore the
+  // default disposition right before the callback runs.
+  struct sigaction action;
+  std::memset(&action, 0, sizeof(action));
+  action.sa_handler = SIG_DFL;
+  sigemptyset(&action.sa_mask);
+  ::sigaction(SIGTERM, &action, nullptr);
+  ::sigaction(SIGINT, &action, nullptr);
+
+  try {
+    if (shutdown_callback) shutdown_callback();
+    std::_Exit(EXIT_SUCCESS);
+  } catch (...) {
+    std::_Exit(EXIT_FAILURE);
+  }
+}
+
+}  // namespace
+
+void InstallShutdownHook(std::function<void()> callback) {
+  if (shutdown_pipe_read >= 0)
+    throw std::runtime_error("shutdown hook is already installed");
+
+  int fds[2]{-1, -1};
+  if (::pipe2(fds, O_CLOEXEC) != 0) {
+    throw std::runtime_error(std::string("shutdown hook pipe failed: ") +
+                             std::strerror(errno));
+  }
+
+  auto close_pipe = [&] {
+    ::close(fds[0]);
+    ::close(fds[1]);
+  };
+  int const write_flags = ::fcntl(fds[1], F_GETFL, 0);
+  if (write_flags < 0 ||
+      ::fcntl(fds[1], F_SETFL, write_flags | O_NONBLOCK) != 0) {
+    int const saved = errno;
+    close_pipe();
+    throw std::runtime_error(std::string("shutdown hook pipe setup failed: ") +
+                             std::strerror(saved));
+  }
+
+  shutdown_pipe_read = fds[0];
+  shutdown_pipe_write = fds[1];
+  shutdown_callback = std::move(callback);
+
+  struct sigaction action;
+  std::memset(&action, 0, sizeof(action));
+  action.sa_handler = rivet_shutdown_signal_handler;
+  sigemptyset(&action.sa_mask);
+  sigaddset(&action.sa_mask, SIGTERM);
+  sigaddset(&action.sa_mask, SIGINT);
+  action.sa_flags = SA_RESTART;
+
+  struct sigaction previous_term;
+  struct sigaction previous_int;
+  if (::sigaction(SIGTERM, &action, &previous_term) != 0) {
+    int const saved = errno;
+    shutdown_pipe_read = -1;
+    shutdown_pipe_write = -1;
+    shutdown_signal_received = 0;
+    shutdown_callback = nullptr;
+    close_pipe();
+    throw std::runtime_error(std::string("shutdown hook installation failed: ") +
+                             std::strerror(saved));
+  }
+  if (::sigaction(SIGINT, &action, &previous_int) != 0) {
+    int const saved = errno;
+    ::sigaction(SIGTERM, &previous_term, nullptr);
+    shutdown_pipe_read = -1;
+    shutdown_pipe_write = -1;
+    shutdown_signal_received = 0;
+    shutdown_callback = nullptr;
+    close_pipe();
+    throw std::runtime_error(std::string("shutdown hook installation failed: ") +
+                             std::strerror(saved));
+  }
+
+  try {
+    std::thread(rivet_shutdown_watch_loop).detach();
+  } catch (...) {
+    ::sigaction(SIGTERM, &previous_term, nullptr);
+    ::sigaction(SIGINT, &previous_int, nullptr);
+    shutdown_pipe_read = -1;
+    shutdown_pipe_write = -1;
+    shutdown_signal_received = 0;
+    shutdown_callback = nullptr;
+    close_pipe();
+    throw;
+  }
+}
+
 }  // namespace rivet::system

platform/linux/system/system_services.hpp

@@ -153,4 +153,13 @@ using CrashCallback = void (*)(int signal_number) noexcept;
 void InstallCrashHook(CrashCallback callback,
                       std::string const& restart_arguments = std::string());
 
+// SIGTERM/SIGINT shutdown plumbing (embedded runtimes install their own
+// signal handlers and otherwise absorb termination requests, so hosts that
+// persist state on exit never see SIGTERM). The first signal drains into a
+// self-pipe; a watcher thread runs `callback` on a normal stack — state
+// flushing is allowed there — and the process then exits with status 0. A
+// second signal exits immediately so operators can still hard-kill a stuck
+// shutdown. Install once, early, from the main thread.
+void InstallShutdownHook(std::function<void()> callback);
+
 }  // namespace rivet::system