prefect-client 3.7.1.dev2__tar.gz → 3.7.1.dev3__tar.gz

{prefect_client-3.7.1.dev2 → prefect_client-3.7.1.dev3}/PKG-INFO

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

{prefect_client-3.7.1.dev2 → prefect_client-3.7.1.dev3}/src/prefect/AGENTS.md

@@ -31,6 +31,7 @@ There is no formal public/private boundary beyond the `_` prefix convention. Mod
 - **`ThreadPoolTaskRunner` is cloudpickled when a flow run is dispatched to a subprocess.** `threading.Lock` and other non-picklable thread primitives must be dropped in `__getstate__` and rebuilt in `__setstate__`. Any new instance state added to this class must be evaluated for picklability.
 - **Nested task submissions on a bounded `ThreadPoolTaskRunner` can deadlock.** When a worker task submits children and blocks on `.result()` while all `max_workers` threads are busy, the pool starves. `_warn_if_nested_submit_would_deadlock` detects this and emits a one-time warning — preserve this detection when changing pool management.
 - **`ResultRecordMetadata` tolerates unknown serializer types.** When loading persisted metadata, an unrecognized serializer `type` is converted to an `UnknownSerializer` placeholder rather than raising `ValidationError`. This allows inspecting result metadata when the serializer implementation is unavailable in the current environment. However, known serializer types with invalid fields still raise `ValidationError`. `UnknownSerializer.dumps()` and `UnknownSerializer.loads()` raise `RuntimeError` — the tolerance is for inspection only, not actual serialization/deserialization.
+- **Flow-run suspension is enforced at orchestration boundaries.** Suspension is delivered via `FlowRunSuspensionRequest` and raised with `raise_if_flow_run_suspension_requested()`. When changing engines, futures, task runners, or generator execution, check before returning control to flow user code or proposing a flow state that could leave `Suspended`; keep sync/async paths aligned and avoid per-boundary API reads.
 
 ## Logging
 

prefect_client-3.7.1.dev3/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.7.1.dev3"
+__build_date__ = "2026-05-09 08:38:35.993918+00:00"
+__git_commit__ = "fe44ad330730d7beedda307786fea83e062ced39"
+__dirty__ = False

prefect_client-3.7.1.dev3/src/prefect/_flow_run_suspension.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import asyncio
+import contextvars
+import threading
+from contextlib import contextmanager
+from typing import Generator
+from uuid import UUID
+
+from prefect.client.schemas.objects import State
+from prefect.exceptions import Pause
+from prefect.logging.loggers import get_logger
+
+
+class FlowRunSuspensionRequest:
+    """
+    Mutable in-process suspension request shared by flow, child flow, and task contexts.
+
+    The stored state is the server-accepted `Suspended` state that should be raised
+    through Prefect's existing `Pause` control-flow path at the next orchestration
+    boundary.
+    """
+
+    def __init__(self) -> None:
+        self._suspended_state: State | None = None
+        self._lock = threading.Lock()
+
+    def mark_requested(self, state: State) -> None:
+        with self._lock:
+            self._suspended_state = state
+
+    def get_state(self) -> State | None:
+        with self._lock:
+            return self._suspended_state
+
+    def is_requested(self) -> bool:
+        return self.get_state() is not None
+
+    def raise_if_requested(self) -> None:
+        if state := self.get_state():
+            raise Pause(state=state)
+
+
+def is_suspended_flow_run_state(state: State | None) -> bool:
+    return bool(state and state.is_paused() and state.name == "Suspended")
+
+
+_active_flow_run_suspension_requests: dict[UUID, FlowRunSuspensionRequest] = {}
+_active_flow_run_suspension_requests_lock = threading.Lock()
+
+
+@contextmanager
+def register_flow_run_suspension_request(
+    flow_run_id: UUID,
+    suspension_request: FlowRunSuspensionRequest,
+) -> Generator[None, None, None]:
+    with _active_flow_run_suspension_requests_lock:
+        _active_flow_run_suspension_requests[flow_run_id] = suspension_request
+
+    try:
+        yield
+    finally:
+        with _active_flow_run_suspension_requests_lock:
+            if (
+                _active_flow_run_suspension_requests.get(flow_run_id)
+                is suspension_request
+            ):
+                _active_flow_run_suspension_requests.pop(flow_run_id, None)
+
+
+def mark_flow_run_suspension_requested(flow_run_id: UUID, state: State) -> bool:
+    with _active_flow_run_suspension_requests_lock:
+        suspension_request = _active_flow_run_suspension_requests.get(flow_run_id)
+
+    if suspension_request is None:
+        return False
+
+    suspension_request.mark_requested(state)
+    return True
+
+
+def raise_if_flow_run_suspension_requested() -> None:
+    from prefect.context import FlowRunContext
+
+    if flow_run_context := FlowRunContext.get():
+        flow_run_context.flow_run_suspension_request.raise_if_requested()
+
+
+@contextmanager
+def observe_flow_run_suspension(
+    flow_run_id: UUID,
+    suspension_request: FlowRunSuspensionRequest,
+    polling_interval: float = 10,
+) -> Generator[None, None, None]:
+    from prefect._observers import FlowRunSuspendingObserver
+
+    logger = get_logger("flow_run_suspension")
+    stop_event = threading.Event()
+    ready_event = threading.Event()
+
+    def mark_suspended(flow_run_id: UUID, state: State) -> None:
+        if not mark_flow_run_suspension_requested(flow_run_id, state):
+            suspension_request.mark_requested(state)
+
+    async def run_observer() -> None:
+        async with FlowRunSuspendingObserver(
+            on_suspended=mark_suspended,
+            polling_interval=polling_interval,
+        ) as observer:
+            await observer.watch_flow_run_id(flow_run_id)
+            ready_event.set()
+            while not stop_event.is_set():
+                await asyncio.sleep(0.2)
+
+    context = contextvars.copy_context()
+
+    def observer_thread() -> None:
+        try:
+            context.run(lambda: asyncio.run(run_observer()))
+        except Exception:
+            logger.debug(
+                "Flow run suspension observer exited with an exception",
+                exc_info=True,
+            )
+        finally:
+            ready_event.set()
+
+    thread = threading.Thread(target=observer_thread, daemon=True)
+    thread.start()
+    ready_event.wait()
+
+    try:
+        yield
+    finally:
+        stop_event.set()
+        thread.join(timeout=2)

prefect_client-3.7.1.dev3/src/prefect/_observers.py

@@ -0,0 +1,494 @@
+from __future__ import annotations
+
+import asyncio
+import uuid
+from contextlib import AsyncExitStack
+from typing import Any, Protocol
+
+from prefect._flow_run_suspension import is_suspended_flow_run_state
+from prefect.client.orchestration import PrefectClient, get_client
+from prefect.client.schemas.filters import (
+    FlowRunFilter,
+    FlowRunFilterId,
+    FlowRunFilterState,
+    FlowRunFilterStateName,
+    FlowRunFilterStateType,
+)
+from prefect.client.schemas.objects import State, StateType
+from prefect.events.clients import PrefectEventSubscriber, get_events_subscriber
+from prefect.events.filters import EventFilter, EventNameFilter
+from prefect.logging.loggers import get_logger
+from prefect.utilities.services import critical_service_loop
+
+
+class OnCancellingCallback(Protocol):
+    def __call__(self, flow_run_id: uuid.UUID) -> None: ...
+
+
+class OnSuspendedCallback(Protocol):
+    def __call__(self, flow_run_id: uuid.UUID, state: State) -> None: ...
+
+
+class OnFailureCallback(Protocol):
+    def __call__(self, flow_run_ids: set[uuid.UUID]) -> None: ...
+
+
+class FlowRunCancellingObserver:
+    def __init__(
+        self,
+        on_cancelling: OnCancellingCallback,
+        polling_interval: float = 10,
+        event_filter: EventFilter | None = None,
+        on_failure: OnFailureCallback | None = None,
+    ):
+        """
+        Observer that cancels flow runs when they are marked as cancelling.
+
+        Will use a websocket connection to listen for cancelling flow run events by default with a fallback
+        to polling when the websocket connection is lost.
+
+        Args:
+            on_cancelling: Callback to call when a flow run is marked as cancelling.
+            polling_interval: Interval in seconds to poll for cancelling flow runs when websocket connection is lost.
+            event_filter: Optional event filter to use for the websocket subscription.
+                If not provided, defaults to filtering for "prefect.flow-run.Cancelling" events.
+            on_failure: Optional callback to call when both websocket and polling mechanisms fail.
+                Called with the set of in-flight flow run IDs that can no longer be monitored for cancellation.
+        """
+        self.logger = get_logger("FlowRunCancellingObserver")
+        self.on_cancelling = on_cancelling
+        self.on_failure = on_failure
+        self.polling_interval = polling_interval
+
+        if event_filter is not None:
+            if (
+                event_filter.event is None
+                or event_filter.event.name is None
+                or "prefect.flow-run.Cancelling" not in event_filter.event.name
+            ):
+                raise ValueError(
+                    "event_filter must include 'prefect.flow-run.Cancelling' in event.name"
+                )
+            self._event_filter = event_filter
+        else:
+            self._event_filter = EventFilter(
+                event=EventNameFilter(name=["prefect.flow-run.Cancelling"])
+            )
+        self._in_flight_flow_run_ids: set[uuid.UUID] = set()
+        self._events_subscriber: PrefectEventSubscriber | None
+        self._exit_stack = AsyncExitStack()
+        self._consumer_task: asyncio.Task[None] | None = None
+        self._polling_task: asyncio.Task[None] | None = None
+        self._is_shutting_down = False
+        self._client: PrefectClient | None = None
+        self._cancelling_flow_run_ids: set[uuid.UUID] = set()
+
+    def add_in_flight_flow_run_id(self, flow_run_id: uuid.UUID):
+        self.logger.debug("Adding in-flight flow run ID: %s", flow_run_id)
+        self._in_flight_flow_run_ids.add(flow_run_id)
+
+    def remove_in_flight_flow_run_id(self, flow_run_id: uuid.UUID):
+        self.logger.debug("Removing in-flight flow run ID: %s", flow_run_id)
+        self._in_flight_flow_run_ids.discard(flow_run_id)
+        self._cancelling_flow_run_ids.discard(flow_run_id)
+
+    async def _consume_events(self):
+        if self._events_subscriber is None:
+            raise RuntimeError(
+                "Events subscriber not initialized. Please use `async with` to initialize the observer."
+            )
+        async for event in self._events_subscriber:
+            try:
+                flow_run_id = uuid.UUID(
+                    event.resource["prefect.resource.id"].replace(
+                        "prefect.flow-run.", ""
+                    )
+                )
+                if flow_run_id not in self._in_flight_flow_run_ids:
+                    continue
+                self.on_cancelling(flow_run_id)
+            except ValueError:
+                self.logger.warning(
+                    "Received event with invalid flow run ID: %s",
+                    event.resource["prefect.resource.id"],
+                )
+
+    def _start_polling_task(self, task: asyncio.Task[None]):
+        if task.cancelled():
+            # If the consumer task was cancelled, the observer is shutting down
+            # and we don't need to start the polling task
+            return
+        if exc := task.exception():
+            self.logger.warning(
+                "The FlowRunCancellingObserver websocket failed with an exception. Switching to polling mode.",
+                exc_info=exc,
+            )
+            self._polling_task = asyncio.create_task(
+                critical_service_loop(
+                    workload=self._check_for_cancelled_flow_runs,
+                    interval=self.polling_interval,
+                    jitter_range=0.3,
+                )
+            )
+            self._polling_task.add_done_callback(self._handle_polling_task_done)
+
+    def _handle_polling_task_done(self, task: asyncio.Task[None]):
+        if task.exception():
+            self.logger.error(
+                "Cancellation polling task failed. Execution will continue, but flow run cancellation will fail.",
+                exc_info=task.exception(),
+            )
+            if self.on_failure is not None:
+                self.on_failure(self._in_flight_flow_run_ids.copy())
+        else:
+            self.logger.debug("Polling task completed")
+
+    async def _check_for_cancelled_flow_runs(self):
+        if self._is_shutting_down:
+            return
+        if self._client is None:
+            raise RuntimeError(
+                "Client not initialized. Please use `async with` to initialize the observer."
+            )
+
+        self.logger.debug("Checking for cancelled flow runs")
+        named_cancelling_flow_runs = await self._client.read_flow_runs(
+            flow_run_filter=FlowRunFilter(
+                state=FlowRunFilterState(
+                    type=FlowRunFilterStateType(any_=[StateType.CANCELLED]),
+                    name=FlowRunFilterStateName(any_=["Cancelling"]),
+                ),
+                # Avoid duplicate cancellation calls
+                id=FlowRunFilterId(
+                    any_=list(
+                        self._in_flight_flow_run_ids - self._cancelling_flow_run_ids
+                    )
+                ),
+            ),
+        )
+
+        typed_cancelling_flow_runs = await self._client.read_flow_runs(
+            flow_run_filter=FlowRunFilter(
+                state=FlowRunFilterState(
+                    type=FlowRunFilterStateType(any_=[StateType.CANCELLING]),
+                ),
+                # Avoid duplicate cancellation calls
+                id=FlowRunFilterId(
+                    any_=list(
+                        self._in_flight_flow_run_ids - self._cancelling_flow_run_ids
+                    )
+                ),
+            ),
+        )
+
+        cancelling_flow_runs = named_cancelling_flow_runs + typed_cancelling_flow_runs
+
+        if cancelling_flow_runs:
+            self.logger.info(
+                "Found %s flow runs awaiting cancellation.", len(cancelling_flow_runs)
+            )
+
+        for flow_run in cancelling_flow_runs:
+            self._cancelling_flow_run_ids.add(flow_run.id)
+            self.on_cancelling(flow_run.id)
+
+    async def __aenter__(self):
+        try:
+            self._events_subscriber = await self._exit_stack.enter_async_context(
+                get_events_subscriber(filter=self._event_filter)
+            )
+        except Exception as e:
+            self.logger.warning(
+                "Failed to connect to the events stream. Falling back to polling "
+                "for cancellation events. Reason: %s",
+                str(e),
+            )
+            self._events_subscriber = None
+
+        self._client = await self._exit_stack.enter_async_context(get_client())
+
+        if self._events_subscriber is not None:
+            self._consumer_task = asyncio.create_task(self._consume_events())
+            self._consumer_task.add_done_callback(self._start_polling_task)
+        else:
+            # WebSocket unavailable — start polling immediately
+            self._polling_task = asyncio.create_task(
+                critical_service_loop(
+                    workload=self._check_for_cancelled_flow_runs,
+                    interval=self.polling_interval,
+                    jitter_range=0.3,
+                )
+            )
+            self._polling_task.add_done_callback(self._handle_polling_task_done)
+
+        return self
+
+    async def __aexit__(self, *exc_info: Any):
+        self.logger.debug("Shutting down FlowRunCancellingObserver")
+        self._is_shutting_down = True
+        await self._exit_stack.__aexit__(*exc_info)
+        if self._consumer_task is not None:
+            self._consumer_task.cancel()
+            try:
+                await self._consumer_task
+            except asyncio.CancelledError:
+                pass
+            except Exception:
+                self.logger.warning(
+                    "Consumer task exited with exception", exc_info=True
+                )
+                pass
+
+        if self._polling_task is not None:
+            self._polling_task.cancel()
+            try:
+                await self._polling_task
+            except asyncio.CancelledError:
+                pass
+            except Exception:
+                self.logger.warning("Polling task exited with exception", exc_info=True)
+                pass
+
+
+class FlowRunSuspendingObserver:
+    def __init__(
+        self,
+        on_suspended: OnSuspendedCallback,
+        polling_interval: float = 10,
+        event_filter: EventFilter | None = None,
+        on_failure: OnFailureCallback | None = None,
+    ):
+        """
+        Observer that notices flow runs when they are marked as suspended.
+
+        Uses the events stream to listen for suspension events by default, with a
+        polling fallback when the websocket connection is unavailable or lost.
+        """
+        self.logger = get_logger("FlowRunSuspendingObserver")
+        self.on_suspended = on_suspended
+        self.on_failure = on_failure
+        self.polling_interval = polling_interval
+
+        if event_filter is not None:
+            if (
+                event_filter.event is None
+                or event_filter.event.name is None
+                or "prefect.flow-run.Suspended" not in event_filter.event.name
+            ):
+                raise ValueError(
+                    "event_filter must include 'prefect.flow-run.Suspended' in event.name"
+                )
+            self._event_filter = event_filter
+        else:
+            self._event_filter = EventFilter(
+                event=EventNameFilter(name=["prefect.flow-run.Suspended"])
+            )
+        self._in_flight_flow_run_ids: set[uuid.UUID] = set()
+        self._events_subscriber: PrefectEventSubscriber | None
+        self._exit_stack = AsyncExitStack()
+        self._consumer_task: asyncio.Task[None] | None = None
+        self._polling_task: asyncio.Task[None] | None = None
+        self._is_shutting_down = False
+        self._client: PrefectClient | None = None
+        self._suspended_flow_run_ids: set[uuid.UUID] = set()
+
+    def add_in_flight_flow_run_id(self, flow_run_id: uuid.UUID):
+        self.logger.debug("Adding in-flight flow run ID: %s", flow_run_id)
+        self._in_flight_flow_run_ids.add(flow_run_id)
+
+    def remove_in_flight_flow_run_id(self, flow_run_id: uuid.UUID):
+        self.logger.debug("Removing in-flight flow run ID: %s", flow_run_id)
+        self._in_flight_flow_run_ids.discard(flow_run_id)
+        self._suspended_flow_run_ids.discard(flow_run_id)
+
+    async def watch_flow_run_id(self, flow_run_id: uuid.UUID) -> None:
+        self.add_in_flight_flow_run_id(flow_run_id)
+        if self._client is None:
+            raise RuntimeError(
+                "Client not initialized. Please use `async with` to initialize the observer."
+            )
+        retry_interval = max(min(self.polling_interval, 1.0), 0.01)
+        attempts = 0
+
+        while not self._is_shutting_down:
+            if flow_run_id in self._suspended_flow_run_ids:
+                return
+
+            try:
+                flow_run = await self._client.read_flow_run(flow_run_id)
+            except Exception:
+                attempts += 1
+                log = self.logger.warning if attempts == 1 else self.logger.debug
+                log(
+                    "Failed to check current state for flow run %s while starting"
+                    " suspension observer. Retrying before reporting observer ready.",
+                    flow_run_id,
+                    exc_info=True,
+                )
+                await asyncio.sleep(retry_interval)
+                continue
+
+            self._notify_if_suspended_state(flow_run_id, flow_run.state)
+            return
+
+    def _notify_if_suspended_state(
+        self, flow_run_id: uuid.UUID, state: State | None
+    ) -> None:
+        if state is not None and is_suspended_flow_run_state(state):
+            self._suspended_flow_run_ids.add(flow_run_id)
+            self.on_suspended(flow_run_id, state)
+
+    async def _notify_if_suspended(self, flow_run_id: uuid.UUID) -> None:
+        if self._client is None:
+            raise RuntimeError(
+                "Client not initialized. Please use `async with` to initialize the observer."
+            )
+        if flow_run_id in self._suspended_flow_run_ids:
+            return
+
+        flow_run = await self._client.read_flow_run(flow_run_id)
+        self._notify_if_suspended_state(flow_run_id, flow_run.state)
+
+    async def _consume_events(self):
+        if self._events_subscriber is None:
+            raise RuntimeError(
+                "Events subscriber not initialized. Please use `async with` to initialize the observer."
+            )
+        async for event in self._events_subscriber:
+            try:
+                flow_run_id = uuid.UUID(
+                    event.resource["prefect.resource.id"].replace(
+                        "prefect.flow-run.", ""
+                    )
+                )
+                if flow_run_id not in self._in_flight_flow_run_ids:
+                    continue
+                await self._notify_if_suspended(flow_run_id)
+            except ValueError:
+                self.logger.warning(
+                    "Received event with invalid flow run ID: %s",
+                    event.resource["prefect.resource.id"],
+                )
+
+    def _start_polling_task(self, task: asyncio.Task[None]):
+        if task.cancelled() or self._is_shutting_down:
+            return
+
+        if exc := task.exception():
+            self.logger.warning(
+                "The FlowRunSuspendingObserver websocket failed with an exception. Switching to polling mode.",
+                exc_info=exc,
+            )
+        else:
+            self.logger.warning(
+                "The FlowRunSuspendingObserver websocket closed. Switching to polling mode.",
+            )
+
+        self._polling_task = asyncio.create_task(
+            critical_service_loop(
+                workload=self._check_for_suspended_flow_runs,
+                interval=self.polling_interval,
+                jitter_range=0.3,
+            )
+        )
+        self._polling_task.add_done_callback(self._handle_polling_task_done)
+
+    def _handle_polling_task_done(self, task: asyncio.Task[None]):
+        if task.exception():
+            self.logger.error(
+                "Suspension polling task failed. Execution will continue, but external flow run suspension will fail.",
+                exc_info=task.exception(),
+            )
+            if self.on_failure is not None:
+                self.on_failure(self._in_flight_flow_run_ids.copy())
+        else:
+            self.logger.debug("Polling task completed")
+
+    async def _check_for_suspended_flow_runs(self):
+        if self._is_shutting_down:
+            return
+        if self._client is None:
+            raise RuntimeError(
+                "Client not initialized. Please use `async with` to initialize the observer."
+            )
+
+        flow_run_ids = self._in_flight_flow_run_ids - self._suspended_flow_run_ids
+        if not flow_run_ids:
+            return
+
+        self.logger.debug("Checking for suspended flow runs")
+        suspended_flow_runs = await self._client.read_flow_runs(
+            flow_run_filter=FlowRunFilter(
+                state=FlowRunFilterState(
+                    type=FlowRunFilterStateType(any_=[StateType.PAUSED]),
+                    name=FlowRunFilterStateName(any_=["Suspended"]),
+                ),
+                id=FlowRunFilterId(any_=list(flow_run_ids)),
+            ),
+        )
+
+        if suspended_flow_runs:
+            self.logger.info(
+                "Found %s flow runs awaiting suspension.", len(suspended_flow_runs)
+            )
+
+        for flow_run in suspended_flow_runs:
+            if flow_run.state:
+                self._suspended_flow_run_ids.add(flow_run.id)
+                self.on_suspended(flow_run.id, flow_run.state)
+
+    async def __aenter__(self):
+        try:
+            self._events_subscriber = await self._exit_stack.enter_async_context(
+                get_events_subscriber(filter=self._event_filter)
+            )
+        except Exception as e:
+            self.logger.warning(
+                "Failed to connect to the events stream. Falling back to polling "
+                "for suspension events. Reason: %s",
+                str(e),
+            )
+            self._events_subscriber = None
+
+        self._client = await self._exit_stack.enter_async_context(get_client())
+
+        if self._events_subscriber is not None:
+            self._consumer_task = asyncio.create_task(self._consume_events())
+            self._consumer_task.add_done_callback(self._start_polling_task)
+        else:
+            self._polling_task = asyncio.create_task(
+                critical_service_loop(
+                    workload=self._check_for_suspended_flow_runs,
+                    interval=self.polling_interval,
+                    jitter_range=0.3,
+                )
+            )
+            self._polling_task.add_done_callback(self._handle_polling_task_done)
+
+        return self
+
+    async def __aexit__(self, *exc_info: Any):
+        self.logger.debug("Shutting down FlowRunSuspendingObserver")
+        self._is_shutting_down = True
+        await self._exit_stack.__aexit__(*exc_info)
+        if self._consumer_task is not None:
+            self._consumer_task.cancel()
+            try:
+                await self._consumer_task
+            except asyncio.CancelledError:
+                pass
+            except Exception:
+                self.logger.warning(
+                    "Consumer task exited with exception", exc_info=True
+                )
+                pass
+
+        if self._polling_task is not None:
+            self._polling_task.cancel()
+            try:
+                await self._polling_task
+            except asyncio.CancelledError:
+                pass
+            except Exception:
+                self.logger.warning("Polling task exited with exception", exc_info=True)
+                pass

{prefect_client-3.7.1.dev2 → prefect_client-3.7.1.dev3}/src/prefect/bundles/__init__.py

@@ -539,7 +539,7 @@ def _extract_and_run_flow(
         env: The environment to use when running the flow.
     """
 
-    os.environ.update(sanitize_subprocess_env(env))
+    os.environ.update(sanitize_subprocess_env(env, remove_from=os.environ))
     # TODO: make this a thing we can pass directly to the engine
     os.environ["PREFECT__ENABLE_CANCELLATION_AND_CRASHED_HOOKS"] = "false"
     settings_context = get_settings_context()

{prefect_client-3.7.1.dev2 → prefect_client-3.7.1.dev3}/src/prefect/client/AGENTS.md

@@ -10,6 +10,7 @@ HTTP client for communicating with Prefect server and Prefect Cloud.
 - **Client schemas are separate from server schemas.** This module has its own `schemas/` to avoid tangling with `server/schemas/`. Keep the boundary clean.
 - **Do not import server-only modules** (`server/database`, `server/models`, etc.) from anything in this directory — it would break the `prefect-client` package build.
 - **Task-run submission schemas must be eagerly rebuilt.** Schemas instantiated on the concurrent submission path (`Task.create_local_run()`) are rebuilt at import time via `model_rebuild()` at the bottom of `schemas/objects.py`. Pydantic defers schema construction to first use; under threadpool contention, multiple workers race to build the same schema simultaneously. If you add a new schema used in this hot path, add a corresponding `model_rebuild()` call there.
+- **`schemas/worker_channel.py` is a versioned cross-system protocol contract.** It defines the `work_pool_worker_channel.v1` WebSocket handshake shared between workers and server — both sides must stay in sync. `WorkerChannelAuthRequest`/`WorkerChannelAuthSuccess` are pre-handshake and deliberately excluded from the `WorkerChannelApplicationFrame` union; `validate_worker_channel_frame()` will reject them. All frame models use `extra="forbid"`, so adding a new field to an existing frame requires a new version string, not just a field addition. Cloud authorization details are intentionally excluded from this shared contract.
 
 ## Structure