brawny 0.1.13__py3-none-any.whl → 0.1.22__py3-none-any.whl

brawny/http.py

@@ -0,0 +1,194 @@
+"""Approved HTTP client for job code with allowlist enforcement."""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+from urllib.parse import urlparse
+
+import httpx
+
+from brawny.logging import get_logger
+from brawny.network_guard import allow_network_calls
+
+logger = get_logger(__name__)
+
+_RETRY_STATUS = {429, 500, 502, 503, 504}
+
+
+@dataclass(frozen=True)
+class HttpConfig:
+    """HTTP policy for job-originated requests."""
+
+    allowed_domains: list[str] = field(default_factory=list)
+    connect_timeout_seconds: float = 5.0
+    read_timeout_seconds: float = 10.0
+    max_retries: int = 2
+    backoff_base_seconds: float = 0.5
+
+
+class ApprovedHttpClient:
+    """HTTP client with retries, timeouts, and domain allowlist.
+
+    Retries apply to GET/HEAD by default. Non-idempotent methods require
+    explicit opt-in or an idempotency key.
+    """
+
+    def __init__(self, config: HttpConfig) -> None:
+        self._config = config
+
+    @property
+    def config(self) -> HttpConfig:
+        return self._config
+
+    def _is_allowed_host(self, host: str) -> bool:
+        if not host:
+            return False
+        allowed = self._config.allowed_domains
+        if not allowed:
+            return False
+        if "*" in allowed:
+            return True
+        host = host.lower().rstrip(".")
+        try:
+            import ipaddress
+
+            ip = ipaddress.ip_address(host)
+            return any(entry.strip().lower() == str(ip) for entry in allowed)
+        except ValueError:
+            pass
+        for entry in allowed:
+            entry = entry.lower().strip()
+            if not entry:
+                continue
+            if entry.startswith("*."):
+                suffix = entry[1:]
+                if host.endswith(suffix):
+                    return True
+            elif entry.startswith("."):
+                if host.endswith(entry):
+                    return True
+            elif host == entry:
+                return True
+        return False
+
+    def _validate_url(self, url: str) -> None:
+        parsed = urlparse(url)
+        if parsed.scheme not in ("http", "https"):
+            raise ValueError(f"Only http/https URLs are allowed: {url}")
+        host = parsed.hostname or ""
+        if not self._is_allowed_host(host):
+            raise ValueError(f"HTTP domain not allowed: {host or url}")
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        timeout: float | None = None,
+        retry_non_idempotent: bool = False,
+        idempotency_key: str | None = None,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        self._validate_url(url)
+        timeout = timeout or self._timeout()
+        last_error: Exception | None = None
+        attempts = max(0, self._config.max_retries) + 1
+        method_upper = method.upper()
+        allow_retry = method_upper in ("GET", "HEAD") or retry_non_idempotent or idempotency_key is not None
+        headers = dict(kwargs.pop("headers", {}) or {})
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        kwargs["headers"] = headers
+
+        for attempt in range(attempts):
+            try:
+                with allow_network_calls(reason="approved_http_client"):
+                    with httpx.Client(timeout=timeout) as client:
+                        resp = client.request(method, url, **kwargs)
+                if resp.status_code in _RETRY_STATUS and attempt < attempts - 1 and allow_retry:
+                    self._sleep_backoff(attempt)
+                    continue
+                resp.raise_for_status()
+                return resp
+            except (httpx.RequestError, httpx.HTTPStatusError) as exc:
+                last_error = exc
+                if attempt < attempts - 1 and allow_retry:
+                    self._sleep_backoff(attempt)
+                    continue
+                raise
+        if last_error:
+            raise last_error
+        raise RuntimeError("HTTP request failed without error")
+
+    async def async_request(
+        self,
+        method: str,
+        url: str,
+        *,
+        timeout: float | None = None,
+        retry_non_idempotent: bool = False,
+        idempotency_key: str | None = None,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        self._validate_url(url)
+        timeout = timeout or self._timeout()
+        last_error: Exception | None = None
+        attempts = max(0, self._config.max_retries) + 1
+        method_upper = method.upper()
+        allow_retry = method_upper in ("GET", "HEAD") or retry_non_idempotent or idempotency_key is not None
+        headers = dict(kwargs.pop("headers", {}) or {})
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        kwargs["headers"] = headers
+
+        for attempt in range(attempts):
+            try:
+                with allow_network_calls(reason="approved_http_client"):
+                    async with httpx.AsyncClient(timeout=timeout) as client:
+                        resp = await client.request(method, url, **kwargs)
+                if resp.status_code in _RETRY_STATUS and attempt < attempts - 1 and allow_retry:
+                    await self._async_sleep_backoff(attempt)
+                    continue
+                resp.raise_for_status()
+                return resp
+            except (httpx.RequestError, httpx.HTTPStatusError) as exc:
+                last_error = exc
+                if attempt < attempts - 1 and allow_retry:
+                    await self._async_sleep_backoff(attempt)
+                    continue
+                raise
+        if last_error:
+            raise last_error
+        raise RuntimeError("HTTP request failed without error")
+
+    def get(self, url: str, **kwargs: Any) -> httpx.Response:
+        return self.request("GET", url, **kwargs)
+
+    def post(self, url: str, **kwargs: Any) -> httpx.Response:
+        return self.request("POST", url, **kwargs)
+
+    async def async_get(self, url: str, **kwargs: Any) -> httpx.Response:
+        return await self.async_request("GET", url, **kwargs)
+
+    async def async_post(self, url: str, **kwargs: Any) -> httpx.Response:
+        return await self.async_request("POST", url, **kwargs)
+
+    def _sleep_backoff(self, attempt: int) -> None:
+        delay = self._config.backoff_base_seconds * (2 ** attempt)
+        time.sleep(delay)
+
+    async def _async_sleep_backoff(self, attempt: int) -> None:
+        import asyncio
+
+        delay = self._config.backoff_base_seconds * (2 ** attempt)
+        await asyncio.sleep(delay)
+
+    def _timeout(self) -> httpx.Timeout:
+        return httpx.Timeout(
+            connect=self._config.connect_timeout_seconds,
+            read=self._config.read_timeout_seconds,
+            write=self._config.read_timeout_seconds,
+            pool=self._config.connect_timeout_seconds,
+        )

brawny/invariants.py

@@ -36,30 +36,17 @@ def _get_stuck_claim_details(
     limit: int = 20,
 ) -> list[dict[str, Any]]:
     """Fetch sample of stuck claimed intents for debugging context."""
-    if db.dialect == "sqlite":
-        query = """
-            SELECT intent_id, job_id,
-                   (julianday('now') - julianday(claimed_at)) * 86400 as age_seconds
-            FROM tx_intents
-            WHERE chain_id = :chain_id
-              AND status = 'claimed'
-              AND datetime(claimed_at) < datetime('now', :offset || ' minutes')
-            ORDER BY claimed_at ASC
-            LIMIT :limit
-        """
-        params = {"chain_id": chain_id, "offset": -older_than_minutes, "limit": limit}
-    else:
-        query = """
-            SELECT intent_id, job_id,
-                   EXTRACT(EPOCH FROM (NOW() - claimed_at)) as age_seconds
-            FROM tx_intents
-            WHERE chain_id = :chain_id
-              AND status = 'claimed'
-              AND claimed_at < NOW() - make_interval(mins => :older_than_minutes)
-            ORDER BY claimed_at ASC
-            LIMIT :limit
-        """
-        params = {"chain_id": chain_id, "older_than_minutes": older_than_minutes, "limit": limit}
+    query = """
+        SELECT intent_id, job_id,
+               (julianday('now') - julianday(claimed_at)) * 86400 as age_seconds
+        FROM tx_intents
+        WHERE chain_id = :chain_id
+          AND status = 'claimed'
+          AND datetime(claimed_at) < datetime('now', :offset || ' minutes')
+        ORDER BY claimed_at ASC
+        LIMIT :limit
+    """
+    params = {"chain_id": chain_id, "offset": -older_than_minutes, "limit": limit}
 
     return db.execute_returning(query, params)
 

brawny/jobs/base.py

@@ -104,6 +104,7 @@ class Job(ABC):
     check_timeout_seconds: int = 30
     build_timeout_seconds: int = 10
     max_in_flight_intents: int | None = None
+    cooldown_seconds: int | None = None
 
     # Simulation config
     disable_simulation: bool = False
@@ -165,6 +166,13 @@ class Job(ABC):
         elif cls.telegram_chat_ids is None:
             cls.telegram_chat_ids = []
 
+    def cooldown_key(self, trigger: Trigger) -> str | None:
+        """Optional cooldown key for this trigger.
+
+        Return None for job-wide cooldown.
+        """
+        return None
+
     def check(self, *args: Any, **kwargs: Any) -> Trigger | None:
         """Check if job should trigger.
 

brawny/jobs/job_validation.py

@@ -79,7 +79,8 @@ def validate_job(job: "Job", keystore: "Keystore | None" = None) -> list[str]:
     signer = getattr(job, "_signer_name", None)
     if signer and keystore:
         if not keystore.has_key(signer):
-            available = keystore.list_keys()
+            # Show aliases if available (what user can type), else addresses
+            available = keystore.list_aliases() or keystore.list_keys()
             if available:
                 errors.append(f"signer '{signer}' not found in keystore (available: {', '.join(available)})")
             else:

brawny/keystore.py

@@ -31,6 +31,16 @@ load_dotenv()
 
 logger = get_logger(__name__)
 
+
+def _normalize_addr(addr: str) -> str:
+    """Normalize address to checksummed format.
+
+    Handles addresses with or without 0x prefix.
+    """
+    if not addr.startswith("0x"):
+        addr = "0x" + addr
+    return Web3.to_checksum_address(addr)
+
 if TYPE_CHECKING:
     from eth_account.datastructures import SignedTransaction
 
@@ -80,13 +90,35 @@ class Keystore(ABC):
 
     @abstractmethod
     def list_keys(self) -> list[str]:
-        """List available key identifiers.
+        """Return list of signer addresses (checksummed, sorted, de-duplicated).
 
         Returns:
-            List of key identifiers (addresses)
+            Sorted list of unique checksummed Ethereum addresses.
         """
         ...
 
+    def list_aliases(self) -> list[str]:
+        """Return list of signer aliases/names (sorted).
+
+        Default implementation returns empty list.
+        Override in subclasses that support aliases.
+
+        Returns:
+            Sorted list of human-readable aliases, or empty if no aliases configured.
+        """
+        return []
+
+    def list_keys_with_aliases(self) -> list[tuple[str, str | None]]:
+        """Return list of (address, alias) tuples, sorted by address.
+
+        Default implementation returns addresses with None alias.
+        Override in subclasses that support aliases.
+
+        Returns:
+            List of tuples where each tuple is (checksummed_address, alias_or_none).
+        """
+        return [(addr, None) for addr in self.list_keys()]
+
     def has_key(self, key_id: str) -> bool:
         """Check if a key exists.
 
@@ -196,8 +228,8 @@ class EnvKeystore(Keystore):
             raise KeystoreError(f"Signing failed: {type(e).__name__}: {e}")
 
     def list_keys(self) -> list[str]:
-        """List all available signer addresses."""
-        return list(self._accounts.keys())
+        """Return list of signer addresses (checksummed, sorted)."""
+        return sorted(self._accounts.keys())
 
 
 class FileKeystore(Keystore):
@@ -430,13 +462,57 @@ class FileKeystore(Keystore):
             raise KeystoreError(f"Signing failed: {type(e).__name__}: {e}")
 
     def list_keys(self) -> list[str]:
-        """List all available signer addresses."""
+        """Return list of signer addresses (checksummed, sorted, de-duplicated).
+
+        **Source of truth behavior:**
+        - When _name_to_address mapping exists, it is the SOLE source of truth.
+          The keystore directory is NOT scanned. This means addresses only in
+          keystore files (without aliases) will NOT appear.
+        - When _name_to_address is empty/None, addresses are extracted from
+          the loaded accounts.
+
+        Returns:
+            Sorted list of unique checksummed Ethereum addresses.
+        """
+        if self._name_to_address:
+            # Mapping is source of truth - normalize, de-dupe, and sort
+            # (multiple aliases may map to same address)
+            return sorted({_normalize_addr(a) for a in self._name_to_address.values()})
+
+        # Return addresses from loaded accounts
+        return sorted(self._accounts.keys())
+
+    def list_aliases(self) -> list[str]:
+        """Return list of signer aliases/names (sorted).
+
+        Returns:
+            Sorted list of human-readable aliases, or empty if no aliases configured.
+        """
         if self._name_to_address:
             return sorted(self._name_to_address.keys())
-        return list(self._accounts.keys())
+        return []
+
+    def list_keys_with_aliases(self) -> list[tuple[str, str | None]]:
+        """Return list of (address, alias) tuples, sorted by address.
+
+        Returns:
+            List of tuples where each tuple is (checksummed_address, alias_or_none).
+        """
+        if self._name_to_address:
+            pairs = [
+                (_normalize_addr(addr), name)
+                for name, addr in self._name_to_address.items()
+            ]
+            return sorted(pairs, key=lambda x: x[0])  # Sort by address
+
+        # No aliases: return addresses with None alias
+        return [(addr, None) for addr in self.list_keys()]
 
     def list_named_keys(self) -> dict[str, str]:
-        """Return mapping of wallet name to address."""
+        """Return mapping of wallet name to address.
+
+        DEPRECATED: Use list_aliases() or list_keys_with_aliases() instead.
+        """
         return dict(self._name_to_address)
 
     def get_warnings(self) -> list[StartupMessage]:

brawny/lifecycle.py

@@ -10,9 +10,11 @@ from contextlib import contextmanager
 from typing import TYPE_CHECKING, Any
 from uuid import UUID
 
-from brawny.alerts.send import AlertConfig, AlertEvent, AlertPayload
+from brawny.alerts.send import AlertConfig, AlertEvent, AlertPayload, JobAlertSender
+from brawny.http import ApprovedHttpClient
 from brawny.jobs.kv import DatabaseJobKVStore, DatabaseJobKVReader
 from brawny.logging import LogEvents, get_logger
+from brawny.metrics import BACKGROUND_TASK_ERRORS, get_metrics
 from brawny.model.contexts import (
     AlertContext,
     BlockContext,
@@ -29,13 +31,14 @@ from brawny.model.errors import (
 )
 from brawny.model.events import DecodedEvent
 from brawny.model.types import BlockInfo, Trigger, HookName
+from brawny.network_guard import job_network_guard
 
 if TYPE_CHECKING:
     from brawny.config import Config
     from brawny.db.base import Database
     from brawny.jobs.base import Job, TxInfo, TxReceipt, BlockInfo as AlertBlockInfo
     from brawny.model.types import TxAttempt, TxIntent
-    from brawny._rpc.manager import RPCManager
+    from brawny._rpc.clients import ReadClient
     from brawny.alerts.contracts import ContractSystem, SimpleContractFactory
     from brawny.telegram import TelegramBot
 
@@ -57,7 +60,7 @@ class LifecycleDispatcher:
     def __init__(
         self,
         db: Database,
-        rpc: RPCManager,
+        rpc: ReadClient,
         config: Config,
         jobs: dict[str, Job],
         contract_system: ContractSystem | None = None,
@@ -69,6 +72,7 @@ class LifecycleDispatcher:
         self._jobs = jobs
         self._contract_system = contract_system
         self._telegram_bot = telegram_bot
+        self._http_client = ApprovedHttpClient(config.http)
         self._global_alert_config = self._build_global_alert_config()
 
     # =========================================================================
@@ -95,7 +99,8 @@ class LifecycleDispatcher:
         try:
             with self._alert_context(ctx):
                 set_job_context(True)
-                hook_fn(ctx)
+                with job_network_guard():
+                    hook_fn(ctx)
         except Exception as e:
             logger.error(
                 f"job.{hook}_crashed",
@@ -143,6 +148,7 @@ class LifecycleDispatcher:
             block=block_ctx,
             kv=DatabaseJobKVStore(self._db, job.job_id),
             logger=logger.bind(job_id=job.job_id, chain_id=self._config.chain_id),
+            http=self._http_client,
             job_id=job.job_id,
             job_name=job.name,
             chain_id=self._config.chain_id,
@@ -150,6 +156,7 @@ class LifecycleDispatcher:
             telegram_config=self._config.telegram,
             telegram_bot=self._telegram_bot,
             job_alert_to=getattr(job, "_alert_to", None),
+            _alert_sender=self._make_job_alert_sender(job),
         )
         self.dispatch_hook(job, "on_trigger", ctx)
 
@@ -188,6 +195,7 @@ class LifecycleDispatcher:
             block=block_ctx,
             kv=DatabaseJobKVReader(self._db, job.job_id),
             logger=logger.bind(job_id=job.job_id, chain_id=self._config.chain_id),
+            http=self._http_client,
             job_id=job.job_id,
             job_name=job.name,
             chain_id=self._config.chain_id,
@@ -195,6 +203,7 @@ class LifecycleDispatcher:
             telegram_config=self._config.telegram,
             telegram_bot=self._telegram_bot,
             job_alert_to=getattr(job, "_alert_to", None),
+            _alert_sender=self._make_job_alert_sender(job),
         )
         self.dispatch_hook(job, "on_success", ctx)
 
@@ -223,6 +232,7 @@ class LifecycleDispatcher:
             block=block_ctx,
             kv=DatabaseJobKVReader(self._db, job.job_id),
             logger=logger.bind(job_id=job.job_id, chain_id=self._config.chain_id),
+            http=self._http_client,
             job_id=job.job_id,
             job_name=job.name,
             chain_id=self._config.chain_id,
@@ -230,6 +240,7 @@ class LifecycleDispatcher:
             telegram_config=self._config.telegram,
             telegram_bot=self._telegram_bot,
             job_alert_to=getattr(job, "_alert_to", None),
+            _alert_sender=self._make_job_alert_sender(job),
         )
         self.dispatch_hook(job, "on_failure", ctx)
 
@@ -256,6 +267,7 @@ class LifecycleDispatcher:
             block=block_ctx,
             kv=DatabaseJobKVReader(self._db, job.job_id),
             logger=logger.bind(job_id=job.job_id, chain_id=self._config.chain_id),
+            http=self._http_client,
             job_id=job.job_id,
             job_name=job.name,
             chain_id=self._config.chain_id,
@@ -263,6 +275,7 @@ class LifecycleDispatcher:
             telegram_config=self._config.telegram,
             telegram_bot=self._telegram_bot,
             job_alert_to=getattr(job, "_alert_to", None),
+            _alert_sender=self._make_job_alert_sender(job),
         )
         self.dispatch_hook(job, "on_failure", ctx)
 
@@ -290,6 +303,7 @@ class LifecycleDispatcher:
             block=block_ctx,
             kv=DatabaseJobKVReader(self._db, job.job_id),
             logger=logger.bind(job_id=job.job_id, chain_id=self._config.chain_id),
+            http=self._http_client,
             job_id=job.job_id,
             job_name=job.name,
             chain_id=self._config.chain_id,
@@ -297,6 +311,7 @@ class LifecycleDispatcher:
             telegram_config=self._config.telegram,
             telegram_bot=self._telegram_bot,
             job_alert_to=getattr(job, "_alert_to", None),
+            _alert_sender=self._make_job_alert_sender(job),
         )
         self.dispatch_hook(job, "on_failure", ctx)
 
@@ -342,15 +357,28 @@ class LifecycleDispatcher:
 
     def _fire_alert(self, payload: AlertPayload, config: AlertConfig) -> None:
         """Fire alert asynchronously. Fire-and-forget."""
-        import asyncio
         from brawny.alerts import send as alerts_send
 
         try:
-            loop = asyncio.get_running_loop()
-            loop.create_task(alerts_send.send_alert(payload, config))
-        except RuntimeError:
-            # No running loop - run synchronously
-            asyncio.run(alerts_send.send_alert(payload, config))
+            alerts_send.enqueue_alert(payload, config)
+        except Exception as exc:
+            metrics = get_metrics()
+            metrics.counter(BACKGROUND_TASK_ERRORS).inc(task="alert_send")
+            logger.warning("alert.enqueue_failed", error=str(exc)[:200])
+
+    def _handle_alert_task_result(self, task: "asyncio.Task[object]") -> None:
+        import asyncio
+
+        if task.cancelled():
+            return
+        try:
+            task.result()
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            metrics = get_metrics()
+            metrics.counter(BACKGROUND_TASK_ERRORS).inc(task="alert_send")
+            self._log.warning("alert.task_failed", error=str(exc)[:200])
 
     def _build_global_alert_config(self) -> AlertConfig:
         """Build global AlertConfig from application config (legacy compatibility)."""
@@ -390,6 +418,18 @@ class LifecycleDispatcher:
             and self._global_alert_config.telegram_chat_ids
         )
 
+    def _make_job_alert_sender(self, job: Job) -> JobAlertSender:
+        """Create alert sender for ctx.alert() in lifecycle hooks.
+
+        Returns a JobAlertSender that routes to job-specific destinations.
+        """
+        return JobAlertSender(
+            telegram_bot=self._telegram_bot,
+            telegram_config=self._config.telegram,
+            job_alert_to=getattr(job, "_alert_to", None),
+            job_id=job.job_id,
+        )
+
     # =========================================================================
     # Helpers
     # =========================================================================
@@ -453,7 +493,12 @@ class LifecycleDispatcher:
             return None
         try:
             block = self._rpc.get_block(block_number)
-        except Exception:
+        except Exception as e:
+            logger.warning(
+                "alerts.block_fetch_failed",
+                block_number=block_number,
+                error=str(e)[:200],
+            )
             return None
         return self._to_alert_block(
             BlockInfo(
@@ -463,6 +508,7 @@ class LifecycleDispatcher:
                 if hasattr(block["hash"], "hex")
                 else block["hash"],
                 timestamp=block["timestamp"],
+                base_fee=block.get("baseFeePerGas", 0),
             )
         )
 
@@ -470,7 +516,12 @@ class LifecycleDispatcher:
         """Get BlockInfo model from block number."""
         try:
             block = self._rpc.get_block(block_number)
-        except Exception:
+        except Exception as e:
+            logger.warning(
+                "alerts.block_model_failed",
+                block_number=block_number,
+                error=str(e)[:200],
+            )
             return None
         return BlockInfo(
             chain_id=self._config.chain_id,
@@ -479,6 +530,7 @@ class LifecycleDispatcher:
             if hasattr(block["hash"], "hex")
             else block["hash"],
             timestamp=block["timestamp"],
+            base_fee=block.get("baseFeePerGas", 0),
         )
 
     def _to_alert_block(self, block: BlockInfo) -> AlertBlockInfo:

brawny/logging.py

@@ -282,8 +282,6 @@ class LogEvents:
     RPC_REQUEST = "rpc.request"
     RPC_ERROR = "rpc.error"
     RPC_ALL_ENDPOINTS_FAILED = "rpc.all_endpoints_failed"
-    RPC_CIRCUIT_BREAKER_OPEN = "rpc.circuit_breaker_open"
-    RPC_CIRCUIT_BREAKER_CLOSED = "rpc.circuit_breaker_closed"
 
     # Shutdown
     SHUTDOWN_INITIATED = "shutdown.initiated"