yamine 0.21.1 → 0.21.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e920f5f6d29a92e0a6e81ca671bccf62e0a264ec453f9b5bc4d42d4e56980d3
-  data.tar.gz: cc06342930ee7c882cf30fd2818f1a60495c8a59e44ec6779cc666f569493ac0
+  metadata.gz: 618e529eeea12aa43397e084455136a4062bd55a546e904a1cb4170e3fc1466f
+  data.tar.gz: aa598da83330345ca84a60b168539262aa516df7440d6d91611b5cc853c584ec
 SHA512:
-  metadata.gz: 4164dabf9bd5537023ad59d426a958a5e284a90f0226cc83e0533cf635edf0c65acc16dd311d58a88df83d7abdcdfb92034703ecda06d89af08bb5ec96c73635
-  data.tar.gz: 1e3af2b55e54885fe8aeed98856c4371eab280ec981cd2644ebb75aba0206752ae44307c0252f51188a778426efbb882ef2285c63f142def39f4e876f77302d6
+  metadata.gz: 848bb6e6cced84dc132e38dc2ce4828c3514b4fca2c4596e796e9e938b1b2f23d164aadea56e14aed9e8c13d7f732723ede5b377f443db068f74bfd7a9e88410
+  data.tar.gz: 453dd9432df8527eace777b7894abf8540b60f103243ce4917593cd021c38506a0aa76614ca0eb926caea5ebfca6f25177729148e5342f22e1b571f7571d104a

data/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 ## [Unreleased]
 
+## [0.21.2] — 2026-09-29
+
+### Fixed
+
+- **Linux no longer orphans the app behind a boot's shell.** Every
+  process is spawned as `["sh", "-c", cmd]`, so the pid yamine tracks
+  is the *shell* — and on Linux a TERM to that shell does not reach the
+  app behind it, which reparents to init and keeps running. Every stop
+  path inherited the hole: `yamine stop` printed "Stopped <host>" and
+  left the app serving, Ctrl-C left the whole tree up, and
+  `yamine worktree remove` deleted the directory under a live process.
+  (macOS forwards the signal, which is why the unit suite never saw
+  it.) Each process now spawns as its own process-group leader and
+  stop signals the *group*, so one syscall reaches the shell and
+  everything below it. Only a pid that actually leads a group is
+  signalled by group id — the kernel is asked first — so the paths that
+  never had a shell in front of them (a directly-spawned puma, a pid
+  that is already gone) keep signalling exactly as before.
+- **A stop that lands while the tree is still being built no longer
+  leaves a live process behind.** The group signal reaches the members
+  that exist at the instant it is sent, and a `sh -c` shell that has
+  not forked its app yet forks it *after* that sweep — so the app never
+  hears the TERM, reparents to init, and goes on serving with its
+  directory already on the way out. Measured on linux: TERM the group a
+  few milliseconds after the spawn and the shell dies while the app
+  comes up behind it and stays up. Asking was never the same as
+  stopping, and every caller that goes on to report "Stopped", drop the
+  route, or delete the worktree was exposed. Stops now ask and then
+  insist: TERM the group, let it leave on its own terms briefly, and
+  KILL whatever is still in it — liveness asked of the *group*, since a
+  dead leader that is a zombie still answers to its own pid while a live
+  tree behind it does not. The signal-trap path keeps the single-shot
+  signal, because a trap handler must not sleep.
+
 ## [0.21.1] — 2026-09-29
 
 ### Fixed

data/lib/yamine/cli/boot.rb

@@ -345,10 +345,19 @@ module Yamine
         stop_spawned_pid(app.pid)
       end
 
+      # The pid of a spawned process is its `sh -c` shell, so the whole
+      # group gets the signal: the app behind the shell is what must
+      # actually stop. Falls back to the single pid for a process that
+      # leads no group, and never raises (see ProcessTree).
+      #
+      # Escalated, because this is the "a failure leaves nothing running"
+      # contract and asking is not enough: a shell still assembling its
+      # tree forks the app after the signal sweep, and that app is then
+      # unreachable by the signal that was just sent to its group
+      # (ProcessTree.terminate). The signal-trap path stays on the
+      # single-shot `term` — a trap handler must not sleep.
       def stop_spawned_pid(pid)
-        Process.kill("TERM", pid)
-      rescue SystemCallError
-        nil
+        ProcessTree.terminate(pid)
       end
 
       # A background process (proxy: false) is spawned, logged, and
@@ -853,9 +862,10 @@ module Yamine
             $stderr.puts "  log: #{log}" if File.file?(log)
             reporter&.note("#{name} exited; cleaning up routes")
             cleanup_routes(ctx, hostnames)
-            # Kill remaining children
+            # Kill remaining children — by group, so a `sh -c` backend's
+            # process dies with the shell we hold a pid for.
             named_pids.each_key do |other|
-              Process.kill("TERM", other) rescue nil
+              ProcessTree.term(other)
             end
             exit 0
           end
@@ -893,7 +903,11 @@ module Yamine
         %w[INT TERM].each do |sig|
           trap(sig) do
             cleanup_routes(ctx, hostnames)
-            pids.each { |pid| Process.kill("TERM", pid) rescue nil }
+            # The children are in their own process groups, so the
+            # terminal's signal reaches only us — this is the one place
+            # their trees get told to stop. By group, not by pid: a
+            # `sh -c` backend's real process is behind the pid we hold.
+            pids.each { |pid| ProcessTree.term(pid) }
             exit 0
           end
         end
@@ -905,7 +919,9 @@ module Yamine
             entry = ctx.store.find(h)
             pid = ctx.backend_pid_for(entry) if entry
             if pid && ProxyControl.pid_alive?(pid)
-              Process.kill("TERM", pid) rescue nil
+              # Group, not pid: the sidecar names the `sh -c` shell, and
+              # the app behind it is the process that must stop.
+              ProcessTree.term(pid)
             end
             ctx.store.remove_route(h, owner_pid: Process.pid) rescue nil
             FileUtils.rm_f(File.join(ctx.store.dir, "backend-#{h}.pid"))

data/lib/yamine/cli/routes.rb

@@ -206,14 +206,21 @@ module Yamine
 
           backend_pid = ctx.backend_pid_for(entry)
           if backend_pid && ProxyControl.pid_alive?(backend_pid)
-            begin
-              Process.kill("TERM", backend_pid)
+            # The sidecar names the `sh -c` shell a boot-mode backend was
+            # spawned behind, so the whole group is signalled — otherwise
+            # "Stopped" is reported while the app keeps serving (linux).
+            # And it escalates rather than merely asking: a shell still
+            # assembling its tree forks the app after the signal sweep,
+            # so that app never hears the TERM and "Stopped" would be a
+            # lie (ProcessTree.terminate). A false return means there
+            # was nothing left to signal.
+            if ProcessTree.terminate(backend_pid)
               if ctx.wait_for_exit(backend_pid, timeout: 10)
                 stopped << "#{hostname} (backend #{backend_pid})"
               else
                 stopped << "#{hostname} (backend #{backend_pid} still draining)"
               end
-            rescue SystemCallError
+            else
               gone << hostname
             end
           else

data/lib/yamine/cli/worktree.rb

@@ -604,12 +604,20 @@ module Yamine
           hostname = entry["hostname"]
           backend_pid = ctx.backend_pid_for(entry)
           if backend_pid && ProxyControl.pid_alive?(backend_pid)
-            begin
-              Process.kill("TERM", backend_pid)
-              ctx.wait_for_exit(backend_pid, timeout: 10)
-            rescue SystemCallError
-              nil
-            end
+            # Group, not pid: a boot-mode backend's sidecar names the
+            # `sh -c` shell, and on linux the app behind that shell does
+            # not stop with it (a live process whose cwd is about to be
+            # deleted is exactly what must not survive here). A pid that
+            # leads no group is signalled on its own, as before.
+            #
+            # And not a bare TERM: the directory is about to be deleted
+            # out from under whatever is left, so this stop has to be
+            # able to report "stopped" and mean it. `terminate`
+            # escalates, because a shell that is still assembling its
+            # tree forks the app after the signal sweep, and that app
+            # never hears the TERM at all (ProcessTree.terminate).
+            ProcessTree.terminate(backend_pid)
+            ctx.wait_for_exit(backend_pid, timeout: 10)
           end
           ctx.store.remove_route(hostname)
           FileUtils.rm_f(File.join(ctx.store.dir, "backend-#{hostname}.pid"))

data/lib/yamine/process_tree.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+module Yamine
+  # Stopping a spawned process AND everything it started.
+  #
+  # Every run-mode process is spawned as ["sh", "-c", cmd] (see
+  # BootCommand.collect_spawns), so the pid yamine owns is the SHELL and
+  # the app is the shell's child. Signalling that pid alone is not
+  # stopping the app: on linux the shell's child is outside the shell's
+  # own signal scope, so TERM to the shell leaves the app running,
+  # reparented to init. `yamine stop` reports "Stopped <host>" and the
+  # app goes on serving, the route is gone, and nothing holds a handle
+  # to the process anymore. macOS forwards the signal, which is why a
+  # linux-only defect stayed invisible to the unit suite.
+  #
+  # Two halves, and the second is only safe with the first:
+  #   * spawn each process as its own group leader (pgroup: true), so
+  #     the whole tree shares a group that dies together;
+  #   * signal the GROUP (-pid), which reaches the shell and every
+  #     descendant in one syscall.
+  #
+  # A negative pid means "the process group whose id is that number",
+  # not "this process and its children" — so it is only correct for a
+  # pid that actually LEADS a group, and the two ways to know that are
+  # not equally good.
+  #
+  # The kernel can be asked, and it is the only option for a pid that
+  # came from a file (`yamine stop` and `yamine worktree remove` run in
+  # a different process than the spawn, with nothing but a pid from a
+  # route entry or a sidecar). But that is a reading, and it has two
+  # ways of being wrong:
+  #
+  #   * ESRCH. The pid is gone — yet a process group outlives its
+  #     leader, and the members behind it are exactly what needs
+  #     stopping: a `sh -c` shell that died on its own leaves the app
+  #     running in its group with nothing left to signal it by pid. A
+  #     dead leader answers ESRCH, which reads exactly like "leads no
+  #     group".
+  #
+  #   * "Same group as me". A pid that never led a group answers this
+  #     (a directly-spawned puma), and so does one of ours that has not
+  #     run its setpgid yet — `pgroup: true` puts that in the child, so
+  #     whether the parent can look first is a property of the spawn
+  #     path, not something to bet a stop on.
+  #
+  # So a process spawned through `ProcessTree.spawn` is recorded as a
+  # leader, and the record is a fact about what we asked for rather than
+  # a reading of the moment. Everything else is the kernel's answer, and
+  # a pid number on its own is never evidence: 1234 may be a live
+  # process that inherited its group, and `kill(-1234)` would then hit
+  # whatever unrelated group wears that id.
+  module ProcessTree
+    # Pids we spawned as group leaders. A plain Hash, deliberately
+    # unlocked: every operation on it is a single call the GVL makes
+    # atomic, and yamine stops its processes from inside a trap handler
+    # (BootCommand.trap_cleanup), where Mutex#synchronize raises
+    # "can't be called from trap context" — a stop path that only works
+    # outside a trap is a stop that never happens on Ctrl-C.
+    PGROUP_LEADERS = {}
+
+    module_function
+
+    # Spawn a boot process as its own group leader and record that it is
+    # one. This is the only place a boot process is created, so "every
+    # process we boot leads a group" is one fact in one place rather
+    # than a convention spread across spawns.
+    def spawn(*args, **opts)
+      pid = ::Process.spawn(*args, pgroup: true, **opts)
+      note_group_leader(pid)
+      pid
+    end
+
+    # A pid we spawned with pgroup: true leads its own group — that is
+    # what we asked for, so the kernel is not consulted. Two readings it
+    # could give are both wrong here: "still in my group" while the
+    # child has not run its setpgid, and ESRCH once it is gone while
+    # the members it left behind are still running.
+    def note_group_leader(pid)
+      return unless pid.to_i.positive?
+
+      PGROUP_LEADERS[pid] = true
+    end
+
+    def known_group_leader?(pid)
+      PGROUP_LEADERS.key?(pid)
+    end
+
+    def forget(pid)
+      PGROUP_LEADERS.delete(pid)
+    end
+
+    # Does this pid lead its own process group? Ours, if we spawned it.
+    # Otherwise the kernel — and its "no" is the answer we want: a dead
+    # pid and a process that inherited its group are exactly the pids
+    # that must be signalled on their own, never by group id.
+    def group_leader?(pid)
+      return true if known_group_leader?(pid)
+
+      Process.getpgid(pid) == pid
+    rescue SystemCallError
+      false
+    end
+
+    # TERM a spawned process and its whole tree. Returns true when the
+    # signal was delivered, false when there was nothing left to signal
+    # (already dead, or a pid we may not touch) — which is the end
+    # state every caller wants, not an error, so this never raises.
+    def term(pid, signal: "TERM")
+      return false unless pid.to_i.positive?
+
+      group_signal(pid, signal) || pid_signal(pid, signal)
+    ensure
+      # The record is about a spawn, not about a pid that must keep
+      # this meaning: dropping it here keeps a pid that later gets
+      # recycled from being signalled as a group it never led.
+      forget(pid) if pid.to_i.positive?
+    end
+
+    # The whole group, one syscall. Best-effort: returns false when
+    # there is no such group left, so the caller can fall back.
+    def group_signal(pid, signal)
+      return false unless group_leader?(pid)
+
+      Process.kill(signal, -pid)
+      true
+    rescue SystemCallError
+      # ESRCH: the group outlived neither the leader nor its members.
+      # EPERM: the group exists but is not ours to signal. Either way a
+      # single-pid signal is the last thing left to try.
+      false
+    end
+
+    def pid_signal(pid, signal)
+      Process.kill(signal, pid)
+      true
+    rescue SystemCallError
+      false
+    end
+
+    # Stop a tree and make sure it is GONE — for the callers that go on
+    # to delete the directory it runs in, drop the route, or report
+    # "Stopped <host>". `term` alone is not that promise: it hands the
+    # signal to the group and returns, and the kernel's sweep covers
+    # the members that exist at that instant. A `sh -c` shell that is
+    # still assembling its tree forks its app *after* the sweep, and
+    # that app never sees the signal at all.
+    #
+    # Measured on linux: TERM the group of a `sh -c "ruby <app>"` a
+    # few milliseconds after the spawn and the shell dies while the app
+    # comes up behind it, reparented to init and serving forever —
+    # a live process whose working directory is on the way out, which
+    # is the exact shape of the bug this module exists to kill. A stop
+    # that only asks cannot rule that out, so this asks and then
+    # insists: TERM, give the group a moment to leave on its own
+    # terms, KILL whatever is still in it.
+    #
+    # The liveness question is asked of the GROUP, not of the pid: a
+    # dead leader that is a zombie still answers `kill(0, pid)`, and a
+    # live tree behind one does not answer to its pid at all. The group
+    # is the only handle that tells the two apart.
+    #
+    # `term` is deliberately left alone: it is the primitive a signal
+    # trap handler uses (BootCommand.trap_cleanup), and a trap handler
+    # must not sit in a sleep loop.
+    def terminate(pid, grace: 5)
+      return false unless term(pid)
+
+      deadline = monotonic + grace
+      sleep 0.05 while group?(pid) && monotonic < deadline
+      return true unless group?(pid)
+
+      # A group that outlived its grace period is not draining, it is
+      # stuck or ignoring us, and the caller is about to delete what it
+      # runs in. No group_leader? check here: the leader is very likely
+      # already gone, and it is the members behind it that need the
+      # signal.
+      Process.kill("KILL", -pid)
+      true
+    rescue SystemCallError
+      # The group went away between the last look and this signal.
+      true
+    end
+
+    # Does this process group still have a member in it? Signal 0 asks
+    # the kernel about the group rather than about a pid, so it stays
+    # true while anything behind a dead leader is still running, and
+    # goes false only once the tree really is down.
+    def group?(pid)
+      return false unless pid.to_i.positive?
+
+      Process.kill(0, -pid)
+      true
+    rescue SystemCallError
+      false
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/yamine/runner.rb

@@ -96,6 +96,12 @@ module Yamine
     # view yamine's failure payloads use. Interleaving matches the
     # foreman/without-yamine experience.
     #
+    # Spawned through ProcessTree, not Kernel#spawn: the command is an
+    # argv that starts with `sh -c` (collect_spawns), so the pid we get
+    # back is the shell. Its own process group is what makes the process
+    # behind it stoppable — stop signals the group (ProcessTree.term),
+    # and the shell cannot leave its child outside the group it leads.
+    #
     # extra_env is the config's env.clear/env.secret for this process —
     # yamine's own keys (PORT, YAMINE_URL, DATABASE_URL, the TLS vars)
     # win over it, because those describe the boot rather than the app.
@@ -106,7 +112,7 @@ module Yamine
       env = child_env(dir, url: url, port: port, rails_dev_host: rails_dev_host,
         database_url: database_url, database_env: database_env, extra_env: extra_env)
       path = log_path(dir, name)
-      pid = with_clean_env { spawn(env, *command, chdir: dir, out: path, err: [:child, :out]) }
+      pid = with_clean_env { ProcessTree.spawn(env, *command, chdir: dir, out: path, err: [:child, :out]) }
       Process.detach(pid)
       target = "127.0.0.1:#{port}"
       if register
@@ -130,12 +136,16 @@ module Yamine
     # whole tree up concurrently, then polls every route until healthy.
     # Returns the placeholder App (target known before bind). Fate of
     # the backend is decided by wait, not by spawn.
+    #
+    # Through ProcessTree, for the same reason as boot_run: a `sh -c`
+    # pid is not the process doing the work, so its group is the only
+    # handle that reaches it.
     def spawn_http(name:, hostname:, url:, dir:, command:, port:, rails_dev_host: nil,
       database_url: nil, database_env: nil, force: false, extra_env: nil)
       env = child_env(dir, url: url, port: port, rails_dev_host: rails_dev_host,
         database_url: database_url, database_env: database_env, extra_env: extra_env)
       path = log_path(dir, name)
-      pid = with_clean_env { spawn(env, *command, chdir: dir, out: path, err: [:child, :out]) }
+      pid = with_clean_env { ProcessTree.spawn(env, *command, chdir: dir, out: path, err: [:child, :out]) }
       Process.detach(pid)
       App.new(name: name, hostname: hostname, url: url, pid: pid,
         target: "127.0.0.1:#{port}", kind: "tcp", command: command)
@@ -340,10 +350,14 @@ module Yamine
 
     private
 
+    # A backend we spawned is stopped by its whole group: the pid we
+    # hold for a run-mode process is the `sh -c` shell, and on linux the
+    # app behind it does not see a signal aimed at that shell alone.
+    # A pid that leads no group (the socket spawns, a pid already gone)
+    # falls back to the single-pid signal. Never raises: a stopped
+    # backend is the goal, and "it was already dead" is a success here.
     def stop_pid(pid)
-      Process.kill("TERM", pid)
-    rescue SystemCallError
-      nil
+      ProcessTree.term(pid)
     end
   end
 end

data/lib/yamine/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Yamine
-  VERSION = "0.21.1"
+  VERSION = "0.21.2"
 end

data/lib/yamine.rb

@@ -19,6 +19,7 @@ require_relative "yamine/log"
 require_relative "yamine/route_store"
 require_relative "yamine/certs"
 require_relative "yamine/ports"
+require_relative "yamine/process_tree"
 require_relative "yamine/hosts"
 require_relative "yamine/proxy"
 require_relative "yamine/proxy_control"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: yamine
 version: !ruby/object:Gem::Version
-  version: 0.21.1
+  version: 0.21.2
 platform: ruby
 authors:
 - Kaka Ruto
@@ -105,6 +105,7 @@ files:
 - lib/yamine/ports.rb
 - lib/yamine/privileged_payload.rb
 - lib/yamine/probe.rb
+- lib/yamine/process_tree.rb
 - lib/yamine/procfile.rb
 - lib/yamine/proxy.rb
 - lib/yamine/proxy_control.rb