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

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev3}/.gitignore

@@ -54,6 +54,8 @@ src/mkdocs-material
 # UI artifacts
 src/prefect/server/ui/*
 src/prefect/server/ui_build/*
+src/prefect/server/ui-v2/*
+src/prefect/server/ui_v2_build/*
 **/node_modules
 
 # Databases

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.6.30.dev2
+Version: 3.6.30.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.6.30.dev3/hatch_build.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+try:
+    from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+except ModuleNotFoundError:  # pragma: no cover - only used when testing helpers
+
+    class BuildHookInterface:  # type: ignore[no-redef]
+        root: str
+        target_name: str
+
+
+PACKAGED_UI_INDEX_FILES = (
+    Path("src/prefect/server/ui/index.html"),
+    Path("src/prefect/server/ui-v2/index.html"),
+)
+REQUIRE_PACKAGED_UI_ENV_VAR = "PREFECT_REQUIRE_PACKAGED_UI_BUNDLES"
+
+
+def _truthy_env_var(name: str) -> bool:
+    return os.environ.get(name, "").lower() not in {"", "0", "false", "no", "off"}
+
+
+def should_validate_packaged_ui_index_files(root: str | Path) -> bool:
+    if _truthy_env_var(REQUIRE_PACKAGED_UI_ENV_VAR):
+        return True
+
+    root_path = Path(root)
+    return any(
+        (root_path / index_file.parent).exists()
+        for index_file in PACKAGED_UI_INDEX_FILES
+    )
+
+
+def validate_packaged_ui_index_files(root: str | Path) -> None:
+    root_path = Path(root)
+    missing_index_files = [
+        str(index_file)
+        for index_file in PACKAGED_UI_INDEX_FILES
+        if not (root_path / index_file).is_file()
+    ]
+
+    if missing_index_files:
+        raise RuntimeError(
+            "Prefect package builds require both UI bundles to be built. "
+            "Missing index.html files: "
+            f"{', '.join(missing_index_files)}"
+        )
+
+
+class CustomBuildHook(BuildHookInterface):
+    def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+        if (
+            version != "editable"
+            and self.target_name in {"sdist", "wheel"}
+            and should_validate_packaged_ui_index_files(self.root)
+        ):
+            validate_packaged_ui_index_files(self.root)

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

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.6.30.dev3"
+__build_date__ = "2026-05-05 08:51:50.984328+00:00"
+__git_commit__ = "39cb01298f84ceabc816f0beb3696849f412d313"
+__dirty__ = False

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev3}/src/prefect/client/orchestration/__init__.py

@@ -110,6 +110,8 @@ from prefect.client.schemas.objects import (
     FlowRunResult,
     Parameter,
     Constant,
+    ServerDefaultResultStorage,
+    ServerDefaultResultStorageUpdate,
     TaskRunPolicy,
     WorkQueue,
     WorkQueueStatusDetail,
@@ -1079,6 +1081,27 @@ class PrefectClient(
         res = await self._client.get("/admin/version")
         return res.json()
 
+    async def read_server_default_result_storage(
+        self,
+    ) -> ServerDefaultResultStorage:
+        response = await self._client.get("/admin/storage")
+        return ServerDefaultResultStorage.model_validate(response.json())
+
+    async def update_server_default_result_storage(
+        self,
+        default_result_storage_block_id: UUID,
+    ) -> ServerDefaultResultStorage:
+        response = await self._client.put(
+            "/admin/storage",
+            json=ServerDefaultResultStorageUpdate(
+                default_result_storage_block_id=default_result_storage_block_id
+            ).model_dump(mode="json"),
+        )
+        return ServerDefaultResultStorage.model_validate(response.json())
+
+    async def clear_server_default_result_storage(self) -> None:
+        await self._client.delete("/admin/storage")
+
     def client_version(self) -> str:
         return prefect.__version__
 
@@ -1451,6 +1474,25 @@ class SyncPrefectClient(
         res = self._client.get("/admin/version")
         return res.json()
 
+    def read_server_default_result_storage(self) -> ServerDefaultResultStorage:
+        response = self._client.get("/admin/storage")
+        return ServerDefaultResultStorage.model_validate(response.json())
+
+    def update_server_default_result_storage(
+        self,
+        default_result_storage_block_id: UUID,
+    ) -> ServerDefaultResultStorage:
+        response = self._client.put(
+            "/admin/storage",
+            json=ServerDefaultResultStorageUpdate(
+                default_result_storage_block_id=default_result_storage_block_id
+            ).model_dump(mode="json"),
+        )
+        return ServerDefaultResultStorage.model_validate(response.json())
+
+    def clear_server_default_result_storage(self) -> None:
+        self._client.delete("/admin/storage")
+
     def client_version(self) -> str:
         return prefect.__version__
 

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev3}/src/prefect/client/orchestration/routes.py

@@ -1,6 +1,7 @@
 from typing import Literal
 
 ServerRoutes = Literal[
+    "/admin/storage",
     "/admin/settings",
     "/admin/version",
     "/artifacts/",

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev3}/src/prefect/client/schemas/objects.py

@@ -1550,6 +1550,24 @@ class WorkPoolStorageConfiguration(PrefectBaseModel):
     )
 
 
+class ServerDefaultResultStorage(PrefectBaseModel):
+    """Server-side default result storage configuration."""
+
+    default_result_storage_block_id: Optional[UUID] = Field(
+        default=None,
+        description="The block document ID of the server default result storage block.",
+    )
+
+
+class ServerDefaultResultStorageUpdate(PrefectBaseModel):
+    """Request payload for setting the server default result storage block."""
+
+    default_result_storage_block_id: UUID = Field(
+        default=...,
+        description="The block document ID of the server default result storage block.",
+    )
+
+
 class WorkPool(ObjectBaseModel):
     """An ORM representation of a work pool"""
 

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

@@ -23,6 +23,8 @@ Built-in steps:
 - `steps/pull.py` — `git_clone`, `set_working_directory`, `pull_from_remote_storage`
 - `steps/utility.py` — `run_shell_script`, `pip_install_requirements`
 
+**Step observer**: `run_steps` does not accept a step completion callback as a parameter by design — inject one via `_observe_step_completion(callback)` context manager from `steps/core.py`. The callback receives `(step, output, cwd_before, cwd_after)` after each step; either CWD arg is `None` when the directory becomes inaccessible (e.g., the step deleted its working directory).
+
 ## Entrypoint Formats
 
 `runner.py`'s `from_storage` / `afrom_storage` (and `Flow.from_source`) support two entrypoint formats:

{prefect_client-3.6.30.dev2 → prefect_client-3.6.30.dev3}/src/prefect/deployments/steps/core.py

@@ -17,8 +17,12 @@ import os
 import re
 import subprocess
 import warnings
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
 from copy import deepcopy
 from importlib import import_module
+from pathlib import Path
 from typing import Any
 from uuid import UUID
 
@@ -39,6 +43,15 @@ from prefect.utilities.templating import (
 
 RESERVED_KEYWORDS = {"id", "requires"}
 
+_StepCompletionObserver = Callable[
+    [dict[str, Any], Any, Path | None, Path | None],
+    None,
+]
+_STEP_COMPLETION_OBSERVER: ContextVar[_StepCompletionObserver | None] = ContextVar(
+    "step_completion_observer",
+    default=None,
+)
+
 
 class StepExecutionError(Exception):
     """
@@ -46,6 +59,22 @@ class StepExecutionError(Exception):
     """
 
 
+def _safe_current_working_directory() -> Path | None:
+    try:
+        return Path.cwd().resolve()
+    except OSError:
+        return None
+
+
+@contextmanager
+def _observe_step_completion(callback: _StepCompletionObserver) -> Iterator[None]:
+    token = _STEP_COMPLETION_OBSERVER.set(callback)
+    try:
+        yield
+    finally:
+        _STEP_COMPLETION_OBSERVER.reset(token)
+
+
 def _strip_version(requirement: str) -> str:
     """
     Strips the version from a requirement string.
@@ -152,6 +181,7 @@ async def run_steps(
     logger: Any | None = None,
 ) -> dict[str, Any]:
     upstream_outputs = deepcopy(upstream_outputs) if upstream_outputs else {}
+    step_completion_observer = _STEP_COMPLETION_OBSERVER.get()
     for step_index, step in enumerate(steps):
         if not step:
             continue
@@ -177,6 +207,11 @@ async def run_steps(
 
         try:
             # catch warnings to ensure deprecation warnings are printed
+            step_start_cwd = (
+                _safe_current_working_directory()
+                if step_completion_observer is not None
+                else None
+            )
             with warnings.catch_warnings(record=True) as w:
                 warnings.simplefilter(
                     "always",
@@ -201,6 +236,14 @@ async def run_steps(
                             print_function(message)
                         printed_messages.append(message)
 
+            if step_completion_observer is not None:
+                step_completion_observer(
+                    step,
+                    step_output,
+                    step_start_cwd,
+                    _safe_current_working_directory(),
+                )
+
             if not isinstance(step_output, dict):
                 if PREFECT_DEBUG_MODE:
                     get_logger().warning(

prefect_client-3.6.30.dev3/src/prefect/locking/_filelock.py

@@ -0,0 +1,242 @@
+"""Internal cross-platform file lock using lock file creation.
+
+Uses the existence of a lock file to indicate the lock is held, following
+the same pattern as FileSystemLockManager. The lock file is created
+atomically and removed on release. No OS-specific locking primitives are
+required.
+
+The owning process's PID is written to the lock file so that stale locks
+left behind by crashed processes can be detected and recovered.
+"""
+
+import asyncio
+import os
+import sys
+import tempfile
+import time
+from pathlib import Path
+
+
+def _is_pid_alive(pid: int) -> bool:
+    """Check whether a process with the given PID is still running.
+
+    Uses `os.kill(pid, 0)` on Unix (harmless signal-0 probe).  On Windows
+    `os.kill` terminates the target process, so we use
+    `kernel32.OpenProcess` instead.
+    """
+    if sys.platform == "win32":
+        import ctypes
+
+        _PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+        handle = ctypes.windll.kernel32.OpenProcess(  # type: ignore[attr-defined]
+            _PROCESS_QUERY_LIMITED_INFORMATION, False, pid
+        )
+        if handle:
+            ctypes.windll.kernel32.CloseHandle(handle)  # type: ignore[attr-defined]
+            return True
+        return False
+
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except OSError:
+        # PermissionError means the process exists but we can't signal it
+        return True
+    return True
+
+
+_STALE_EMPTY_THRESHOLD = 5  # seconds before an empty/malformed lock is stale
+
+
+def _remove_stale_lock(path: Path) -> None:
+    """Remove the lock file if the owning process is no longer alive.
+
+    For empty or malformed lock files (e.g. from a writer that crashed
+    between creating the file and writing the PID), the file's mtime is
+    checked: if it was last modified more than _STALE_EMPTY_THRESHOLD
+    seconds ago the writer must have crashed, so the file is removed.
+    If the mtime is recent the writer may still be running, so the file
+    is left alone and the poll loop will retry.
+
+    To avoid a TOCTOU race where another waiter removes the stale file
+    and acquires a new lock between our read and our unlink, we record
+    the file's inode before deciding it is stale and verify it has not
+    changed before unlinking.
+    """
+    try:
+        st = os.stat(str(path))
+        contents = path.read_text().strip()
+    except (FileNotFoundError, OSError):
+        return
+
+    original_ino = st.st_ino
+
+    if not contents:
+        # Empty file -- check mtime to decide if the writer crashed.
+        _remove_if_same(path, original_ino, st.st_mtime)
+        return
+
+    try:
+        pid = int(contents)
+    except ValueError:
+        # Malformed content -- check mtime to decide if the writer crashed.
+        _remove_if_same(path, original_ino, st.st_mtime)
+        return
+
+    if not _is_pid_alive(pid):
+        _unlink_if_same_inode(path, original_ino)
+
+
+def _remove_if_same(path: Path, original_ino: int, mtime: float) -> None:
+    """Remove *path* if mtime is stale and the inode has not changed."""
+    if time.time() - mtime > _STALE_EMPTY_THRESHOLD:
+        _unlink_if_same_inode(path, original_ino)
+
+
+def _unlink_if_same_inode(path: Path, expected_ino: int) -> None:
+    """Unlink *path* only if its current inode matches *expected_ino*.
+
+    This prevents removing a fresh lock file that was created by another
+    process between our staleness check and the unlink call.
+    """
+    try:
+        current_st = os.stat(str(path))
+    except (FileNotFoundError, OSError):
+        return
+    if current_st.st_ino == expected_ino:
+        path.unlink(missing_ok=True)
+
+
+def _write_lock(path: Path) -> None:
+    """Atomically create the lock file with the current PID.
+
+    Writes the PID to a temporary file in the same directory and then
+    uses `os.rename` (atomic on POSIX, atomic on Windows for same
+    volume) to move it into place.  This guarantees the lock file is
+    never visible in an empty or partial state, which prevents a
+    concurrent `_remove_stale_lock` from falsely treating it as stale.
+
+    Raises `FileExistsError` if the lock file already exists (via
+    `os.link` on POSIX for true atomic create-or-fail, or
+    `os.open(O_CREAT | O_EXCL)` as a fallback on filesystems without
+    hard-link support).
+    """
+    # Ensure the parent directory exists so that mkstemp and the lock
+    # file can be created even when the storage base path is fresh.
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Write PID to a temp file in the same directory so rename stays
+    # on the same filesystem.
+    fd, tmp = tempfile.mkstemp(dir=str(path.parent), prefix=".lock_")
+    try:
+        os.write(fd, str(os.getpid()).encode())
+        os.close(fd)
+        fd = -1  # mark as closed
+        # Use os.link (hard link) to atomically claim the lock path.
+        # If the target already exists, this raises FileExistsError.
+        try:
+            os.link(tmp, str(path))
+        except FileExistsError:
+            raise
+        except OSError:
+            # Fallback for filesystems that don't support hard links
+            # (e.g. some Windows or network mounts): use O_CREAT|O_EXCL
+            # which is atomic on all POSIX and Windows filesystems.
+            try:
+                excl_fd = os.open(str(path), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            except FileExistsError:
+                raise
+            try:
+                os.write(excl_fd, str(os.getpid()).encode())
+            finally:
+                os.close(excl_fd)
+            return
+    finally:
+        if fd >= 0:
+            os.close(fd)
+        # Always clean up the temp file (link created a second entry)
+        try:
+            os.unlink(tmp)
+        except FileNotFoundError:
+            pass
+
+
+class FileLock:
+    """A cross-platform file lock using lock file existence.
+
+    Can be used as a synchronous context manager or with the async
+    aacquire/release pair. The lock file stores the owning process's
+    PID so that stale locks from crashed processes are automatically
+    recovered.
+
+    Args:
+        path: Path to the lock file.
+        timeout: Maximum seconds to wait for lock acquisition.
+            Use -1 to wait indefinitely. Defaults to -1.
+        poll_interval: Seconds between lock attempts.
+            Defaults to 0.1.
+    """
+
+    def __init__(
+        self,
+        path: str | Path,
+        timeout: float = -1,
+        poll_interval: float = 0.1,
+    ) -> None:
+        self._path = Path(path)
+        self._timeout = timeout
+        self._poll_interval = poll_interval
+        self._locked = False
+
+    def acquire(self) -> None:
+        """Acquire the file lock, blocking until available or timeout."""
+        start = time.monotonic()
+        while True:
+            try:
+                _write_lock(self._path)
+                self._locked = True
+                return
+            except FileExistsError:
+                _remove_stale_lock(self._path)
+                elapsed = time.monotonic() - start
+                if self._timeout >= 0 and elapsed >= self._timeout:
+                    raise TimeoutError(
+                        f"Failed to acquire lock on {str(self._path)!r}"
+                        f" within {self._timeout}s"
+                    )
+                time.sleep(self._poll_interval)
+
+    async def aacquire(self) -> None:
+        """Acquire the file lock without blocking the event loop."""
+        start = time.monotonic()
+        while True:
+            try:
+                _write_lock(self._path)
+                self._locked = True
+                return
+            except FileExistsError:
+                _remove_stale_lock(self._path)
+                elapsed = time.monotonic() - start
+                if self._timeout >= 0 and elapsed >= self._timeout:
+                    raise TimeoutError(
+                        f"Failed to acquire lock on {str(self._path)!r}"
+                        f" within {self._timeout}s"
+                    )
+                await asyncio.sleep(self._poll_interval)
+
+    def release(self) -> None:
+        """Release the file lock."""
+        if self._locked:
+            self._path.unlink(missing_ok=True)
+            self._locked = False
+
+    def __enter__(self) -> "FileLock":
+        self.acquire()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.release()
+
+    def __del__(self) -> None:
+        self.release()

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

@@ -23,6 +23,7 @@ Thin facade over single-responsibility extracted classes. New behavior belongs i
 | FlowRunExecutorContext | _flow_run_executor.py | Async context manager for one-shot execution outside Runner (CLI, bundles) |
 | DirectSubprocessStarter | _starter_direct.py | Runs Flow object via run_flow_in_subprocess |
 | EngineCommandStarter | _starter_engine.py | Spawns `python -m prefect.engine` subprocess |
+| WorkspaceResolvingEngineCommandStarter | _workspace_starter.py | Resolves workspace (pull steps) via `_workspace_resolver` subprocess then delegates to EngineCommandStarter; used by `prefect flow-run execute` |
 | BundleExecutionStarter | _starter_bundle.py | Executes serialized bundle in SpawnProcess |
 
 ## Key Contracts
@@ -40,7 +41,7 @@ Thin facade over single-responsibility extracted classes. New behavior belongs i
 - `_flow_run_process_map` dict -- replaced by ProcessManager
 - `_kill_process()` -- replaced by ProcessManager.kill()
 - `_run_on_crashed_hooks()` / `_run_on_cancellation_hooks()` -- replaced by HookRunner
-- `execute_flow_run()` -- deprecated (Mar 2026); use `FlowRunExecutorContext` + `EngineCommandStarter`
+- `execute_flow_run()` -- deprecated (Mar 2026); use `FlowRunExecutorContext` + `WorkspaceResolvingEngineCommandStarter`
 - `execute_bundle()` -- deprecated (Mar 2026); use `execute_bundle()` from `prefect._experimental.bundles.execute`
 - `reschedule_current_flow_runs()` -- deprecated (Mar 2026); SIGTERM rescheduling is now handled inline by the CLI execute path
 
@@ -123,6 +124,20 @@ This matters because `get_directory` typically calls `shutil.copytree(..., dirs_
 
 These validations exist to prevent git argument injection. Do not bypass them when constructing `GitRepository` programmatically.
 
+## GitRepository Concurrent Pull Protection
+
+`GitRepository.pull_code()` serializes concurrent calls via a `FileLock` (`prefect.locking._filelock`). The lock file sits adjacent to the destination: `destination.parent / (destination.name + ".lock")`. Stale locks from crashed processes are recovered automatically via PID check. Tests that broadly monkeypatch `pathlib.Path.exists` must account for this lock file being created next to the destination.
+
+## Workspace Resolver Subprocess
+
+`_workspace_resolver.py` prepares a flow run workspace in an isolated subprocess (storage pull, pull steps, CWD/env/sys.path capture). Runs as `python -m prefect.runner._workspace_resolver`.
+
+**Stdout is reserved for the JSON `PreparedWorkspaceResult` payload only.** Pull step output (including inherited stdout from child processes) is redirected to stderr. Parse `process.stdout` for the result, `process.stderr` for diagnostics. Violating this breaks callers silently.
+
+**Caller-facing API:** Use `WorkspaceResolvingEngineCommandStarter` (`_workspace_starter.py`) rather than calling the resolver directly. It wraps the subprocess call, memoizes the resolved workspace (one subprocess call per starter instance), and provides `resolve_flow()` that loads the flow inside the resolved workspace context. Pass `starter.resolve_flow` as the `resolve_flow` argument to `FlowRunExecutorContext.create_executor()` — using a separate lambda bypasses the workspace context and will fail to find the flow.
+
+**Env/sys.path isolation:** `_prepared_workspace_context` mutates `os.environ` and `sys.path` in the caller process but does NOT change `os.getcwd()`. The parent working directory is preserved.
+
 ## Reference
 
 Full refactor design and rationale: plans/completed/2026-02-18-runner-refactor.md