Enhancement: add host-all serve alias and document binding options

- Add pypnm serve --host-all as a convenience alias for 0.0.0.0
- Keep --host available for explicit interface and address binding
- Resolve the effective bind host consistently in serve output and uvicorn launch
- Add CLI coverage for host-all parsing and runtime binding behavior
- Update README and user docs to explain all-interface and single-interface binding - 2026-04-18 18:52:48

Author: mgarcia01752

README.md

@@ -206,6 +206,18 @@ HTTP (default: `http://127.0.0.1:8000`):
   pypnm serve
   ```
 
+Expose PyPNM on all IPv4 interfaces assigned to the host:
+
+  ```bash
+  pypnm serve --host-all
+  ```
+
+Bind to one specific interface or address:
+
+  ```bash
+  pypnm serve --host 192.168.1.20
+  ```
+
 Development hot-reload:
 
   ```bash

docs/system/pypnm-cli.md

@@ -28,6 +28,7 @@ Starts the FastAPI service (`pypnm.api.main:app`) through Uvicorn.
 Common options:
 
 - `--host` (default `127.0.0.1`)
+- `--host-all` (bind to `0.0.0.0`)
 - `--port` (default `8000`)
 - `--ssl`, `--cert`, `--key`
 - `--log-level {critical,error,warning,info,debug,trace}`
@@ -48,7 +49,7 @@ Examples:
 
 ```bash
 pypnm serve
-pypnm serve --host 0.0.0.0 --port 8080
+pypnm serve --host-all --port 8080
 pypnm serve --reload
 pypnm serve --workers 4 --limit-max-requests 2000
 pypnm serve --run-background
@@ -60,6 +61,8 @@ pypnm serve --mute-tags "Orchestrator,Operational" --mute-tags-hard
 
 Notes:
 
+- `--host-all` is a convenience alias for binding on all IPv4 interfaces assigned to the host.
+- Use `--host <ip-or-name>` when you want to bind to one specific interface or address.
 - When `--reload` is enabled, `--workers` is forced to `1`.
 - `--run-background` detaches the service, writes a pidfile, and redirects stdout/stderr to a log file.
 - `--run-background` cannot be used with `--reload`.
@@ -98,5 +101,5 @@ New:
 
 ```bash
 pypnm serve --reload
-pypnm serve --host 0.0.0.0 --port 8000
+pypnm serve --host-all --port 8000
 ```

docs/system/worker-sizing.md

@@ -92,13 +92,13 @@ Suggested memory guardrails:
 
 ```bash
 # Small node
-pypnm serve --host 0.0.0.0 --port 8000 --workers 1 --limit-max-requests 1000
+pypnm serve --host-all --port 8000 --workers 1 --limit-max-requests 1000
 
 # Standard production node
-pypnm serve --host 0.0.0.0 --port 8000 --workers 4 --limit-max-requests 2000
+pypnm serve --host-all --port 8000 --workers 4 --limit-max-requests 2000
 
 # Higher-capacity node with proven concurrency need
-pypnm serve --host 0.0.0.0 --port 8000 --workers 6 --limit-max-requests 2000
+pypnm serve --host-all --port 8000 --workers 6 --limit-max-requests 2000
 ```
 
 ## Practical Guidance

pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name            = "pypnm-docsis"
-version         = "1.6.3.1"
+version         = "1.6.3.2"
 description     = "DOCSIS 3.x/4.0 Proactive Network Maintenance Toolkit"
 readme          = "README.md"
 requires-python = ">=3.10"

src/pypnm/cli.py

@@ -41,6 +41,7 @@
 DEFAULT_WORKERS = 1
 TIMEOUT_KEEP_ALIVE_SECONDS = 120
 DEFAULT_LIMIT_MAX_REQUESTS = 0
+ALL_INTERFACES_HOST = "0.0.0.0"
 
 
 def _runtime_profile_selection_message(workers: int, limit_max_requests: int) -> str:
@@ -115,6 +116,10 @@ def _sanitize_pythonpath_for_serve() -> None:
     os.environ["PYTHONPATH"] = src_path
 
 
+def _resolve_bind_host(args: argparse.Namespace) -> str:
+    return ALL_INTERFACES_HOST if bool(getattr(args, "host_all", False)) else str(args.host)
+
+
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         description="PyPNM CLI for service startup and system configuration.",
@@ -140,7 +145,13 @@ def _build_parser() -> argparse.ArgumentParser:
     subparsers = parser.add_subparsers(dest="command")
 
     serve_parser = subparsers.add_parser("serve", help="Start the FastAPI service (Uvicorn).")
-    serve_parser.add_argument("--host", default=HOST_DEFAULT, help=f"Host to bind (default: {HOST_DEFAULT})")
+    host_group = serve_parser.add_mutually_exclusive_group()
+    host_group.add_argument("--host", default=HOST_DEFAULT, help=f"Host to bind (default: {HOST_DEFAULT})")
+    host_group.add_argument(
+        "--host-all",
+        action="store_true",
+        help=f"Bind on all IPv4 interfaces ({ALL_INTERFACES_HOST}).",
+    )
     serve_parser.add_argument("--port", default=PORT_DEFAULT, type=int, help=f"Port to bind (default: {PORT_DEFAULT})")
     serve_parser.add_argument("--ssl", action="store_true", help="Enable HTTPS (requires cert and key).")
     serve_parser.add_argument("--cert", default="./certs/cert.pem", help="Path to SSL certificate (PEM).")
@@ -230,6 +241,7 @@ def _build_parser() -> argparse.ArgumentParser:
 
 
 def _run_serve(args: argparse.Namespace) -> int:
+    bind_host = _resolve_bind_host(args)
     run_background = bool(getattr(args, "run_background", False))
     background_log_file = str(getattr(args, "background_log_file", "")).strip()
     background_pidfile = str(getattr(args, "background_pidfile", "")).strip()
@@ -239,9 +251,9 @@ def _run_serve(args: argparse.Namespace) -> int:
         return EXIT_CODE_USAGE
 
     if args.ssl:
-        print(f"🔒 Launching FastAPI with HTTPS on https://{args.host}:{args.port}")
+        print(f"🔒 Launching FastAPI with HTTPS on https://{bind_host}:{args.port}")
     else:
-        print(f"🌐 Launching FastAPI with HTTP on http://{args.host}:{args.port}")
+        print(f"🌐 Launching FastAPI with HTTP on http://{bind_host}:{args.port}")
 
     _sanitize_pythonpath_for_serve()
 
@@ -269,7 +281,7 @@ def _run_serve(args: argparse.Namespace) -> int:
 
     uvicorn_args = {
         "app": "pypnm.api.main:app",
-        "host": args.host,
+        "host": bind_host,
         "port": args.port,
         "timeout_keep_alive": TIMEOUT_KEEP_ALIVE_SECONDS,
         "log_level": args.log_level,

src/pypnm/version.py

@@ -6,4 +6,4 @@
 __all__ = ["__version__"]
 
 # MAJOR.MINOR.MAINTENANCE.BUILD
-__version__: str = "1.6.3.1"
+__version__: str = "1.6.3.2"

tests/test_cli.py

@@ -15,6 +15,7 @@
 def _serve_args(**overrides: object) -> Namespace:
     base = {
         "host": "127.0.0.1",
+        "host_all": False,
         "port": 8000,
         "ssl": False,
         "cert": "./certs/cert.pem",
@@ -58,6 +59,38 @@ def fake_uvicorn_run(**kwargs: object) -> None:
     assert recorded["workers"] == 2
 
 
+def test_run_serve_host_all_binds_all_ipv4_interfaces(monkeypatch, capsys) -> None:
+    recorded: dict[str, object] = {}
+
+    def fake_uvicorn_run(**kwargs: object) -> None:
+        recorded.update(kwargs)
+
+    monkeypatch.setattr(cli, "_sanitize_pythonpath_for_serve", lambda: None)
+    monkeypatch.setattr(cli.uvicorn, "run", fake_uvicorn_run)
+    monkeypatch.setattr(
+        cli,
+        "detect_worker_profile",
+        lambda: cli.WorkerProfile(cpu_count=4, total_memory_gib=16.0, workers=2, limit_max_requests=1000),
+    )
+
+    exit_code = cli._run_serve(_serve_args(host_all=True))
+    captured = capsys.readouterr()
+
+    assert exit_code == cli.SUCCESS_EXIT_CODE
+    assert recorded["host"] == cli.ALL_INTERFACES_HOST
+    assert f"http://{cli.ALL_INTERFACES_HOST}:8000" in captured.out
+
+
+def test_build_parser_host_all_sets_all_interfaces_host() -> None:
+    parser = cli._build_parser()
+
+    args = parser.parse_args(["serve", "--host-all"])
+
+    assert args.command == "serve"
+    assert args.host_all is True
+    assert cli._resolve_bind_host(args) == cli.ALL_INTERFACES_HOST
+
+
 def test_run_serve_rejects_negative_limit_max_requests(monkeypatch) -> None:
     uvicorn_called = False