overman 0.88.2 → 0.88.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa4c1fac0ddfb73ffbdabc7baefeacfd726c2d3515d12c235bc7d1866e9fa94c
-  data.tar.gz: 7182befecdc71d50c0d243f184fe2d7c7232ff7c1e5a475d047a46adfecd71df
+  metadata.gz: a59c47fdea5d85e4feed1826151bc2960e46a3dee0b4a51864f21a31fcb7b737
+  data.tar.gz: 1181655ed2d379993e36adcac427cc66626c1abbedd513059d8e8d81aa4bbb18
 SHA512:
-  metadata.gz: 9416439d17c702295a94ee9ca347e285e2be0af7d61ac512e9824a6329b088a82c67aa992325b13aa83b19cbb1b608616d27f775cbdf28a4e9ae55746d9fa336
-  data.tar.gz: b7925120857061b1eb7774ca72719e1fb207a31d5693f197cb9feae90b641d3cc3587fcbb31a9e7e6e5c253dd1edf814981c66b9fa6a92edcd9dbbd966e21165
+  metadata.gz: 2c503d7c15d4254006a46b92858f271dd3dc679668459de9f9fad2a5a78337af7e37bc297a9135003eab56ad999a79b4478b93642fd58490935cb34d2d38564b
+  data.tar.gz: 2f5badad607d6a17591459cff32354d9f8d06f37aede7d05b40cf7a63f2a9a31ea1bb8c6ff32508e6ea2f007ba7e089990d21c7132499a69401905580422e46e

data/README.md

@@ -14,6 +14,20 @@ Ruby users should take care _not_ to install foreman in their project's `Gemfile
 
 - http://blog.daviddollar.org/2011/05/06/introducing-foreman.html
 
+## Process lifecycle
+
+`overman start` runs each command in a separate process group. On Unix, shutdown
+sends SIGTERM to those groups and waits for them to exit, including descendants
+that remain in the group after their immediate parent exits. Groups still running
+after the shutdown timeout receive SIGKILL. Descendants that leave the group,
+for example by calling `setsid`, are not tracked. On Windows, shutdown sends
+SIGKILL immediately.
+
+Groups that cannot be signaled due to permission errors are skipped with a warning.
+On systems where zombie-only groups still appear alive, an ancestor that does not
+reap orphaned processes can cause shutdown to wait the full timeout; use a reaping
+init process when running in a container, such as Docker's `--init` option.
+
 ## Supported Ruby versions
 
 See [ci.yml](.github/workflows/ci.yml) for a list of Ruby versions against which Foreman is tested.

data/lib/foreman/engine.rb

@@ -35,7 +35,9 @@ class Foreman::Engine
     @names     = {}
     @processes = []
     @running   = {}
+    @process_groups = {}
     @readers   = {}
+    @reader_names = {}
     @shutdown  = false
 
     # Self-pipe for deferred signal-handling (ala djb: http://cr.yp.to/docs/selfpipe.html)
@@ -196,10 +198,15 @@ class Foreman::Engine
         end
       end
     else
-      begin
-        pids = @running.keys.compact
-        Process.kill("-#{signal}", *pids) unless pids.empty?
-      rescue Errno::ESRCH, Errno::EPERM
+      @process_groups.each_key do |pid|
+        begin
+          Process.kill("-#{signal}", pid)
+        rescue Errno::ESRCH
+          @process_groups.delete(pid)
+        rescue Errno::EPERM
+          warn_unsignalable_group(pid)
+          @process_groups.delete(pid)
+        end
       end
     end
   end
@@ -312,7 +319,7 @@ private
   end
 
   def name_for(pid)
-    process, index = @running[pid]
+    process, index = @running[pid] || @process_groups[pid]
     name_for_index(process, index)
   end
 
@@ -353,7 +360,7 @@ private
   def flush_reader(reader)
     until reader.eof?
       data = reader.gets
-      output_with_mutex name_for(@readers.key(reader)), data
+      output_with_mutex @reader_names[reader], data
     end
   end
 
@@ -373,7 +380,9 @@ private
           writer.puts "unknown command: #{process.command}"
         end
         @running[pid] = [process, n]
+        @process_groups[pid] = [process, n] if pid && !Foreman.windows?
         @readers[pid] = reader
+        @reader_names[reader] = name_for_index(process, n)
       end
     end
   end
@@ -396,9 +405,10 @@ private
 
       if reader.eof?
         @readers.delete_if { |key, value| value == reader }
+        @reader_names.delete(reader)
       else
         data = reader.gets
-        output_with_mutex name_for(@readers.invert[reader]), data
+        output_with_mutex @reader_names[reader], data
       end
     end
   end
@@ -464,6 +474,10 @@ private
   def terminate_gracefully
     restore_default_signal_handlers
 
+    reap_children
+    prune_process_groups
+    return unless processes_running?
+
     # Tell all children to stop gracefully
     if Foreman.windows?
       system  "sending SIGKILL to all processes"
@@ -476,8 +490,9 @@ private
     # Wait for all children to stop or until the time comes to kill them all
     start_time = Time.now
     while Time.now - start_time <= options[:timeout]
-      return if @running.empty?
-      check_for_termination
+      reap_children
+      prune_process_groups
+      return unless processes_running?
 
       # Sleep for a moment and do not blow up if more signals are coming our way
       begin
@@ -487,8 +502,39 @@ private
       end
     end
 
+    reap_children
+    prune_process_groups
+    return unless processes_running?
+
     # Ok, we have no other option than to kill all of our children
     system  "sending SIGKILL to all processes"
     kill_children "SIGKILL"
   end
+
+  def processes_running?
+    !@running.empty? || !@process_groups.empty?
+  end
+
+  def reap_children
+    loop { break unless check_for_termination }
+  end
+
+  def prune_process_groups
+    # A group can outlive its immediate child when descendants ignore SIGTERM.
+    @process_groups.delete_if do |pid, _|
+      begin
+        Process.kill(0, -pid)
+        false
+      rescue Errno::ESRCH
+        true
+      rescue Errno::EPERM
+        warn_unsignalable_group(pid)
+        true
+      end
+    end
+  end
+
+  def warn_unsignalable_group(pid)
+    system "WARNING: permission denied signaling process group #{pid}; skipping group"
+  end
 end

data/lib/foreman/version.rb

@@ -1,5 +1,5 @@
 module Foreman
 
-  VERSION = "0.88.2"
+  VERSION = "0.88.3"
 
 end

data/man/overman.1

@@ -1,6 +1,6 @@
 .\" generated with Ronn-NG/v0.10.1
 .\" http://github.com/apjanke/ronn-ng/tree/0.10.1
-.TH "FOREMAN" "1" "September 2026" "Foreman 0.88.2" "Foreman Manual"
+.TH "FOREMAN" "1" "September 2026" "Foreman 0.88.3" "Foreman Manual"
 .SH "NAME"
 \fBforeman\fR \- manage Procfile\-based applications
 .SH "SYNOPSIS"

data/spec/foreman/engine_spec.rb

@@ -60,6 +60,72 @@ describe "Foreman::Engine", :fakefs do
     end
   end
 
+  describe "shutdown", :unless => Foreman.windows? do
+    before do
+      subject.options[:formation] = "alpha=1"
+      allow(subject.process("alpha")).to receive(:run) do |options|
+        @process_writer = options[:output]
+        1234
+      end
+      subject.startup
+      subject.send(:spawn_processes)
+    end
+
+    let(:status) { instance_double(Process::Status, :exitstatus => 0, :exited? => true) }
+
+    it "warns and stops tracking a group it cannot signal" do
+      reaped = false
+      allow(Process).to receive(:wait2) do
+        raise Errno::ECHILD if reaped
+        reaped = true
+        [1234, status]
+      end
+      allow(Process).to receive(:kill).and_raise(Errno::EPERM)
+      expect(subject).not_to receive(:sleep)
+
+      subject.send(:terminate_gracefully)
+
+      expect(subject.buffer).to include("WARNING: permission denied signaling process group 1234")
+      expect(subject.buffer).not_to include("sending SIGKILL")
+    end
+
+    it "reaps and rechecks groups at the timeout before escalating" do
+      subject.options[:timeout] = 0.2
+      allow(Time).to receive(:now).and_return(Time.at(0), Time.at(1))
+      polls = 0
+      allow(Process).to receive(:wait2) do
+        polls += 1
+        polls == 2 ? [1234, status] : [nil, nil]
+      end
+      allow(Process).to receive(:kill).with(0, -1234) do
+        raise Errno::ESRCH if polls >= 2
+        1
+      end
+      expect(Process).to receive(:kill).with("-SIGTERM", 1234).and_return(1)
+      expect(Process).not_to receive(:kill).with("-SIGKILL", 1234)
+
+      subject.send(:terminate_gracefully)
+
+      expect(subject.buffer).to include("exited with code 0")
+      expect(subject.buffer).not_to include("sending SIGKILL")
+    end
+
+    it "keeps the process name while draining output after it exits" do
+      reader = subject.instance_variable_get(:@readers).fetch(1234)
+      subject.send(:handle_io, [reader])
+
+      allow(Process).to receive(:wait2).and_return([1234, status])
+      subject.send(:check_for_termination)
+      allow(Process).to receive(:kill).with(0, -1234).and_raise(Errno::ESRCH)
+      subject.send(:prune_process_groups)
+
+      @process_writer.puts "buffered output"
+      subject.send(:handle_io, [reader])
+
+      expect(subject.buffer).to include("alpha.1: buffered output")
+    end
+  end
+
   describe "environment" do
     it "should read env files" do
       write_file("/tmp/env") { |f| f.puts("FOO=baz") }

data/spec/foreman/shutdown_spec.rb

@@ -0,0 +1,117 @@
+require "spec_helper"
+require "foreman"
+require "foreman/engine"
+require "rbconfig"
+require "timeout"
+require "tmpdir"
+
+describe "Process-group shutdown", :unless => Foreman.windows? do
+  def wait_until
+    Timeout.timeout(10) { sleep 0.02 until yield }
+  end
+
+  def stop_supervisor(pid)
+    return if Process.waitpid(pid, Process::WNOHANG)
+
+    Process.kill("INT", pid)
+    begin
+      Timeout.timeout(2) { Process.wait(pid) }
+    rescue Timeout::Error
+      Process.kill("KILL", pid)
+      Process.wait(pid)
+    end
+  rescue Errno::ESRCH, Errno::ECHILD
+    # The supervisor has already exited or been reaped by the example.
+  end
+
+  def with_supervisor(dir)
+    command = File.expand_path("../../bin/overman", __dir__)
+    output = "#{dir}/output"
+    supervisor = Process.spawn(RbConfig.ruby, command, "start", "-t", "0.2",
+      :chdir => dir, [:out, :err] => output)
+    begin
+      yield supervisor
+    rescue Exception
+      warn "Supervisor output:\n#{File.read(output)}"
+      raise
+    ensure
+      stop_supervisor(supervisor)
+      Dir["#{dir}/*.group"].each do |file|
+        group = File.read(file).to_i
+        Process.kill("KILL", -group) rescue nil if group > 0
+      end
+    end
+  end
+
+  it "kills surviving descendants after their immediate parent exits" do
+    Dir.mktmpdir("overman-shutdown") do |dir|
+      File.write("#{dir}/service.rb", <<~RUBY)
+        File.write("service.group", Process.getpgrp)
+        fork do
+          trap("TERM", "IGNORE")
+          File.open("descendant.lock", "w") do |lock|
+            lock.flock(File::LOCK_EX)
+            File.write("ready", "ready")
+            sleep
+          end
+        end
+        sleep
+      RUBY
+      File.write("#{dir}/Procfile", "service: #{RbConfig.ruby} service.rb\n")
+
+      with_supervisor(dir) do |supervisor|
+        wait_until { File.size?("#{dir}/ready") }
+        File.open("#{dir}/descendant.lock", "r") do |lock|
+          expect(lock.flock(File::LOCK_EX | File::LOCK_NB)).to eq(false)
+          Process.kill("INT", supervisor)
+          Timeout.timeout(10) { Process.wait(supervisor) }
+
+          wait_until { lock.flock(File::LOCK_EX | File::LOCK_NB) }
+        end
+        expect(File.read("#{dir}/output")).to match(/terminated by SIGTERM.*sending SIGKILL/m)
+      end
+    end
+  end
+
+  it "signals later groups when an earlier group has disappeared" do
+    Dir.mktmpdir("overman-signals") do |dir|
+      File.write("#{dir}/service.rb", <<~RUBY)
+        name = ARGV.fetch(0)
+        File.write("\#{name}.group", Process.getpgrp)
+        exit if name == "gone"
+        trap("TERM") do
+          File.write("terminated", "TERM")
+          exit
+        end
+        File.write("ready", "ready")
+        sleep
+      RUBY
+      File.write("#{dir}/Procfile", <<~PROCFILE)
+        gone: #{RbConfig.ruby} service.rb gone
+        remaining: #{RbConfig.ruby} service.rb remaining
+      PROCFILE
+      engine = Foreman::Engine.new.load_procfile("#{dir}/Procfile")
+      begin
+        engine.send(:spawn_processes)
+        wait_until { File.size?("#{dir}/gone.group") && File.size?("#{dir}/ready") }
+        gone = File.read("#{dir}/gone.group").to_i
+        remaining = File.read("#{dir}/remaining.group").to_i
+        Timeout.timeout(10) { Process.wait(gone) }
+        expect { Process.kill(0, -gone) }.to raise_error(Errno::ESRCH)
+
+        engine.kill_children
+
+        Timeout.timeout(10) { Process.wait(remaining) }
+        expect(File.read("#{dir}/terminated")).to eq("TERM")
+      ensure
+        Dir["#{dir}/*.group"].each do |file|
+          group = File.read(file).to_i
+          if group > 0
+            Process.kill("KILL", -group) rescue nil
+            Process.wait(group) rescue nil
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -1,16 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: overman
 version: !ruby/object:Gem::Version
-  version: 0.88.2
+  version: 0.88.3
 platform: ruby
 authors:
 - David Dollar
+- Patrik Ragnarsson
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: Process manager for applications with multiple components, fork of ddollar/foreman
-email: ddollar@gmail.com
+email:
+- ddollar@gmail.com
+- patrik@starkast.net
 executables:
 - overman
 extensions: []
@@ -108,6 +111,7 @@ files:
 - spec/foreman/helpers_spec.rb
 - spec/foreman/process_spec.rb
 - spec/foreman/procfile_spec.rb
+- spec/foreman/shutdown_spec.rb
 - spec/foreman_spec.rb
 - spec/helper_spec.rb
 - spec/resources/Procfile
@@ -169,7 +173,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Process manager for applications with multiple components, fork of ddollar/foreman
 test_files: []