brawny 0.1.13__py3-none-any.whl

brawny/scheduler/shutdown.py

@@ -0,0 +1,371 @@
+"""Graceful shutdown handling for brawny.
+
+Implements SPEC 9.5 Graceful Shutdown:
+- Signal handling (SIGTERM, SIGINT)
+- Graceful shutdown sequence
+- In-progress intent handling
+- Connection cleanup
+"""
+
+from __future__ import annotations
+
+import signal
+import threading
+import time
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING, Callable
+
+from brawny.logging import LogEvents, get_logger
+from brawny.model.enums import IntentStatus, NonceStatus
+
+if TYPE_CHECKING:
+    from brawny.config import Config
+    from brawny.db.base import Database
+    from brawny._rpc.manager import RPCManager
+    from brawny.tx.nonce import NonceManager
+
+logger = get_logger(__name__)
+
+
+class ShutdownState(str, Enum):
+    """Shutdown state machine."""
+
+    RUNNING = "running"
+    SHUTTING_DOWN = "shutting_down"
+    SHUTDOWN_COMPLETE = "shutdown_complete"
+
+
+@dataclass
+class ShutdownStats:
+    """Statistics from shutdown process."""
+
+    claimed_released: int = 0
+    pending_orphaned: int = 0
+    errors: int = 0
+
+
+class ShutdownHandler:
+    """Manages graceful shutdown of brawny.
+
+    Handles SIGTERM and SIGINT signals to trigger graceful shutdown.
+    Coordinates shutdown of all components in proper order.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        db: Database | None = None,
+        rpc: RPCManager | None = None,
+        nonce_manager: NonceManager | None = None,
+    ) -> None:
+        """Initialize shutdown handler.
+
+        Args:
+            config: Application configuration
+            db: Database connection (optional, set later)
+            rpc: RPC manager (optional, set later)
+            nonce_manager: Nonce manager (optional, set later)
+        """
+        self._config = config
+        self._db = db
+        self._rpc = rpc
+        self._nonce_manager = nonce_manager
+
+        self._state = ShutdownState.RUNNING
+        self._shutdown_flag = threading.Event()
+        self._shutdown_lock = threading.Lock()
+
+        # Callbacks to notify on shutdown
+        self._shutdown_callbacks: list[Callable[[], None]] = []
+        self._callbacks_notified = False
+
+        # Force exit counter
+        self._signal_count = 0
+
+        # Stats
+        self._stats = ShutdownStats()
+
+    def set_db(self, db: Database) -> None:
+        """Set database connection."""
+        self._db = db
+
+    def set_rpc(self, rpc: RPCManager) -> None:
+        """Set RPC manager."""
+        self._rpc = rpc
+
+    def set_nonce_manager(self, nonce_manager: NonceManager) -> None:
+        """Set nonce manager."""
+        self._nonce_manager = nonce_manager
+
+    def register_callback(self, callback: Callable[[], None]) -> None:
+        """Register a callback to be called on shutdown.
+
+        Args:
+            callback: Function to call during shutdown
+        """
+        self._shutdown_callbacks.append(callback)
+
+    def install_signal_handlers(self) -> None:
+        """Install signal handlers for graceful shutdown."""
+        signal.signal(signal.SIGTERM, self._signal_handler)
+        signal.signal(signal.SIGINT, self._signal_handler)
+        logger.debug("shutdown.handlers_installed")
+
+    def _signal_handler(self, signum: int, frame) -> None:
+        """Handle shutdown signal.
+
+        Args:
+            signum: Signal number
+            frame: Current stack frame
+        """
+        import os
+        import sys
+
+        self._signal_count += 1
+        signal_name = signal.Signals(signum).name
+
+        if self._signal_count >= 3:
+            logger.warning("shutdown.force_exit", signal_count=self._signal_count)
+            print("\nForce exit.", file=sys.stderr)
+            os._exit(1)
+
+        logger.info(
+            "shutdown.signal_received",
+            signal=signal_name,
+            count=self._signal_count,
+        )
+        self.initiate_shutdown()
+
+    @property
+    def is_shutting_down(self) -> bool:
+        """Check if shutdown has been initiated."""
+        return self._state != ShutdownState.RUNNING
+
+    @property
+    def shutdown_flag(self) -> threading.Event:
+        """Get shutdown flag for waiting."""
+        return self._shutdown_flag
+
+    def initiate_shutdown(self) -> None:
+        """Initiate graceful shutdown.
+
+        Can be called from signal handler or programmatically.
+        Immediately notifies callbacks to stop blocking loops.
+        """
+        with self._shutdown_lock:
+            if self._state != ShutdownState.RUNNING:
+                return
+
+            self._state = ShutdownState.SHUTTING_DOWN
+            self._shutdown_flag.set()
+
+            logger.info(LogEvents.SHUTDOWN_INITIATED)
+
+        # Notify callbacks immediately (outside lock to avoid deadlock)
+        # This stops blocking loops like the poller
+        self._notify_callbacks()
+
+    def wait_for_shutdown(self, timeout: float | None = None) -> bool:
+        """Wait for shutdown signal.
+
+        Args:
+            timeout: Maximum time to wait in seconds
+
+        Returns:
+            True if shutdown was signaled, False if timeout
+        """
+        return self._shutdown_flag.wait(timeout)
+
+    def execute_shutdown(self, timeout: float | None = None) -> ShutdownStats:
+        """Execute the full shutdown sequence.
+
+        Per SPEC 9.5:
+        1. Stop accepting new block processing
+        2. Wait for current block to finish
+        3. Handle in-progress intents
+        4. Flush logs and metrics
+        5. Close connections
+
+        Args:
+            timeout: Maximum time for shutdown (default from config)
+
+        Returns:
+            Shutdown statistics
+        """
+        timeout = timeout or self._config.shutdown_timeout_seconds
+
+        logger.info(
+            "shutdown.executing",
+            timeout_seconds=timeout,
+        )
+
+        start_time = time.time()
+        self._stats = ShutdownStats()
+
+        # 1. Notify registered callbacks (stops pollers, workers, etc.)
+        self._notify_callbacks()
+
+        # 2. Wait for graceful completion (callbacks should signal)
+        remaining = timeout - (time.time() - start_time)
+        if remaining > 0:
+            time.sleep(min(remaining, 2.0))  # Brief wait for work to finish
+
+        # 3. Handle in-progress intents
+        self._handle_in_progress_intents()
+
+        # 4. Close RPC connections
+        if self._rpc:
+            try:
+                self._rpc.close()
+            except Exception as e:
+                logger.warning("shutdown.rpc_close_failed", error=str(e)[:200])
+
+        # 5. Close database
+        if self._db:
+            try:
+                self._db.close()
+            except Exception as e:
+                logger.warning("shutdown.db_close_failed", error=str(e)[:200])
+
+        # Mark shutdown complete
+        self._state = ShutdownState.SHUTDOWN_COMPLETE
+
+        elapsed = time.time() - start_time
+        logger.info(
+            LogEvents.SHUTDOWN_COMPLETE,
+            elapsed_seconds=round(elapsed, 2),
+            claimed_released=self._stats.claimed_released,
+            pending_orphaned=self._stats.pending_orphaned,
+        )
+
+        return self._stats
+
+    def _notify_callbacks(self) -> None:
+        """Notify all registered shutdown callbacks.
+
+        Only runs once, even if called multiple times.
+        """
+        if self._callbacks_notified:
+            return
+        self._callbacks_notified = True
+
+        logger.info("shutdown.notifying_callbacks", count=len(self._shutdown_callbacks))
+
+        for i, callback in enumerate(self._shutdown_callbacks):
+            try:
+                logger.debug("shutdown.callback_start", index=i)
+                callback()
+                logger.debug("shutdown.callback_done", index=i)
+            except Exception as e:
+                logger.warning(
+                    "shutdown.callback_failed",
+                    index=i,
+                    error=str(e)[:200],
+                )
+                self._stats.errors += 1
+
+        logger.info("shutdown.callbacks_complete")
+
+    def _handle_in_progress_intents(self) -> None:
+        """Handle intents that are in progress during shutdown.
+
+        Per SPEC 9.5:
+        - Claimed but not broadcast: release back to queue
+        - Sending/pending: leave for reconciliation on restart
+        """
+        if not self._db:
+            return
+
+        try:
+            # Handle claimed intents (not yet broadcast)
+            claimed = self._db.get_intents_by_status(
+                IntentStatus.CLAIMED.value,
+                chain_id=self._config.chain_id,
+            )
+
+            for intent in claimed:
+                try:
+                    # Release claim (revert to created)
+                    self._db.release_intent_claim(intent.intent_id)
+
+                    # Get the attempt to find nonce
+                    attempt = self._db.get_latest_attempt_for_intent(intent.intent_id)
+                    if attempt and self._nonce_manager:
+                        # Release nonce reservation
+                        self._nonce_manager.release(
+                            intent.signer_address,
+                            attempt.nonce,
+                        )
+
+                    logger.debug(
+                        "shutdown.intent_released",
+                        intent_id=str(intent.intent_id),
+                    )
+                    self._stats.claimed_released += 1
+
+                except Exception as e:
+                    logger.warning(
+                        "shutdown.intent_release_failed",
+                        intent_id=str(intent.intent_id),
+                        error=str(e)[:200],
+                    )
+                    self._stats.errors += 1
+
+            # Log pending/sending intents (left for reconciliation)
+            in_flight_statuses = [
+                IntentStatus.SENDING.value,
+                IntentStatus.PENDING.value,
+            ]
+
+            for status in in_flight_statuses:
+                intents = self._db.get_intents_by_status(
+                    status,
+                    chain_id=self._config.chain_id,
+                )
+
+                for intent in intents:
+                    logger.info(
+                        "shutdown.orphan_pending",
+                        intent_id=str(intent.intent_id),
+                        status=status,
+                    )
+                    self._stats.pending_orphaned += 1
+
+        except Exception as e:
+            logger.error(
+                "shutdown.handle_intents_failed",
+                error=str(e)[:200],
+            )
+            self._stats.errors += 1
+
+
+class ShutdownContext:
+    """Context manager for graceful shutdown handling.
+
+    Usage:
+        handler = ShutdownHandler(config)
+        with ShutdownContext(handler):
+            # Main application loop
+            while not handler.is_shutting_down:
+                process_block()
+    """
+
+    def __init__(self, handler: ShutdownHandler) -> None:
+        """Initialize context.
+
+        Args:
+            handler: Shutdown handler to use
+        """
+        self._handler = handler
+
+    def __enter__(self) -> ShutdownHandler:
+        """Enter context and install signal handlers."""
+        self._handler.install_signal_handlers()
+        return self._handler
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:
+        """Exit context and execute shutdown."""
+        if self._handler.is_shutting_down:
+            self._handler.execute_shutdown()
+        return False  # Don't suppress exceptions

brawny/script_tx.py

@@ -0,0 +1,297 @@
+"""Transaction broadcasting for standalone scripts.
+
+Simpler flow than job-based execution:
+- No intent persistence
+- No replacement/monitoring
+- Direct broadcast and wait
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+import time
+
+from brawny.tx.utils import normalize_tx_dict
+
+if TYPE_CHECKING:
+    from brawny.keystore import Keystore
+    from brawny._rpc.manager import RPCManager
+    from brawny.jobs.base import TxReceipt
+
+
+class TransactionBroadcaster:
+    """Broadcasts transactions for script context.
+
+    Uses brawny RPC infrastructure (retry, failover) but
+    simpler execution flow than job-based TxExecutor.
+    """
+
+    def __init__(
+        self,
+        rpc: "RPCManager",
+        keystore: "Keystore",
+        chain_id: int,
+        timeout_seconds: int = 120,
+        poll_interval: float = 1.0,
+    ) -> None:
+        self._rpc = rpc
+        self._keystore = keystore
+        self._chain_id = chain_id
+        self._timeout = timeout_seconds
+        self._poll_interval = poll_interval
+
+    def transfer(
+        self,
+        sender: str,
+        to: str,
+        value: int,
+        gas_limit: int | None = None,
+        gas_price: int | None = None,
+        max_fee_per_gas: int | None = None,
+        max_priority_fee_per_gas: int | None = None,
+        data: str | None = None,
+        nonce: int | None = None,
+        private_key: bytes | None = None,
+    ) -> "TxReceipt":
+        """Send a transfer transaction.
+
+        Args:
+            sender: Sender address
+            to: Recipient address
+            value: Amount in wei
+            gas_limit: Optional gas limit
+            gas_price: Optional legacy gas price
+            max_fee_per_gas: Optional EIP-1559 max fee
+            max_priority_fee_per_gas: Optional EIP-1559 priority fee
+            data: Optional calldata
+            nonce: Optional nonce override
+            private_key: Optional private key for signing (from Account).
+                        If None, uses the keystore to sign.
+
+        Returns:
+            Transaction receipt on confirmation
+
+        Raises:
+            TransactionRevertedError: If transaction reverts
+            TransactionTimeoutError: If confirmation times out
+        """
+        from brawny.history import _add_to_history
+
+        # Build transaction
+        tx = self._build_transaction(
+            sender=sender,
+            to=to,
+            value=value,
+            data=data or "0x",
+            gas_limit=gas_limit,
+            gas_price=gas_price,
+            max_fee_per_gas=max_fee_per_gas,
+            max_priority_fee_per_gas=max_priority_fee_per_gas,
+            nonce=nonce,
+        )
+
+        # Sign and broadcast
+        receipt = self._sign_and_broadcast(tx, sender, private_key)
+
+        # Add to history
+        _add_to_history(receipt)
+
+        return receipt
+
+    def transact(
+        self,
+        sender: str,
+        to: str,
+        data: str,
+        value: int = 0,
+        gas_limit: int | None = None,
+        gas_price: int | None = None,
+        max_fee_per_gas: int | None = None,
+        max_priority_fee_per_gas: int | None = None,
+        nonce: int | None = None,
+        private_key: bytes | None = None,
+    ) -> "TxReceipt":
+        """Send a contract transaction.
+
+        Args:
+            sender: Sender address
+            to: Contract address
+            data: Encoded calldata
+            value: Optional ETH value in wei
+            gas_limit: Optional gas limit
+            gas_price: Optional legacy gas price
+            max_fee_per_gas: Optional EIP-1559 max fee
+            max_priority_fee_per_gas: Optional EIP-1559 priority fee
+            nonce: Optional nonce override
+            private_key: Optional private key for signing (from Account).
+                        If None, uses the keystore to sign.
+
+        Returns:
+            Transaction receipt on confirmation
+        """
+        from brawny.history import _add_to_history
+
+        tx = self._build_transaction(
+            sender=sender,
+            to=to,
+            value=value,
+            data=data,
+            gas_limit=gas_limit,
+            gas_price=gas_price,
+            max_fee_per_gas=max_fee_per_gas,
+            max_priority_fee_per_gas=max_priority_fee_per_gas,
+            nonce=nonce,
+        )
+
+        receipt = self._sign_and_broadcast(tx, sender, private_key)
+        _add_to_history(receipt)
+
+        return receipt
+
+    def _build_transaction(
+        self,
+        sender: str,
+        to: str,
+        value: int,
+        data: str,
+        gas_limit: int | None,
+        gas_price: int | None,
+        max_fee_per_gas: int | None,
+        max_priority_fee_per_gas: int | None,
+        nonce: int | None,
+    ) -> dict[str, Any]:
+        """Build transaction dictionary."""
+        tx: dict[str, Any] = {
+            "from": sender,
+            "to": to,
+            "value": value,
+            "data": data,
+            "chainId": self._chain_id,
+        }
+
+        # Nonce
+        if nonce is None:
+            nonce = self._rpc.get_transaction_count(sender, "pending")
+        tx["nonce"] = nonce
+
+        # Gas price (EIP-1559 or legacy)
+        if max_fee_per_gas is not None:
+            tx["maxFeePerGas"] = max_fee_per_gas
+            tx["maxPriorityFeePerGas"] = max_priority_fee_per_gas or 0
+            tx["type"] = 2
+        elif gas_price is not None:
+            tx["gasPrice"] = gas_price
+        else:
+            # Auto gas price
+            try:
+                base_fee = self._rpc.get_block("latest").get("baseFeePerGas")
+                if base_fee:
+                    # EIP-1559
+                    priority = self._rpc.call("eth_maxPriorityFeePerGas")
+                    tx["maxFeePerGas"] = base_fee * 2 + int(priority, 16)
+                    tx["maxPriorityFeePerGas"] = int(priority, 16)
+                    tx["type"] = 2
+                else:
+                    tx["gasPrice"] = self._rpc.get_gas_price()
+            except Exception:
+                tx["gasPrice"] = self._rpc.get_gas_price()
+
+        # Gas limit
+        if gas_limit is None:
+            estimate_tx = {k: v for k, v in tx.items() if k != "nonce"}
+            gas_limit = self._rpc.estimate_gas(estimate_tx)
+            gas_limit = gas_limit * 1.1  # 10% buffer
+        tx["gas"] = gas_limit
+
+        return normalize_tx_dict(tx)
+
+    def _sign_and_broadcast(
+        self,
+        tx: dict[str, Any],
+        sender: str,
+        private_key: bytes | None = None,
+    ) -> "TxReceipt":
+        """Sign transaction and broadcast, waiting for receipt.
+
+        Args:
+            tx: Transaction dictionary
+            sender: Sender address
+            private_key: Optional private key for direct signing (from Account).
+                        If None, uses the keystore to sign.
+        """
+        from brawny.jobs.base import TxReceipt
+        from brawny.scripting import TransactionRevertedError, TransactionTimeoutError
+        from eth_account import Account as EthAccount
+
+        # Sign - either with private key or keystore
+        if private_key is not None:
+            signed = EthAccount.sign_transaction(tx, private_key)
+        else:
+            signed = self._keystore.sign_transaction(tx, sender)
+
+        # Broadcast (handle both old and new eth-account attribute names)
+        raw_tx = getattr(signed, "raw_transaction", None) or signed.rawTransaction
+        tx_hash = self._rpc.send_raw_transaction(raw_tx)
+
+        # Wait for receipt
+        start = time.time()
+        while True:
+            receipt_data = self._rpc.get_transaction_receipt(tx_hash)
+            if receipt_data is not None:
+                # Handle status as hex string or int
+                status = receipt_data["status"]
+                if isinstance(status, str):
+                    status = int(status, 16)
+
+                # Handle block_number as hex string or int
+                block_number = receipt_data["blockNumber"]
+                if isinstance(block_number, str):
+                    block_number = int(block_number, 16)
+
+                # Handle gas_used as hex string or int
+                gas_used = receipt_data["gasUsed"]
+                if isinstance(gas_used, str):
+                    gas_used = int(gas_used, 16)
+
+                receipt = TxReceipt(
+                    transaction_hash=receipt_data["transactionHash"],
+                    block_number=block_number,
+                    block_hash=receipt_data["blockHash"],
+                    status=status,
+                    gas_used=gas_used,
+                    logs=receipt_data.get("logs", []),
+                )
+
+                if receipt.status == 0:
+                    raise TransactionRevertedError(tx_hash)
+
+                return receipt
+
+            if time.time() - start > self._timeout:
+                raise TransactionTimeoutError(tx_hash, self._timeout)
+
+            time.sleep(self._poll_interval)
+
+
+# Global broadcaster instance
+_broadcaster: TransactionBroadcaster | None = None
+
+
+def _init_broadcaster(
+    rpc: "RPCManager",
+    keystore: "Keystore",
+    chain_id: int,
+) -> None:
+    """Initialize global broadcaster."""
+    global _broadcaster
+    _broadcaster = TransactionBroadcaster(rpc, keystore, chain_id)
+
+
+def _get_broadcaster() -> TransactionBroadcaster:
+    """Get broadcaster singleton."""
+    if _broadcaster is None:
+        raise RuntimeError(
+            "Transaction broadcaster not initialized. "
+            "Run within script context."
+        )
+    return _broadcaster