alloy_node_bindings/nodes/

reth.rs

//! Utilities for configuring and launching a Reth node.

use crate::{
    utils::{extract_endpoint, GracefulShutdown},
    NodeError, NODE_STARTUP_TIMEOUT,
};
use alloy_genesis::Genesis;
use rand::Rng;
use std::{
    ffi::OsString,
    fs::create_dir_all,
    io::{BufRead, BufReader},
    path::PathBuf,
    process::{Child, ChildStdout, Command, Stdio},
    time::Instant,
};
use url::Url;

/// The exposed APIs
const API: &str = "eth,net,web3,txpool,trace,rpc,reth,ots,admin,debug";

/// The reth command
const RETH: &str = "reth";

/// The default HTTP port for Reth.
const DEFAULT_HTTP_PORT: u16 = 8545;

/// The default WS port for Reth.
const DEFAULT_WS_PORT: u16 = 8546;

/// The default auth port for Reth.
const DEFAULT_AUTH_PORT: u16 = 8551;

/// The default P2P port for Reth.
const DEFAULT_P2P_PORT: u16 = 30303;

/// A Reth instance. Will close the instance when dropped.
///
/// Construct this using [`Reth`].
#[derive(Debug)]
pub struct RethInstance {
    pid: Child,
    host: String,
    instance: u16,
    http_port: u16,
    ws_port: u16,
    auth_port: Option<u16>,
    p2p_port: Option<u16>,
    ipc: Option<PathBuf>,
    data_dir: Option<PathBuf>,
    genesis: Option<Genesis>,
}

impl RethInstance {
    /// Returns the host of this instance.
    pub fn host(&self) -> &str {
        &self.host
    }

    /// Returns the instance number of this instance.
    pub const fn instance(&self) -> u16 {
        self.instance
    }

    /// Returns the HTTP port of this instance.
    pub const fn http_port(&self) -> u16 {
        self.http_port
    }

    /// Returns the WS port of this instance.
    pub const fn ws_port(&self) -> u16 {
        self.ws_port
    }

    /// Returns the auth port of this instance.
    pub const fn auth_port(&self) -> Option<u16> {
        self.auth_port
    }

    /// Returns the p2p port of this instance.
    /// If discovery is disabled, this will be `None`.
    pub const fn p2p_port(&self) -> Option<u16> {
        self.p2p_port
    }

    /// Returns the HTTP endpoint of this instance.
    #[doc(alias = "http_endpoint")]
    pub fn endpoint(&self) -> String {
        format!("http://{}:{}", self.host, self.http_port)
    }

    /// Returns the Websocket endpoint of this instance.
    pub fn ws_endpoint(&self) -> String {
        format!("ws://{}:{}", self.host, self.ws_port)
    }

    /// Returns the IPC endpoint of this instance.
    pub fn ipc_endpoint(&self) -> String {
        self.ipc.as_ref().map_or_else(|| "reth.ipc".to_string(), |ipc| ipc.display().to_string())
    }

    /// Returns the HTTP endpoint url of this instance.
    #[doc(alias = "http_endpoint_url")]
    pub fn endpoint_url(&self) -> Url {
        Url::parse(&self.endpoint()).unwrap()
    }

    /// Returns the Websocket endpoint url of this instance.
    pub fn ws_endpoint_url(&self) -> Url {
        Url::parse(&self.ws_endpoint()).unwrap()
    }

    /// Returns the path to this instances' data directory.
    pub const fn data_dir(&self) -> Option<&PathBuf> {
        self.data_dir.as_ref()
    }

    /// Returns the genesis configuration supplied with [`Reth::genesis`], if any.
    pub const fn genesis(&self) -> Option<&Genesis> {
        self.genesis.as_ref()
    }

    /// Takes the stdout contained in the child process.
    ///
    /// Stdout is available only when [`Reth::keep_stdout`] was set. This leaves `None` in its
    /// place, so a second call returns [`NodeError::NoStdout`].
    pub fn stdout(&mut self) -> Result<ChildStdout, NodeError> {
        self.pid.stdout.take().ok_or(NodeError::NoStdout)
    }
}

impl Drop for RethInstance {
    fn drop(&mut self) {
        GracefulShutdown::shutdown(&mut self.pid, 10, "reth");
    }
}

/// Builder for launching `reth`.
///
/// [`Reth::new`] configures a regular node. Call [`Reth::dev`] for an isolated development chain.
/// [`Reth::spawn`] panics on any startup failure; use [`Reth::try_spawn`] to handle errors.
///
/// # Example
///
/// ```no_run
/// use alloy_node_bindings::Reth;
///
/// # fn main() -> Result<(), alloy_node_bindings::NodeError> {
/// let reth = Reth::new().dev().block_time("12s").try_spawn()?;
/// println!("Reth is listening at {}", reth.endpoint());
///
/// drop(reth); // this will kill the instance
/// # Ok(())
/// # }
/// ```
#[derive(Clone, Debug)]
#[must_use = "This Builder struct does nothing unless it is `spawn`ed"]
pub struct Reth {
    dev: bool,
    host: Option<String>,
    http_port: u16,
    ws_port: u16,
    auth_port: u16,
    p2p_port: u16,
    block_time: Option<String>,
    instance: u16,
    discovery_enabled: bool,
    program: Option<PathBuf>,
    ipc_path: Option<PathBuf>,
    ipc_enabled: bool,
    data_dir: Option<PathBuf>,
    chain_or_path: Option<String>,
    genesis: Option<Genesis>,
    args: Vec<OsString>,
    keep_stdout: bool,
}

impl Default for Reth {
    fn default() -> Self {
        Self::new()
    }
}

impl Reth {
    /// Creates a Reth builder in regular (non-dev) mode.
    ///
    /// The instance number is chosen from `1..=199` to reduce the odds of port conflicts. Change it
    /// with [`Reth::instance`], or set it to zero to use Reth's base default ports. Reth permits
    /// instance numbers up to 200.
    pub fn new() -> Self {
        Self {
            dev: false,
            host: None,
            http_port: DEFAULT_HTTP_PORT,
            ws_port: DEFAULT_WS_PORT,
            auth_port: DEFAULT_AUTH_PORT,
            p2p_port: DEFAULT_P2P_PORT,
            block_time: None,
            instance: rand::thread_rng().gen_range(1..200),
            discovery_enabled: true,
            program: None,
            ipc_path: None,
            ipc_enabled: false,
            data_dir: None,
            chain_or_path: None,
            genesis: None,
            args: Vec::new(),
            keep_stdout: false,
        }
    }

    /// Creates a Reth builder which will execute `reth` at the given path.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use alloy_node_bindings::Reth;
    /// # fn main() -> Result<(), alloy_node_bindings::NodeError> {
    /// let reth = Reth::at("/path/to/reth").dev().try_spawn()?;
    ///
    /// println!("Reth running at `{}`", reth.endpoint());
    /// # Ok(())
    /// # }
    /// ```
    pub fn at(path: impl Into<PathBuf>) -> Self {
        Self::new().path(path)
    }

    /// Sets the `path` to the `reth` executable
    ///
    /// By default, it's expected that `reth` is in `$PATH`, see also
    /// [`std::process::Command::new()`]
    pub fn path<T: Into<PathBuf>>(mut self, path: T) -> Self {
        self.program = Some(path.into());
        self
    }

    /// Enable `dev` mode for the Reth instance.
    pub const fn dev(mut self) -> Self {
        self.dev = true;
        self
    }

    /// Sets the host which will be used when the `reth` instance is launched.
    ///
    /// Defaults to `localhost`.
    pub fn host<T: Into<String>>(mut self, host: T) -> Self {
        self.host = Some(host.into());
        self
    }

    /// Sets the HTTP port for the Reth instance.
    /// Note: this resets the instance number to 0 to allow for custom ports.
    pub const fn http_port(mut self, http_port: u16) -> Self {
        self.http_port = http_port;
        self.instance = 0;
        self
    }

    /// Sets the WS port for the Reth instance.
    /// Note: this resets the instance number to 0 to allow for custom ports.
    pub const fn ws_port(mut self, ws_port: u16) -> Self {
        self.ws_port = ws_port;
        self.instance = 0;
        self
    }

    /// Sets the auth port for the Reth instance.
    /// Note: this resets the instance number to 0 to allow for custom ports.
    pub const fn auth_port(mut self, auth_port: u16) -> Self {
        self.auth_port = auth_port;
        self.instance = 0;
        self
    }

    /// Sets the p2p port for the Reth instance.
    /// Note: this resets the instance number to 0 to allow for custom ports.
    pub const fn p2p_port(mut self, p2p_port: u16) -> Self {
        self.p2p_port = p2p_port;
        self.instance = 0;
        self
    }

    /// Sets the block time for a dev-mode Reth instance.
    ///
    /// Reth parses this with `humantime` syntax, such as `"12s"`. The setting is ignored unless
    /// [`Self::dev`] is also enabled.
    pub fn block_time(mut self, block_time: &str) -> Self {
        self.block_time = Some(block_time.to_string());
        self
    }

    /// Disables discovery for the Reth instance.
    pub const fn disable_discovery(mut self) -> Self {
        self.discovery_enabled = false;
        self
    }

    /// Sets the chain name or path to a chain spec for the Reth instance.
    ///
    /// Passed through to `reth node --chain <name-or-path>`. To launch Reth with a custom genesis,
    /// write the genesis or chain specification to disk and pass that path here.
    pub fn chain_or_path(mut self, chain_or_path: &str) -> Self {
        self.chain_or_path = Some(chain_or_path.to_string());
        self
    }

    /// Enable IPC for the Reth instance.
    pub const fn enable_ipc(mut self) -> Self {
        self.ipc_enabled = true;
        self
    }

    /// Sets the Reth instance number. Set to zero to use the base default ports.
    ///
    /// By default, a random number in `1..=199` is used; Reth permits values up to 200.
    pub const fn instance(mut self, instance: u16) -> Self {
        self.instance = instance;
        self
    }

    /// Sets the IPC path for the socket.
    ///
    /// This also enables IPC, as setting a path implies the intent to use IPC.
    pub fn ipc_path<T: Into<PathBuf>>(mut self, path: T) -> Self {
        self.ipc_path = Some(path.into());
        self.ipc_enabled = true;
        self
    }

    /// Sets the data directory for reth.
    pub fn data_dir<T: Into<PathBuf>>(mut self, path: T) -> Self {
        self.data_dir = Some(path.into());
        self
    }

    /// Stores the genesis configuration on the returned [`RethInstance`].
    ///
    /// The spawned node can be inspected through [`RethInstance::genesis`] to recover the genesis
    /// value that was supplied to the builder. To launch Reth with a custom genesis or chain
    /// specification, write that specification to disk and pass the path with
    /// [`Reth::chain_or_path`].
    pub fn genesis(mut self, genesis: Genesis) -> Self {
        self.genesis = Some(genesis);
        self
    }

    /// Keep the handle to reth's stdout in order to read from it.
    ///
    /// Caution: if the stdout handle isn't used, this can end up blocking.
    pub const fn keep_stdout(mut self) -> Self {
        self.keep_stdout = true;
        self
    }

    /// Adds an argument to pass to `reth`.
    ///
    /// Pass any arg that is not supported by the builder.
    pub fn arg<T: Into<OsString>>(mut self, arg: T) -> Self {
        self.args.push(arg.into());
        self
    }

    /// Adds multiple arguments to pass to `reth`.
    ///
    /// Pass any args that is not supported by the builder.
    pub fn args<I, S>(mut self, args: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<OsString>,
    {
        for arg in args {
            self = self.arg(arg);
        }
        self
    }

    /// Consumes the builder and spawns `reth`.
    ///
    /// # Panics
    ///
    /// If spawning the instance fails at any point.
    #[track_caller]
    pub fn spawn(self) -> RethInstance {
        self.try_spawn().unwrap()
    }

    /// Consumes the builder, spawns `reth`, and waits for its services to report ready.
    ///
    /// Returns an error if the process cannot be started, reports a fatal startup error, or does
    /// not become ready before [`NODE_STARTUP_TIMEOUT`] is observed. The deadline is checked
    /// between complete stdout lines; a live process that emits no newline can block this call
    /// past the deadline.
    pub fn try_spawn(self) -> Result<RethInstance, NodeError> {
        let bin_path = self
            .program
            .as_ref()
            .map_or_else(|| RETH.as_ref(), |bin| bin.as_os_str())
            .to_os_string();
        let mut cmd = Command::new(&bin_path);
        // `reth` uses stdout for its logs
        cmd.stdout(Stdio::piped());

        // Use Reth's `node` subcommand.
        cmd.arg("node");

        // Set the ports if they are not the default.
        if self.http_port != DEFAULT_HTTP_PORT {
            cmd.arg("--http.port").arg(self.http_port.to_string());
        }

        if self.ws_port != DEFAULT_WS_PORT {
            cmd.arg("--ws.port").arg(self.ws_port.to_string());
        }

        if self.auth_port != DEFAULT_AUTH_PORT {
            cmd.arg("--authrpc.port").arg(self.auth_port.to_string());
        }

        if self.p2p_port != DEFAULT_P2P_PORT {
            cmd.arg("--discovery.port").arg(self.p2p_port.to_string());
        }

        // If the `dev` flag is set, enable it.
        if self.dev {
            // Enable the dev mode.
            // This mode uses a local proof-of-authority consensus engine with either fixed block
            // times or automatically mined blocks.
            // Disables network discovery and enables local http server.
            // Prefunds 20 accounts derived by mnemonic "test test test test test test test test
            // test test test junk" with 10 000 ETH each.
            cmd.arg("--dev");

            // If the block time is set, use it.
            if let Some(block_time) = self.block_time {
                cmd.arg("--dev.block-time").arg(block_time);
            }
        }

        // If IPC is not enabled on the builder, disable it.
        if !self.ipc_enabled {
            cmd.arg("--ipcdisable");
        }

        // Open the HTTP API.
        cmd.arg("--http");
        cmd.arg("--http.api").arg(API);

        if let Some(ref host) = self.host {
            cmd.arg("--http.addr").arg(host);
        }

        // Open the WS API.
        cmd.arg("--ws");
        cmd.arg("--ws.api").arg(API);

        if let Some(ref host) = self.host {
            cmd.arg("--ws.addr").arg(host);
        }

        // Configure the IPC path if it is set.
        if let Some(ipc) = &self.ipc_path {
            cmd.arg("--ipcpath").arg(ipc);
        }

        // If the instance is set, use it.
        // Set the `instance` to 0 to use the default ports.
        // By defining a custom `http_port`, `ws_port`, `auth_port`, or `p2p_port`, the instance
        // number will be set to 0 automatically.
        if self.instance > 0 {
            cmd.arg("--instance").arg(self.instance.to_string());
        }

        if let Some(data_dir) = &self.data_dir {
            cmd.arg("--datadir").arg(data_dir);

            // create the directory if it doesn't exist
            if !data_dir.exists() {
                create_dir_all(data_dir).map_err(NodeError::CreateDirError)?;
            }
        }

        if self.discovery_enabled {
            // Verbosity is required to read the P2P port from the logs.
            cmd.arg("--verbosity").arg("-vvv");
        } else {
            cmd.arg("--disable-discovery");
            cmd.arg("--no-persist-peers");
        }

        if let Some(chain_or_path) = self.chain_or_path {
            cmd.arg("--chain").arg(chain_or_path);
        }

        // Disable color output to make parsing logs easier.
        cmd.arg("--color").arg("never");

        // Add any additional arguments.
        cmd.args(self.args);

        let mut child = cmd.spawn().map_err(NodeError::SpawnError)?;

        let stdout = child.stdout.take().ok_or(NodeError::NoStdout)?;

        let start = Instant::now();
        let mut reader = BufReader::new(stdout);

        let mut http_port = 0;
        let mut ws_port = 0;
        let mut auth_port = 0;
        let mut p2p_port = 0;

        let mut ports_started = false;
        let mut p2p_started = !self.discovery_enabled;

        loop {
            if start + NODE_STARTUP_TIMEOUT <= Instant::now() {
                let _ = child.kill();
                return Err(NodeError::Timeout);
            }

            let mut line = String::with_capacity(120);
            reader.read_line(&mut line).map_err(NodeError::ReadLineError)?;

            if line.contains("RPC HTTP server started") {
                if let Some(addr) = extract_endpoint("url=", &line) {
                    http_port = addr.port();
                }
            }

            if line.contains("RPC WS server started") {
                if let Some(addr) = extract_endpoint("url=", &line) {
                    ws_port = addr.port();
                }
            }

            if line.contains("RPC auth server started") {
                if let Some(addr) = extract_endpoint("url=", &line) {
                    auth_port = addr.port();
                }
            }

            // Encountered a critical error, exit early.
            if line.contains("ERROR") {
                let _ = child.kill();
                return Err(NodeError::Fatal(line));
            }

            if http_port != 0 && ws_port != 0 && auth_port != 0 {
                ports_started = true;
            }

            if self.discovery_enabled {
                if line.contains("Updated local ENR") {
                    if let Some(port) = extract_endpoint("IpV4 UDP Socket", &line) {
                        p2p_port = port.port();
                        p2p_started = true;
                    }
                }
            } else {
                p2p_started = true;
            }

            // If all ports have started we are ready to be queried.
            if ports_started && p2p_started {
                break;
            }
        }

        if self.keep_stdout {
            // re-attach the stdout handle if requested
            child.stdout = Some(reader.into_inner());
        }

        Ok(RethInstance {
            pid: child,
            host: self.host.unwrap_or_else(|| "localhost".to_string()),
            instance: self.instance,
            http_port,
            ws_port,
            p2p_port: (p2p_port != 0).then_some(p2p_port),
            ipc: self.ipc_path,
            data_dir: self.data_dir,
            auth_port: Some(auth_port),
            genesis: self.genesis,
        })
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn can_set_host() {
        let reth = Reth::new().host("0.0.0.0").dev().try_spawn();
        if let Ok(reth) = reth {
            assert_eq!(reth.host(), "0.0.0.0");
            assert!(reth.endpoint().starts_with("http://0.0.0.0:"));
            assert!(reth.ws_endpoint().starts_with("ws://0.0.0.0:"));
        }
    }

    #[test]
    fn default_host_is_localhost() {
        let reth = Reth::new().dev().try_spawn();
        if let Ok(reth) = reth {
            assert_eq!(reth.host(), "localhost");
            assert!(reth.endpoint().starts_with("http://localhost:"));
            assert!(reth.ws_endpoint().starts_with("ws://localhost:"));
        }
    }

    #[test]
    fn default_matches_new_semantics() {
        let reth = Reth::default();

        assert!(!reth.dev);
        assert_eq!(reth.host, None);
        assert_eq!(reth.http_port, DEFAULT_HTTP_PORT);
        assert_eq!(reth.ws_port, DEFAULT_WS_PORT);
        assert_eq!(reth.auth_port, DEFAULT_AUTH_PORT);
        assert_eq!(reth.p2p_port, DEFAULT_P2P_PORT);
        assert_eq!(reth.block_time, None);
        assert!((1..200).contains(&reth.instance));
        assert!(reth.discovery_enabled);
        assert_eq!(reth.program, None);
        assert_eq!(reth.ipc_path, None);
        assert!(!reth.ipc_enabled);
        assert_eq!(reth.data_dir, None);
        assert_eq!(reth.chain_or_path, None);
        assert_eq!(reth.genesis, None);
        assert!(reth.args.is_empty());
        assert!(!reth.keep_stdout);
    }
}