linera_base/

lib.rs

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

//! This module provides a common set of types and library functions that are shared
//! between the Linera protocol (compiled from Rust to native code) and Linera
//! applications (compiled from Rust to Wasm).

#![deny(missing_docs)]
#![allow(async_fn_in_trait)]

// The protocol assumes `usize` is at least as wide as `u32`: many call sites
// convert `u32` lengths or counts to `usize` (and back) without an explicit
// `try_from`. This rules out 16-bit targets workspace-wide.
const _: () = assert!(
    usize::BITS >= u32::BITS,
    "linera-base requires a target with usize of at least 32 bits",
);

use std::fmt;

#[doc(hidden)]
pub use async_trait::async_trait;
#[cfg(all(not(target_arch = "wasm32"), unix))]
use tokio::signal::unix;
#[cfg(not(target_arch = "wasm32"))]
use {::tracing::debug, tokio_util::sync::CancellationToken};
pub mod abi;
#[cfg(not(target_arch = "wasm32"))]
pub mod command;
pub mod crypto;
pub mod data_types;
mod graphql;
pub mod hashed;
pub mod http;
pub mod identifiers;
mod limited_writer;
pub mod ownership;
#[cfg(not(target_arch = "wasm32"))]
pub mod panic_hook;
#[cfg(not(target_arch = "wasm32"))]
pub mod port;
#[cfg(with_metrics)]
pub mod prometheus_util;
#[cfg(not(chain))]
pub mod task;
#[cfg(not(chain))]
pub use task::Task;
pub mod task_processor;
pub mod time;
#[cfg(test)]
mod unit_tests;
pub mod util;
pub mod vm;

pub use graphql::BcsHexParseError;
#[doc(hidden)]
pub use {async_graphql, bcs, hex};

/// A macro for asserting that a condition is true, returning an error if it is not.
///
/// # Examples
///
/// ```
/// # use linera_base::ensure;
/// fn divide(x: i32, y: i32) -> Result<i32, String> {
///     ensure!(y != 0, "division by zero");
///     Ok(x / y)
/// }
///
/// assert_eq!(divide(10, 2), Ok(5));
/// assert_eq!(divide(10, 0), Err(String::from("division by zero")));
/// ```
#[macro_export]
macro_rules! ensure {
    ($cond:expr, $e:expr) => {
        if !($cond) {
            return Err($e.into());
        }
    };
}

/// Formats a byte sequence as a hexadecimal string, and elides bytes in the middle if it is longer
/// than 32 bytes.
///
/// This function is intended to be used with the `#[debug(with = "hex_debug")]` field
/// annotation of `custom_debug_derive::Debug`.
///
/// # Examples
///
/// ```
/// # use linera_base::hex_debug;
/// use custom_debug_derive::Debug;
///
/// #[derive(Debug)]
/// struct Message {
///     #[debug(with = "hex_debug")]
///     bytes: Vec<u8>,
/// }
///
/// let msg = Message {
///     bytes: vec![0x12, 0x34, 0x56, 0x78],
/// };
///
/// assert_eq!(format!("{:?}", msg), "Message { bytes: 12345678 }");
///
/// let long_msg = Message {
///     bytes: b"        10        20        30        40        50".to_vec(),
/// };
///
/// assert_eq!(
///     format!("{:?}", long_msg),
///     "Message { bytes: 20202020202020203130202020202020..20202020343020202020202020203530 }"
/// );
/// ```
pub fn hex_debug<T: AsRef<[u8]>>(bytes: &T, f: &mut fmt::Formatter) -> fmt::Result {
    const ELIDE_AFTER: usize = 16;
    let bytes = bytes.as_ref();
    if bytes.len() <= 2 * ELIDE_AFTER {
        write!(f, "{}", hex::encode(bytes))?;
    } else {
        write!(
            f,
            "{}..{}",
            hex::encode(&bytes[..ELIDE_AFTER]),
            hex::encode(&bytes[(bytes.len() - ELIDE_AFTER)..])
        )?;
    }
    Ok(())
}

/// Applies `hex_debug` to a slice of byte vectors.
///
///  # Examples
///
/// ```
/// # use linera_base::hex_vec_debug;
/// use custom_debug_derive::Debug;
///
/// #[derive(Debug)]
/// struct Messages {
///     #[debug(with = "hex_vec_debug")]
///     byte_vecs: Vec<Vec<u8>>,
/// }
///
/// let msgs = Messages {
///     byte_vecs: vec![vec![0x12, 0x34, 0x56, 0x78], vec![0x9A]],
/// };
///
/// assert_eq!(
///     format!("{:?}", msgs),
///     "Messages { byte_vecs: [12345678, 9a] }"
/// );
/// ```
#[expect(clippy::ptr_arg)] // This only works with custom_debug_derive if it's &Vec.
pub fn hex_vec_debug(list: &Vec<Vec<u8>>, f: &mut fmt::Formatter) -> fmt::Result {
    write!(f, "[")?;
    for (i, bytes) in list.iter().enumerate() {
        if i != 0 {
            write!(f, ", ")?;
        }
        hex_debug(bytes, f)?;
    }
    write!(f, "]")
}

/// Helper function for allocative.
pub fn visit_allocative_simple<T>(_: &T, visitor: &mut allocative::Visitor<'_>) {
    visitor.visit_simple_sized::<T>();
}

/// Listens for shutdown signals, and notifies the [`CancellationToken`] if one is
/// received.
#[cfg(not(target_arch = "wasm32"))]
pub async fn listen_for_shutdown_signals(shutdown_sender: CancellationToken) {
    let _shutdown_guard = shutdown_sender.drop_guard();

    #[cfg(unix)]
    {
        let mut sigint =
            unix::signal(unix::SignalKind::interrupt()).expect("Failed to set up SIGINT handler");
        let mut sigterm =
            unix::signal(unix::SignalKind::terminate()).expect("Failed to set up SIGTERM handler");
        let mut sighup =
            unix::signal(unix::SignalKind::hangup()).expect("Failed to set up SIGHUP handler");

        tokio::select! {
            _ = sigint.recv() => debug!("Received SIGINT"),
            _ = sigterm.recv() => debug!("Received SIGTERM"),
            _ = sighup.recv() => debug!("Received SIGHUP"),
        }
    }

    #[cfg(windows)]
    {
        tokio::signal::ctrl_c()
            .await
            .expect("Failed to set up Ctrl+C handler");
        debug!("Received Ctrl+C");
    }
}

/// Registers every metric this crate declares.
///
/// Without this, a metric is only exported after the code path that observes it has run, so a
/// rarely-taken path leaves its panels blank and makes a routine restart look like the metric
/// was removed.
#[cfg(with_metrics)]
pub fn init_metrics() {
    data_types::metrics::init_metrics();
    panic_hook::metrics::init_metrics();
}