raptor 0.26.0 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01e94b50f111d86ede3add1b2ff22fe674c4b2da50d748fc81728ac56458d9c4
-  data.tar.gz: cff8caa5355ce8f7b4e1d7fb7ec1ae17e8fe5332852b57042831d9a10921276f
+  metadata.gz: 6f72ac9941a9da99f3fe49f3464ac925ff6304cf196836502a480220eb99d48f
+  data.tar.gz: 7a72e415e3663c54ac3c4f2fcfd13481356b3357693298c082f2b2eda3727182
 SHA512:
-  metadata.gz: a9d7fd70b2cea77c2d6b1b232542a9a70d8d4f7a40a88870128af620e5125e24d4578e77885dcbd1df9fc750785547a8a71f87791381358a693a3ee382defdf9
-  data.tar.gz: ea9c5cf5e367b17e47bdaeb8e927d5c2214a7d739d6a646b3162c808b3bbc3f82c026e3632a8846f4f978069add42f34cc3727415a8b90a9a321eb20dea93147
+  metadata.gz: bf330c4d82552ee29b56b4bf0998355d3faad012147a5d34b9ade39d1f333ef4cc46b9d0e81c9b96516462fa920c3efe0c849fb716cdb158261cc3a6aff5014c
+  data.tar.gz: 9ff03e07f24109d0c1a0af66c309b6a49fa8f45c6db0aecd0a1c8507082d2e558a67bf72c01bf6c59f83c2aa379a41e8046f2b91f2d17deb8ecd59c5e44b162f

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.27.0] - 2026-11-10
+
+- Support master-owned Rack listeners across worker forks
+- Add `after_worker_exit` hooks
+- Add `after_worker_drain` hooks
+
 ## [0.26.0] - 2026-11-10
 
 - Add in-process Rack serving

data/README.md

@@ -37,7 +37,7 @@ run proc { |_env| [200, { "content-type" => "text/plain" }, ["Hello, World!"]] }
 ```
 > bundle exec raptor -w 10 -t 3 hello_world.ru
 [Raptor 39704|Main|Main] Cluster initializing:
-[Raptor 39704|Main|Main] ├─ Version: 0.26.0
+[Raptor 39704|Main|Main] ├─ Version: 0.27.0
 [Raptor 39704|Main|Main] ├─ Ruby Version: ruby 4.0.9 (2026-10-23 revision 3e93b23afc) +YJIT +PRISM [arm64-darwin25]
 [Raptor 39704|Main|Main] ├─ Environment: development
 [Raptor 39704|Main|Main] ├─ Master PID: 39704
@@ -148,8 +148,11 @@ working directory. Pass `-c PATH` to point at a specific file.
   worker_shutdown_timeout: 30,
   refork_after: 1000, # `nil` on non-Linux
   before_fork: [],
+  after_fork: [],
   before_worker_boot: [],
   before_worker_shutdown: [],
+  after_worker_drain: [],
+  after_worker_exit: [],
   before_refork: [],
   plugins: [],
   stats_file: "tmp/raptor.json",
@@ -191,21 +194,9 @@ Raptor::Plugin.create(:stats_logger) do
 end
 ```
 
-For an existing class, inherit from `Raptor::Plugin` and register it with
-`Raptor::Plugin.register(:stats_logger, MyStatsLogger)` instead.
-
-`start(cluster)` runs once before the initial workers fork. `cluster.options` exposes configuration, including
-plugin-specific keys. Append callbacks to its `before_fork`, `before_worker_boot`, `before_worker_shutdown`, and
-`before_refork` arrays during startup. If your plugin opens a listener, close the worker's inherited copy with
-`cluster.options[:before_worker_boot] << proc { @listener.close }` so only the master serves it.
-
-`cluster.stats` returns per-worker snapshots. `cluster.stats_hash` returns the same aggregate structure as `GET /stats`,
-including boot status, busy threads, capacity, backlog, and request counts. Both remain available while workers drain.
-
-Override `stop` to close listeners and flush exporters. Raptor calls it after workers exit, in reverse plugin order,
-then stops and joins threads created with `in_background`. These callbacks also run before hot restart and when startup
-fails, so `stop` must handle partially initialized resources. Worker replacement and phased restart keep the same
-master plugin instances running.
+`cluster.options` exposes configuration and lifecycle hooks. `cluster.stats` and `cluster.stats_hash` provide worker
+and aggregate statistics. Override `stop` to release plugin resources after workers exit, including during hot restart.
+See the [API documentation](https://joshuay03.github.io/raptor/Raptor/Plugin.html) for lifecycle details.
 
 ## Bindings
 
@@ -274,7 +265,7 @@ Set `control_url` to a Unix socket URL such as `unix:///tmp/raptor-control.sock`
 
 ## (Micro) Benchmarks
 
-Raptor 0.26.0 vs Puma 8.0.2 vs Falcon 0.57.0. Each case has 3 fresh-process samples, interleaved in seeded shuffled
+Raptor 0.27.0 vs Puma 8.0.2 vs Falcon 0.57.0. Each case has 3 fresh-process samples, interleaved in seeded shuffled
 rounds. Each sample warms up for 3s and measures for 15s. Metrics are independent medians. ± is (max − min) / 2 /
 median, not a confidence interval. Failure counts below each table sum all samples, so a failed run cannot disappear in
 a median. Throughput counts successful ordinary requests only.
@@ -302,90 +293,90 @@ accounting for shared pages instead of counting them fully in every worker.
 
 | Server | Mode           | Raptor baseline | req/s        | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------ | -------------- | --------------- | ------------ | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Fixed (3)      | -               | 3.39k ±0.6%  | -               | 46.17  | -             | 2.434      | 337.1   |
-| Raptor | Scaling (3–16) | -               | 8.18k ±1.3%  | -               | 22.19  | -             | 0.467      | 325.6   |
-| Puma   | Fixed (3)      | Fixed (3)       | 1.52k ±1.1%  | 55.2% lower     | 117.49 | 154.5% higher | 0.996      | 272.0   |
-| Puma   | Scaling (3–16) | Scaling (3–16)  | 8.14k ±1.3%  | 0.4% lower      | 22.37  | 0.8% higher   | 0.473      | 318.8   |
-| Falcon | Fibers         | Fixed (3)       | 10.99k ±1.2% | 224.1% higher   | 15.60  | 66.2% lower   | 0.440      | 447.2   |
-| Falcon | Fibers         | Scaling (3–16)  | 10.99k ±1.2% | 34.3% higher    | 15.60  | 29.7% lower   | 0.440      | 447.2   |
+| Raptor | Fixed (3)      | -               | 3.35k ±1.2%  | -               | 49.00  | -             | 2.421      | 337.8   |
+| Raptor | Scaling (3–16) | -               | 8.21k ±0.6%  | -               | 22.09  | -             | 0.468      | 323.6   |
+| Puma   | Fixed (3)      | Fixed (3)       | 1.53k ±0.7%  | 54.4% lower     | 120.94 | 146.8% higher | 0.969      | 272.0   |
+| Puma   | Scaling (3–16) | Scaling (3–16)  | 8.15k ±0.5%  | 0.7% lower      | 22.23  | 0.6% higher   | 0.467      | 319.5   |
+| Falcon | Fibers         | Fixed (3)       | 11.07k ±0.5% | 230.3% higher   | 15.44  | 68.5% lower   | 0.439      | 446.6   |
+| Falcon | Fibers         | Scaling (3–16)  | 11.07k ±0.5% | 34.8% higher    | 15.44  | 30.1% lower   | 0.439      | 446.6   |
 
 ### IO over HTTP/1.1 keep-alive
 
 | Server | Mode           | Raptor baseline | req/s       | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------ | -------------- | --------------- | ----------- | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Fixed (3)      | -               | 3.37k ±1.8% | -               | 37.11  | -             | 2.460      | 353.2   |
-| Raptor | Scaling (3–16) | -               | 7.39k ±1.7% | -               | 24.53  | -             | 0.470      | 344.9   |
-| Raptor | Fixed (16)     | -               | 7.49k ±1.6% | -               | 24.24  | -             | 0.455      | 341.6   |
-| Puma   | Fixed (3)      | Fixed (3)       | 1.48k ±0.2% | 56.2% lower     | 106.41 | 186.8% higher | 0.979      | 282.1   |
-| Puma   | Scaling (3–16) | Scaling (3–16)  | 7.58k ±1.1% | 2.5% higher     | 24.00  | 2.2% lower    | 0.435      | 310.5   |
-| Puma   | Fixed (16)     | Fixed (16)      | 7.59k ±0.9% | 1.4% higher     | 23.97  | 1.1% lower    | 0.437      | 316.5   |
-| Falcon | Fibers         | Fixed (3)       | 7.31k ±1.5% | 116.9% higher   | 24.86  | 33.0% lower   | 0.380      | 336.6   |
-| Falcon | Fibers         | Scaling (3–16)  | 7.31k ±1.5% | 1.1% lower      | 24.86  | 1.4% higher   | 0.380      | 336.6   |
-| Falcon | Fibers         | Fixed (16)      | 7.31k ±1.5% | 2.3% lower      | 24.86  | 2.6% higher   | 0.380      | 336.6   |
+| Raptor | Fixed (3)      | -               | 3.09k ±6.5% | -               | 51.42  | -             | 2.346      | 348.9   |
+| Raptor | Scaling (3–16) | -               | 7.39k ±0.6% | -               | 24.67  | -             | 0.465      | 344.2   |
+| Raptor | Fixed (16)     | -               | 7.48k ±0.5% | -               | 24.30  | -             | 0.453      | 344.1   |
+| Puma   | Fixed (3)      | Fixed (3)       | 1.49k ±0.4% | 51.7% lower     | 100.59 | 95.6% higher  | 1.009      | 282.5   |
+| Puma   | Scaling (3–16) | Scaling (3–16)  | 7.39k ±0.4% | 0.0% higher     | 24.58  | 0.4% lower    | 0.434      | 310.0   |
+| Puma   | Fixed (16)     | Fixed (16)      | 7.52k ±0.4% | 0.5% higher     | 24.16  | 0.6% lower    | 0.428      | 316.3   |
+| Falcon | Fibers         | Fixed (3)       | 7.34k ±2.1% | 137.4% higher   | 24.78  | 51.8% lower   | 0.382      | 329.6   |
+| Falcon | Fibers         | Scaling (3–16)  | 7.34k ±2.1% | 0.7% lower      | 24.78  | 0.4% higher   | 0.382      | 329.6   |
+| Falcon | Fibers         | Fixed (16)      | 7.34k ±2.1% | 1.9% lower      | 24.78  | 2.0% higher   | 0.382      | 329.6   |
 
 ### IO over HTTP/2
 
-| Server | Mode           | Raptor baseline | req/s        | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
-| ------ | -------------- | --------------- | ------------ | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Fixed (3)      | -               | 1.61k ±4.7%  | -               | 120.85 | -             | 0.815      | 399.9   |
-| Raptor | Scaling (3–16) | -               | 6.80k ±22.8% | -               | 40.32  | -             | 0.580      | 912.4   |
-| Falcon | Fibers         | Fixed (3)       | 7.12k ±3.5%  | 342.8% higher   | 26.17  | 78.3% lower   | 0.432      | 539.7   |
-| Falcon | Fibers         | Scaling (3–16)  | 7.12k ±3.5%  | 4.7% higher     | 26.17  | 35.1% lower   | 0.432      | 539.7   |
+| Server | Mode           | Raptor baseline | req/s       | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
+| ------ | -------------- | --------------- | ----------- | --------------- | ------ | ------------- | ---------- | ------- |
+| Raptor | Fixed (3)      | -               | 1.61k ±0.3% | -               | 131.78 | -             | 0.901      | 410.2   |
+| Raptor | Scaling (3–16) | -               | 7.24k ±8.6% | -               | 30.21  | -             | 0.563      | 940.4   |
+| Falcon | Fibers         | Fixed (3)       | 7.82k ±1.7% | 386.4% higher   | 25.75  | 80.5% lower   | 0.426      | 526.6   |
+| Falcon | Fibers         | Scaling (3–16)  | 7.82k ±1.7% | 8.0% higher     | 25.75  | 14.7% lower   | 0.426      | 526.6   |
 
 ### CPU over HTTP/1.1
 
 | Server | Mode           | Raptor baseline | req/s       | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------ | -------------- | --------------- | ----------- | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Fixed (3)      | -               | 3.43k ±1.1% | -               | 67.46  | -             | 2.507      | 509.4   |
-| Raptor | Scaling (3–16) | -               | 3.26k ±2.5% | -               | 70.51  | -             | 2.572      | 499.6   |
-| Puma   | Fixed (3)      | Fixed (3)       | 3.21k ±3.5% | 6.3% lower      | 56.00  | 17.0% lower   | 2.454      | 441.3   |
-| Puma   | Scaling (3–16) | Scaling (3–16)  | 3.15k ±2.3% | 3.4% lower      | 49.26  | 30.1% lower   | 2.186      | 431.0   |
-| Falcon | Fibers         | Fixed (3)       | 3.36k ±4.2% | 2.1% lower      | 48.20  | 28.5% lower   | 2.555      | 435.8   |
-| Falcon | Fibers         | Scaling (3–16)  | 3.36k ±4.2% | 3.0% higher     | 48.20  | 31.6% lower   | 2.555      | 435.8   |
+| Raptor | Fixed (3)      | -               | 3.40k ±1.5% | -               | 66.74  | -             | 2.519      | 511.8   |
+| Raptor | Scaling (3–16) | -               | 3.45k ±3.9% | -               | 62.67  | -             | 2.389      | 504.6   |
+| Puma   | Fixed (3)      | Fixed (3)       | 3.24k ±0.9% | 4.7% lower      | 57.00  | 14.6% lower   | 2.457      | 444.5   |
+| Puma   | Scaling (3–16) | Scaling (3–16)  | 3.09k ±2.7% | 10.4% lower     | 49.54  | 21.0% lower   | 2.182      | 437.4   |
+| Falcon | Fibers         | Fixed (3)       | 3.53k ±0.8% | 3.8% higher     | 47.04  | 29.5% lower   | 2.430      | 432.3   |
+| Falcon | Fibers         | Scaling (3–16)  | 3.53k ±0.8% | 2.2% higher     | 47.04  | 24.9% lower   | 2.430      | 432.3   |
 
 ### CPU over HTTP/1.1 keep-alive
 
 | Server | Mode           | Raptor baseline | req/s       | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------ | -------------- | --------------- | ----------- | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Fixed (3)      | -               | 3.10k ±5.2% | -               | 54.76  | -             | 2.560      | 484.4   |
-| Raptor | Scaling (3–16) | -               | 2.97k ±1.2% | -               | 49.64  | -             | 2.553      | 505.3   |
-| Puma   | Fixed (3)      | Fixed (3)       | 3.52k ±6.1% | 13.7% higher    | 51.14  | 6.6% lower    | 2.299      | 384.4   |
-| Puma   | Scaling (3–16) | Scaling (3–16)  | 2.90k ±4.2% | 2.3% lower      | 65.73  | 32.4% higher  | 2.283      | 472.5   |
-| Falcon | Fibers         | Fixed (3)       | 3.17k ±1.9% | 2.4% higher     | 69.58  | 27.1% higher  | 2.766      | 536.5   |
-| Falcon | Fibers         | Scaling (3–16)  | 3.17k ±1.9% | 6.7% higher     | 69.58  | 40.2% higher  | 2.766      | 536.5   |
+| Raptor | Fixed (3)      | -               | 3.12k ±0.3% | -               | 50.35  | -             | 2.534      | 483.3   |
+| Raptor | Scaling (3–16) | -               | 2.99k ±2.1% | -               | 50.79  | -             | 2.532      | 502.5   |
+| Puma   | Fixed (3)      | Fixed (3)       | 3.49k ±6.5% | 11.7% higher    | 51.75  | 2.8% higher   | 2.319      | 383.4   |
+| Puma   | Scaling (3–16) | Scaling (3–16)  | 3.00k ±3.8% | 0.5% higher     | 64.39  | 26.8% higher  | 2.224      | 470.8   |
+| Falcon | Fibers         | Fixed (3)       | 3.17k ±0.2% | 1.7% higher     | 67.10  | 33.3% higher  | 2.763      | 529.6   |
+| Falcon | Fibers         | Scaling (3–16)  | 3.17k ±0.2% | 6.1% higher     | 67.10  | 32.1% higher  | 2.763      | 529.6   |
 
 ### CPU over HTTP/2
 
 | Server | Mode           | Raptor baseline | req/s        | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------ | -------------- | --------------- | ------------ | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Fixed (3)      | -               | 3.26k ±2.1%  | -               | 71.84  | -             | 2.329      | 573.4   |
-| Raptor | Scaling (3–16) | -               | 3.25k ±2.6%  | -               | 69.37  | -             | 2.383      | 590.6   |
-| Falcon | Fibers         | Fixed (3)       | 2.02k ±11.2% | 37.9% lower     | 176.57 | 145.8% higher | 2.405      | 559.2   |
-| Falcon | Fibers         | Scaling (3–16)  | 2.02k ±11.2% | 37.9% lower     | 176.57 | 154.5% higher | 2.405      | 559.2   |
+| Raptor | Fixed (3)      | -               | 3.32k ±3.7%  | -               | 70.25  | -             | 2.374      | 583.2   |
+| Raptor | Scaling (3–16) | -               | 3.31k ±0.9%  | -               | 60.05  | -             | 2.347      | 562.3   |
+| Falcon | Fibers         | Fixed (3)       | 2.36k ±18.9% | 29.0% lower     | 127.17 | 81.0% higher  | 2.399      | 561.8   |
+| Falcon | Fibers         | Scaling (3–16)  | 2.36k ±18.9% | 28.8% lower     | 127.17 | 111.8% higher | 2.399      | 561.8   |
 
 ### 64 KiB body over HTTP/1.1 keep-alive
 
 | Server | Mode           | Raptor baseline | req/s         | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------ | -------------- | --------------- | ------------- | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor | Scaling (3–16) | -               | 94.58k ±2.0%  | -               | 3.77   | -             | 0.052      | 507.6   |
-| Puma   | Scaling (3–16) | Scaling (3–16)  | 88.40k ±2.1%  | 6.5% lower      | 3.66   | 2.9% lower    | 0.054      | 1237.4  |
-| Falcon | Fibers         | Scaling (3–16)  | 103.33k ±5.0% | 9.2% higher     | 3.89   | 3.2% higher   | 0.051      | 344.7   |
+| Raptor | Scaling (3–16) | -               | 94.57k ±1.5%  | -               | 3.70   | -             | 0.051      | 592.0   |
+| Puma   | Scaling (3–16) | Scaling (3–16)  | 88.51k ±0.7%  | 6.4% lower      | 3.67   | 0.6% lower    | 0.054      | 1201.7  |
+| Falcon | Fibers         | Scaling (3–16)  | 103.00k ±5.1% | 8.9% higher     | 3.84   | 3.9% higher   | 0.051      | 341.1   |
 
 ### IO + SSE (native) over HTTP/1.1 keep-alive
 
 | Server        | Mode           | Raptor baseline | req/s       | vs Raptor req/s | p95 ms | vs Raptor p95 | CPU ms/req | PSS MiB |
 | ------------- | -------------- | --------------- | ----------- | --------------- | ------ | ------------- | ---------- | ------- |
-| Raptor        | Fixed (3)      | -               | 3.24k ±1.6% | -               | 44.69  | -             | 2.396      | 355.6   |
-| Raptor        | Scaling (3–16) | -               | 7.39k ±0.8% | -               | 24.47  | -             | 0.468      | 346.4   |
-| Puma          | Fixed (3)      | Fixed (3)       | 0.35k ±4.5% | 89.3% lower     | 316.86 | 609.1% higher | 1.764      | 243.6   |
-| Puma          | Scaling (3–16) | Scaling (3–16)  | 7.38k ±4.3% | 0.2% lower      | 24.61  | 0.6% higher   | 0.440      | 311.3   |
-| Falcon        | Fibers         | Fixed (3)       | 7.32k ±1.0% | 125.8% higher   | 24.83  | 44.4% lower   | 0.383      | 354.4   |
-| Falcon        | Fibers         | Scaling (3–16)  | 7.32k ±1.0% | 1.0% lower      | 24.83  | 1.5% higher   | 0.383      | 354.4   |
-| Raptor (enum) | Fixed (3)      | -               | 0.97k ±4.8% | -               | 56.38  | -             | 7.624      | 324.4   |
+| Raptor        | Fixed (3)      | -               | 2.74k ±6.2% | -               | 59.25  | -             | 2.298      | 341.5   |
+| Raptor        | Scaling (3–16) | -               | 7.41k ±1.2% | -               | 24.53  | -             | 0.471      | 345.4   |
+| Puma          | Fixed (3)      | Fixed (3)       | 0.34k ±5.4% | 87.5% lower     | 361.94 | 510.8% higher | 1.715      | 263.9   |
+| Puma          | Scaling (3–16) | Scaling (3–16)  | 7.34k ±1.0% | 1.0% lower      | 24.70  | 0.7% higher   | 0.430      | 310.9   |
+| Falcon        | Fibers         | Fixed (3)       | 7.30k ±1.0% | 165.9% higher   | 24.88  | 58.0% lower   | 0.379      | 356.6   |
+| Falcon        | Fibers         | Scaling (3–16)  | 7.30k ±1.0% | 1.6% lower      | 24.88  | 1.5% higher   | 0.379      | 356.6   |
+| Raptor (enum) | Fixed (3)      | -               | 0.88k ±0.3% | -               | 66.74  | -             | 8.142      | 382.6   |
 
-Puma, Fixed (3) had 68 timeouts, 1 stalled stream across all samples.
+Puma, Fixed (3) had 37 timeouts, 1 stalled stream across all samples.
 
-Raptor (enum), Fixed (3) had 21 timeouts, 2 stalled streams across all samples.
+Raptor (enum), Fixed (3) had 16 timeouts across all samples.
 
 > ruby 4.1.0dev (2026-11-10T00:02:04Z HEAD 7a07e456e4) +YJIT +PRISM [aarch64-linux]
 > 10 workers, 120 HTTP/1.1 client connections, 40 HTTP/2 connections × 3 streams.

data/lib/raptor/cli.rb

@@ -67,8 +67,11 @@ module Raptor
       worker_shutdown_timeout: 30,
       refork_after: (RUBY_PLATFORM.include?("linux") ? 1000 : nil),
       before_fork: [].freeze,
+      after_fork: [].freeze,
       before_worker_boot: [].freeze,
       before_worker_shutdown: [].freeze,
+      after_worker_drain: [].freeze,
+      after_worker_exit: [].freeze,
       before_refork: [].freeze,
       plugins: [].freeze,
       stats_file: "tmp/raptor.json",

data/lib/raptor/cluster.rb

@@ -80,8 +80,11 @@ module Raptor
     # @rbs @worker_drain_timeout: Integer
     # @rbs @worker_shutdown_timeout: Integer
     # @rbs @before_fork: Array[Proc]
+    # @rbs @after_fork: Array[Proc]
     # @rbs @before_worker_boot: Array[Proc]
     # @rbs @before_worker_shutdown: Array[Proc]
+    # @rbs @after_worker_drain: Array[Proc]
+    # @rbs @after_worker_exit: Array[Proc]
     # @rbs @before_refork: Array[Proc]
     # @rbs @stats_file: String?
     # @rbs @control_server: ControlServer?
@@ -97,6 +100,7 @@ module Raptor
     # @rbs @app: untyped
     # @rbs @shutdown: bool
     # @rbs @workers: Hash[Integer, Integer]
+    # @rbs @worker_indices: Hash[Integer, Integer]
     # @rbs @timed_out: Set[Integer]
     # @rbs @stats: Stats
     # @rbs @started_at: Float
@@ -146,9 +150,12 @@ module Raptor
     # @option options [Integer] :worker_drain_timeout seconds a worker waits for in-flight requests during shutdown before force-killing app threads
     # @option options [Integer] :worker_shutdown_timeout seconds to wait for graceful worker exit before force-killing
     # @option options [Integer, Array<Integer>, nil] :refork_after request-count threshold(s) at which a warm worker is promoted to a fork source for phased refork; nil or 0 disables. Requires `PR_SET_CHILD_SUBREAPER` (Linux)
-    # @option options [Array<Proc>] :before_fork procs called in the master before every worker fork
+    # @option options [Array<Proc>] :before_fork procs called in the master before each direct worker fork, not seed forks
+    # @option options [Array<Proc>] :after_fork procs called in the master after each direct fork attempt, including failures
     # @option options [Array<Proc>] :before_worker_boot procs called with the worker index before it begins serving
     # @option options [Array<Proc>] :before_worker_shutdown procs called with the worker index before its graceful shutdown
+    # @option options [Array<Proc>] :after_worker_drain procs called with the worker index after draining, before exit or seed promotion
+    # @option options [Array<Proc>] :after_worker_exit procs called in the master after reaping, with the worker index, pid, and Process::Status
     # @option options [Array<Proc>] :before_refork procs called in a worker before it transitions to a seed
     # @option options [Array<String, Symbol>] :plugins plugins to load and start in order
     # @option options [String, nil] :stats_file path to write per-worker stats JSON, or nil to disable
@@ -178,8 +185,11 @@ module Raptor
       @worker_drain_timeout = options[:worker_drain_timeout]
       @worker_shutdown_timeout = options[:worker_shutdown_timeout]
       @before_fork = options[:before_fork] = Array(options[:before_fork]).dup
+      @after_fork = options[:after_fork] = Array(options[:after_fork]).dup
       @before_worker_boot = options[:before_worker_boot] = Array(options[:before_worker_boot]).dup
       @before_worker_shutdown = options[:before_worker_shutdown] = Array(options[:before_worker_shutdown]).dup
+      @after_worker_drain = options[:after_worker_drain] = Array(options[:after_worker_drain]).dup
+      @after_worker_exit = options[:after_worker_exit] = Array(options[:after_worker_exit]).dup
       @before_refork = options[:before_refork] = Array(options[:before_refork]).dup
       @stats_file = options[:stats_file]
       @control_server = ControlServer.new(options[:control_url]) { stats_hash } if options[:control_url]
@@ -208,6 +218,7 @@ module Raptor
 
       @shutdown = false
       @workers = {}
+      @worker_indices = {}
       @timed_out = Set.new
       @stats = Stats.new(@worker_count)
       @started_at = Process.clock_gettime(Process::CLOCK_REALTIME)
@@ -438,15 +449,34 @@ module Raptor
         pid = spawn_worker_via_seed(index)
         if pid
           @workers[index] = pid
+          @worker_indices[pid] = index
           return
         end
         Log.warn "Seed (#{@seed_pid}) failed to fork worker #{index}, falling back to direct fork"
         @seed_pid = nil
       end
 
-      @before_fork.each(&:call)
-      pid = fork { run_worker(index, @phase) }
-      @workers[index] = pid
+      master_pid = Process.pid
+      begin
+        @before_fork.each(&:call)
+        pid = fork { run_worker(index, @phase) }
+        @workers[index] = pid
+        @worker_indices[pid] = index
+      ensure
+        if Process.pid == master_pid
+          error = $!
+          @after_fork.each do |hook|
+            hook.call
+          rescue => hook_error
+            if error
+              Log.rescued_error(hook_error)
+            else
+              error = hook_error
+            end
+          end
+          raise error if error
+        end
+      end
     end
 
     # Asks the seed to fork a new worker at the given index, returning the
@@ -511,19 +541,20 @@ module Raptor
     #
     # @rbs (Integer pid, Process::Status status) -> void
     def reap_pid(pid, status)
+      index = @worker_indices.delete(pid)
+      return unless index
+
+      active = @workers[index] == pid
       if pid == @seed_pid
         Log.info "Seed (#{pid}) exited, #{exit_description(status)}"
         @seed_pid = nil
-        return
       end
 
-      index = @workers.key(pid)
-      return unless index
-
-      @workers.delete(index)
+      @workers.delete(index) if active
       @timed_out.delete(pid)
+      @after_worker_exit.each { |hook| hook.parameters.empty? ? hook.call : hook.call(index, pid, status) }
 
-      unless @shutdown
+      if active && !@shutdown
         Log.warn "Restarting worker #{index} (#{pid}), #{exit_description(status)}"
         spawn_worker(index)
       end
@@ -655,7 +686,11 @@ module Raptor
       pids = @workers.values + [@seed_pid].compact
       Log.warn "Force-killing #{pids.size} process(es) after #{@worker_shutdown_timeout}s"
       pids.each { |pid| Process.kill("KILL", pid) rescue nil }
-      pids.each { |pid| Process.wait(pid) rescue nil }
+      pids.each do |pid|
+        _, status = Process.wait2(pid)
+        reap_pid(pid, status)
+      rescue Errno::ECHILD
+      end
     end
 
     # Kills workers that have stopped checking in. A booted worker that
@@ -903,6 +938,7 @@ module Raptor
       end
 
       worker.shutdown(close_listeners: !promote_to_seed)
+      @after_worker_drain.each { |hook| hook.parameters.empty? ? hook.call : hook.call(index) }
       # A seed never accepts again, and the workers it forks bind their own.
       bpf_listeners.each(&:close) if promote_to_seed
       stats_thread.join

data/lib/raptor/embedded.rb

@@ -61,15 +61,7 @@ module Raptor
           @binder = Binder.new(@binds, socket_backlog: @options[:socket_backlog])
           @port = @binder.server_port
           @addresses = @binder.addresses
-          @worker = Worker.new(
-            @app,
-            listeners: @binder.listeners,
-            port: @port,
-            options: @options,
-            http1_ractors: @options[:http1][:ractors] || Cluster.default_http1_ractor_count(1),
-            http2_ractors: @options[:http2][:ractors] || Cluster.default_http2_ractor_count(1)
-          )
-          @worker.start
+          start_worker
         rescue
           @stopped = true
           @binder&.close
@@ -89,6 +81,57 @@ module Raptor
       join
     end
 
+    # Drains serving work while retaining the bound listeners for resume.
+    # Connections may queue, but requests are not served while paused.
+    # Existing keep-alive connections close. Repeated pauses have no effect.
+    #
+    # Pause before master forks and resume in the parent. Close the inherited
+    # instance before other worker boot hooks, and shut down when the plugin stops.
+    #
+    # @example From a plugin's start callback
+    #   @server = Raptor::Embedded.new(app, port: 9293).start
+    #   cluster.options[:before_fork] << proc { @server.pause }
+    #   cluster.options[:after_fork] << proc { @server.resume }
+    #   cluster.options[:before_worker_boot].unshift(proc { @server.shutdown })
+    #
+    # @rbs () -> Embedded
+    def pause
+      with_lifecycle do
+        raise ThreadError, "server is not running" unless @started && !@stopped
+
+        begin
+          @worker&.shutdown(close_listeners: false)
+          @worker = nil
+        rescue
+          @stopped = true
+          @binder&.close
+          raise
+        end
+      end
+
+      self
+    end
+
+    # Resumes serving on the retained listeners. Has no effect while running.
+    # Shutdown remains terminal. Startup failures release the listeners and propagate.
+    #
+    # @rbs () -> Embedded
+    def resume
+      with_lifecycle do
+        raise ThreadError, "server has not been started or has been stopped" unless @started && !@stopped
+
+        begin
+          start_worker unless @worker
+        rescue
+          @stopped = true
+          @binder&.close
+          raise
+        end
+      end
+
+      self
+    end
+
     # Drains requests and closes the server's sockets, threads, and Ractors.
     # Calling shutdown more than once has no effect.
     #
@@ -106,20 +149,43 @@ module Raptor
       end
     end
 
-    # Waits for termination and propagates serving thread failures.
+    # Waits across pauses until termination and propagates serving failures.
     #
     # @rbs () -> void
     def join
-      worker = with_lifecycle { @worker }
-      raise ThreadError, "server has not been started" unless worker
-
-      worker.join
+      started = with_lifecycle { @started }
+      raise ThreadError, "server has not been started" unless started
+
+      loop do
+        worker, stopped = with_lifecycle { [@worker, @stopped] }
+        break if stopped
+
+        if worker
+          worker.join
+          break if with_lifecycle { @worker.equal?(worker) }
+        else
+          @lifecycle_available.wait { @worker || @stopped }
+        end
+      end
     ensure
-      shutdown if worker
+      shutdown if started
     end
 
     private
 
+    # @rbs () -> void
+    def start_worker
+      @worker = Worker.new(
+        @app,
+        listeners: @binder.listeners,
+        port: @port,
+        options: @options,
+        http1_ractors: @options[:http1][:ractors] || Cluster.default_http1_ractor_count(1),
+        http2_ractors: @options[:http2][:ractors] || Cluster.default_http2_ractor_count(1)
+      )
+      @worker.start
+    end
+
     # @rbs () -> void
     def log_initialization
       environment = @options[:environment] || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"

data/lib/raptor/plugin.rb

@@ -53,6 +53,7 @@ module Raptor
 
     # Starts in the master before workers fork. Override to open resources
     # and append callbacks to the cluster's lifecycle hook arrays.
+    # See {Cluster#initialize} for hooks and {Embedded#pause} for fork-safe Rack listeners.
     #
     # @rbs (Cluster cluster) -> void
     def start(cluster)

data/lib/raptor/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Raptor
-  VERSION = "0.26.0"
+  VERSION = "0.27.0"
 end

data/sig/generated/raptor/cluster.rbs

@@ -72,20 +72,22 @@ module Raptor
 
     @before_refork: Array[Proc]
 
+    @after_worker_exit: Array[Proc]
+
+    @after_worker_drain: Array[Proc]
+
     @before_worker_shutdown: Array[Proc]
 
     @before_worker_boot: Array[Proc]
 
+    @after_fork: Array[Proc]
+
     @before_fork: Array[Proc]
 
     @worker_shutdown_timeout: Integer
 
     @worker_drain_timeout: Integer
 
-    @worker_timeout: Integer
-
-    @worker_boot_timeout: Integer
-
     @bpf_active: bool
 
     @resp_w: IO?
@@ -122,10 +124,16 @@ module Raptor
 
     @timed_out: Set[Integer]
 
+    @worker_indices: Hash[Integer, Integer]
+
     @workers: Hash[Integer, Integer]
 
     @shutdown: bool
 
+    @worker_timeout: Integer
+
+    @worker_boot_timeout: Integer
+
     @environment: String
 
     @cpu_affinity: bool
@@ -169,9 +177,12 @@ module Raptor
     # @option options [Integer] :worker_drain_timeout seconds a worker waits for in-flight requests during shutdown before force-killing app threads
     # @option options [Integer] :worker_shutdown_timeout seconds to wait for graceful worker exit before force-killing
     # @option options [Integer, Array<Integer>, nil] :refork_after request-count threshold(s) at which a warm worker is promoted to a fork source for phased refork; nil or 0 disables. Requires `PR_SET_CHILD_SUBREAPER` (Linux)
-    # @option options [Array<Proc>] :before_fork procs called in the master before every worker fork
+    # @option options [Array<Proc>] :before_fork procs called in the master before each direct worker fork, not seed forks
+    # @option options [Array<Proc>] :after_fork procs called in the master after each direct fork attempt, including failures
     # @option options [Array<Proc>] :before_worker_boot procs called with the worker index before it begins serving
     # @option options [Array<Proc>] :before_worker_shutdown procs called with the worker index before its graceful shutdown
+    # @option options [Array<Proc>] :after_worker_drain procs called with the worker index after draining, before exit or seed promotion
+    # @option options [Array<Proc>] :after_worker_exit procs called in the master after reaping, with the worker index, pid, and Process::Status
     # @option options [Array<Proc>] :before_refork procs called in a worker before it transitions to a seed
     # @option options [Array<String, Symbol>] :plugins plugins to load and start in order
     # @option options [String, nil] :stats_file path to write per-worker stats JSON, or nil to disable

data/sig/generated/raptor/embedded.rbs

@@ -46,19 +46,44 @@ module Raptor
     # @rbs () -> void
     def run: () -> void
 
+    # Drains serving work while retaining the bound listeners for resume.
+    # Connections may queue, but requests are not served while paused.
+    # Existing keep-alive connections close. Repeated pauses have no effect.
+    #
+    # Pause before master forks and resume in the parent. Close the inherited
+    # instance before other worker boot hooks, and shut down when the plugin stops.
+    #
+    # @example From a plugin's start callback
+    #   @server = Raptor::Embedded.new(app, port: 9293).start
+    #   cluster.options[:before_fork] << proc { @server.pause }
+    #   cluster.options[:after_fork] << proc { @server.resume }
+    #   cluster.options[:before_worker_boot].unshift(proc { @server.shutdown })
+    #
+    # @rbs () -> Embedded
+    def pause: () -> Embedded
+
+    # Resumes serving on the retained listeners. Has no effect while running.
+    # Shutdown remains terminal. Startup failures release the listeners and propagate.
+    #
+    # @rbs () -> Embedded
+    def resume: () -> Embedded
+
     # Drains requests and closes the server's sockets, threads, and Ractors.
     # Calling shutdown more than once has no effect.
     #
     # @rbs () -> void
     def shutdown: () -> void
 
-    # Waits for termination and propagates serving thread failures.
+    # Waits across pauses until termination and propagates serving failures.
     #
     # @rbs () -> void
     def join: () -> void
 
     private
 
+    # @rbs () -> void
+    def start_worker: () -> void
+
     # @rbs () -> void
     def log_initialization: () -> void
 

data/sig/generated/raptor/plugin.rbs

@@ -28,6 +28,7 @@ module Raptor
 
     # Starts in the master before workers fork. Override to open resources
     # and append callbacks to the cluster's lifecycle hook arrays.
+    # See {Cluster#initialize} for hooks and {Embedded#pause} for fork-safe Rack listeners.
     #
     # @rbs (Cluster cluster) -> void
     def start: (Cluster cluster) -> void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: raptor
 version: !ruby/object:Gem::Version
-  version: 0.26.0
+  version: 0.27.0
 platform: ruby
 authors:
 - Joshua Young