linera-service 0.15.21

// Copyright (c) Zefchain Labs, Inc.
// SPDX-License-Identifier: Apache-2.0

//! Helper module to call the binaries of `linera-service` with appropriate command-line
//! arguments.

/// How to run Linera validators locally as native processes.
pub mod local_net;
#[cfg(all(with_testing, feature = "remote-net"))]
/// How to connect to running GCP devnet.
pub mod remote_net;
/// How to run a Linera wallet and its GraphQL service.
mod wallet;

use anyhow::Result;
use async_trait::async_trait;
pub use linera_faucet_client::Faucet;
#[cfg(with_testing)]
pub use wallet::NotificationsExt;
pub use wallet::{ApplicationWrapper, ClientWrapper, FaucetService, NodeService, OnClientDrop};

/// The information needed to start a Linera net of a particular kind.
#[async_trait]
pub trait LineraNetConfig {
    /// The type of Linera net produced by this configuration.
    type Net: LineraNet + Sized + Send + Sync + 'static;

    /// Starts the Linera net and returns it together with a client to interact with it.
    async fn instantiate(self) -> Result<(Self::Net, ClientWrapper)>;
}

/// A running Linera net.
#[async_trait]
pub trait LineraNet {
    /// Checks that the net is still running and returns an error otherwise.
    async fn ensure_is_running(&mut self) -> Result<()>;

    /// Creates a new client to interact with the net.
    async fn make_client(&mut self) -> ClientWrapper;

    /// Shuts down the net.
    async fn terminate(&mut self) -> Result<()>;
}

/// Network protocol in use
#[derive(Copy, Clone)]
pub enum Network {
    /// gRPC over cleartext (unencrypted) HTTP/2.
    Grpc,
    /// gRPC over TLS.
    Grpcs,
    /// A simple transport protocol over TCP.
    Tcp,
    /// A simple transport protocol over UDP.
    Udp,
}

/// Network protocol in use outside and inside a Linera net.
#[derive(Copy, Clone)]
pub struct NetworkConfig {
    /// The internal network (e.g. proxy to validator)
    pub internal: Network,
    /// The external network (e.g. proxy to the exterior)
    pub external: Network,
}

impl Network {
    fn toml(&self) -> &'static str {
        match self {
            Network::Grpc => "{ Grpc = \"ClearText\" }",
            Network::Grpcs => "{ Grpc = \"Tls\" }",
            Network::Tcp => "{ Simple = \"Tcp\" }",
            Network::Udp => "{ Simple = \"Udp\" }",
        }
    }

    /// Returns a short lowercase name for the network protocol.
    pub fn short(&self) -> &'static str {
        match self {
            Network::Grpc => "grpc",
            Network::Grpcs => "grpcs",
            Network::Tcp => "tcp",
            Network::Udp => "udp",
        }
    }

    /// Returns the equivalent network protocol without TLS.
    pub fn drop_tls(&self) -> Self {
        match self {
            Network::Grpc => Network::Grpc,
            Network::Grpcs => Network::Grpc,
            Network::Tcp => Network::Tcp,
            Network::Udp => Network::Udp,
        }
    }

    /// Returns the localhost address to use for this network protocol.
    pub fn localhost(&self) -> &'static str {
        match self {
            Network::Grpc | Network::Grpcs => "localhost",
            Network::Tcp | Network::Udp => "127.0.0.1",
        }
    }

    /// Returns the protocol schema to use in the node address tuple.
    pub fn schema(&self) -> &'static str {
        match self {
            Network::Grpc | Network::Grpcs => "grpc",
            Network::Tcp => "tcp",
            Network::Udp => "udp",
        }
    }
}