Remove SyncWorker, make ThreadWorker the only worker type

ThreadWorker with threads=1 behaves nearly identically to SyncWorker,
so there's no need for two worker implementations. This also updates
the CLI defaults to --workers auto --threads 4 and validates that
threads >= 1.

Author: davegaeddert

plain-dev/plain/dev/core.py

@@ -338,6 +338,8 @@ def add_server(self) -> None:
             "'[%(levelname)s] %(message)s'",
             "--access-log-format",
             "'\"%(r)s\" status=%(s)s length=%(b)s time=%(M)sms'",
+            "--workers",
+            "1",
             "--reload",  # Enable auto-reload for development
         ]
 

plain/plain/cli/server.py

@@ -23,16 +23,16 @@ def parse_workers(ctx: click.Context, param: click.Parameter, value: str) -> int
 )
 @click.option(
     "--threads",
-    type=int,
-    default=1,
+    type=click.IntRange(min=1),
+    default=4,
     help="Number of threads per worker",
     show_default=True,
 )
 @click.option(
     "--workers",
     "-w",
     type=str,
-    default="1",
+    default="auto",
     envvar="WEB_CONCURRENCY",
     callback=parse_workers,
     help="Number of worker processes (or 'auto' for CPU count)",

plain/plain/server/README.md

@@ -3,7 +3,7 @@
 **A production-ready WSGI HTTP server based on gunicorn.**
 
 - [Overview](#overview)
-- [Worker types](#worker-types)
+- [Workers and threads](#workers-and-threads)
 - [Configuration options](#configuration-options)
 - [Environment variables](#environment-variables)
 - [Signals](#signals)
@@ -19,44 +19,37 @@ You can run the built-in HTTP server with the `plain server` command.
 plain server
 ```
 
-By default, the server binds to `127.0.0.1:8000` and uses a single worker process. In production, you will typically want to increase the number of workers and optionally enable threading.
-
-```bash
-# Run with 4 worker processes
-plain server --workers 4
-
-# Auto-detect based on available CPUs
-plain server --workers auto
-
-# Run with 2 workers and 4 threads each
-plain server --workers 2 --threads 4
-```
+By default, the server binds to `127.0.0.1:8000` with one worker process per CPU core and 4 threads per worker.
 
 For local development, you can enable auto-reload to restart workers when code changes.
 
 ```bash
 plain server --reload
 ```
 
-## Worker types
+## Workers and threads
 
-The server automatically selects the worker type based on your configuration.
+The server uses two levels of concurrency:
 
-**Sync workers** handle one request at a time per worker. These are simple and predictable.
+- **Workers** are separate OS processes. Each worker runs independently with its own memory. The default is `auto`, which spawns one worker per CPU core.
+- **Threads** run inside each worker. Threads share memory within a worker and handle concurrent requests using a thread pool. The default is 4 threads per worker.
 
-```bash
-# Single-threaded (uses sync worker)
-plain server --workers 4
-```
+Total concurrent requests = `workers × threads`. On a 4-core machine with the defaults, that's `4 × 4 = 16` concurrent requests.
+
+**When to adjust workers:** Workers provide true parallelism since each is a separate process with its own Python GIL. More workers means more memory usage but better CPU utilization. Use `--workers auto` (the default) to match your CPU cores, or set an explicit number.
 
-**Threaded workers** handle multiple concurrent requests per worker using a thread pool. These are useful when your application does blocking I/O.
+**When to adjust threads:** Threads are efficient for I/O-bound work (database queries, external API calls) since they release the GIL while waiting. Most web applications are I/O-bound, so the default of 4 threads works well. Increase threads if your application spends a lot of time waiting on I/O. Decrease to 1 if you need to avoid thread-safety concerns.
 
 ```bash
-# Multi-threaded (uses threaded worker)
-plain server --workers 2 --threads 8
-```
+# Explicit worker count
+plain server --workers 2
 
-For advanced worker customization, see the [`SyncWorker`](./workers/sync.py#SyncWorker) and [`ThreadWorker`](./workers/thread.py#ThreadWorker) classes.
+# More threads for I/O-heavy apps
+plain server --threads 8
+
+# Single-threaded workers (simplest, one request at a time per worker)
+plain server --threads 1
+```
 
 ## Configuration options
 
@@ -65,8 +58,8 @@ All options are available via the command line. Run `plain server --help` to see
 | Option             | Default          | Description                                           |
 | ------------------ | ---------------- | ----------------------------------------------------- |
 | `--bind` / `-b`    | `127.0.0.1:8000` | Address to bind (can be used multiple times)          |
-| `--workers` / `-w` | `1`              | Number of worker processes (or `auto` for CPU count)  |
-| `--threads`        | `1`              | Number of threads per worker                          |
+| `--workers` / `-w` | `auto`           | Number of worker processes (or `auto` for CPU count)  |
+| `--threads`        | `4`              | Number of threads per worker                          |
 | `--timeout` / `-t` | `30`             | Worker timeout in seconds                             |
 | `--reload`         | `False`          | Restart workers when code changes                     |
 | `--certfile`       | -                | Path to SSL certificate file                          |

plain/plain/server/arbiter.py

@@ -22,12 +22,12 @@
 from . import sock, util
 from .errors import AppImportError, HaltServer
 from .pidfile import Pidfile
+from .workers.thread import ThreadWorker
 
 if TYPE_CHECKING:
     from .app import ServerApplication
     from .config import Config
     from .glogging import Logger
-    from .workers.base import Worker
 
 
 class Arbiter:
@@ -48,7 +48,7 @@ class Arbiter:
     START_CTX: dict[int | str, Any] = {}
 
     LISTENERS: list[sock.BaseSocket] = []
-    WORKERS: dict[int, Worker] = {}
+    WORKERS: dict[int, ThreadWorker] = {}
     PIPE: list[int] = []
 
     # I love dynamic languages
@@ -101,7 +101,6 @@ def setup(self, app: ServerApplication) -> None:
 
             self.log: Logger = Logger(self.cfg)
 
-        self.worker_class: type[Worker] = self.cfg.worker_class
         self.address: str = self.cfg.address
         self.num_workers = self.cfg.workers
         self.timeout: int = self.cfg.timeout
@@ -122,16 +121,13 @@ def start(self) -> None:
 
         listeners_str = ",".join([str(lnr) for lnr in self.LISTENERS])
         self.log.info(
-            "Plain server started address=%s pid=%s worker=%s version=%s",
+            "Plain server started address=%s pid=%s version=%s",
             listeners_str,
             self.pid,
-            self.cfg.worker_class_str,
             plain.runtime.__version__,
         )
 
-        # check worker class requirements
-        if check_config := getattr(self.worker_class, "check_config", None):
-            check_config(self.cfg, self.log)
+        ThreadWorker.check_config(self.cfg, self.log)
 
     def init_signals(self) -> None:
         """\
@@ -468,7 +464,7 @@ def manage_workers(self) -> None:
 
     def spawn_worker(self) -> int:
         self.worker_age += 1
-        worker = self.worker_class(
+        worker = ThreadWorker(
             self.worker_age,
             self.pid,
             self.LISTENERS,

plain/plain/server/config.py

@@ -10,8 +10,6 @@
 from dataclasses import dataclass
 
 from . import util
-from .workers.sync import SyncWorker
-from .workers.thread import ThreadWorker
 
 
 @dataclass
@@ -38,25 +36,6 @@ class Config:
     log_format: str
     access_log_format: str
 
-    @property
-    def worker_class_str(self) -> str:
-        # Auto-select based on threads
-        if self.threads > 1:
-            return "thread"
-        return "sync"
-
-    @property
-    def worker_class(self) -> type:
-        # Auto-select based on threads
-        if self.threads > 1:
-            worker_class = ThreadWorker
-        else:
-            worker_class = SyncWorker
-
-        if hasattr(worker_class, "setup"):
-            worker_class.setup()
-        return worker_class
-
     @property
     def address(self) -> list[tuple[str, int] | str]:
         return [util.parse_address(util.bytes_to_str(bind)) for bind in self.bind]