Add VGI_SIGNING_KEY and VGI_ENABLE_DESCRIBE env var support

VGI_SIGNING_KEY provides a shared signing key for state tokens in
multi-process deployments (suppresses random key warning).
VGI_ENABLE_DESCRIBE overrides --describe/--no-describe from the
environment (accepts 1/true/yes and 0/false/no). Both env vars work
in vgi-serve CLI and Worker.main()/main_http() paths.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: rustyconover

tests/test_serve.py

@@ -13,7 +13,7 @@
 import pytest
 
 from vgi.scalar_function import ScalarFunction
-from vgi.serve import create_app, load_worker_class
+from vgi.serve import _resolve_describe, _resolve_signing_key, create_app, load_worker_class
 from vgi.worker import Worker
 
 # ---------------------------------------------------------------------------
@@ -198,6 +198,64 @@ def test_describe_disabled(self) -> None:
 
         assert isinstance(app, falcon.App)
 
+    def test_signing_key_passed(self) -> None:
+        """Explicit signing_key is accepted without warning."""
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("error", UserWarning)
+            app = create_app(_SingleWorker, signing_key=b"test-secret-key-1234")
+
+        import falcon
+
+        assert isinstance(app, falcon.App)
+
+
+# ---------------------------------------------------------------------------
+# Tests: env var helpers
+# ---------------------------------------------------------------------------
+
+
+class TestResolveSigningKey:
+    """Tests for _resolve_signing_key()."""
+
+    def test_unset_returns_none(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """No env var returns None."""
+        monkeypatch.delenv("VGI_SIGNING_KEY", raising=False)
+        assert _resolve_signing_key() is None
+
+    def test_empty_returns_none(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Empty string returns None."""
+        monkeypatch.setenv("VGI_SIGNING_KEY", "")
+        assert _resolve_signing_key() is None
+
+    def test_value_returns_bytes(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Non-empty value returns UTF-8 encoded bytes."""
+        monkeypatch.setenv("VGI_SIGNING_KEY", "my-secret")
+        assert _resolve_signing_key() == b"my-secret"
+
+
+class TestResolveDescribe:
+    """Tests for _resolve_describe()."""
+
+    def test_unset_uses_cli(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """No env var passes through CLI value."""
+        monkeypatch.delenv("VGI_ENABLE_DESCRIBE", raising=False)
+        assert _resolve_describe(True) is True
+        assert _resolve_describe(False) is False
+
+    def test_env_true_overrides(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Truthy env values enable describe regardless of CLI."""
+        for val in ("1", "true", "yes", "True", "YES"):
+            monkeypatch.setenv("VGI_ENABLE_DESCRIBE", val)
+            assert _resolve_describe(False) is True
+
+    def test_env_false_overrides(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Falsy env values disable describe regardless of CLI."""
+        for val in ("0", "false", "no", "False", "NO"):
+            monkeypatch.setenv("VGI_ENABLE_DESCRIBE", val)
+            assert _resolve_describe(True) is False
+
 
 # ---------------------------------------------------------------------------
 # Tests: CLI integration
@@ -319,3 +377,77 @@ def test_auto_discover_module(self) -> None:
         finally:
             proc.terminate()
             proc.wait(timeout=5)
+
+    def test_describe_env_var_disables_worker_page(self) -> None:
+        """VGI_ENABLE_DESCRIBE=0 disables the worker description page."""
+        import urllib.error
+        import urllib.request
+
+        port = _free_port()
+        env = os.environ.copy()
+        env["VGI_ENABLE_DESCRIBE"] = "0"
+        proc = subprocess.Popen(
+            [
+                sys.executable,
+                "-m",
+                "vgi.serve",
+                "vgi.examples.worker:ExampleWorker",
+                "--http",
+                "--host",
+                "127.0.0.1",
+                "--port",
+                str(port),
+            ],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            env=env,
+        )
+        try:
+            assert proc.stdout is not None
+            port_line = proc.stdout.readline()
+            assert port_line.strip() == f"PORT:{port}"
+
+            time.sleep(0.5)
+
+            # Worker page should not be served (404 or 405, not 200)
+            url = f"http://127.0.0.1:{port}/vgi/worker"
+            with pytest.raises(urllib.error.HTTPError) as exc_info:
+                urllib.request.urlopen(url, timeout=5)
+            assert exc_info.value.code in (404, 405)
+        finally:
+            proc.terminate()
+            proc.wait(timeout=5)
+
+    def test_signing_key_env_var(self) -> None:
+        """VGI_SIGNING_KEY suppresses the random key warning."""
+        port = _free_port()
+        env = os.environ.copy()
+        env["VGI_SIGNING_KEY"] = "test-key-for-ci"
+        proc = subprocess.Popen(
+            [
+                sys.executable,
+                "-m",
+                "vgi.serve",
+                "vgi.examples.worker:ExampleWorker",
+                "--http",
+                "--host",
+                "127.0.0.1",
+                "--port",
+                str(port),
+            ],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            env=env,
+        )
+        try:
+            assert proc.stdout is not None
+            port_line = proc.stdout.readline()
+            assert port_line.strip() == f"PORT:{port}"
+        finally:
+            proc.terminate()
+            proc.wait(timeout=5)
+            assert proc.stderr is not None
+            stderr = proc.stderr.read()
+            assert "No signing_key provided" not in stderr

vgi/serve.py

@@ -154,6 +154,7 @@ def create_app(
     prefix: str = "/vgi",
     cors_origins: str = "*",
     describe: bool = True,
+    signing_key: bytes | None = None,
     log_level: int = logging.INFO,
 ) -> falcon.App[Any, Any]:
     """Create a WSGI app for a VGI worker.
@@ -166,6 +167,10 @@ def create_app(
         prefix: URL prefix for RPC endpoints.
         cors_origins: Allowed CORS origins.
         describe: Enable worker + API description pages.
+        signing_key: Shared signing key for state tokens.  When ``None``,
+            a random per-process key is generated (tokens are invalid
+            across workers).  Set via ``VGI_SIGNING_KEY`` env var or
+            pass explicitly for multi-process deployments.
         log_level: Logging level for the worker instance.
 
     Returns:
@@ -186,7 +191,7 @@ def create_app(
 
     worker = worker_cls(quiet=True, log_level=log_level)
     server = RpcServer(VgiProtocol, worker, enable_describe=describe)
-    wsgi_app = make_wsgi_app(server, prefix=prefix, cors_origins=cors_origins)
+    wsgi_app = make_wsgi_app(server, prefix=prefix, cors_origins=cors_origins, signing_key=signing_key)
 
     if describe:
         from vgi.http.worker_page import WorkerPageResource, build_worker_page
@@ -241,6 +246,10 @@ def serve(
             log_format=log_format,
         )
 
+        # Resolve env var overrides
+        describe = _resolve_describe(describe)
+        signing_key = _resolve_signing_key()
+
         worker_cls = load_worker_class(worker_ref)
 
         if http:
@@ -252,13 +261,38 @@ def serve(
                 prefix=prefix,
                 cors_origins=cors_origins,
                 describe=describe,
+                signing_key=signing_key,
             )
         else:
             worker_cls(quiet=quiet, log_level=effective_level).run()
 
     app()
 
 
+def _resolve_signing_key() -> bytes | None:
+    """Read ``VGI_SIGNING_KEY`` from the environment."""
+    raw = os.environ.get("VGI_SIGNING_KEY")
+    if raw:
+        return raw.encode()
+    return None
+
+
+def _resolve_describe(cli_value: bool) -> bool:
+    """Apply ``VGI_ENABLE_DESCRIBE`` env var override.
+
+    The env var only takes effect when it is explicitly set.  Accepts
+    ``1``/``true``/``yes`` (enable) and ``0``/``false``/``no`` (disable),
+    case-insensitive.  The CLI flag (``--describe`` / ``--no-describe``)
+    wins when Typer reports a non-default value, but since we cannot
+    distinguish "user passed --describe" from "default True", the env var
+    always overrides when present.
+    """
+    raw = os.environ.get("VGI_ENABLE_DESCRIBE")
+    if raw is None:
+        return cli_value
+    return raw.lower() in ("1", "true", "yes")
+
+
 def _serve_http(
     worker_cls: type[Worker],
     *,
@@ -268,6 +302,7 @@ def _serve_http(
     prefix: str,
     cors_origins: str,
     describe: bool,
+    signing_key: bytes | None,
 ) -> None:
     """Start the worker as an HTTP server."""
     import socket
@@ -295,6 +330,7 @@ def _serve_http(
         prefix=prefix,
         cors_origins=cors_origins,
         describe=describe,
+        signing_key=signing_key,
         log_level=effective_level,
     )
 

vgi/worker.py

@@ -547,13 +547,17 @@ def _run_http(
                 s.bind((host, 0))
                 port = int(s.getsockname()[1])
 
-        from vgi.serve import create_app
+        from vgi.serve import _resolve_describe, _resolve_signing_key, create_app
+
+        describe = _resolve_describe(describe)
+        signing_key = _resolve_signing_key()
 
         wsgi_app = create_app(
             cls,
             prefix=prefix,
             cors_origins=cors_origins,
             describe=describe,
+            signing_key=signing_key,
             log_level=effective_level,
         )