Merge pull request #3504 from benoitc/feature/dirty-ttin-ttou

feat(dirty): add TTIN/TTOU signal support for dynamic worker scaling

Author: benoitc

README.md

@@ -34,9 +34,9 @@ gunicorn myapp:app --worker-class asgi
 ## Features
 
 - WSGI support for Django, Flask, Pyramid, and any WSGI framework
-- **ASGI support** (beta) for FastAPI, Starlette, Quart
+- **ASGI support** for FastAPI, Starlette, Quart
 - **HTTP/2 support** (beta) with multiplexed streams
-- **Dirty Arbiters** for heavy workloads (ML models, long-running tasks)
+- **Dirty Arbiters** (beta) for heavy workloads (ML models, long-running tasks)
 - uWSGI binary protocol for nginx integration
 - Multiple worker types: sync, gthread, gevent, eventlet, asgi
 - Graceful worker process management

docs/content/2026-news.md

@@ -1,6 +1,52 @@
 <span id="news-2026"></span>
 # Changelog - 2026
 
+## 25.1.0 - 2026-02-12
+
+### New Features
+
+- **Dirty Stash**: Add global shared state between workers via `dirty.stash`
+  ([PR #3503](https://github.com/benoitc/gunicorn/pull/3503))
+  - In-memory key-value store accessible by all workers
+  - Supports get, set, delete, clear, keys, and has operations
+  - Useful for sharing state like feature flags, rate limits, or cached data
+
+- **Dirty Binary Protocol**: Implement efficient binary protocol for dirty arbiter IPC
+  using TLV (Type-Length-Value) encoding
+  ([PR #3500](https://github.com/benoitc/gunicorn/pull/3500))
+  - More efficient than JSON for binary data
+  - Supports all Python types: str, bytes, int, float, bool, None, list, dict
+  - Better performance for large payloads
+
+- **Dirty TTIN/TTOU Signals**: Add dynamic worker scaling for dirty arbiters
+  ([PR #3504](https://github.com/benoitc/gunicorn/pull/3504))
+  - Send SIGTTIN to increase dirty workers
+  - Send SIGTTOU to decrease dirty workers
+  - Respects minimum worker constraints from app configurations
+
+### Changes
+
+- **ASGI Worker**: Promoted from beta to stable
+- **Dirty Arbiters**: Now marked as beta feature
+
+### Documentation
+
+- Fix Markdown formatting in /configure documentation
+
+---
+
+## 25.0.3 - 2026-02-07
+
+### Bug Fixes
+
+- Fix RuntimeError when StopIteration is raised inside ASGI response body
+  coroutine (PEP 479 compliance)
+
+- Fix deprecation warning for passing maxsplit as positional argument in
+  `re.split()` (Python 3.13+)
+
+---
+
 ## 25.0.2 - 2026-02-06
 
 ### Bug Fixes

docs/content/asgi.md

@@ -1,10 +1,5 @@
 # ASGI Worker
 
-!!! warning "Beta Feature"
-    The ASGI worker is a beta feature introduced in Gunicorn 24.0.0. While it has been tested,
-    the API and behavior may change in future releases. Please report any issues on
-    [GitHub](https://github.com/benoitc/gunicorn/issues).
-
 Gunicorn includes a native ASGI worker that enables running async Python web frameworks
 like FastAPI, Starlette, and Quart without external dependencies like Uvicorn.
 

docs/content/dirty.md

@@ -7,6 +7,11 @@ menu:
 
 # Dirty Arbiters
 
+!!! warning "Beta Feature"
+    Dirty Arbiters is a beta feature introduced in Gunicorn 25.0.0. While it has been tested,
+    the API and behavior may change in future releases. Please report any issues on
+    [GitHub](https://github.com/benoitc/gunicorn/issues).
+
 Dirty Arbiters provide a separate process pool for executing long-running, blocking operations (AI model loading, heavy computation) without blocking HTTP workers. This feature is inspired by Erlang's dirty schedulers.
 
 ## Overview
@@ -907,9 +912,40 @@ Dirty Arbiters integrate with the main arbiter's signal handling. Signals are fo
 | `SIGQUIT` | Immediate exit via `sys.exit(0)` | Killed immediately | Fast shutdown, no cleanup |
 | `SIGHUP` | Kills all workers, spawns new ones | Exits immediately | Hot reload of workers |
 | `SIGUSR1` | Reopens log files, forwards to workers | Reopens log files | Log rotation support |
+| `SIGTTIN` | Increases worker count by 1 | N/A | Dynamic scaling up |
+| `SIGTTOU` | Decreases worker count by 1 | N/A | Dynamic scaling down |
 | `SIGCHLD` | Handled by event loop, triggers reap | N/A | Worker death detection |
 | `SIGINT` | Same as SIGTERM | Same as SIGTERM | Ctrl-C handling |
 
+### Dynamic Scaling with TTIN/TTOU
+
+You can dynamically scale the number of dirty workers at runtime using signals, without restarting gunicorn:
+
+```bash
+# Find the dirty arbiter process
+ps aux | grep dirty-arbiter
+# Or use the PID file (location depends on your app name)
+cat /tmp/gunicorn-dirty-myapp.pid
+
+# Increase dirty workers by 1
+kill -TTIN <dirty-arbiter-pid>
+
+# Decrease dirty workers by 1
+kill -TTOU <dirty-arbiter-pid>
+```
+
+**Minimum Worker Constraint:** The dirty arbiter will not decrease below the minimum number of workers required by your app configurations. For example, if you have an app with `workers = 3`, you cannot scale below 3 dirty workers. When this limit is reached, a warning is logged:
+
+```
+WARNING: SIGTTOU: Cannot decrease below 3 workers (required by app specs)
+```
+
+**Use Cases:**
+
+- **Burst handling** - Scale up when you anticipate heavy load
+- **Cost optimization** - Scale down during low-traffic periods
+- **Recovery** - Scale up if workers are busy with long-running tasks
+
 ### Forwarded Signals
 
 The main arbiter forwards these signals to the dirty arbiter process:

docs/content/index.md

@@ -83,7 +83,7 @@ title: Gunicorn - Python WSGI HTTP Server
         <p>Multiple threads per worker. Balance concurrency and simplicity.</p>
       </a>
       <a class="worker" href="asgi/">
-        <h3>ASGI <span class="badge">Beta</span></h3>
+        <h3>ASGI</h3>
         <p>Native asyncio for FastAPI, Starlette, and async frameworks.</p>
       </a>
     </div>

docs/content/news.md

@@ -1,6 +1,40 @@
 <span id="news"></span>
 # Changelog
 
+## 25.1.0 - 2026-02-12
+
+### New Features
+
+- **Dirty Stash**: Add global shared state between workers via `dirty.stash`
+  ([PR #3503](https://github.com/benoitc/gunicorn/pull/3503))
+  - In-memory key-value store accessible by all workers
+  - Supports get, set, delete, clear, keys, and has operations
+  - Useful for sharing state like feature flags, rate limits, or cached data
+
+- **Dirty Binary Protocol**: Implement efficient binary protocol for dirty arbiter IPC
+  using TLV (Type-Length-Value) encoding
+  ([PR #3500](https://github.com/benoitc/gunicorn/pull/3500))
+  - More efficient than JSON for binary data
+  - Supports all Python types: str, bytes, int, float, bool, None, list, dict
+  - Better performance for large payloads
+
+- **Dirty TTIN/TTOU Signals**: Add dynamic worker scaling for dirty arbiters
+  ([PR #3504](https://github.com/benoitc/gunicorn/pull/3504))
+  - Send SIGTTIN to increase dirty workers
+  - Send SIGTTOU to decrease dirty workers
+  - Respects minimum worker constraints from app configurations
+
+### Changes
+
+- **ASGI Worker**: Promoted from beta to stable
+- **Dirty Arbiters**: Now marked as beta feature
+
+### Documentation
+
+- Fix Markdown formatting in /configure documentation
+
+---
+
 ## 25.0.3 - 2026-02-07
 
 ### Bug Fixes

gunicorn/__init__.py

@@ -2,7 +2,7 @@
 # This file is part of gunicorn released under the MIT license.
 # See the NOTICE for more information.
 
-version_info = (25, 0, 3)
+version_info = (25, 1, 0)
 __version__ = ".".join([str(v) for v in version_info])
 SERVER = "gunicorn"
 SERVER_SOFTWARE = "%s/%s" % (SERVER, __version__)

gunicorn/dirty/arbiter.py

@@ -57,7 +57,7 @@ class DirtyArbiter:
     """
 
     SIGNALS = [getattr(signal, "SIG%s" % x) for x in
-               "HUP QUIT INT TERM USR1 USR2 CHLD".split()]
+               "HUP QUIT INT TERM TTIN TTOU USR1 USR2 CHLD".split()]
 
     # Worker boot error code
     WORKER_BOOT_ERROR = 3
@@ -92,6 +92,7 @@ def __init__(self, cfg, log, socket_path=None, pidfile=None):
         self._worker_rr_index = 0  # Round-robin index for worker selection
         self.worker_age = 0
         self.alive = True
+        self.num_workers = self.cfg.dirty_workers  # Dynamic count for TTIN/TTOU
 
         self._server = None
         self._loop = None
@@ -150,6 +151,23 @@ def _parse_app_specs(self):
             # Initialize the app_worker_map for this app
             self.app_worker_map[import_path] = set()
 
+    def _get_minimum_workers(self):
+        """
+        Calculate minimum number of workers required by app specs.
+
+        Returns the maximum worker_count across all apps that have limits.
+        Apps with worker_count=None don't impose a minimum.
+
+        Returns:
+            int: Minimum workers required (at least 1)
+        """
+        min_required = 1
+        for spec in self.app_specs.values():
+            worker_count = spec['worker_count']
+            if worker_count is not None:
+                min_required = max(min_required, worker_count)
+        return min_required
+
     def _get_apps_for_new_worker(self):
         """
         Determine which apps a new worker should load.
@@ -255,6 +273,8 @@ def init_signals(self):
         signal.signal(signal.SIGHUP, self._signal_handler)
         signal.signal(signal.SIGUSR1, self._signal_handler)
         signal.signal(signal.SIGCHLD, self._signal_handler)
+        signal.signal(signal.SIGTTIN, self._signal_handler)
+        signal.signal(signal.SIGTTOU, self._signal_handler)
 
     def _signal_handler(self, sig, frame):
         """Handle signals."""
@@ -279,6 +299,36 @@ def _signal_handler(self, sig, frame):
                 )
             return
 
+        if sig == signal.SIGTTIN:
+            # Increase number of workers
+            self.num_workers += 1
+            self.log.info("SIGTTIN: Increasing dirty workers to %s",
+                          self.num_workers)
+            if self._loop:
+                self._loop.call_soon_threadsafe(
+                    lambda: asyncio.create_task(self.manage_workers())
+                )
+            return
+
+        if sig == signal.SIGTTOU:
+            # Decrease number of workers (respecting minimum)
+            min_workers = self._get_minimum_workers()
+            if self.num_workers <= min_workers:
+                self.log.warning(
+                    "SIGTTOU: Cannot decrease below %s workers "
+                    "(required by app specs)",
+                    min_workers
+                )
+                return
+            self.num_workers -= 1
+            self.log.info("SIGTTOU: Decreasing dirty workers to %s",
+                          self.num_workers)
+            if self._loop:
+                self._loop.call_soon_threadsafe(
+                    lambda: asyncio.create_task(self.manage_workers())
+                )
+            return
+
         # Shutdown signals
         self.alive = False
         if self._loop:
@@ -717,7 +767,7 @@ async def manage_workers(self):
         if not self.alive:
             return
 
-        num_workers = self.cfg.dirty_workers
+        num_workers = self.num_workers
 
         # Spawn workers if needed
         while self.alive and len(self.workers) < num_workers: