Merge branch 'release-1.11.0' into fix/admin-auth-pages-a11y

Author: erichare

.secrets.baseline

@@ -7034,23 +7034,23 @@
         "filename": "src/lfx/tests/unit/inputs/test_max_tokens_propagation.py",
         "hashed_secret": "665b1e3851eefefa3fb878654292f16597d25155",
         "is_verified": false,
-        "line_number": 121,
+        "line_number": 122,
         "is_secret": false
       },
       {
         "type": "Secret Keyword",
         "filename": "src/lfx/tests/unit/inputs/test_max_tokens_propagation.py",
         "hashed_secret": "e9b4dce312643ee0e1bd0561a50d9d5a7e5a2be1",
         "is_verified": false,
-        "line_number": 154,
+        "line_number": 155,
         "is_secret": false
       },
       {
         "type": "Secret Keyword",
         "filename": "src/lfx/tests/unit/inputs/test_max_tokens_propagation.py",
         "hashed_secret": "3f2df46921dd8e2c36e2ce85238705ac0774c74a",
         "is_verified": false,
-        "line_number": 234,
+        "line_number": 235,
         "is_secret": false
       }
     ],
@@ -7222,5 +7222,5 @@
       }
     ]
   },
-  "generated_at": "2026-07-13T20:51:12Z"
+  "generated_at": "2026-07-13T20:58:07Z"
 }

src/lfx/README.md

@@ -435,9 +435,13 @@ uv run lfx serve my-flow.json --upgrade-flow=safe
 | `--no-env-fallback` / `--env-fallback` | Disable process-environment fallback for credential resolution. Use with per-request `LANGFLOW_REQUEST_VARIABLES`. Default: `--env-fallback`. |
 | `--port`, `-p` | Port to bind the server to. Default: `8000`. |
 | `--stdin` | Read JSON flow content from `stdin`. Example: `cat flow.json | uv run lfx serve --stdin`. |
+| `--max-requests` | Recycle each worker after N requests to bound memory (gunicorn, Unix, `--workers > 1`). Default: every ~1000 (10% jitter); `0` disables; `1` = every request. Worker hygiene, **not** per-request isolation. Not applied on Windows. |
+| `--reset-environ` / `--no-reset-environ` | Snapshot/restore `os.environ` around each flow run so one request's env mutations or request-scoped credentials can't leak into the next on a warm worker. **A strict per-request isolation mechanism** (any worker, any platform). Default: `--no-reset-environ` (off). |
+| `--use-sync-workers` / `--use-async-workers` | Multi-worker only (`--workers > 1`, Unix). gunicorn's blocking `sync` worker serves one request at a time per worker, so the kernel routes each to an idle worker. With `--max-requests 1` it is **the other strict per-request isolation mechanism** (each request gets a fresh process). Uses the `a2wsgi` bridge, which ships with lfx on Unix. Default: `--use-async-workers`. |
+| `--timeout` | Worker timeout in seconds (gunicorn, Unix, `--workers > 1`): a worker that doesn't finish a request in this many seconds is killed and restarted. Raise it for long flows, especially with `--use-sync-workers`. Default: `120`. No effect on Windows. |
 | `--upgrade-flow` | Compatibility mode: `check` reports issues and fails, `safe` applies safe upgrades in memory. |
 | `--verbose`, `-v` | Show diagnostic output and execution details. |
-| `--workers`, `-w` | Number of uvicorn worker processes. Default: `1`. Use with `--flow-dir` for multi-worker flow sharing. |
+| `--workers`, `-w` | Number of worker processes. Use with `--flow-dir` for multi-worker flow sharing. Default: `1`. |
 
 ## Run the simple agent flow with `lfx run`
 

src/lfx/pyproject.toml

@@ -18,7 +18,12 @@ dependencies = [
     "pydantic>=2.0.0,<3.0.0",
     "pillow>=11.1.0,<13.0.0",
     "fastapi>=0.135.0,<1.0.0",
-    "uvicorn>=0.34.3,<1.0.0",
+    # [standard] adds uvloop + httptools (fast loop + HTTP parser) for the `lfx serve` worker path.
+    "uvicorn[standard]>=0.34.3,<1.0.0",
+    # gunicorn powers `lfx serve --workers N` on Unix; Windows falls back to uvicorn and rejects gunicorn-only flags.
+    "gunicorn>=22.0; sys_platform != 'win32'",
+    # a2wsgi bridges the ASGI app onto gunicorn's sync worker for `lfx serve --use-sync-workers` (Unix).
+    "a2wsgi>=1.10.0; sys_platform != 'win32'",
     "typer>=0.16.0,<1.0.0",
     "platformdirs>=4.3.8,<5.0.0",
     "aiofiles>=24.1.0,<25.0.0",

src/lfx/src/lfx/_assets/component_index.json

@@ -271,6 +271,11 @@ async def _get_all_variables():
         var_key = var_info.get("variable_key")
         if not var_key or db_values.get(var_key):
             continue
+        # Honor the request's no-env-fallback contract: a served flow under
+        # no_env_fallback must stay isolated from process-wide credentials even on
+        # this post-DB-miss rotation fallback.
+        if is_env_fallback_disabled():
+            continue
         env_value = _env_value_for(var_key)
         if env_value:
             db_values[var_key] = env_value

src/lfx/src/lfx/base/models/unified_models/credentials.py

@@ -2,6 +2,7 @@
 
 import typer
 
+from lfx.cli import _serve_help
 from lfx.upgrade.cli_gate import UpgradeFlowMode
 
 
@@ -126,7 +127,8 @@ def serve_command_wrapper(
             1,
             "--workers",
             "-w",
-            help="Number of uvicorn worker processes. Use with --flow-dir for multi-worker flow sharing.",
+            help="Number of worker processes (gunicorn on Unix, uvicorn on Windows). "
+            "Use with --flow-dir for multi-worker flow sharing.",
         ),
         verbose: bool = typer.Option(False, "--verbose", "-v", help="Show diagnostic output and execution details"),
         env_file: str | None = typer.Option(
@@ -147,12 +149,17 @@ def serve_command_wrapper(
         flow_dir: str | None = typer.Option(
             None,
             "--flow-dir",
-            help=(
-                "Directory for filesystem-backed flow storage. "
-                "All uvicorn workers sharing this path will serve the same flows. "
-                "Use /tmp/lfx-flows for single-pod sharing or a PVC mount for cross-pod. "
-                "Defaults to in-memory only when omitted."
-            ),
+            help=_serve_help.FLOW_DIR,
+        ),
+        max_requests: int | None = typer.Option(
+            None,
+            "--max-requests",
+            help=_serve_help.MAX_REQUESTS,
+        ),
+        timeout: int | None = typer.Option(
+            None,
+            "--timeout",
+            help=_serve_help.TIMEOUT,
         ),
         *,
         stdin: bool = typer.Option(
@@ -177,11 +184,17 @@ def serve_command_wrapper(
         no_env_fallback: bool = typer.Option(
             False,
             "--no-env-fallback/--env-fallback",
-            help=(
-                "Disable os.environ fallback for credential variables. "
-                "Variables not supplied via global_vars on each request resolve to None "
-                "instead of reading from the process environment."
-            ),
+            help=_serve_help.NO_ENV_FALLBACK,
+        ),
+        reset_environ: bool = typer.Option(
+            False,
+            "--reset-environ/--no-reset-environ",
+            help=_serve_help.RESET_ENVIRON,
+        ),
+        sync_workers: bool = typer.Option(
+            False,
+            "--use-sync-workers/--use-async-workers",
+            help=_serve_help.SYNC_WORKERS,
         ),
         identity_mode: str = typer.Option(
             "off",
@@ -251,6 +264,10 @@ def serve_command_wrapper(
             check_variables=check_variables,
             upgrade_flow=upgrade_flow,
             no_env_fallback=no_env_fallback,
+            max_requests=max_requests,
+            reset_environ=reset_environ,
+            sync_workers=sync_workers,
+            timeout=timeout,
             identity_mode=identity_mode,
             identity_jwt_issuer=identity_jwt_issuer,
             identity_jwt_audience=identity_jwt_audience,

src/lfx/src/lfx/cli/_running_commands.py

@@ -0,0 +1,51 @@
+"""Shared ``--help`` text for the multi-line ``lfx serve`` options.
+
+These options are declared twice — in the lazy CLI wrapper (``_running_commands``) and in
+the implementation ``commands.serve_command`` (which is also registered as a standalone
+typer command in tests). Defining the substantial help text once here keeps the two from
+drifting. Trivial one-line help (host, port, ...) stays inline at each call site.
+
+Kept dependency-free so importing it never defeats the wrapper's lazy import of the heavy
+``commands`` module.
+"""
+
+FLOW_DIR = (
+    "Directory for filesystem-backed flow storage. "
+    "All uvicorn workers sharing this path will serve the same flows. "
+    "Use /tmp/lfx-flows for single-pod sharing or a PVC mount for cross-pod. "
+    "Defaults to in-memory only when omitted."
+)
+
+MAX_REQUESTS = (
+    "Recycle each worker after N requests to bound memory (gunicorn, Unix, --workers > 1). "
+    "Default: recycle every ~1000 (10% jitter); 0 disables; 1 = every request. Not applied "
+    "on Windows. Worker hygiene, NOT per-request isolation — for that use --reset-environ, "
+    "or --use-sync-workers together with --max-requests 1 (a sync worker alone only prevents "
+    "in-worker overlap; a warm process still carries os.environ mutations to later requests)."
+)
+
+TIMEOUT = (
+    "Worker timeout in seconds (gunicorn, Unix, --workers > 1): a worker that does not "
+    "complete a request within this many seconds is killed and restarted. Raise it for "
+    "long-running flows, especially with --use-sync-workers (a blocking sync worker cannot "
+    "heartbeat mid-request). Default: 120. No effect on Windows (uvicorn fallback)."
+)
+
+NO_ENV_FALLBACK = (
+    "Disable os.environ fallback for credential variables. "
+    "Variables not supplied via global_vars on each request resolve to None "
+    "instead of reading from the process environment."
+)
+
+RESET_ENVIRON = (
+    "Snapshot os.environ before each flow run and restore it afterward, so a "
+    "flow's environment mutations (or request-scoped credentials) cannot leak "
+    "into the next request served by the same warm worker. Off by default."
+)
+
+SYNC_WORKERS = (
+    "Use gunicorn's blocking 'sync' worker (Unix, --workers > 1) so the kernel "
+    "routes each request to an idle worker instead of queueing it behind an "
+    "in-flight request on a busy async worker. Uses the 'a2wsgi' bridge bundled "
+    "with lfx on Unix. Off by default (async worker)."
+)