pitchfork 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f37584c7333941059ab10086a74d1102b1969c2fefb7a759fc13f9e4f837891e
-  data.tar.gz: bc69759f0a53d98d81648ee60b833e6c49fd3f88d53f7ac319e9acff845c7cf1
+  metadata.gz: ccd444fbdc89d5a253819e7be03e5d097c5aaf8b061980e15d4ec5326d2c54b5
+  data.tar.gz: f300bd3135e8d8d9e15f14dfe2780c75521ececeb72b8245fef0380e2ba338f5
 SHA512:
-  metadata.gz: 69d796bf414bb4bf7b7867e61229fa12764ca12dd1aaf2b36a615c2b806a64aa665b4c1483147e6d39a4d49df340ad31406f0db294da52e9a8a5740b186233a9
-  data.tar.gz: 51dc5852d5bc26fbba0f1824beb76977653ae089d589e33a1d7defca89b9b2235f466c5fc59419f56d0944b6c5ee819e1f966e9c32eac3d79029d951a6071c38
+  metadata.gz: b054a33d46f4b60c14e44fbac330bc4318a1b52259e89f2e8a1c16a58d8467f02eef981dbe018906a0c7a027c98db75a8efd483619d7ea5e2ece234b30b3846f
+  data.tar.gz: b12a622275fe638d49be5d9457d11309421119f9628044dec9898231f83425cab6aa6434b9f42372c5f8954b261f7e979e300a41fa75c39172fb8e1832cb0805

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Unreleased
 
+- Added a soft timeout in addition to the historical Unicorn hard timeout.
+  On soft timeout, the `after_worker_timeout` callback is invoked.
+- Implement `after_request_complete` callback.
+
+# 0.4.1
+
+- Avoid a Rack 3 deprecation warning.
+- Fix handling on non-ASCII cookies.
+- Log unknown process being reaped at INFO level.
+
 # 0.4.0
 
 - Preserve the current thread when reforking.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pitchfork (0.4.0)
+    pitchfork (0.5.0)
       rack (>= 2.0)
       raindrops (~> 0.7)
 
@@ -12,7 +12,7 @@ GEM
     nio4r (2.5.8)
     puma (6.1.1)
       nio4r (~> 2.0)
-    rack (3.0.7)
+    rack (3.0.8)
     raindrops (0.20.1)
     rake (13.0.6)
     rake-compiler (1.2.1)

data/docs/Application_Timeouts.md

@@ -70,5 +70,5 @@ handle network/server failures.
 The `timeout` mechanism in pitchfork is an extreme solution that should
 be avoided whenever possible.
 It will help preserve the platform if your application or a dependency
-has a bug that cause it to either get stuck or two slow, but it is not a
+has a bug that cause it to either get stuck or be too slow, but it is not a
 solution to such bugs, merely a mitigation.

data/docs/CONFIGURATION.md

@@ -173,33 +173,55 @@ The following options may be specified (but are generally not needed):
 ### `timeout`
 
 ```ruby
-timeout 10
+timeout 10, cleanup: 3
 ```
 
-Sets the timeout of worker processes to a number of seconds.
-Workers handling the request/app.call/response cycle taking longer than
-this time period will be forcibly killed (via `SIGKILL`).
+Sets the timeout for worker processes to a number of seconds.
 
-This timeout mecanism shouldn't be routinely relying on, and should
+Note that Pitchfork has two layers of timeout.
+
+A first "soft" timeout will invoke the `after_worker_timeout` from
+within the worker (but from a background thread) and then call `exit`
+to terminate the worker cleanly.
+
+The second "hard" timeout, is the sum of `timeout` and `cleanup`.
+Workers taking longer than this time period to be ready to handle a new
+request will be forcibly killed (via `SIGKILL`).
+
+Neither of these timeout mecanisms should be routinely relied on, and should
 instead be considered as a last line of defense in case you application
 is impacted by bugs causing unexpectedly slow response time, or fully stuck
 processes.
 
+If some of the application endpoints require an unreasonably large timeout,
+rather than to increase the global application timeout, it is possible to
+adjust it on a per request basis via the rack request environment:
+
+```ruby
+class MyMiddleware
+  def call(env)
+    if slow_endpoint?(env)
+      # Give 10 more seconds
+      env["pitchfork.timeout"]&.extend_deadline(10)
+    end
+    @app.call(env)
+  end
+end
+```
+
 Make sure to read the guide on [application timeouts](Application_Timeouts.md).
 
-This configuration defaults to a (too) generous 20 seconds, it is
-highly recommended to set a stricter one based on your application
-profile.
+This configuration defaults to a (too) generous 20 seconds for the soft timeout
+and an extra 2 seconds for the hard timeout. It is highly recommended to set a
+stricter one based on your application profile.
 
-This timeout is enforced by the master process itself and not subject
-to the scheduling limitations by the worker process.
 Due the low-complexity, low-overhead implementation, timeouts of less
 than 3.0 seconds can be considered inaccurate and unsafe.
 
 For running Pitchfork behind nginx, it is recommended to set
 "fail_timeout=0" for in your nginx configuration like this
 to have nginx always retry backends that may have had workers
-SIGKILL-ed due to timeouts.
+exit or be SIGKILL-ed due to timeouts.
 
 ```
    upstream pitchfork_backend {
@@ -284,6 +306,36 @@ after_worker_ready do |server, worker|
 end
 ```
 
+### `after_worker_timeout`
+
+Called by the worker process when the request timeout is elapsed:
+
+```ruby
+after_worker_timeout do |server, worker, timeout_info|
+  timeout_info.copy_thread_variables!
+  timeout_info.thread.kill
+  server.logger.error("Request timed out: #{timeout_info.rack_env.inspect}")
+  $stderr.puts timeout_info.thread.backtrace
+end
+```
+
+Note that this callback is invoked from a different thread. You can access the
+main thread via `timeout_info.thread`, as well as the rack environment via `timeout_info.rack_env`.
+
+If you need to invoke cleanup code that rely on thread local state, you can copy
+that state with `timeout_info.copy_thread_variables!`, but it's best avoided as the
+thread local state could contain thread unsafe objects.
+
+Also note that at this stage, the thread is still alive, if your callback does
+substantial work, you may want to kill the thread.
+
+After the callback is executed the worker will exit with status `0`.
+
+It is recommended not to do slow operations in this callback, but if you
+really have to, make sure to configure the `cleanup` timeout so that the
+callback has time to complete before the "hard" timeout triggers.
+By default the cleanup timeout is 2 seconds.
+
 ### `after_worker_exit`
 
 Called in the master process after a worker exits.
@@ -297,6 +349,20 @@ after_worker_exit do |server, worker, status|
 end
 ```
 
+### `after_request_complete`
+
+Called in the worker processes after a request has completed.
+
+Can be used for out of band work, or to exit unhealthy workers.
+
+```ruby
+after_request_complete do |server, worker|
+  if something_wrong?
+    exit
+  end
+end
+```
+
 ## Reforking
 
 ### `refork_after`