prefect-client 3.8.3.dev3__tar.gz → 3.8.4.dev2__tar.gz

{prefect_client-3.8.3.dev3 → prefect_client-3.8.4.dev2}/PKG-INFO

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

prefect_client-3.8.4.dev2/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.8.4.dev2"
+__build_date__ = "2026-08-18 08:12:49.074361+00:00"
+__git_commit__ = "ed602f1862dbad4820c985fefae1c6175a38e491"
+__dirty__ = False

prefect_client-3.8.4.dev2/src/prefect/_internal/attempt_control.py

@@ -0,0 +1,158 @@
+"""Shared types and wire framing for the internal Attempt Control Session."""
+
+from __future__ import annotations
+
+import json
+import struct
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal, TypeAlias
+from uuid import UUID
+
+Intent = Literal["cancel", "reschedule", "relinquish"]
+
+BYTE_FOR_INTENT: dict[Intent, bytes] = {
+    "cancel": b"c",
+    "reschedule": b"r",
+    "relinquish": b"q",
+}
+INTENT_FOR_BYTE: dict[bytes, Intent] = {
+    value: key for key, value in BYTE_FOR_INTENT.items()
+}
+
+LEGACY_PROTOCOL_VERSION = 1
+CURRENT_PROTOCOL_VERSION = 2
+RECEIPT_CAPABILITY = 1 << 0
+
+# The child-initiated hello deliberately contains no legacy acknowledgement byte
+# (`b"a"`), so a version-one supervisor can safely ignore it.
+NEGOTIATION_PREFIX = b"\x00PF"
+NEGOTIATION_FRAME_SIZE = len(NEGOTIATION_PREFIX) + 2
+RECEIPT_PREFIX = b"\x01"
+RECEIPT_ACK = b"\x02"
+MAX_RECEIPT_SIZE = 4096
+
+
+class EngineDisposition(str, Enum):
+    STATE_REPORTED = "STATE_REPORTED"
+    ORCHESTRATION_ABORTED = "ORCHESTRATION_ABORTED"
+
+
+@dataclass(frozen=True)
+class EngineOutcomeReceipt:
+    """Sanitized evidence that an engine concluded an execution attempt."""
+
+    disposition: EngineDisposition
+    state_id: UUID | None = None
+    state_type: str | None = None
+    state_name: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.disposition, EngineDisposition):
+            raise TypeError("Receipt disposition must be an EngineDisposition")
+        state_fields = (self.state_id, self.state_type, self.state_name)
+        if self.disposition is EngineDisposition.STATE_REPORTED:
+            if any(value is None for value in state_fields):
+                raise ValueError("STATE_REPORTED receipts require all state fields")
+            if not isinstance(self.state_id, UUID):
+                raise TypeError("Receipt state ID must be a UUID")
+            if not isinstance(self.state_type, str) or not isinstance(
+                self.state_name, str
+            ):
+                raise TypeError("Receipt state type and name must be strings")
+            if not self.state_type:
+                raise ValueError("Receipt state type must not be empty")
+            if len(self.state_type) > 64:
+                raise ValueError("Receipt state type is too long")
+        elif any(value is not None for value in state_fields):
+            raise ValueError(
+                "ORCHESTRATION_ABORTED receipts cannot include state fields"
+            )
+
+    @classmethod
+    def state_reported(
+        cls, *, state_id: UUID, state_type: str, state_name: str
+    ) -> EngineOutcomeReceipt:
+        return cls(
+            disposition=EngineDisposition.STATE_REPORTED,
+            state_id=state_id,
+            state_type=state_type,
+            state_name=state_name,
+        )
+
+    @classmethod
+    def orchestration_aborted(cls) -> EngineOutcomeReceipt:
+        return cls(disposition=EngineDisposition.ORCHESTRATION_ABORTED)
+
+
+@dataclass(frozen=True)
+class StateOwnershipDelegation:
+    """Evidence that the supervisor's acknowledged control intent won."""
+
+    intent: Intent
+
+
+AttemptConclusion: TypeAlias = EngineOutcomeReceipt | StateOwnershipDelegation
+
+
+def encode_negotiation(version: int, capabilities: int) -> bytes:
+    if not 0 <= version <= 255 or not 0 <= capabilities <= 255:
+        raise ValueError("Protocol version and capabilities must fit in one byte")
+    return NEGOTIATION_PREFIX + bytes((version, capabilities))
+
+
+def decode_negotiation(frame: bytes) -> tuple[int, int]:
+    if len(frame) != NEGOTIATION_FRAME_SIZE or not frame.startswith(NEGOTIATION_PREFIX):
+        raise ValueError("Malformed Attempt Control Session negotiation")
+    return frame[-2], frame[-1]
+
+
+def encode_receipt(receipt: EngineOutcomeReceipt) -> bytes:
+    payload: dict[str, str] = {"disposition": receipt.disposition.value}
+    if receipt.disposition is EngineDisposition.STATE_REPORTED:
+        assert receipt.state_id is not None
+        assert receipt.state_type is not None
+        assert receipt.state_name is not None
+        payload.update(
+            {
+                "state_id": str(receipt.state_id),
+                "state_type": receipt.state_type,
+                "state_name": receipt.state_name,
+            }
+        )
+    encoded = json.dumps(payload, separators=(",", ":"), sort_keys=True).encode()
+    if len(encoded) > MAX_RECEIPT_SIZE:
+        raise ValueError("Receipt payload is too large")
+    return RECEIPT_PREFIX + struct.pack("!I", len(encoded)) + encoded
+
+
+def decode_receipt(payload: bytes) -> EngineOutcomeReceipt:
+    if len(payload) > MAX_RECEIPT_SIZE:
+        raise ValueError("Receipt payload is too large")
+    try:
+        decoded = json.loads(payload)
+    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+        raise ValueError("Malformed receipt payload") from exc
+    if not isinstance(decoded, dict):
+        raise TypeError("Receipt payload must be an object")
+
+    try:
+        disposition = EngineDisposition(decoded["disposition"])
+    except (KeyError, TypeError, ValueError) as exc:
+        raise ValueError("Receipt disposition is invalid") from exc
+
+    if disposition is EngineDisposition.ORCHESTRATION_ABORTED:
+        if set(decoded) != {"disposition"}:
+            raise ValueError("Aborted receipt contains unexpected fields")
+        return EngineOutcomeReceipt.orchestration_aborted()
+
+    if set(decoded) != {"disposition", "state_id", "state_type", "state_name"}:
+        raise ValueError("State receipt fields are invalid")
+    try:
+        return EngineOutcomeReceipt.state_reported(
+            state_id=UUID(decoded["state_id"]),
+            state_type=decoded["state_type"],
+            state_name=decoded["state_name"],
+        )
+    except (AttributeError, TypeError, ValueError) as exc:
+        raise ValueError("State receipt fields are invalid") from exc

prefect_client-3.8.4.dev2/src/prefect/_internal/control_listener.py

@@ -0,0 +1,457 @@
+"""
+Child side of the internal Attempt Control Session.
+
+This module is intentionally small. It only supports steady-state graceful
+control delivery after Prefect has already installed its SIGTERM bridge via
+`capture_sigterm()`.
+
+The version-one protocol remains intact: the supervisor sends one-byte control
+intents and the child acknowledges a committed intent with `b"a"`. Version-two
+peers additionally negotiate outcome receipts over the same authenticated,
+full-duplex loopback connection.
+
+Session outline:
+
+1. The runner injects `PREFECT__CONTROL_PORT` and `PREFECT__CONTROL_TOKEN`
+   into the child environment.
+2. Process entrypoints call `configure_from_env()` early to consume those
+   one-shot env vars without connecting yet.
+3. The outermost `capture_sigterm()` calls `start()`, which connects back to
+   the runner and spawns a daemon thread blocked on the socket.
+4. The child sends a reserved negotiation hello. A version-one supervisor
+   ignores it; a version-two supervisor selects the protocol and capabilities.
+5. The first terminal exchange is either an existing control intent plus
+   `b"a"`, or a structured engine outcome receipt plus a receipt ack.
+6. For control, the runner then sends its normal external termination signal.
+   On POSIX, that real `SIGTERM` remains the only trigger that interrupts
+   blocking code.
+
+If the child is not connected yet, or can no longer safely acknowledge the
+intent, the runner sees no ack and falls back to its existing crash-style
+termination path. There is deliberately no startup-time graceful cancellation
+contract in this implementation.
+"""
+
+from __future__ import annotations
+
+import _thread
+import os
+import signal
+import socket
+import threading
+import time
+
+from prefect._internal.attempt_control import (
+    CURRENT_PROTOCOL_VERSION,
+    INTENT_FOR_BYTE,
+    NEGOTIATION_FRAME_SIZE,
+    NEGOTIATION_PREFIX,
+    RECEIPT_ACK,
+    RECEIPT_CAPABILITY,
+    EngineOutcomeReceipt,
+    Intent,
+    decode_negotiation,
+    encode_negotiation,
+    encode_receipt,
+)
+from prefect.logging import get_logger
+from prefect.utilities.engine import commit_control_intent_and_ack
+
+_NEGOTIATION_PROBE_TIMEOUT = 0.25
+_NEGOTIATION_RESPONSE_TIMEOUT = 1.0
+_RECEIPT_ACK_TIMEOUT = 1.0
+
+_logger = get_logger(__name__)
+
+_intent: Intent | None = None
+_intent_lock = threading.Lock()
+
+_configured = False
+_configured_port: int | None = None
+_configured_token: str | None = None
+
+_started = False
+_started_lock = threading.Lock()
+_owner_thread_id: int | None = None
+_socket: socket.socket | None = None
+_reader_thread: threading.Thread | None = None
+_send_lock = threading.Lock()
+_negotiation_complete = threading.Event()
+_negotiation_deadline: float | None = None
+_receipt_acked = threading.Event()
+_receipt_capable = False
+_terminal_lock = threading.Lock()
+_terminal_claimed = False
+_receipt_in_flight = False
+_outcome_report_started = False
+_engine_outcome_handled = False
+
+
+def get_intent() -> Intent | None:
+    """Return the committed control intent, if any."""
+    with _intent_lock:
+        return _intent
+
+
+def engine_outcome_is_handled() -> bool:
+    """Return whether the engine concluded the current execution attempt."""
+    return _engine_outcome_handled
+
+
+def _set_intent(value: Intent) -> None:
+    global _intent
+    with _intent_lock:
+        _intent = value
+
+
+def _clear_intent() -> None:
+    global _intent
+    with _intent_lock:
+        _intent = None
+
+
+def clear_intent() -> None:
+    """Clear the committed control intent after the current session consumes it."""
+    _clear_intent()
+
+
+def configure_from_env() -> None:
+    """Consume one-shot control-channel env vars without connecting yet."""
+    global _configured, _configured_port, _configured_token, _engine_outcome_handled
+
+    with _started_lock:
+        if _configured:
+            return
+
+        _configured = True
+        _engine_outcome_handled = False
+        port_str = os.environ.pop("PREFECT__CONTROL_PORT", None)
+        token = os.environ.pop("PREFECT__CONTROL_TOKEN", None)
+        if not port_str or not token:
+            return
+
+        try:
+            _configured_port = int(port_str)
+        except ValueError:
+            _configured_port = None
+            _configured_token = None
+            return
+
+        _configured_token = token
+
+
+def _acknowledge_intent(sock: socket.socket, intent: Intent) -> bool:
+    """Commit intent and acknowledge it to the runner."""
+    return commit_control_intent_and_ack(
+        commit_intent=lambda: _set_intent(intent),
+        clear_intent=_clear_intent,
+        send_ack=lambda: sock.sendall(b"a"),
+        trigger_cancel=(
+            (lambda: _thread.interrupt_main(signal.SIGTERM))
+            if os.name == "nt"
+            else None
+        ),
+    )
+
+
+def _send(sock: socket.socket, data: bytes) -> None:
+    with _send_lock:
+        sock.sendall(data)
+
+
+def _recv_exactly(sock: socket.socket, size: int) -> bytes:
+    chunks = bytearray()
+    while len(chunks) < size:
+        chunk = sock.recv(size - len(chunks))
+        if not chunk:
+            raise OSError("Control session closed")
+        chunks.extend(chunk)
+    return bytes(chunks)
+
+
+def _receive_negotiation_response(sock: socket.socket, first: bytes) -> None:
+    """Apply one complete negotiation response from the supervisor."""
+    global _receipt_capable
+
+    response = first + _recv_exactly(sock, NEGOTIATION_FRAME_SIZE - 1)
+    version, capabilities = decode_negotiation(response)
+    _receipt_capable = (
+        version == CURRENT_PROTOCOL_VERSION and capabilities & RECEIPT_CAPABILITY != 0
+    )
+    _negotiation_complete.set()
+    _logger.debug(
+        "Attempt control negotiation selected protocol %d with receipt support %s",
+        version,
+        _receipt_capable,
+    )
+
+
+def _handle_intent_byte(sock: socket.socket, data: bytes) -> bool | None:
+    """Handle an intent, returning whether the reader should close the session."""
+    global _terminal_claimed
+
+    intent = INTENT_FOR_BYTE.get(data)
+    if intent is None:
+        return None
+
+    # Serialize terminal writes so the wire order matches the local decision:
+    # an intent that claims this lock before receipt transmission wins, while
+    # an already-transmitted receipt remains authoritative.
+    with _send_lock, _terminal_lock:
+        if _terminal_claimed or _receipt_in_flight:
+            _logger.debug(
+                "Ignoring control intent after a terminal exchange has started"
+            )
+            return False
+        if _acknowledge_intent(sock, intent):
+            _terminal_claimed = True
+        return True
+
+
+def _reader_loop(sock: socket.socket) -> None:
+    """Negotiate receipt support, then handle session responses and intent."""
+    global _receipt_capable
+
+    negotiation_pending = True
+    try:
+        first = b""
+        try:
+            _send(
+                sock,
+                encode_negotiation(CURRENT_PROTOCOL_VERSION, RECEIPT_CAPABILITY),
+            )
+            sock.settimeout(_NEGOTIATION_PROBE_TIMEOUT)
+            first = sock.recv(1)
+            if not first:
+                return
+            intent_handled = _handle_intent_byte(sock, first)
+            if intent_handled is not None:
+                if intent_handled:
+                    return
+                first = b""
+            if first != NEGOTIATION_PREFIX[:1]:
+                _logger.warning("Attempt control negotiation response was malformed")
+                return
+            _receive_negotiation_response(sock, first)
+            negotiation_pending = False
+        except TimeoutError:
+            if first:
+                _logger.warning("Attempt control negotiation response was malformed")
+            # A version-one supervisor sends no response to the reserved hello.
+            # Keep accepting a late response so scheduler latency does not
+            # permanently downgrade a version-two peer.
+            _receipt_capable = False
+        except OSError:
+            # The owning context may close the socket while negotiation is blocked.
+            return
+        except ValueError:
+            _logger.warning("Attempt control negotiation response was malformed")
+            return
+        finally:
+            try:
+                sock.settimeout(None)
+            except OSError:
+                pass
+
+        while True:
+            try:
+                data = sock.recv(1)
+            except OSError:
+                return
+            if not data:
+                return
+            intent_handled = _handle_intent_byte(sock, data)
+            if intent_handled is not None:
+                if intent_handled:
+                    return
+                continue
+            if data == NEGOTIATION_PREFIX[:1] and negotiation_pending:
+                try:
+                    _receive_negotiation_response(sock, data)
+                except OSError:
+                    return
+                except ValueError:
+                    _logger.warning(
+                        "Attempt control negotiation response was malformed"
+                    )
+                    return
+                negotiation_pending = False
+                continue
+            if data == RECEIPT_ACK:
+                global _receipt_in_flight, _terminal_claimed
+                with _terminal_lock:
+                    if not _receipt_in_flight:
+                        _logger.debug(
+                            "Ignoring receipt acknowledgement after terminal exchange"
+                        )
+                        continue
+                    _receipt_in_flight = False
+                    _terminal_claimed = True
+                    _receipt_acked.set()
+                return
+            _logger.warning("Attempt control session received a malformed message")
+            return
+    finally:
+        _negotiation_complete.set()
+        try:
+            sock.close()
+        except OSError:
+            pass
+
+
+def report_engine_outcome(receipt: EngineOutcomeReceipt) -> bool:
+    """Send one negotiated outcome receipt without changing engine semantics."""
+    global _outcome_report_started, _receipt_in_flight, _engine_outcome_handled
+
+    if _owner_thread_id is not None and threading.get_ident() != _owner_thread_id:
+        _logger.debug(
+            "Ignoring engine outcome from a thread that does not own the control session"
+        )
+        return False
+
+    # The immediate first-party engine process treats a concluded attempt as
+    # successful infrastructure execution even when its supervisor cannot
+    # negotiate or acknowledge the optional receipt transport.
+    _engine_outcome_handled = True
+
+    sock = _socket
+    if sock is None:
+        return False
+
+    negotiation_deadline = _negotiation_deadline
+    if negotiation_deadline is not None:
+        _negotiation_complete.wait(max(0.0, negotiation_deadline - time.monotonic()))
+    if not _receipt_capable:
+        return False
+
+    try:
+        encoded_receipt = encode_receipt(receipt)
+    except ValueError:
+        _logger.warning("Failed to encode engine outcome receipt")
+        return False
+
+    try:
+        with _send_lock, _terminal_lock:
+            if _terminal_claimed or _outcome_report_started:
+                return False
+            _outcome_report_started = True
+            _receipt_in_flight = True
+            _receipt_acked.clear()
+            sock.sendall(encoded_receipt)
+    except OSError:
+        with _terminal_lock:
+            _receipt_in_flight = False
+        _logger.warning("Failed to send engine outcome receipt")
+        return False
+
+    if _receipt_acked.wait(_RECEIPT_ACK_TIMEOUT):
+        return True
+
+    with _terminal_lock:
+        _receipt_in_flight = False
+    _logger.warning("Engine outcome receipt was not acknowledged")
+    return False
+
+
+def start() -> None:
+    """Connect to the runner's control channel if bootstrap config is present."""
+    global _started, _owner_thread_id, _socket, _reader_thread, _receipt_capable
+    global _terminal_claimed, _receipt_in_flight, _outcome_report_started
+    global _negotiation_deadline
+
+    configure_from_env()
+
+    with _started_lock:
+        if _started:
+            return
+        if _configured_port is None or _configured_token is None:
+            return
+
+        # A new listener session must not inherit a committed intent from an
+        # earlier flow run in the same interpreter.
+        _clear_intent()
+        _negotiation_complete.clear()
+        _negotiation_deadline = None
+        _receipt_acked.clear()
+        _receipt_capable = False
+        with _terminal_lock:
+            _terminal_claimed = False
+            _receipt_in_flight = False
+            _outcome_report_started = False
+
+        try:
+            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+            sock.connect(("127.0.0.1", _configured_port))
+            sock.sendall(_configured_token.encode("ascii") + b"\n")
+        except OSError:
+            try:
+                sock.close()
+            except (OSError, UnboundLocalError):
+                pass
+            return
+
+        thread = threading.Thread(
+            target=_reader_loop,
+            args=(sock,),
+            name="prefect-control-listener",
+            daemon=True,
+        )
+        _socket = sock
+        _reader_thread = thread
+        _owner_thread_id = threading.get_ident()
+        _negotiation_deadline = time.monotonic() + _NEGOTIATION_RESPONSE_TIMEOUT
+        _started = True
+        thread.start()
+
+
+def stop() -> None:
+    """Close the active control connection, if any."""
+    global _configured, _configured_port, _configured_token
+    global _started, _owner_thread_id, _socket, _reader_thread, _receipt_capable
+    global _terminal_claimed, _receipt_in_flight, _outcome_report_started
+    global _negotiation_deadline
+
+    with _started_lock:
+        sock = _socket
+        _socket = None
+        _reader_thread = None
+        _owner_thread_id = None
+        _started = False
+        _configured = False
+        _configured_port = None
+        _configured_token = None
+        _receipt_capable = False
+        _negotiation_complete.clear()
+        _negotiation_deadline = None
+        _receipt_acked.clear()
+        with _terminal_lock:
+            _terminal_claimed = False
+            _receipt_in_flight = False
+            _outcome_report_started = False
+
+    if sock is not None:
+        try:
+            sock.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+        try:
+            sock.close()
+        except OSError:
+            pass
+
+
+def reset_for_testing() -> None:
+    """Reset module state. Tests only."""
+    global _intent, _configured, _configured_port, _configured_token
+    global _engine_outcome_handled
+
+    with _intent_lock:
+        _intent = None
+
+    stop()
+
+    with _started_lock:
+        _configured = False
+        _configured_port = None
+        _configured_token = None
+        _engine_outcome_handled = False

{prefect_client-3.8.3.dev3 → prefect_client-3.8.4.dev2}/src/prefect/engine.py

@@ -13,6 +13,7 @@ from prefect._internal.compatibility.migration import getattr_migration
 from prefect._internal.control_listener import (
     clear_intent,
     configure_from_env,
+    engine_outcome_is_handled,
     get_intent,
 )
 from prefect.exceptions import (
@@ -102,17 +103,22 @@ def handle_engine_signals(flow_run_id: UUID | None = None):
     except TerminationSignal:
         # An intent means the runner or the `prefect flow-run execute` supervisor
         # drove this termination and owns the flow run's next state, so exit cleanly.
-        # A raw external termination has no intent and must keep propagating.
-        if get_intent() is not None:
+        # An engine outcome means orchestration already handled the termination.
+        # A raw external termination with neither form of evidence must propagate.
+        intent = get_intent()
+        if intent is not None or engine_outcome_is_handled():
             if flow_run_id:
                 msg = f"Execution of flow run '{flow_run_id}' was terminated."
             else:
                 msg = "Execution was terminated."
             engine_logger.info(msg)
-            clear_intent()
+            if intent is not None:
+                clear_intent()
             exit(0)
         raise
     except Exception:
+        if engine_outcome_is_handled():
+            exit(0)
         if flow_run_id:
             msg = f"Execution of flow run '{flow_run_id}' exited with unexpected exception"
         else:
@@ -120,6 +126,8 @@ def handle_engine_signals(flow_run_id: UUID | None = None):
         engine_logger.error(msg, exc_info=True)
         exit(1)
     except BaseException:
+        if engine_outcome_is_handled():
+            exit(0)
         if flow_run_id:
             msg = f"Execution of flow run '{flow_run_id}' interrupted by base exception"
         else: