pitchfork 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c9d47a7cd3604f0807a41882322b4461edf2a990439e152dfa2d94bb731eff7
-  data.tar.gz: 1a38267df9cff0493452fa88c65cb4c9a502643aaf05c8e0b60544f93e9f6e4f
+  metadata.gz: eb4e22969b9f2c38717f0cfa7a3c966995814156a17589bc06bdc609b7ad6e32
+  data.tar.gz: dbf7833c26ef94962abbd71d66c63e40dd0f7f405ee82951723ad3b4cbfa864f
 SHA512:
-  metadata.gz: e8318fc2ae118a7e4a89f65e76e0634d306abd1838f0e4957f638bc870ddd202bc72c006fe3b93b6eec52f1765daea43b24b68eb7b8249b5b21b28a8b9abd51b
-  data.tar.gz: 5f23586cf49e29649496e15577ce7344c477b99878bfd6756f685f2a96ad40fc202d4f3cf97dad8183dd50b2489423c1fcfd48e20303d4eafae6b7f1db586e9b
+  metadata.gz: 0f0c029a01bc999d90421fe0ed77f76c6f1e56a9f3ec8eaa4ab6722f40eb0ee7f9aa0f004044e4c97e93a593cdba0d7a6bab01ef6b075440c76012f05e5cccd4
+  data.tar.gz: 4ae4d319ffd2acbf99ad29156622510c951ca095c20074f8415376d6e217be1b959e68e3245590cce62de66f3f8af8f0aae469fec842865dd4dcfe1b060e3db9

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Unreleased
 
+# 0.9.0
+
+- Implement `spawn_timeout` to protect against bugs causing workers to get stuck before they reach ready state.
+
 # 0.8.0
 
 - Add an `after_monitor_ready` callback, called in the monitor process at end of boot.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pitchfork (0.8.0)
+    pitchfork (0.9.0)
       rack (>= 2.0)
       raindrops (~> 0.7)
 

data/README.md

@@ -9,13 +9,6 @@ advantage of features in Unix/Unix-like kernels. Slow clients should
 only be served by placing a reverse proxy capable of fully buffering
 both the request and response in between `pitchfork` and slow clients.
 
-## Disclaimer
-
-Until this notice is removed from the README, `pitchfork` should be
-considered experimental. As such it is not encouraged to run it in
-production just yet unless you feel capable of debugging yourself
-any issue that may arise.
-
 ## Features
 
 * Designed for Rack, Linux, fast clients, and ease-of-debugging. We
@@ -40,9 +33,23 @@ any issue that may arise.
   or ports yourself. `pitchfork` can spawn and manage any number of
   worker processes you choose to scale to your backend.
 
+* Adaptative timeout: request timeout can be extended dynamically on a
+  per request basis, which allows to keep a strict overall timeout for
+  most endpoints, but allow a few endpoints to take longer.
+
 * Load balancing is done entirely by the operating system kernel.
   Requests never pile up behind a busy worker process.
 
+## When to Use
+
+Pitchfork isn't inherently better than other Ruby application servers, it mostly
+focus on different tradeoffs.
+
+If you are fine with your current server, it's best to stick with it.
+
+If there is a problem you are trying to solve, please read the
+[migration guide](docs/WHY_MIGRATE.md) first.
+
 ## Requirements
 
 Ruby(MRI) Version 2.5 and above.

data/docs/CONFIGURATION.md

@@ -238,6 +238,19 @@ exit or be SIGKILL-ed due to timeouts.
 See https://nginx.org/en/docs/http/ngx_http_upstream_module.html
 for more details on nginx upstream configuration.
 
+### `spawn_timeout`
+
+```ruby
+timeout 5
+```
+
+Sets the timeout for a newly spawned worker to be ready after being spawned.
+
+This timeout is a safeguard against various low-level fork safety bugs that could cause
+a process to dead-lock.
+
+The default of `10` seconds is quite generous and likely doesn't need to be adjusted.
+
 ### `logger`
 
 ```ruby

data/docs/WHY_MIGRATE.md

@@ -0,0 +1,93 @@
+# Why migrate to Pitchfork?
+
+First and foremost, if you don't have any specific problem with your current server, then don't.
+
+Pitchfork isn't a silver bullet, it's a very opinionated software that focus on very specific tradeoffs,
+that are different from other servers.
+
+## Coming from Unicorn
+
+### Why Migrate?
+
+#### Adaptative timeout
+
+Pitchfork allows to extend the request timeout on a per request basis,
+this can be helpful when trying to reduce the global request timeout
+to a saner value. You can enforce a stricter value, and extend it
+in the minority of offending endpoints.
+
+#### Memory Usage - Reforking
+
+If you are unsatisfied with Unicorn memory usage, but threaded Puma isn't an option
+for you, then Pitchfork may be an option if you are able to enable reforking.
+
+However be warned that making an application fork safe can be non-trivial,
+and mistakes can lead to critical bugs.
+
+#### Rack 3
+
+As of Unicorn `6.1.0`, Rack 3 isn't yet supported by Unicorn.
+
+Pitchfork is compatible with Rack 3.
+
+### Why Not Migrate?
+
+#### Reduced Features
+
+While Pitchfork started as a fork of Unicorn, many features such as daemonization,
+pid file management, hot reload have been stripped.
+
+Pitchfork only kept features that makes sense in a containerized world.
+
+## Coming from Puma
+
+Generally speaking, compared to (threaded) Puma, Pitchfork *may* offer better latency and isolation at the expense of throughput.
+
+### Why Migrate?
+
+#### Latency
+
+If you suspect your application is subject to contention on the GVL or some other in-process shared resources,
+then Pitchfork may offer improved latency.
+
+It is however heavily recommended to first confirm this suspicion with profiling
+tools such as [gvltools](https://github.com/Shopify/gvltools).
+
+If you application isn't subject to in-process contention, Pitchfork is unlikely to improve latency.
+
+#### Out of Band Garbage Collection
+
+Another advantage of only processing a single request per process is that
+[it allows to periodically trigger garbage collection when the worker isn't processing any request](https://shopify.engineering/adventures-in-garbage-collection).
+
+This can significantly improve tail latency at the expense of throughput.
+
+#### Resiliency and Isolation
+
+Since Pitchfork workers have their own address space and only process one request at a time
+it makes it much harder for one faulty request to impact another.
+
+Even if a bug causes Ruby to crash, only the request that triggered the bug will be impacted.
+
+If a bug causes Ruby to hang, the monitor process will SIGKILL the worker and the capacity will be
+reclaimed.
+
+This makes Pitchfork more resilient to some classes of bugs.
+
+#### Thread Safety
+
+Pitchfork doesn't require applications to be thread-safe. That is probably the worst reason
+to migrate though.
+
+### Why Not Migrate?
+
+#### Memory Usage
+
+Without reforking enabled Pitchfork will without a doubt use more memory than threaded Puma.
+
+With reforking enabled, results will vary based on the application profile and the number of Puma threads,
+but should be in the same ballpark, sometimes better, but likely worse, this depends on many variables and
+can't really be predicted.
+
+However be warned that [making an application fork safe](FORK_SAFETY.md) can be non-trivial,
+and mistakes can lead to critical bugs.

data/lib/pitchfork/configurator.rb

@@ -33,6 +33,7 @@ module Pitchfork
     DEFAULTS = {
       :soft_timeout => 20,
       :cleanup_timeout => 2,
+      :spawn_timeout => 10,
       :timeout => 22,
       :logger => default_logger,
       :worker_processes => 1,
@@ -174,6 +175,10 @@ module Pitchfork
       set_int(:timeout, soft_timeout + cleanup_timeout, 5)
     end
 
+    def spawn_timeout(seconds)
+      set_int(:spawn_timeout, seconds, 1)
+    end
+
     def worker_processes(nr)
       set_int(:worker_processes, nr, 1)
     end

data/lib/pitchfork/http_server.rb

@@ -74,7 +74,7 @@ module Pitchfork
     end
 
     # :stopdoc:
-    attr_accessor :app, :timeout, :soft_timeout, :cleanup_timeout, :worker_processes,
+    attr_accessor :app, :timeout, :soft_timeout, :cleanup_timeout, :spawn_timeout, :worker_processes,
                   :after_worker_fork, :after_mold_fork,
                   :listener_opts, :children,
                   :orig_app, :config, :ready_pipe,
@@ -556,6 +556,10 @@ module Pitchfork
     def spawn_worker(worker, detach:)
       logger.info("worker=#{worker.nr} gen=#{worker.generation} spawning...")
 
+      # We set the deadline before spawning the child so that if for some
+      # reason it gets stuck before reaching the worker loop,
+      # the monitor process will kill it.
+      worker.update_deadline(@spawn_timeout)
       Pitchfork.fork_sibling do
         worker.pid = Process.pid
 

data/lib/pitchfork/info.rb

@@ -6,14 +6,35 @@ module Pitchfork
   module Info
     @workers_count = 0
     @fork_safe = true
-    @kept_ios = ObjectSpace::WeakMap.new
+
+    class WeakSet # :nodoc
+      def initialize
+        @map = ObjectSpace::WeakMap.new
+      end
+
+      if RUBY_VERSION < "2.7"
+        def <<(object)
+          @map[object] = object
+        end
+      else
+        def <<(object)
+          @map[object] = true
+        end
+      end
+
+      def each(&block)
+        @map.each_key(&block)
+      end
+    end
+    
+    @kept_ios = WeakSet.new
 
     class << self
       attr_accessor :workers_count
 
       def keep_io(io)
         raise ArgumentError, "#{io.inspect} doesn't respond to :to_io" unless io.respond_to?(:to_io)
-        @kept_ios[io] = io
+        @kept_ios << io
         io
       end
 
@@ -22,9 +43,9 @@ module Pitchfork
       end
 
       def close_all_ios!
-        ignored_ios = [$stdin, $stdout, $stderr]
+        ignored_ios = [$stdin, $stdout, $stderr, STDIN, STDOUT, STDERR].uniq.compact
 
-        @kept_ios.each_value do |io_like|
+        @kept_ios.each do |io_like|
           ignored_ios << (io_like.is_a?(IO) ? io_like : io_like.to_io)
         end
 

data/lib/pitchfork/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Pitchfork
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
   module Const
     UNICORN_VERSION = '6.1.0'
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pitchfork
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Jean Boussier
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-08 00:00:00.000000000 Z
+date: 2023-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: raindrops
@@ -72,6 +72,7 @@ files:
 - docs/REFORKING.md
 - docs/SIGNALS.md
 - docs/TUNING.md
+- docs/WHY_MIGRATE.md
 - examples/constant_caches.ru
 - examples/echo.ru
 - examples/hello.ru