prefect 3.6.25.dev4__tar.gz → 3.6.25.dev5__tar.gz

{prefect-3.6.25.dev4 → prefect-3.6.25.dev5}/PKG-INFO

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

{prefect-3.6.25.dev4 → prefect-3.6.25.dev5}/src/prefect/AGENTS.md

@@ -50,5 +50,6 @@ Use `get_logger()` from `prefect.logging` instead of raw `logging.getLogger()`
 - `deployments/` → YAML-driven deployment lifecycle: project init, build/push/pull steps, and triggering remote flow runs (see deployments/AGENTS.md)
 - `utilities/` → Cross-cutting helpers: async utils, schema hydration, callables introspection, and more (see utilities/AGENTS.md)
 - `blocks/` → Server-persisted configuration objects for external service credentials and settings (see blocks/AGENTS.md)
+- `workers/` → Work-pool-based execution layer: polls for flow runs, dispatches to infrastructure (see workers/AGENTS.md)
 - `docker/` → `DockerImage` class for building and pushing Docker images during deployment
 - `telemetry/` → OS-level resource metric collection and run telemetry

prefect-3.6.25.dev5/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.6.25.dev5"
+__build_date__ = "2026-04-01 08:35:18.994448+00:00"
+__git_commit__ = "69775fbacada216f639d444d25535de62ff8f651"
+__dirty__ = False

{prefect-3.6.25.dev4 → prefect-3.6.25.dev5}/src/prefect/_internal/schemas/validators.py

@@ -9,6 +9,7 @@ This will be subject to consolidation and refactoring over the next few months.
 from __future__ import annotations
 
 import datetime
+import json
 import os
 import urllib.parse
 import warnings
@@ -81,6 +82,28 @@ def validate_values_conform_to_schema(
         ) from exc
 
 
+def validate_parameter_size(parameters: dict[str, Any], max_size: int) -> None:
+    """Raise ValueError if serialized parameters exceed max_size bytes. If max_size is 0, skip validation."""
+    if max_size <= 0 or not parameters:
+        return
+    size = len(json.dumps(parameters, separators=(",", ":")).encode())
+    if size > max_size:
+        raise ValueError(
+            f"Flow run parameters must be less than {max_size:,} bytes when serialized (got {size:,} bytes)."
+        )
+
+
+def validate_parameter_size_field(
+    parameters: dict[str, Any],
+) -> dict[str, Any]:
+    """AfterValidator-compatible wrapper for validate_parameter_size."""
+    from prefect.settings import get_current_settings
+
+    max_size = get_current_settings().server.api.max_parameter_size
+    validate_parameter_size(parameters, max_size)
+    return parameters
+
+
 ### DEPLOYMENT SCHEMA VALIDATORS ###
 
 

{prefect-3.6.25.dev4 → prefect-3.6.25.dev5}/src/prefect/cli/deploy/_actions.py

@@ -240,6 +240,44 @@ async def _generate_default_pull_action(
                 console, deploy_config, auto=False
             )
     else:
+        # Check if user has a custom image in job_variables but no build step.
+        # In this case, the local cwd won't exist inside the container, so we
+        # need to use a container-appropriate working directory instead.
+        custom_image = (
+            deploy_config.get("work_pool", {}).get("job_variables", {}).get("image")
+        )
+        if custom_image:
+            if is_interactive():
+                dir_name = os.path.basename(os.getcwd())
+                pull_step = prompt(
+                    "What is the working directory in your Docker image"
+                    " where your flow code lives?",
+                    default=f"/opt/prefect/{dir_name}",
+                    console=console,
+                )
+                return [
+                    {
+                        "prefect.deployments.steps.set_working_directory": {
+                            "directory": pull_step
+                        }
+                    }
+                ]
+            else:
+                console.print(
+                    "[yellow]Warning: Using default working directory"
+                    " '/opt/prefect' for your Docker image. If your flow"
+                    " code is in a different location, add an explicit"
+                    " set_working_directory pull step to your"
+                    " prefect.yaml.[/yellow]"
+                )
+                return [
+                    {
+                        "prefect.deployments.steps.set_working_directory": {
+                            "directory": "/opt/prefect"
+                        }
+                    }
+                ]
+
         entrypoint_path, _ = deploy_config["entrypoint"].split(":")
         console.print(
             "Your Prefect workers will attempt to load your flow from:"

{prefect-3.6.25.dev4 → prefect-3.6.25.dev5}/src/prefect/runner/AGENTS.md

@@ -13,7 +13,7 @@ Thin facade over single-responsibility extracted classes. New behavior belongs i
 | StateProposer | _state_proposer.py | All API state transition proposals |
 | CancellationManager | _cancellation_manager.py | Kill -> hooks -> state -> event cancellation sequence |
 | HookRunner | _hook_runner.py | on_cancellation / on_crashed hook execution |
-| EventEmitter | _event_emitter.py | Event emission via EventsClient |
+| EventEmitter | _event_emitter.py | Event emission via EventsClient; degrades to NullEventsClient on WebSocket rejection |
 | LimitManager | _limit_manager.py | Concurrency limiting |
 | DeploymentRegistry | _deployment_registry.py | Deployment/flow/storage/bundle maps |
 | ScheduledRunPoller | _scheduled_run_poller.py | Poll loop, run discovery, scheduling |
@@ -44,6 +44,10 @@ Thin facade over single-responsibility extracted classes. New behavior belongs i
 
 These will be removed once internal callers (notably ProcessWorker) are migrated. ProcessWorker currently suppresses the deprecation warnings via `warnings.catch_warnings()`.
 
+## EventEmitter WebSocket Degradation
+
+`EventEmitter.__aenter__` catches `websockets.exceptions.InvalidStatus` (HTTP 4xx rejections) and silently swaps the failed client for a `NullEventsClient`. This handles old clients (≤3.6.13) connecting to servers ≥3.6.14 with `PREFECT_SERVER_API_AUTH_STRING` configured — the server rejects the WebSocket handshake, but events are non-critical telemetry so the flow run must not crash. A `WARNING` is logged. If `__aenter__` raises, `__aexit__` is **not** called on the original client (it was never successfully entered); the replacement `NullEventsClient` is entered instead.
+
 ## AsyncExitStack LIFO Ordering
 
 Services enter in this order during `Runner.__aenter__` (teardown is exact reverse):

{prefect-3.6.25.dev4 → prefect-3.6.25.dev5}/src/prefect/runner/_event_emitter.py

@@ -3,7 +3,9 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, Callable
 
 from cachetools import TTLCache
+from websockets.exceptions import InvalidStatus as _WsInvalidStatus
 
+from prefect.events.clients import NullEventsClient
 from prefect.events.related import tags_as_related_resources
 from prefect.events.schemas.events import Event, RelatedResource, Resource
 from prefect.logging import get_logger
@@ -16,6 +18,13 @@ if TYPE_CHECKING:
     from prefect.client.schemas.responses import DeploymentResponse
     from prefect.events.clients import EventsClient
 
+# Exceptions that indicate a permanent connection failure (e.g. auth rejected).
+# On these, EventEmitter degrades gracefully to NullEventsClient rather than
+# crashing the flow run.  This preserves backwards-compatibility with clients
+# running against a server that has PREFECT_SERVER_API_AUTH_STRING configured
+# (server >=3.6.14) where the WS handshake is rejected with HTTP 401/403.
+_NONFATAL_CONNECTION_EXCEPTIONS: tuple[type[Exception], ...] = (_WsInvalidStatus,)
+
 
 def _default_get_events_client() -> "EventsClient":
     from prefect.events.clients import get_events_client
@@ -48,7 +57,26 @@ class EventEmitter:
 
     async def __aenter__(self) -> "EventEmitter":
         self._events_client = self._get_events_client()
-        await self._events_client.__aenter__()
+        try:
+            await self._events_client.__aenter__()
+        except _NONFATAL_CONNECTION_EXCEPTIONS as exc:
+            # The events WebSocket was rejected by the server (e.g. HTTP 401/403).
+            # This happens when an old client (<=3.6.13) connects to a server
+            # >=3.6.14 that has PREFECT_SERVER_API_AUTH_STRING configured: the
+            # server now requires the "prefect" subprotocol + auth handshake, but
+            # old clients omit it.  Events are non-critical telemetry, so we
+            # degrade gracefully instead of crashing the flow run.
+            self._logger.warning(
+                "Unable to connect to the events WebSocket (%s). "
+                "Event data will not be emitted for this runner. "
+                "Upgrade the Prefect client to >=3.6.14 to restore event support "
+                "when the server has authentication configured.",
+                exc,
+            )
+            # __aenter__ failed, so __aexit__ must NOT be called on the original
+            # client (it was never successfully entered).
+            self._events_client = NullEventsClient()
+            await self._events_client.__aenter__()
         return self
 
     async def __aexit__(self, *exc_info: Any) -> None:

{prefect-3.6.25.dev4 → prefect-3.6.25.dev5}/src/prefect/server/AGENTS.md

@@ -8,6 +8,7 @@ Orchestration backend managing flow runs, scheduling, and state tracking. This i
 - **SQLite and PostgreSQL must be kept in lockstep** — every migration, every query. Some queries need database-specific variants where SQLite lacks PostgreSQL features. CI tests both databases.
 - **Server and client code should not mix** — the server has its own schemas (`server/schemas/`) separate from client schemas (`client/schemas/`). Keep the boundary clean.
 - **Auth token comparisons must use `hmac.compare_digest`** — never compare auth tokens with `==` or `!=`. Direct equality checks are vulnerable to timing attacks that can leak secrets. Applies to CSRF tokens (`api/middleware.py`), HTTP basic auth (`api/server.py`), and WebSocket auth (`utilities/subscriptions.py`).
+- **Use `SizedParameters` for action schema `parameters` fields** — `schemas/actions.py` defines `SizedParameters = Annotated[Dict[str, Any], AfterValidator(validate_parameter_size_field)]`. Any action model that accepts flow run or deployment parameters must use this type instead of `Dict[str, Any]`. It enforces the `PREFECT_SERVER_API_MAX_PARAMETER_SIZE` limit (default 512 KB, set to 0 to disable) and returns a 422 on violation.
 
 ## Adding a New API Endpoint
 

{prefect-3.6.25.dev4 → prefect-3.6.25.dev5}/src/prefect/server/api/server.py

@@ -557,7 +557,17 @@ def create_ui_app(ephemeral: bool) -> FastAPI:
         # If the static files have already been copied, check if the base_url has changed
         # If it has, we delete the subpath directory and copy the files again
         if not reference_file_matches_base_url():
-            create_ui_static_subpath()
+            try:
+                create_ui_static_subpath()
+            except PermissionError as exc:
+                logger.error(
+                    "Failed to create UI static directory at %s: %s. "
+                    "The UI will not be available. "
+                    "To resolve this, set PREFECT_UI_STATIC_DIRECTORY to a writable directory.",
+                    static_dir,
+                    exc,
+                )
+                return ui_app
 
         ui_app.mount(
             PREFECT_UI_SERVE_BASE.value(),

{prefect-3.6.25.dev4 → prefect-3.6.25.dev5}/src/prefect/server/schemas/actions.py

@@ -25,6 +25,7 @@ from prefect._internal.schemas.validators import (
     validate_max_metadata_length,
     validate_name_present_on_nonanonymous_blocks,
     validate_parameter_openapi_schema,
+    validate_parameter_size_field,
     validate_parameters_conform_to_schema,
     validate_parent_and_ref_diff,
     validate_schedule_max_scheduled_runs,
@@ -53,6 +54,10 @@ from prefect.types.names import (
 from prefect.utilities.names import generate_slug
 from prefect.utilities.templating import find_placeholders
 
+SizedParameters = Annotated[
+    Dict[str, Any], AfterValidator(validate_parameter_size_field)
+]
+
 
 class ActionBaseModel(PrefectBaseModel):
     model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
@@ -192,7 +197,7 @@ class DeploymentCreate(ActionBaseModel):
         description="The parameter schema of the flow, including defaults.",
         json_schema_extra={"additionalProperties": True},
     )
-    parameters: Dict[str, Any] = Field(
+    parameters: SizedParameters = Field(
         default_factory=dict,
         description="Parameters for flow runs scheduled by the deployment.",
         json_schema_extra={"additionalProperties": True},
@@ -313,7 +318,7 @@ class DeploymentUpdate(ActionBaseModel):
         default=None,
         description="The ID of the global concurrency limit to apply to the deployment.",
     )
-    parameters: Optional[Dict[str, Any]] = Field(
+    parameters: Optional[SizedParameters] = Field(
         default=None,
         description="Parameters for flow runs scheduled by the deployment.",
     )
@@ -397,7 +402,7 @@ class FlowRunUpdate(ActionBaseModel):
 
     name: Optional[str] = Field(None)
     flow_version: Optional[str] = Field(None)
-    parameters: Dict[str, Any] = Field(default_factory=dict)
+    parameters: SizedParameters = Field(default_factory=dict)
     empirical_policy: schemas.core.FlowRunPolicy = Field(
         default_factory=schemas.core.FlowRunPolicy
     )
@@ -565,7 +570,7 @@ class FlowRunCreate(ActionBaseModel):
     flow_version: Optional[str] = Field(
         default=None, description="The version of the flow being run."
     )
-    parameters: Dict[str, Any] = Field(
+    parameters: SizedParameters = Field(
         default_factory=dict,
     )
     context: Dict[str, Any] = Field(
@@ -640,7 +645,7 @@ class DeploymentFlowRunCreate(ActionBaseModel):
         ),
         examples=["my-flow-run"],
     )
-    parameters: Dict[str, Any] = Field(
+    parameters: SizedParameters = Field(
         default_factory=dict,
         json_schema_extra={"additionalProperties": True},
     )

{prefect-3.6.25.dev4 → prefect-3.6.25.dev5}/src/prefect/settings/models/server/api.py

@@ -143,3 +143,9 @@ class ServerAPISettings(PrefectBaseSettings):
             "prefect_server_cors_allowed_headers",
         ),
     )
+
+    max_parameter_size: int = Field(
+        default=524_288,
+        description="The maximum size of parameters (in bytes, JSON-serialized) that can be stored on a flow run or deployment. Set to 0 to disable the limit.",
+        ge=0,
+    )

prefect-3.6.25.dev5/src/prefect/workers/AGENTS.md

@@ -0,0 +1,42 @@
+# Workers
+
+Work-pool-based execution layer that polls for flow runs and submits them to infrastructure.
+
+## Purpose & Scope
+
+Workers are long-running processes that pull scheduled flow runs from a work pool and dispatch them to infrastructure (processes, Docker, Kubernetes, cloud VMs, etc.). Each worker type subclasses `BaseWorker` and provides a `BaseJobConfiguration` subclass plus a `run()` method.
+
+This module does NOT manage the Runner execution model (no work pool) — see `runner/AGENTS.md` for that.
+
+## Key Classes
+
+- `BaseWorker` — abstract base; handles heartbeating, polling, cancellation, and attribution env vars
+- `BaseJobConfiguration` — Pydantic model for per-run infrastructure config; `prepare_for_flow_run()` stamps attribution variables into `env`
+- `ProcessWorker` (`process.py`) — runs flow runs as local subprocesses via `Runner.execute_bundle()`
+- `BaseWorkerResult` — result returned by `run()`; wraps infrastructure status codes
+
+## Attribution Env Vars
+
+Workers stamp two env vars into `os.environ` for their own process, so all API requests include attribution headers:
+
+- `PREFECT__WORKER_NAME` — set in `setup()` immediately
+- `PREFECT__WORKER_ID` — set in `sync_with_backend()` after the first successful heartbeat returns a backend ID
+
+**Teardown guard**: `teardown()` only removes these vars if they still match the current worker instance (`os.environ.get("PREFECT__WORKER_NAME") == self.name`). This prevents a second worker sharing the same process from having its vars cleared.
+
+These are separate from the per-flow-run attribution vars injected into the child process environment by `prepare_for_flow_run(worker_name=..., worker_id=...)`.
+
+## Anti-Patterns
+
+- Do not set `PREFECT__WORKER_NAME` / `PREFECT__WORKER_ID` in `os.environ` from outside `BaseWorker` — setup/teardown own this lifecycle.
+- Do not call `prepare_for_flow_run()` without passing `worker_name` and `worker_id` — omitting them silently drops attribution from child-process API requests.
+
+## Pitfalls
+
+- `backend_id` is `None` until the first heartbeat succeeds; `PREFECT__WORKER_ID` is not set until then. Code that reads `self.backend_id` early in the lifecycle may get `None`.
+- `ProcessWorker` calls the deprecated `Runner.execute_flow_run()` / `Runner.execute_bundle()` paths (suppressing `PrefectDeprecationWarning` with `warnings.catch_warnings()`). It bypasses `FlowRunExecutor` and `ProcessStarter` — this is a known migration gap (see `runner/AGENTS.md`).
+
+## Related
+
+- `runner/AGENTS.md` — Runner execution model (no work pool, local deployments)
+- `src/prefect/client/AGENTS.md` — attribution headers set from these env vars

{prefect-3.6.25.dev4 → prefect-3.6.25.dev5}/src/prefect/workers/base.py

@@ -5,6 +5,7 @@ import asyncio
 import copy
 import datetime
 import logging
+import os
 import threading
 import uuid
 import warnings
@@ -1081,6 +1082,10 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
         await self._exit_stack.enter_async_context(self._client)
         await self._exit_stack.enter_async_context(self._runs_task_group)
 
+        # Set worker name in os.environ so get_attribution_headers() includes
+        # it in all API requests made by this worker process.
+        os.environ["PREFECT__WORKER_NAME"] = self.name
+
         await self.sync_with_backend()
 
         # Initialize cancellation handling if enabled
@@ -1113,6 +1118,14 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
         """Cleans up resources after the worker is stopped."""
         self._logger.debug("Tearing down worker...")
         self.is_setup: bool = False
+        # Only remove env vars if they still belong to this worker instance,
+        # in case multiple workers share the same process.
+        if os.environ.get("PREFECT__WORKER_NAME") == self.name:
+            os.environ.pop("PREFECT__WORKER_NAME", None)
+        if self.backend_id and os.environ.get("PREFECT__WORKER_ID") == str(
+            self.backend_id
+        ):
+            os.environ.pop("PREFECT__WORKER_ID", None)
         for scope in self._scheduled_task_scopes:
             scope.cancel()
 
@@ -1288,6 +1301,9 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
         remote_id = await self._send_worker_heartbeat()
         if remote_id:
             self.backend_id = remote_id
+            # Set worker ID in os.environ so get_attribution_headers() includes
+            # it in all API requests made by this worker process.
+            os.environ["PREFECT__WORKER_ID"] = str(remote_id)
             self._logger = get_worker_logger(self)
 
         self._logger.debug(

{prefect-3.6.25.dev4 → prefect-3.6.25.dev5}/src/prefect/workers/process.py

@@ -313,6 +313,7 @@ class ProcessWorker(
             flow=api_flow,
             work_pool=self.work_pool,
             worker_name=self.name,
+            worker_id=self.backend_id,
         )
 
         result = create_bundle_for_flow_run(flow=flow, flow_run=flow_run)

prefect-3.6.25.dev4/src/prefect/_build_info.py

@@ -1,5 +0,0 @@
-# Generated by versioningit
-__version__ = "3.6.25.dev4"
-__build_date__ = "2026-03-31 08:30:52.304912+00:00"
-__git_commit__ = "fcbac206040d74c5c5473525207b144f98cbf80e"
-__dirty__ = False