Allow running a faucet from linera net up (#3115)

## Motivation

First step in addressing #2890

## Proposal

* Make a function of `find_owned_chains` out of the code in
`ClientWrapper::drop()`
* Add an option `--with-faucet-chain N` to `linera net up` as well as
`--faucet-port` and `--faucet-amount`
* Add a simple test

The only caveat is that `N` cannot be a chain-id (since we wouldn't know
what to write) so we use the index amongst root chains (typically 1 for
the first non-admin initial chain).

## Test Plan

CI

Author: ma2bd

CLI.md

@@ -903,6 +903,13 @@ Start a Local Linera Network
 * `--external-protocol <EXTERNAL_PROTOCOL>` — External protocol used, either grpc or grpcs
 
   Default value: `grpc`
+* `--with-faucet-chain <WITH_FAUCET_CHAIN>` — If present, a faucet is started using the given chain root number (0 for the admin chain, 1 for the first non-admin initial chain, etc)
+* `--faucet-port <FAUCET_PORT>` — The port on which to run the faucet server
+
+  Default value: `8080`
+* `--faucet-amount <FAUCET_AMOUNT>` — The number of tokens to send to each new chain created by the faucet
+
+  Default value: `1000`
 
 
 

linera-client/src/client_options.rs

@@ -712,7 +712,7 @@ pub enum ClientCommand {
         config: ChainListenerConfig,
 
         /// The port on which to run the server
-        #[arg(long = "port", default_value = "8080")]
+        #[arg(long, default_value = "8080")]
         port: NonZeroU16,
     },
 
@@ -723,11 +723,11 @@ pub enum ClientCommand {
         chain_id: Option<ChainId>,
 
         /// The port on which to run the server
-        #[arg(long = "port", default_value = "8080")]
+        #[arg(long, default_value = "8080")]
         port: NonZeroU16,
 
         /// The number of tokens to send to each new chain.
-        #[arg(long = "amount")]
+        #[arg(long)]
         amount: Amount,
 
         /// The end timestamp: The faucet will rate-limit the token supply so it runs out of money
@@ -980,6 +980,7 @@ impl DatabaseToolCommand {
     }
 }
 
+#[allow(clippy::large_enum_variant)]
 #[derive(Clone, clap::Parser)]
 pub enum NetCommand {
     /// Start a Local Linera Network
@@ -1052,6 +1053,19 @@ pub enum NetCommand {
         /// External protocol used, either grpc or grpcs.
         #[arg(long, default_value = "grpc")]
         external_protocol: String,
+
+        /// If present, a faucet is started using the given chain root number (0 for the
+        /// admin chain, 1 for the first non-admin initial chain, etc).
+        #[arg(long)]
+        with_faucet_chain: Option<u32>,
+
+        /// The port on which to run the faucet server
+        #[arg(long, default_value = "8080")]
+        faucet_port: NonZeroU16,
+
+        /// The number of tokens to send to each new chain created by the faucet.
+        #[arg(long, default_value = "1000")]
+        faucet_amount: Amount,
     },
 
     /// Print a bash helper script to make `linera net up` easier to use. The script is

linera-service/src/cli_wrappers/mod.rs

@@ -35,7 +35,8 @@ use anyhow::Result;
 use async_trait::async_trait;
 use linera_execution::ResourceControlPolicy;
 pub use wallet::{
-    ApplicationWrapper, ClientWrapper, Faucet, FaucetOption, NodeService, OnClientDrop,
+    ApplicationWrapper, ClientWrapper, Faucet, FaucetOption, FaucetService, NodeService,
+    OnClientDrop,
 };
 
 /// The information needed to start a Linera net of a particular kind.

linera-service/src/linera/main.rs

@@ -1638,6 +1638,9 @@ async fn run(options: &ClientOptions) -> Result<i32, anyhow::Error> {
                 path: _,
                 storage: _,
                 external_protocol: _,
+                with_faucet_chain,
+                faucet_port,
+                faucet_amount,
             } => {
                 net_up_utils::handle_net_up_kubernetes(
                     *extra_wallets,
@@ -1650,6 +1653,9 @@ async fn run(options: &ClientOptions) -> Result<i32, anyhow::Error> {
                     *no_build,
                     docker_image_name.clone(),
                     policy_config.into_policy(),
+                    *with_faucet_chain,
+                    *faucet_port,
+                    *faucet_amount,
                 )
                 .boxed()
                 .await?;
@@ -1667,6 +1673,9 @@ async fn run(options: &ClientOptions) -> Result<i32, anyhow::Error> {
                 path,
                 storage,
                 external_protocol,
+                with_faucet_chain,
+                faucet_port,
+                faucet_amount,
                 ..
             } => {
                 net_up_utils::handle_net_up_service(
@@ -1680,6 +1689,9 @@ async fn run(options: &ClientOptions) -> Result<i32, anyhow::Error> {
                     path,
                     storage,
                     external_protocol.clone(),
+                    *with_faucet_chain,
+                    *faucet_port,
+                    *faucet_amount,
                 )
                 .boxed()
                 .await?;

linera-service/src/linera/net_up_utils.rs

@@ -1,16 +1,17 @@
 // Copyright (c) Zefchain Labs, Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-use std::str::FromStr;
+use std::{num::NonZeroU16, str::FromStr};
 
 use colored::Colorize as _;
-use linera_base::{data_types::Amount, time::Duration};
+use linera_base::{data_types::Amount, identifiers::ChainId, time::Duration};
 use linera_client::storage::{StorageConfig, StorageConfigNamespace};
 use linera_execution::ResourceControlPolicy;
 use linera_service::{
     cli_wrappers::{
         local_net::{Database, LocalNetConfig, PathProvider, StorageConfigBuilder},
-        ClientWrapper, FaucetOption, LineraNet, LineraNetConfig, Network, NetworkConfig,
+        ClientWrapper, FaucetOption, FaucetService, LineraNet, LineraNetConfig, Network,
+        NetworkConfig,
     },
     util::listen_for_shutdown_signals,
 };
@@ -113,6 +114,9 @@ pub async fn handle_net_up_kubernetes(
     no_build: bool,
     docker_image_name: String,
     policy: ResourceControlPolicy,
+    with_faucet_chain: Option<u32>,
+    faucet_port: NonZeroU16,
+    faucet_amount: Amount,
 ) -> anyhow::Result<()> {
     if num_initial_validators < 1 {
         panic!("The local test network must have at least one validator.");
@@ -136,9 +140,17 @@ pub async fn handle_net_up_kubernetes(
         docker_image_name,
         policy,
     };
-    let (mut net, client1) = config.instantiate().await?;
-    net_up(extra_wallets, &mut net, client1).await?;
-    wait_for_shutdown(shutdown_notifier, &mut net).await
+    let (mut net, client) = config.instantiate().await?;
+    let faucet_service = create_wallets_and_faucets(
+        extra_wallets,
+        &mut net,
+        client,
+        with_faucet_chain,
+        faucet_port,
+        faucet_amount,
+    )
+    .await?;
+    wait_for_shutdown(shutdown_notifier, &mut net, faucet_service).await
 }
 
 #[expect(clippy::too_many_arguments)]
@@ -153,6 +165,9 @@ pub async fn handle_net_up_service(
     path: &Option<String>,
     storage: &Option<String>,
     external_protocol: String,
+    with_faucet_chain: Option<u32>,
+    faucet_port: NonZeroU16,
+    faucet_amount: Amount,
 ) -> anyhow::Result<()> {
     if num_initial_validators < 1 {
         panic!("The local test network must have at least one validator.");
@@ -190,29 +205,46 @@ pub async fn handle_net_up_service(
         storage_config_builder,
         path_provider,
     };
-    let (mut net, client1) = config.instantiate().await?;
-    net_up(extra_wallets, &mut net, client1).await?;
-    wait_for_shutdown(shutdown_notifier, &mut net).await
+    let (mut net, client) = config.instantiate().await?;
+    let faucet_service = create_wallets_and_faucets(
+        extra_wallets,
+        &mut net,
+        client,
+        with_faucet_chain,
+        faucet_port,
+        faucet_amount,
+    )
+    .await?;
+    wait_for_shutdown(shutdown_notifier, &mut net, faucet_service).await
 }
 
 async fn wait_for_shutdown(
     shutdown_notifier: CancellationToken,
     net: &mut impl LineraNet,
+    faucet_service: Option<FaucetService>,
 ) -> anyhow::Result<()> {
     shutdown_notifier.cancelled().await;
-    eprintln!("\nTerminating the local test network");
+    eprintln!();
+    if let Some(service) = faucet_service {
+        eprintln!("Terminating the faucet service");
+        service.terminate().await?;
+    }
+    eprintln!("Terminating the local test network");
     net.terminate().await?;
-    eprintln!("\nDone.");
+    eprintln!("Done.");
 
     Ok(())
 }
 
-async fn net_up(
+async fn create_wallets_and_faucets(
     extra_wallets: Option<usize>,
     net: &mut impl LineraNet,
-    client1: ClientWrapper,
-) -> Result<(), anyhow::Error> {
-    let default_chain = client1
+    client: ClientWrapper,
+    with_faucet_chain: Option<u32>,
+    faucet_port: NonZeroU16,
+    faucet_amount: Amount,
+) -> Result<Option<FaucetService>, anyhow::Error> {
+    let default_chain = client
         .default_chain()
         .expect("Initialized clients should always have a default chain");
 
@@ -241,15 +273,15 @@ async fn net_up(
         "{}",
         format!(
             "export LINERA_WALLET{suffix}=\"{}\"",
-            client1.wallet_path().display()
+            client.wallet_path().display()
         )
         .bold()
     );
     println!(
         "{}",
         format!(
             "export LINERA_STORAGE{suffix}=\"{}\"\n",
-            client1.storage_path()
+            client.storage_path()
         )
         .bold()
     );
@@ -260,7 +292,7 @@ async fn net_up(
             let extra_wallet = net.make_client().await;
             extra_wallet.wallet_init(&[], FaucetOption::None).await?;
             let unassigned_key = extra_wallet.keygen().await?;
-            let new_chain_msg_id = client1
+            let new_chain_msg_id = client
                 .open_chain(default_chain, Some(unassigned_key), Amount::ZERO)
                 .await?
                 .0;
@@ -286,9 +318,23 @@ async fn net_up(
         }
     }
 
+    // Run the faucet,
+    let faucet_service = if let Some(faucet_chain) = with_faucet_chain {
+        let service = client
+            .run_faucet(
+                Some(faucet_port.into()),
+                ChainId::root(faucet_chain),
+                faucet_amount,
+            )
+            .await?;
+        Some(service)
+    } else {
+        None
+    };
+
     eprintln!(
         "\nREADY!\nPress ^C to terminate the local test network and clean the temporary directory."
     );
 
-    Ok(())
+    Ok(faucet_service)
 }

linera-service/tests/local_net_tests.rs

@@ -29,6 +29,8 @@ use linera_service::{
     test_name,
 };
 use test_case::test_case;
+#[cfg(feature = "storage-service")]
+use {linera_base::port::get_free_port, linera_service::cli_wrappers::Faucet};
 
 #[cfg(feature = "benchmark")]
 fn get_fungible_account_owner(client: &ClientWrapper) -> AccountOwner {
@@ -732,41 +734,67 @@ async fn test_storage_service_linera_net_up_simple() -> Result<()> {
     let _guard = INTEGRATION_TEST_GUARD.lock().await;
     tracing::info!("Starting test {}", test_name!());
 
+    let port = get_free_port().await?;
+
     let mut command = Command::new(env!("CARGO_BIN_EXE_linera"));
-    command.args(["net", "up"]);
+    command.args([
+        "net",
+        "up",
+        "--with-faucet-chain",
+        "1",
+        "--faucet-port",
+        &port.to_string(),
+    ]);
     let mut child = command
         .stdout(Stdio::piped())
         .stderr(Stdio::piped())
         .spawn()?;
 
     let stdout = BufReader::new(child.stdout.take().unwrap());
     let stderr = BufReader::new(child.stderr.take().unwrap());
+    let mut lines = stderr.lines();
 
-    for line in stderr.lines() {
+    let mut is_ready = false;
+    for line in &mut lines {
         let line = line?;
         if line.starts_with("READY!") {
-            let mut exports = stdout.lines();
-            assert!(exports
-                .next()
-                .unwrap()?
-                .starts_with("export LINERA_WALLET="));
-            assert!(exports
-                .next()
-                .unwrap()?
-                .starts_with("export LINERA_STORAGE="));
-            assert_eq!(exports.next().unwrap()?, "");
-
-            // Send SIGINT to the child process.
-            Command::new("kill")
-                .args(["-s", "INT", &child.id().to_string()])
-                .output()?;
-
-            assert!(exports.next().is_none());
-            assert!(child.wait()?.success());
-            return Ok(());
+            is_ready = true;
+            break;
         }
     }
-    panic!("Unexpected EOF for stderr");
+    assert!(is_ready, "Unexpected EOF for stderr");
+
+    // Echo faucet stderr for debugging and to empty the buffer.
+    std::thread::spawn(move || {
+        for line in lines {
+            let line = line.unwrap();
+            eprintln!("{}", line);
+        }
+    });
+
+    let mut exports = stdout.lines();
+    assert!(exports
+        .next()
+        .unwrap()?
+        .starts_with("export LINERA_WALLET="));
+    assert!(exports
+        .next()
+        .unwrap()?
+        .starts_with("export LINERA_STORAGE="));
+    assert_eq!(exports.next().unwrap()?, "");
+
+    // Test faucet.
+    let faucet = Faucet::new(format!("http://localhost:{}/", port));
+    faucet.version_info().await.unwrap();
+
+    // Send SIGINT to the child process.
+    Command::new("kill")
+        .args(["-s", "INT", &child.id().to_string()])
+        .output()?;
+
+    assert!(exports.next().is_none());
+    assert!(child.wait()?.success());
+    return Ok(());
 }
 
 #[cfg(feature = "benchmark")]