prefect 3.6.22.dev6__tar.gz → 3.6.22.dev7__tar.gz

{prefect-3.6.22.dev6 → prefect-3.6.22.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect
-Version: 3.6.22.dev6
+Version: 3.6.22.dev7
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io

{prefect-3.6.22.dev6 → prefect-3.6.22.dev7}/src/prefect/AGENTS.md

@@ -42,3 +42,4 @@ Use `get_logger()` from `prefect.logging` instead of raw `logging.getLogger()`
 - `cli/` → Command-line interface (see cli/AGENTS.md)
 - `events/` → Event system and automations (see events/AGENTS.md)
 - `settings/` → Configuration system (see settings/AGENTS.md)
+- `concurrency/` → Concurrency slot acquisition and lease management (see concurrency/AGENTS.md)

prefect-3.6.22.dev7/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.6.22.dev7"
+__build_date__ = "2026-03-11 08:18:23.933159+00:00"
+__git_commit__ = "a072125a2f8aabd63d7d4763cde190aa69117451"
+__dirty__ = False

{prefect-3.6.22.dev6 → prefect-3.6.22.dev7}/src/prefect/client/AGENTS.md

@@ -18,6 +18,7 @@ HTTP client for communicating with Prefect server and Prefect Cloud.
 - `schemas/` — Client-side Pydantic models (actions, filters, objects, responses, schedules, sorting)
 - `cloud.py` — Prefect Cloud-specific extensions (workspaces, RBAC)
 - `subscriptions.py` — WebSocket subscription client
+- `_version_checking.py` — Shared server version compatibility check (once-per-process, keyed by `(api_url, client_version)`). Used by HTTP clients and WebSocket clients (`events/clients.py`, `logging/clients.py`). When adding a new client type that connects to the server, call `check_server_version` from here rather than reimplementing the check.
 
 ## Related
 

prefect-3.6.22.dev7/src/prefect/client/_version_checking.py

@@ -0,0 +1,192 @@
+"""Shared server version checking logic for Prefect clients.
+
+This module contains the version compatibility check cache and a standalone
+async helper so that both HTTP-based clients (PrefectClient / SyncPrefectClient)
+and WebSocket-based clients (PrefectEventsClient, PrefectEventSubscriber,
+PrefectLogsSubscriber) can share the same once-per-process guard.
+"""
+
+import base64
+import logging
+import ssl
+import threading
+from urllib.parse import urlparse, urlunparse
+
+import certifi
+import httpx
+from packaging import version
+
+import prefect
+from prefect.settings import (
+    PREFECT_API_AUTH_STRING,
+    PREFECT_API_KEY,
+    PREFECT_API_SSL_CERT_FILE,
+    PREFECT_API_TLS_INSECURE_SKIP_VERIFY,
+    get_current_settings,
+)
+
+# ---------------------------------------------------------------------------
+# Cache – keyed by (api_url, client_version) so each unique pair is checked
+# at most once per process.
+# ---------------------------------------------------------------------------
+_API_VERSION_CHECK_CACHE: set[tuple[str, str]] = set()
+_API_VERSION_CHECK_CACHE_LOCK = threading.Lock()
+
+
+def _api_version_check_key(api_url: str, client_version: str) -> tuple[str, str]:
+    return (api_url, client_version)
+
+
+def _is_api_version_check_cached(key: tuple[str, str]) -> bool:
+    with _API_VERSION_CHECK_CACHE_LOCK:
+        return key in _API_VERSION_CHECK_CACHE
+
+
+def _cache_api_version_check(key: tuple[str, str]) -> None:
+    with _API_VERSION_CHECK_CACHE_LOCK:
+        _API_VERSION_CHECK_CACHE.add(key)
+
+
+def _clear_api_version_check_cache() -> None:
+    """Clear cached API version compatibility checks (for tests)."""
+    with _API_VERSION_CHECK_CACHE_LOCK:
+        _API_VERSION_CHECK_CACHE.clear()
+
+
+def _sanitize_url(url: str) -> str:
+    """Return *url* with any embedded userinfo (user:password@) removed.
+
+    The URL is always reconstructed from its parsed components so that
+    static-analysis tools (e.g. CodeQL) no longer consider the return
+    value tainted.
+    """
+    parsed = urlparse(url)
+    host = parsed.hostname or ""
+    port_part = f":{parsed.port}" if parsed.port else ""
+    sanitized = parsed._replace(netloc=f"{host}{port_part}")
+    return urlunparse(sanitized)
+
+
+# ---------------------------------------------------------------------------
+# Standalone async check – usable by any client that knows its *api_url*.
+# ---------------------------------------------------------------------------
+
+
+async def check_server_version(
+    api_url: str,
+    logger: logging.Logger,
+    *,
+    raise_on_error: bool = True,
+) -> None:
+    """Perform a one-shot server version compatibility check.
+
+    The check is skipped when:
+    * The ``server_version_check_enabled`` setting is ``False``.
+    * The *api_url* points at Prefect Cloud (Cloud is always compatible).
+    * A check for this *(api_url, client_version)* pair has already passed.
+
+    On a major-version mismatch a ``RuntimeError`` is raised (regardless of
+    *raise_on_error*).  When the server is simply older than the client a
+    warning is logged.
+
+    Args:
+        api_url: The base Prefect API URL (e.g. ``http://localhost:4200/api``).
+        logger: Logger used for warnings and debug messages.
+        raise_on_error: When ``True`` (the default, used by HTTP clients),
+            raise ``RuntimeError`` if the version endpoint cannot be reached.
+            When ``False`` (used by WebSocket clients), log a debug message
+            and return silently so that the caller can still attempt its
+            connection.
+    """
+    settings = get_current_settings()
+
+    if not settings.client.server_version_check_enabled:
+        return
+
+    # Cloud is always compatible as a server
+    cloud_api_url = str(settings.cloud.api_url)
+    if api_url.startswith(cloud_api_url):
+        return
+
+    client_version = prefect.__version__
+    key = _api_version_check_key(api_url, client_version)
+    if _is_api_version_check_cached(key):
+        return
+
+    # Build TLS and auth settings to match PrefectClient behaviour so that
+    # the version check works on secured self-hosted deployments.
+    httpx_kwargs: dict[str, object] = {}
+
+    if PREFECT_API_TLS_INSECURE_SKIP_VERIFY:
+        ctx = ssl.create_default_context()
+        ctx.check_hostname = False
+        ctx.verify_mode = ssl.CERT_NONE
+        httpx_kwargs["verify"] = ctx
+    else:
+        cert_file = PREFECT_API_SSL_CERT_FILE.value()
+        if not cert_file:
+            cert_file = certifi.where()
+        ctx = ssl.create_default_context(cafile=cert_file)
+        httpx_kwargs["verify"] = ctx
+
+    headers: dict[str, str] = {}
+    auth_string = PREFECT_API_AUTH_STRING.value()
+    api_key = PREFECT_API_KEY.value()
+    if auth_string:
+        token = base64.b64encode(auth_string.encode("utf-8")).decode("utf-8")
+        headers["Authorization"] = f"Basic {token}"
+    elif api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    if headers:
+        httpx_kwargs["headers"] = headers
+
+    try:
+        async with httpx.AsyncClient(**httpx_kwargs) as http_client:  # type: ignore[arg-type]
+            response = await http_client.get(f"{api_url}/admin/version")
+            response.raise_for_status()
+            api_version_str: str = response.json()
+    except Exception as e:
+        if "Unauthorized" in str(e):
+            raise
+        if raise_on_error:
+            raise RuntimeError(
+                f"Failed to reach API at {_sanitize_url(api_url)}"
+            ) from e
+        logger.debug(
+            "Unable to check server version at %s: %s",
+            _sanitize_url(api_url),
+            e,
+        )
+        return
+
+    try:
+        api_ver = version.parse(api_version_str)
+    except version.InvalidVersion:
+        if raise_on_error:
+            raise
+        logger.debug(
+            "Unable to parse server version %r at %s",
+            api_version_str,
+            _sanitize_url(api_url),
+        )
+        return
+
+    client_ver = version.parse(client_version)
+
+    if api_ver.major != client_ver.major:
+        raise RuntimeError(
+            f"Found incompatible versions: client: {client_ver}, server: {api_ver}. "
+            "Major versions must match."
+        )
+
+    if api_ver < client_ver:
+        logger.warning(
+            "Your Prefect server is running an older version of Prefect "
+            "than your client which may result in unexpected behavior. "
+            "Please upgrade your Prefect server from version %s to "
+            "version %s or higher.",
+            api_ver,
+            client_ver,
+        )
+
+    _cache_api_version_check(key)

{prefect-3.6.22.dev6 → prefect-3.6.22.dev7}/src/prefect/client/orchestration/__init__.py

@@ -3,7 +3,6 @@ import asyncio
 import base64
 import datetime
 import ssl
-import threading
 from collections.abc import Iterable
 from contextlib import AsyncExitStack
 from logging import Logger
@@ -136,6 +135,13 @@ from prefect.settings import (
 )
 from prefect.types._datetime import now
 
+from prefect.client._version_checking import (
+    _api_version_check_key,
+    _cache_api_version_check,
+    _clear_api_version_check_cache,
+    _is_api_version_check_cached,
+)
+
 if TYPE_CHECKING:
     from prefect.tasks import Task as TaskObject
 
@@ -154,11 +160,6 @@ T = TypeVar("T")
 # Cache for TypeAdapter instances to avoid repeated instantiation
 _TYPE_ADAPTER_CACHE: dict[type, pydantic.TypeAdapter[Any]] = {}
 
-# Cache keys for API version compatibility checks that have already passed.
-# Keyed by (api_url, client_version).
-_API_VERSION_CHECK_CACHE: set[tuple[str, str]] = set()
-_API_VERSION_CHECK_CACHE_LOCK = threading.Lock()
-
 
 def _get_type_adapter(type_: type) -> pydantic.TypeAdapter[Any]:
     """Get or create a cached TypeAdapter for the given type."""
@@ -167,26 +168,6 @@ def _get_type_adapter(type_: type) -> pydantic.TypeAdapter[Any]:
     return _TYPE_ADAPTER_CACHE[type_]
 
 
-def _api_version_check_key(api_url: str, client_version: str) -> tuple[str, str]:
-    return (api_url, client_version)
-
-
-def _is_api_version_check_cached(key: tuple[str, str]) -> bool:
-    with _API_VERSION_CHECK_CACHE_LOCK:
-        return key in _API_VERSION_CHECK_CACHE
-
-
-def _cache_api_version_check(key: tuple[str, str]) -> None:
-    with _API_VERSION_CHECK_CACHE_LOCK:
-        _API_VERSION_CHECK_CACHE.add(key)
-
-
-def _clear_api_version_check_cache() -> None:
-    """Clear cached API version compatibility checks (for tests)."""
-    with _API_VERSION_CHECK_CACHE_LOCK:
-        _API_VERSION_CHECK_CACHE.clear()
-
-
 @overload
 def get_client(
     httpx_settings: Optional[dict[str, Any]],

prefect-3.6.22.dev7/src/prefect/concurrency/AGENTS.md

@@ -0,0 +1,42 @@
+# Concurrency
+
+Client-side concurrency limit enforcement: acquires and releases slots against server-defined limits, maintains leases during execution, and tracks events for traceability.
+
+## Purpose & Scope
+
+Manages concurrency slot acquisition/release for flows and tasks enforcing named concurrency limits. Handles the full lifecycle: acquire → maintain lease → release, with both sync and async paths.
+
+Does NOT define concurrency limits (server-side in `server/`). Does NOT handle task runner parallelism (separate concern).
+
+## Entry Points & Contracts
+
+**Public API** (`asyncio.py`, `sync.py`):
+- `concurrency()` — context manager that acquires slots on entry and releases on exit
+- `rate_limit()` — one-shot acquire for decay-based limits (no release needed)
+
+**`strict=False` (default):** logs a warning if the named limit doesn't exist, but proceeds. `strict=True` raises `ConcurrencySlotAcquisitionError`.
+
+**Lease renewal:** `_leases.py` runs a background loop that renews immediately on entry, then sleeps for 75% of `lease_duration` between renewals. Each renewal call uses `@retry_async_fn(max_attempts=3)` for transient failures. If all 3 attempts fail, the background task raises and a done-callback either cancels execution (`raise_on_lease_renewal_failure=True`) or logs a warning.
+
+**Sync/async lockstep invariant:** `asyncio.py`/`sync.py` and `_asyncio.py`/`_sync.py` are parallel implementations. Any behavior change to one must be mirrored in the other.
+
+## Architecture
+
+Layered — public → internal → services, with leases and events as cross-cutting concerns:
+
+- **Public** (`asyncio.py`, `sync.py`) — user-facing context managers; `rate_limit()` emits events directly
+- **Internal** (`_asyncio.py`, `_sync.py`) — orchestrates acquire → lease → release, emits events for `concurrency()`, handles cancellation cleanup via `ConcurrencyContext`
+- **Services** (`services.py`) — serializes API requests per `frozenset(names)` to prevent thundering herd; retries on HTTP 423 with `Retry-After` backoff
+
+## Anti-Patterns
+
+- **Don't call internal `_asyncio`/`_sync` functions directly** — use the public `asyncio.py`/`sync.py` APIs. The internal modules skip event emission setup.
+- **Don't mix sync `concurrency()` in async code** — use `asyncio.concurrency()` to avoid blocking the event loop.
+- **Don't rely on strict=False for correctness** — in tests or scripts where the limit must exist, use `strict=True` so you catch misconfigurations early.
+
+## Pitfalls
+
+- **Service singleton is keyed on `frozenset(names)`.** Passing the same names in different order reuses the same singleton; passing a strict subset creates a different singleton. Each unique name-set gets its own queue.
+- **Lease renewal runs on the global event loop** (sync path). If the global loop is blocked or torn down, renewal silently fails — you'll see the renewal failure callback fire after `max_attempts` retries are exhausted.
+- **Cancellation during acquire** — lease IDs for mid-acquisition slots land in `ConcurrencyContext.cleanup_lease_ids`. `ConcurrencyContext.__exit__` releases them via a sync client. If `ConcurrencyContext` is not active, those leases are abandoned until server-side expiry.
+- **`v1/` subdirectory** contains the legacy slot API (no lease model). New code should use the top-level `concurrency()` / `rate_limit()` APIs.

{prefect-3.6.22.dev6 → prefect-3.6.22.dev7}/src/prefect/concurrency/_leases.py

@@ -10,6 +10,7 @@ from prefect._internal.concurrency.cancellation import (
     WatcherThreadCancelScope,
 )
 from prefect._internal.concurrency.threads import get_global_loop
+from prefect._internal.retries import retry_async_fn
 from prefect.client.orchestration import get_client
 from prefect.logging.loggers import get_logger, get_run_logger
 
@@ -26,10 +27,15 @@ async def _lease_renewal_loop(
         lease_duration: The duration of the lease in seconds.
     """
     async with get_client() as client:
-        while True:
+
+        @retry_async_fn(max_attempts=3, operation_name="concurrency lease renewal")
+        async def renew() -> None:
             await client.renew_concurrency_lease(
                 lease_id=lease_id, lease_duration=lease_duration
             )
+
+        while True:
+            await renew()
             await asyncio.sleep(  # Renew the lease 3/4 of the way through the lease duration
                 lease_duration * 0.75
             )
@@ -73,17 +79,20 @@ def maintain_concurrency_lease(
                     logger = get_logger("concurrency")
                 if raise_on_lease_renewal_failure:
                     logger.error(
-                        "Concurrency lease renewal failed - slots are no longer reserved. Terminating execution to prevent over-allocation."
+                        "Concurrency lease renewal failed - slots are no longer reserved. Terminating execution to prevent over-allocation.",
+                        exc_info=(type(exc), exc, exc.__traceback__),
                     )
                     assert cancel_scope.cancel()
                 else:
                     if suppress_warnings:
                         logger.debug(
-                            "Concurrency lease renewal failed - slots are no longer reserved. Execution will continue, but concurrency limits may be exceeded."
+                            "Concurrency lease renewal failed - slots are no longer reserved. Execution will continue, but concurrency limits may be exceeded.",
+                            exc_info=(type(exc), exc, exc.__traceback__),
                         )
                     else:
                         logger.warning(
-                            "Concurrency lease renewal failed - slots are no longer reserved. Execution will continue, but concurrency limits may be exceeded."
+                            "Concurrency lease renewal failed - slots are no longer reserved. Execution will continue, but concurrency limits may be exceeded.",
+                            exc_info=(type(exc), exc, exc.__traceback__),
                         )
 
         lease_renewal_call.future.add_done_callback(handle_lease_renewal_failure)
@@ -128,17 +137,20 @@ async def amaintain_concurrency_lease(
                     logger = get_logger("concurrency")
                 if raise_on_lease_renewal_failure:
                     logger.error(
-                        "Concurrency lease renewal failed - slots are no longer reserved. Terminating execution to prevent over-allocation."
+                        "Concurrency lease renewal failed - slots are no longer reserved. Terminating execution to prevent over-allocation.",
+                        exc_info=(type(exc), exc, exc.__traceback__),
                     )
                     cancel_scope.cancel()
                 else:
                     if suppress_warnings:
                         logger.debug(
-                            "Concurrency lease renewal failed - slots are no longer reserved. Execution will continue, but concurrency limits may be exceeded."
+                            "Concurrency lease renewal failed - slots are no longer reserved. Execution will continue, but concurrency limits may be exceeded.",
+                            exc_info=(type(exc), exc, exc.__traceback__),
                         )
                     else:
                         logger.warning(
-                            "Concurrency lease renewal failed - slots are no longer reserved. Execution will continue, but concurrency limits may be exceeded."
+                            "Concurrency lease renewal failed - slots are no longer reserved. Execution will continue, but concurrency limits may be exceeded.",
+                            exc_info=(type(exc), exc, exc.__traceback__),
                         )
 
         # Add a callback to stop execution if the lease renewal fails and strict is True

{prefect-3.6.22.dev6 → prefect-3.6.22.dev7}/src/prefect/events/clients.py

@@ -30,6 +30,7 @@ from websockets.exceptions import (
 
 import prefect.types._datetime
 from prefect._internal.websockets import websocket_connect
+from prefect.client._version_checking import check_server_version
 from prefect.events import Event
 from prefect.logging import get_logger
 from prefect.settings import (
@@ -282,6 +283,7 @@ class PrefectEventsClient(EventsClient):
                 "api_url must be provided or set in the Prefect configuration"
             )
 
+        self._api_url = api_url
         auth_string = get_current_settings().api.auth_string
         self._auth_token = (
             auth_string.get_secret_value() if auth_string is not None else None
@@ -298,6 +300,7 @@ class PrefectEventsClient(EventsClient):
 
     async def __aenter__(self) -> Self:
         await super().__aenter__()
+        await check_server_version(self._api_url, logger, raise_on_error=False)
         # Ensure at least one connection attempt even if reconnection_attempts is negative
         max_attempts = max(1, self._reconnection_attempts + 1)
         for i in range(max_attempts):
@@ -623,6 +626,8 @@ class PrefectEventSubscriber:
         if not api_url:
             api_url = cast(str, PREFECT_API_URL.value())
 
+        self._api_url = api_url
+
         from prefect.events.filters import EventFilter
 
         self._filter = filter or EventFilter()  # type: ignore[call-arg]
@@ -646,6 +651,7 @@ class PrefectEventSubscriber:
         return self.__class__.__name__
 
     async def __aenter__(self) -> Self:
+        await check_server_version(self._api_url, logger, raise_on_error=False)
         # Retry initial connection with same logic as __anext__
         try:
             for i in range(self._reconnection_attempts + 1):

{prefect-3.6.22.dev6 → prefect-3.6.22.dev7}/src/prefect/logging/clients.py

@@ -28,6 +28,7 @@ from prefect._internal.websockets import (
     create_ssl_context_for_websocket,
     websocket_connect,
 )
+from prefect.client._version_checking import check_server_version
 from prefect.client.schemas.objects import Log
 from prefect.logging import get_logger
 from prefect.settings import (
@@ -168,6 +169,8 @@ class PrefectLogsSubscriber:
         if not api_url:
             api_url = cast(str, PREFECT_API_URL.value())
 
+        self._api_url = api_url
+
         from prefect.client.schemas.filters import LogFilter
 
         self._filter = filter or LogFilter()  # type: ignore[call-arg]
@@ -194,6 +197,7 @@ class PrefectLogsSubscriber:
         return self.__class__.__name__
 
     async def __aenter__(self) -> Self:
+        await check_server_version(self._api_url, logger, raise_on_error=False)
         # Don't handle any errors in the initial connection, because these are most
         # likely a permission or configuration issue that should propagate
         try:

{prefect-3.6.22.dev6 → prefect-3.6.22.dev7}/src/prefect/runner/_flow_run_executor.py

@@ -6,7 +6,7 @@ import anyio
 import anyio.abc
 
 from prefect.logging import get_logger
-from prefect.runner._exit_code_interpreter import interpret_exit_code
+from prefect.utilities._infrastructure_exit_codes import get_infrastructure_exit_info
 
 if TYPE_CHECKING:
     from prefect.client.schemas.objects import FlowRun
@@ -142,22 +142,22 @@ class FlowRunExecutor:
         # Step 7: interpret exit code and propose terminal state
         exit_code = handle.returncode if handle else None
         if exit_code is not None and exit_code != 0:
-            result = interpret_exit_code(exit_code)
-            msg = f"Process exited with status code: {exit_code}"
-            if result.help_message:
-                msg += f". {result.help_message}"
+            info = get_infrastructure_exit_info(exit_code)
+            msg = f"Process exited with status code: {exit_code}. {info.explanation}"
             self._logger.log(
-                result.level, msg, extra={"flow_run_id": self._flow_run.id}
+                info.log_level, msg, extra={"flow_run_id": self._flow_run.id}
             )
-            if result.is_crash:
-                crashed_state = await self._state_proposer.propose_crashed(
-                    self._flow_run, message=msg
+            if info.resolution:
+                self._logger.info(
+                    info.resolution,
+                    extra={"flow_run_id": self._flow_run.id},
                 )
-                # Step 8: run crashed hooks
-                if crashed_state is not None:
-                    await self._hook_runner.run_crashed_hooks(
-                        self._flow_run, crashed_state
-                    )
+            crashed_state = await self._state_proposer.propose_crashed(
+                self._flow_run, message=msg
+            )
+            # Step 8: run crashed hooks
+            if crashed_state is not None:
+                await self._hook_runner.run_crashed_hooks(self._flow_run, crashed_state)
 
     async def _start_process(
         self,

{prefect-3.6.22.dev6 → prefect-3.6.22.dev7}/src/prefect/runner/runner.py

@@ -805,8 +805,10 @@ class Runner:
                 flow_run_logger.log(
                     info.log_level,
                     f"Process for flow run {flow_run.name!r} exited with status code:"
-                    f" {process.exitcode}; {info.explanation} {info.resolution}",
+                    f" {process.exitcode}; {info.explanation}",
                 )
+                if info.resolution:
+                    flow_run_logger.info(info.resolution)
                 terminal_state = await self._propose_crashed_state(
                     flow_run, info.explanation
                 )
@@ -881,7 +883,7 @@ class Runner:
         if sys.platform == "win32":
             kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
 
-        flow_run_logger.info("Opening process...")
+        flow_run_logger.info("Starting flow run process...")
 
         if env is None:
             env = {}
@@ -1197,8 +1199,10 @@ class Runner:
                 flow_run_logger.log(
                     info.log_level,
                     f"Process for flow run {flow_run.name!r} exited with status code:"
-                    f" {exit_code}; {info.explanation} {info.resolution}",
+                    f" {exit_code}; {info.explanation}",
                 )
+                if info.resolution:
+                    flow_run_logger.info(info.resolution)
             else:
                 flow_run_logger.info(
                     f"Process for flow run {flow_run.name!r} exited cleanly."

{prefect-3.6.22.dev6 → prefect-3.6.22.dev7}/src/prefect/serializers.py

@@ -88,12 +88,20 @@ def prefect_json_object_decoder(result: dict[str, Any]) -> Any:
     if "__class__" in result:
         class_name = result["__class__"]
         if class_name not in _TYPE_ADAPTER_CACHE:
-            _TYPE_ADAPTER_CACHE[class_name] = TypeAdapter(
-                from_qualified_name(class_name)
-            )
+            try:
+                cls = from_qualified_name(class_name)
+            except (ImportError, AttributeError):
+                return result
+            _TYPE_ADAPTER_CACHE[class_name] = TypeAdapter(cls)
         return _TYPE_ADAPTER_CACHE[class_name].validate_python(result["data"])
     elif "__exc_type__" in result:
-        return from_qualified_name(result["__exc_type__"])(result["message"])
+        try:
+            exc_cls = from_qualified_name(result["__exc_type__"])
+        except (ImportError, AttributeError):
+            raise ValueError(f"Invalid exception type: {result['__exc_type__']!r}")
+        if not (isinstance(exc_cls, type) and issubclass(exc_cls, BaseException)):
+            raise ValueError(f"Invalid exception type: {result['__exc_type__']!r}")
+        return exc_cls(result["message"])
     else:
         return result
 

{prefect-3.6.22.dev6 → prefect-3.6.22.dev7}/src/prefect/server/api/middleware.py

@@ -1,3 +1,4 @@
+import hmac
 from typing import Awaitable, Callable
 
 from fastapi import status
@@ -63,7 +64,9 @@ class CsrfMiddleware(BaseHTTPMiddleware):
                     session=session, client=incoming_client
                 )
 
-                if token is None or token.token != incoming_token:
+                if token is None or not hmac.compare_digest(
+                    token.token, incoming_token
+                ):
                     return JSONResponse(
                         {"detail": "Invalid CSRF token or client identifier."},
                         status_code=status.HTTP_403_FORBIDDEN,

{prefect-3.6.22.dev6 → prefect-3.6.22.dev7}/src/prefect/server/api/server.py

@@ -9,6 +9,7 @@ import atexit
 import base64
 import contextlib
 import gc
+import hmac
 import logging
 import mimetypes
 import os
@@ -417,16 +418,20 @@ def create_api_app(
     auth_string = prefect.settings.PREFECT_SERVER_API_AUTH_STRING.value()
 
     if auth_string is not None:
+        health_check_paths = {health_check_path, "/ready"}
 
         @api_app.middleware("http")
         async def token_validation(request: Request, call_next: Any):  # type: ignore[reportUnusedFunction]
             header_token = request.headers.get("Authorization")
 
-            # used for probes in k8s and such
-            if (
-                request.url.path.endswith(("health", "ready"))
-                and request.method.upper() == "GET"
-            ):
+            # Allow unauthenticated health/ready probes (e.g. k8s).
+            # Use scope["path"] (not request.url.path) because url.path
+            # can be spoofed via Host header manipulation. Use exact path
+            # matching (not suffix matching) to prevent auth bypass via
+            # crafted paths like /variables/name/system-health.
+            scope = request.scope
+            app_path = scope["path"].removeprefix(scope.get("root_path", ""))
+            if app_path in health_check_paths and request.method.upper() == "GET":
                 return await call_next(request)
             try:
                 if header_token is None:
@@ -442,7 +447,7 @@ def create_api_app(
                     status_code=status.HTTP_401_UNAUTHORIZED,
                     content={"exception_message": "Unauthorized"},
                 )
-            if decoded != auth_string:
+            if not hmac.compare_digest(decoded, auth_string):
                 return JSONResponse(
                     status_code=status.HTTP_401_UNAUTHORIZED,
                     content={"exception_message": "Unauthorized"},

{prefect-3.6.22.dev6 → prefect-3.6.22.dev7}/src/prefect/server/events/actions.py

@@ -75,6 +75,7 @@ from prefect.server.utilities.http import should_redact_header
 from prefect.server.utilities.messaging import Message, MessageHandler
 from prefect.server.utilities.schemas import PrefectBaseModel
 from prefect.server.utilities.user_templates import (
+    TemplateRenderError,
     TemplateSecurityError,
     matching_types_in_templates,
     maybe_template,
@@ -686,9 +687,14 @@ class JinjaTemplateAction(ExternalDataAction):
 
         context = await self._template_context(templates, triggered_action)
 
-        return await asyncio.gather(
-            *[render_user_template(template, context) for template in templates]
-        )
+        try:
+            return await asyncio.gather(
+                *[render_user_template(template, context) for template in templates]
+            )
+        except TemplateRenderError as e:
+            self._result_details["template_error"] = str(e)
+            self._result_details["template_source"] = e.template
+            raise ActionFailed(f"Template rendering failed: {e.error!r}") from e
 
 
 class DeploymentAction(Action):