brawny 0.1.13__py3-none-any.whl

brawny/networks/config.py

@@ -0,0 +1,269 @@
+"""Network configuration loading (Brownie-compatible).
+
+Loads from:
+1. ~/.brawny/network-config.yaml (if exists)
+2. Auto-copies ~/.brownie/network-config.yaml to ~/.brawny/ on first use
+3. Built-in defaults
+
+NOTE: This module provides Brownie-compatible ~/.brawny/network-config.yaml support.
+Project-level config.yaml network sections are no longer supported.
+They are in separate namespaces and serve different purposes.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+# Pattern to match ${VAR}, ${VAR:-default}, or $VAR forms (consistent with brawny.config)
+_ENV_VAR_PATTERN = re.compile(r"\$\{?([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}?")
+
+
+class EnvVarExpansionError(ValueError):
+    """Raised when an environment variable cannot be expanded."""
+
+    def __init__(self, var_name: str, original_value: str, network_id: str | None = None):
+        self.var_name = var_name
+        self.original_value = original_value
+        self.network_id = network_id
+        network_ctx = f" in network '{network_id}'" if network_id else ""
+        super().__init__(
+            f"Environment variable '{var_name}' is not set{network_ctx}. "
+            f"Original value: {original_value}"
+        )
+
+
+def _expand_env_var(value: str, *, network_id: str | None = None) -> str | None:
+    """Expand environment variables in a string.
+
+    Supports:
+      - $VAR or ${VAR} - replaced with env var value
+      - ${VAR:-default} - replaced with env var value, or default if not set
+
+    Returns:
+      - None if value is purely an env var that wasn't set (allows filtering)
+      - Expanded string otherwise
+
+    Raises:
+      - EnvVarExpansionError if a var inside a larger string is unset (partial expansion)
+        e.g., "https://alchemy.com/v2/$KEY" with KEY unset is an error, not a silent "/v2/"
+    """
+    unset_vars: list[str] = []
+
+    def replacer(match: re.Match[str]) -> str:
+        var_name = match.group(1)
+        default_val = match.group(2)  # None if no default specified
+        env_val = os.environ.get(var_name)
+        if env_val is not None:
+            return env_val
+        if default_val is not None:
+            return default_val
+        # Track unset vars without defaults
+        unset_vars.append(var_name)
+        return ""
+
+    result = _ENV_VAR_PATTERN.sub(replacer, value)
+
+    # If the ENTIRE string was a single env var that wasn't set → return None (filterable)
+    if result == "" and len(unset_vars) == 1 and value.strip() in (f"${unset_vars[0]}", f"${{{unset_vars[0]}}}"):
+        return None
+
+    # If ANY env var was unset inside a larger string → error (partial expansion is dangerous)
+    if unset_vars:
+        raise EnvVarExpansionError(unset_vars[0], value, network_id)
+
+    return result
+
+
+@dataclass
+class NetworkConfig:
+    """Configuration for a single network (Brownie-compatible format)."""
+
+    id: str
+    hosts: list[str]  # Flexible: accepts string or list in config, stored as list
+    chainid: int | None = None
+    name: str | None = None
+    explorer: str | None = None
+    multicall2: str | None = None  # Passed to Contract layer for batch calls
+    timeout: int = 30
+
+    # RPC settings (passed to RPCManager for production-grade handling)
+    max_retries: int = 3
+    retry_backoff_base: float = 1.0
+    circuit_breaker_seconds: int = 300
+    rate_limit_per_second: float | None = None
+    rate_limit_burst: int | None = None
+
+    # Development network fields (None for live networks)
+    cmd: str | None = None
+    cmd_settings: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_development(self) -> bool:
+        return self.cmd is not None
+
+    @property
+    def is_fork(self) -> bool:
+        return self.cmd_settings.get("fork") is not None
+
+    def get_endpoints(self) -> list[str]:
+        """Get RPC endpoints with env var expansion.
+
+        - Pure env var hosts (e.g., "$BACKUP_RPC") are filtered if unset
+        - Partial expansion (e.g., "https://alchemy.com/v2/$KEY" with KEY unset) raises error
+
+        Raises:
+            EnvVarExpansionError: If a partial env var expansion would create invalid URL
+            ValueError: If no valid endpoints remain after expansion
+        """
+        endpoints = []
+        for host in self.hosts:
+            expanded = _expand_env_var(host, network_id=self.id)
+            if expanded:  # Skip None (pure env var that wasn't set)
+                endpoints.append(expanded)
+
+        if not endpoints:
+            raise ValueError(
+                f"Network '{self.id}' has no valid RPC endpoints after env var expansion. "
+                f"Original hosts: {self.hosts}"
+            )
+        return endpoints
+
+    def get_host_with_port(self) -> str:
+        """Get first host URL with port for dev networks.
+
+        Uses urllib.parse to correctly detect if port is already in URL.
+        e.g., "http://127.0.0.1" needs port appended, "http://127.0.0.1:8545" doesn't.
+        """
+        from urllib.parse import urlparse
+
+        endpoints = self.get_endpoints()
+        host = endpoints[0]
+
+        # Only append port for dev networks without explicit port
+        if self.is_development:
+            parsed = urlparse(host)
+            if not parsed.port:  # No explicit port in URL
+                port = self.cmd_settings.get("port", 8545)
+                # Reconstruct URL with port
+                host = f"{parsed.scheme}://{parsed.hostname}:{port}{parsed.path}"
+
+        return host
+
+
+def _get_config_path() -> Path | None:
+    """Get network config file path. Auto-copies brownie config on first use."""
+    brawny_config = Path.home() / ".brawny" / "network-config.yaml"
+
+    if brawny_config.exists():
+        return brawny_config
+
+    # Auto-copy from brownie on first use
+    brownie_config = Path.home() / ".brownie" / "network-config.yaml"
+    if brownie_config.exists():
+        brawny_config.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy(brownie_config, brawny_config)
+        return brawny_config
+
+    return None
+
+
+def _parse_host(host_value: str | list | None, default: str = "") -> list[str]:
+    """Parse host field - accepts string or list, returns list."""
+    if host_value is None:
+        return [default] if default else []
+    if isinstance(host_value, str):
+        return [host_value] if host_value else []
+    return list(host_value)
+
+
+def _parse_networks(data: dict) -> dict[str, NetworkConfig]:
+    """Parse network config file."""
+    networks: dict[str, NetworkConfig] = {}
+
+    # Parse live networks
+    for group in data.get("live", []):
+        for net in group.get("networks", []):
+            networks[net["id"]] = NetworkConfig(
+                id=net["id"],
+                hosts=_parse_host(net.get("host")),
+                chainid=int(net["chainid"]) if "chainid" in net else None,
+                name=net.get("name"),
+                explorer=net.get("explorer"),
+                multicall2=net.get("multicall2"),
+                timeout=net.get("timeout", 30),
+                max_retries=net.get("max_retries", 3),
+                retry_backoff_base=net.get("retry_backoff_base", 1.0),
+                circuit_breaker_seconds=net.get("circuit_breaker_seconds", 300),
+                rate_limit_per_second=net.get("rate_limit_per_second"),
+                rate_limit_burst=net.get("rate_limit_burst"),
+            )
+
+    # Parse development networks (fork resolution happens at connect time)
+    for net in data.get("development", []):
+        networks[net["id"]] = NetworkConfig(
+            id=net["id"],
+            hosts=_parse_host(net.get("host"), default="http://127.0.0.1"),
+            name=net.get("name"),
+            timeout=net.get("timeout", 120),
+            cmd=net.get("cmd"),
+            cmd_settings=dict(net.get("cmd_settings", {})),
+        )
+
+    return networks
+
+
+def load_networks() -> dict[str, NetworkConfig]:
+    """Load all network configurations from Brownie-style config."""
+    networks: dict[str, NetworkConfig] = {}
+
+    # Load from config file
+    config_path = _get_config_path()
+    if config_path:
+        try:
+            with open(config_path) as f:
+                data = yaml.safe_load(f) or {}
+            networks = _parse_networks(data)
+        except yaml.YAMLError as e:
+            raise ValueError(f"Invalid network config at {config_path}: {e}")
+
+    # Add built-in defaults (only if not already defined)
+    _add_defaults(networks)
+
+    return networks
+
+
+def _add_defaults(networks: dict[str, NetworkConfig]) -> None:
+    """Add built-in defaults if not already present."""
+    if "development" not in networks:
+        networks["development"] = NetworkConfig(
+            id="development",
+            name="Anvil (Local)",
+            hosts=["http://127.0.0.1"],
+            cmd="anvil",
+            cmd_settings={"port": 8545, "accounts": 10},
+        )
+
+    if "mainnet-fork" not in networks:
+        # Use env var for fork URL with public fallback
+        # Users should set BRAWNY_FORK_RPC for reliable/fast forking
+        fork_url = "${BRAWNY_FORK_RPC:-https://eth.llamarpc.com}"
+        networks["mainnet-fork"] = NetworkConfig(
+            id="mainnet-fork",
+            name="Anvil (Mainnet Fork)",
+            hosts=["http://127.0.0.1"],
+            cmd="anvil",
+            timeout=120,
+            cmd_settings={
+                "port": 8546,
+                "fork": fork_url,  # Expanded at connect time
+                "accounts": 10,
+            },
+        )

brawny/networks/manager.py

@@ -0,0 +1,423 @@
+"""Network connection management.
+
+Provides Brownie-compatible network.connect()/disconnect() API.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from brawny.networks.config import NetworkConfig, load_networks
+
+if TYPE_CHECKING:
+    from brawny._rpc import RPCManager
+
+
+def _get_pidfile_dir() -> Path:
+    """Get directory for PID files."""
+    path = Path.home() / ".brawny" / "pids"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+class NetworkManager:
+    """Manages network connections with Brownie-compatible API.
+
+    Usage:
+        from brawny import network
+
+        network.connect("mainnet")
+        print(network.show_active())  # "mainnet"
+        print(network.chain_id)       # 1
+        network.disconnect()
+
+    Dev network lifecycle:
+        - PID files stored in ~/.brawny/pids/{network_id}.json
+        - Processes cleaned up on disconnect() or atexit
+        - Handles already-dead processes gracefully
+    """
+
+    def __init__(self) -> None:
+        self._networks: dict[str, NetworkConfig] | None = None
+        self._active: NetworkConfig | None = None
+        self._rpc: RPCManager | None = None
+        self._rpc_process: subprocess.Popen | None = None
+        self._rpc_process_network_id: str | None = None  # Track which network we started
+        self._chain_id: int | None = None  # Cached after first lookup
+
+        # Register cleanup on exit (handles normal exit, not SIGKILL)
+        atexit.register(self._cleanup)
+
+        # Handle SIGTERM gracefully (e.g., from container orchestration)
+        if sys.platform != "win32":
+            signal.signal(signal.SIGTERM, self._signal_cleanup)
+
+    def _signal_cleanup(self, signum: int, frame: object) -> None:
+        """Handle SIGTERM by cleaning up and re-raising."""
+        self._cleanup()
+        # Re-raise to allow normal signal handling
+        signal.signal(signum, signal.SIG_DFL)
+        os.kill(os.getpid(), signum)
+
+    def _cleanup(self) -> None:
+        """Kill RPC process on exit. Safe to call multiple times."""
+        if self._rpc_process is None:
+            return
+
+        # Check if still running (poll() returns None if running)
+        if self._rpc_process.poll() is None:
+            self._rpc_process.terminate()
+            try:
+                self._rpc_process.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                self._rpc_process.kill()
+                self._rpc_process.wait(timeout=1)
+
+        # Clean up PID file
+        if self._rpc_process_network_id:
+            self._remove_pidfile(self._rpc_process_network_id)
+            self._rpc_process_network_id = None
+
+        self._rpc_process = None
+
+    def _write_pidfile(self, network_id: str, pid: int, port: int) -> None:
+        """Write PID file for debugging."""
+        pidfile = _get_pidfile_dir() / f"{network_id}.json"
+        pidfile.write_text(json.dumps({"pid": pid, "port": port, "network_id": network_id}))
+
+    def _remove_pidfile(self, network_id: str) -> None:
+        """Remove PID file."""
+        pidfile = _get_pidfile_dir() / f"{network_id}.json"
+        pidfile.unlink(missing_ok=True)
+
+    def _ensure_networks(self) -> dict[str, NetworkConfig]:
+        """Lazily load networks."""
+        if self._networks is None:
+            self._networks = load_networks()
+        return self._networks
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if connected to a network."""
+        return self._active is not None and self._rpc is not None
+
+    @property
+    def chain_id(self) -> int | None:
+        """Get current chain ID (cached)."""
+        if not self.is_connected or self._rpc is None:
+            return None
+        if self._chain_id is None:
+            self._chain_id = self._rpc.get_chain_id()
+        return self._chain_id
+
+    def show_active(self) -> str | None:
+        """Get ID of currently active network."""
+        return self._active.id if self._active else None
+
+    def connect(
+        self,
+        network_id: str | None = None,
+        launch_rpc: bool = True,
+    ) -> None:
+        """Connect to a network.
+
+        Args:
+            network_id: Network ID to connect to. Priority:
+                       1. Explicit argument
+                       2. BRAWNY_NETWORK env var
+                       3. "development" default
+            launch_rpc: If True, launch RPC process for development networks
+
+        Raises:
+            ConnectionError: If already connected
+            KeyError: If network_id not found
+        """
+        if self.is_connected:
+            raise ConnectionError(
+                f"Already connected to '{self._active.id}'. "
+                "Call network.disconnect() first."
+            )
+
+        networks = self._ensure_networks()
+
+        # Priority: explicit arg > env var > default
+        network_id = network_id or os.environ.get("BRAWNY_NETWORK") or "development"
+
+        if network_id not in networks:
+            available = ", ".join(sorted(networks.keys()))
+            raise KeyError(f"Network '{network_id}' not found. Available: {available}")
+
+        config = networks[network_id]
+
+        # Resolve fork reference at connect time
+        self._resolve_fork(config, networks)
+
+        # Get endpoints (list) - RPCManager handles failover automatically
+        endpoints = config.get_endpoints()
+
+        # Launch RPC for development networks
+        if config.is_development and launch_rpc:
+            local_url = config.get_host_with_port()
+            try:
+                self._launch_rpc(config)
+                self._wait_for_rpc(local_url, timeout=config.timeout)
+            except Exception:
+                # Clean up on failure
+                if self._rpc_process:
+                    self._rpc_process.terminate()
+                    self._rpc_process = None
+                raise
+            # Dev networks only use local endpoint
+            endpoints = [local_url]
+
+        # Create RPCManager with full configuration (preserves brawny's advantages)
+        from brawny._rpc import RPCManager
+
+        self._rpc = RPCManager(
+            endpoints=endpoints,
+            timeout_seconds=float(config.timeout),
+            max_retries=config.max_retries,
+            retry_backoff_base=config.retry_backoff_base,
+            circuit_breaker_seconds=config.circuit_breaker_seconds,
+            rate_limit_per_second=config.rate_limit_per_second,
+            rate_limit_burst=config.rate_limit_burst,
+            chain_id=config.chainid,
+        )
+        self._active = config
+        self._chain_id = None  # Reset cache
+
+        # Verify connection and cache chain_id
+        try:
+            self._chain_id = self._rpc.get_chain_id()
+        except Exception as e:
+            self._cleanup_on_failure()
+            raise ConnectionError(f"Failed to connect to {network_id}: {e}")
+
+        # Update config chainid if not set
+        if config.chainid is None:
+            config.chainid = self._chain_id
+
+    def _cleanup_on_failure(self) -> None:
+        """Clean up state after connection failure."""
+        if self._rpc_process:
+            self._rpc_process.terminate()
+            self._rpc_process = None
+        self._rpc = None
+        self._active = None
+        self._chain_id = None
+
+    def _resolve_fork(
+        self,
+        config: NetworkConfig,
+        networks: dict[str, NetworkConfig],
+    ) -> None:
+        """Resolve fork reference to actual URL at connect time.
+
+        Only inherits chain_id/explorer/multicall2 from forked network if not
+        explicitly set on the dev config. This allows intentional overrides
+        (e.g., testing with a different chain_id).
+        """
+        fork_ref = config.cmd_settings.get("fork")
+        if not fork_ref:
+            return
+
+        # If fork is a network ID, resolve to URL (uses first endpoint from list)
+        if fork_ref in networks:
+            live = networks[fork_ref]
+            endpoints = live.get_endpoints()
+            config.cmd_settings["fork"] = endpoints[0] if endpoints else fork_ref
+
+            # Only inherit properties if not explicitly set on dev config
+            if config.chainid is None:
+                config.chainid = live.chainid
+            if config.explorer is None:
+                config.explorer = live.explorer
+            if config.multicall2 is None:
+                config.multicall2 = live.multicall2
+
+            # Set chain_id in cmd_settings for Anvil (only if not already set)
+            if "chain_id" not in config.cmd_settings and config.chainid:
+                config.cmd_settings["chain_id"] = config.chainid
+
+    def disconnect(self, kill_rpc: bool = True) -> None:
+        """Disconnect from the current network.
+
+        Args:
+            kill_rpc: If True (default), terminate any RPC process we started.
+                     Safe to call even if process already died.
+        """
+        if not self._active:
+            raise ConnectionError("Not connected to any network")
+
+        if kill_rpc and self._rpc_process:
+            # Safe termination - handles already-dead processes
+            if self._rpc_process.poll() is None:
+                self._rpc_process.terminate()
+                try:
+                    self._rpc_process.wait(timeout=3)
+                except subprocess.TimeoutExpired:
+                    self._rpc_process.kill()
+                    self._rpc_process.wait(timeout=1)
+
+            # Clean up PID file
+            if self._rpc_process_network_id:
+                self._remove_pidfile(self._rpc_process_network_id)
+                self._rpc_process_network_id = None
+
+            self._rpc_process = None
+
+        self._rpc = None
+        self._active = None
+        self._chain_id = None
+
+    def _launch_rpc(self, config: NetworkConfig) -> None:
+        """Launch RPC process for development network.
+
+        Writes PID file to ~/.brawny/pids/{network_id}.json for debugging.
+        """
+        import socket
+
+        if config.cmd is None:
+            raise RuntimeError(f"Network '{config.id}' has no cmd configured")
+
+        # Check if port is available
+        port = config.cmd_settings.get("port", 8545)
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            if s.connect_ex(("127.0.0.1", port)) == 0:
+                raise RuntimeError(
+                    f"Port {port} already in use. "
+                    f"Use a different port in cmd_settings or stop the existing process."
+                )
+
+        # Check if command exists
+        cmd_name = config.cmd.split()[0]
+        if not shutil.which(cmd_name):
+            raise RuntimeError(f"RPC command '{cmd_name}' not found. Install it first.")
+
+        # Build command as list (avoids shell=True security issues)
+        cmd_parts = self._build_rpc_command(config)
+
+        # Platform-specific process group handling
+        kwargs: dict[str, object] = {
+            "stdout": subprocess.DEVNULL,
+            "stderr": subprocess.DEVNULL,
+        }
+        if sys.platform != "win32":
+            kwargs["start_new_session"] = True  # Unix: create new process group
+
+        self._rpc_process = subprocess.Popen(cmd_parts, **kwargs)
+        self._rpc_process_network_id = config.id
+
+        # Write PID file for debugging
+        self._write_pidfile(config.id, self._rpc_process.pid, port)
+
+    def _build_rpc_command(self, config: NetworkConfig) -> list[str]:
+        """Build command list for RPC process."""
+        if config.cmd is None:
+            raise RuntimeError(f"Network '{config.id}' has no cmd configured")
+
+        # Split base command (handles "npx hardhat node" etc.)
+        cmd_parts = config.cmd.split()
+        settings = config.cmd_settings
+
+        if "anvil" in config.cmd.lower():
+            if "port" in settings:
+                cmd_parts.extend(["--port", str(settings["port"])])
+            if "fork" in settings:
+                # Use _expand_env_var for consistency with config loading
+                from brawny.networks.config import _expand_env_var
+                fork_url = _expand_env_var(str(settings["fork"]), network_id=config.id)
+                if fork_url:
+                    cmd_parts.extend(["--fork-url", fork_url])
+            if "fork_block" in settings:
+                cmd_parts.extend(["--fork-block-number", str(settings["fork_block"])])
+            if "accounts" in settings:
+                cmd_parts.extend(["--accounts", str(settings["accounts"])])
+            if "balance" in settings:
+                cmd_parts.extend(["--balance", str(settings["balance"])])
+            if "chain_id" in settings:
+                cmd_parts.extend(["--chain-id", str(settings["chain_id"])])
+
+        elif "ganache" in config.cmd.lower():
+            if "port" in settings:
+                cmd_parts.extend(["--port", str(settings["port"])])
+            if "fork" in settings:
+                from brawny.networks.config import _expand_env_var
+                fork_url = _expand_env_var(str(settings["fork"]), network_id=config.id)
+                if fork_url:
+                    cmd_parts.extend(["--fork", fork_url])
+            if "accounts" in settings:
+                cmd_parts.extend(["--accounts", str(settings["accounts"])])
+            if "chain_id" in settings:
+                cmd_parts.extend(["--chainId", str(settings["chain_id"])])
+
+        return cmd_parts
+
+    def _wait_for_rpc(self, host: str, timeout: int = 30) -> None:
+        """Wait for RPC to become responsive.
+
+        Uses httpx for consistency with existing console.py implementation.
+        """
+        import httpx
+
+        start = time.time()
+        while time.time() - start < timeout:
+            # Check if process died
+            if self._rpc_process and self._rpc_process.poll() is not None:
+                raise RuntimeError("RPC process exited unexpectedly")
+
+            try:
+                resp = httpx.post(
+                    host,
+                    json={
+                        "jsonrpc": "2.0",
+                        "method": "eth_blockNumber",
+                        "params": [],
+                        "id": 1,
+                    },
+                    timeout=2.0,
+                )
+                if resp.status_code == 200:
+                    return
+            except httpx.RequestError:
+                pass
+            time.sleep(0.3)
+
+        raise TimeoutError(f"RPC at {host} not responding after {timeout}s")
+
+    def list_networks(self) -> dict[str, list[str]]:
+        """List all available networks grouped by type."""
+        networks = self._ensure_networks()
+        return {
+            "live": [n.id for n in networks.values() if not n.is_development],
+            "development": [n.id for n in networks.values() if n.is_development],
+        }
+
+    @property
+    def rpc(self) -> RPCManager | None:
+        """Get underlying RPCManager."""
+        return self._rpc
+
+
+# Global singleton
+_manager: NetworkManager | None = None
+
+
+def _get_manager() -> NetworkManager:
+    """Get or create network manager singleton."""
+    global _manager
+    if _manager is None:
+        _manager = NetworkManager()
+    return _manager
+
+
+__all__ = ["NetworkManager", "_get_manager"]