From b0037b6218dca6dbabe520bedbff870bd28104e8 Mon Sep 17 00:00:00 2001 From: teor Date: Thu, 26 Oct 2023 09:59:07 +1000 Subject: [PATCH 1/2] Use full module paths to avoid a rustdoc bug --- zebra-consensus/src/lib.rs | 2 +- zebra-network/src/lib.rs | 7 ++-- zebra-state/src/config.rs | 80 +++++++++++++++++++++----------------- zebra-state/src/lib.rs | 4 +- zebrad/src/config.rs | 8 ++-- 5 files changed, 56 insertions(+), 45 deletions(-) diff --git a/zebra-consensus/src/lib.rs b/zebra-consensus/src/lib.rs index 28abdda4e13..f864eac60ed 100644 --- a/zebra-consensus/src/lib.rs +++ b/zebra-consensus/src/lib.rs @@ -46,11 +46,11 @@ mod block; mod checkpoint; -mod config; mod parameters; mod primitives; mod script; +pub mod config; pub mod error; pub mod router; pub mod transaction; diff --git a/zebra-network/src/lib.rs b/zebra-network/src/lib.rs index 0060453846f..2ca0177b8c8 100644 --- a/zebra-network/src/lib.rs +++ b/zebra-network/src/lib.rs @@ -159,11 +159,12 @@ extern crate bitflags; /// parameterized by 'a), *not* that the object itself has 'static lifetime. pub type BoxError = Box; -mod address_book; pub mod address_book_peers; -mod address_book_updater; -mod config; +pub mod config; pub mod constants; + +mod address_book; +mod address_book_updater; mod isolated; mod meta_addr; mod peer; diff --git a/zebra-state/src/config.rs b/zebra-state/src/config.rs index fa9f85fa31f..5defecc74c0 100644 --- a/zebra-state/src/config.rs +++ b/zebra-state/src/config.rs @@ -385,44 +385,52 @@ pub(crate) fn database_format_version_at_path( } } -/// Writes `changed_version` to the on-disk database after the format is changed. -/// (Or a new database is created.) -/// -/// # Correctness -/// -/// This should only be called: -/// - after each format upgrade is complete, -/// - when creating a new database, or -/// - when an older Zebra version opens a newer database. -/// -/// # Concurrency -/// -/// This must only be called while RocksDB has an open database for `config`. -/// Otherwise, multiple Zebra processes could write the version at the same time, -/// corrupting the file. -/// -/// # Panics -/// -/// If the major versions do not match. (The format is incompatible.) -pub fn write_database_format_version_to_disk( - changed_version: &Version, - config: &Config, - network: Network, -) -> Result<(), BoxError> { - let version_path = config.version_file_path(network); +// Hide this destructive method from the public API, except in tests. +pub(crate) use hidden::write_database_format_version_to_disk; - // The major version is already in the directory path. - assert_eq!( - changed_version.major, DATABASE_FORMAT_VERSION, - "tried to do in-place database format change to an incompatible version" - ); +pub(crate) mod hidden { - let version = format!("{}.{}", changed_version.minor, changed_version.patch); + use super::*; - // # Concurrency - // - // The caller handles locking for this file write. - fs::write(version_path, version.as_bytes())?; + /// Writes `changed_version` to the on-disk database after the format is changed. + /// (Or a new database is created.) + /// + /// # Correctness + /// + /// This should only be called: + /// - after each format upgrade is complete, + /// - when creating a new database, or + /// - when an older Zebra version opens a newer database. + /// + /// # Concurrency + /// + /// This must only be called while RocksDB has an open database for `config`. + /// Otherwise, multiple Zebra processes could write the version at the same time, + /// corrupting the file. + /// + /// # Panics + /// + /// If the major versions do not match. (The format is incompatible.) + pub fn write_database_format_version_to_disk( + changed_version: &Version, + config: &Config, + network: Network, + ) -> Result<(), BoxError> { + let version_path = config.version_file_path(network); + + // The major version is already in the directory path. + assert_eq!( + changed_version.major, DATABASE_FORMAT_VERSION, + "tried to do in-place database format change to an incompatible version" + ); + + let version = format!("{}.{}", changed_version.minor, changed_version.patch); - Ok(()) + // # Concurrency + // + // The caller handles locking for this file write. + fs::write(version_path, version.as_bytes())?; + + Ok(()) + } } diff --git a/zebra-state/src/lib.rs b/zebra-state/src/lib.rs index ad2cec55207..07665b8d4f9 100644 --- a/zebra-state/src/lib.rs +++ b/zebra-state/src/lib.rs @@ -25,12 +25,12 @@ #[macro_use] extern crate tracing; +pub mod config; pub mod constants; #[cfg(any(test, feature = "proptest-impl"))] pub mod arbitrary; -mod config; mod error; mod request; mod response; @@ -71,7 +71,7 @@ pub use service::{ }; #[cfg(any(test, feature = "proptest-impl"))] -pub use config::write_database_format_version_to_disk; +pub use config::hidden::write_database_format_version_to_disk; #[cfg(any(test, feature = "proptest-impl"))] pub use constants::latest_version_for_adding_subtrees; diff --git a/zebrad/src/config.rs b/zebrad/src/config.rs index 9a8f9ce1ca8..cb10e4033bf 100644 --- a/zebrad/src/config.rs +++ b/zebrad/src/config.rs @@ -15,16 +15,18 @@ use serde::{Deserialize, Serialize}; #[serde(deny_unknown_fields, default)] pub struct ZebradConfig { /// Consensus configuration - pub consensus: zebra_consensus::Config, + // + // These configs use full paths to avoid a rustdoc link bug (#7048). + pub consensus: zebra_consensus::config::Config, /// Metrics configuration pub metrics: crate::components::metrics::Config, /// Networking configuration - pub network: zebra_network::Config, + pub network: zebra_network::config::Config, /// State configuration - pub state: zebra_state::Config, + pub state: zebra_state::config::Config, /// Tracing configuration pub tracing: crate::components::tracing::Config, From d894eee9e3561e497b96bd12b177b5d91d364c6d Mon Sep 17 00:00:00 2001 From: teor Date: Thu, 26 Oct 2023 10:03:49 +1000 Subject: [PATCH 2/2] Exclude zebra-test from external docs --- .github/workflows/docs-deploy-firebase.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/docs-deploy-firebase.yml b/.github/workflows/docs-deploy-firebase.yml index 29b85def5db..8e886ac4f2c 100644 --- a/.github/workflows/docs-deploy-firebase.yml +++ b/.github/workflows/docs-deploy-firebase.yml @@ -144,8 +144,8 @@ jobs: - name: Build external docs run: | - # Exclude zebra-utils, it is not for library or app users - cargo doc --no-deps --workspace --all-features --exclude zebra-utils --target-dir "$(pwd)"/target/external + # Exclude zebra-utils and zebra-test, they are not for library or app users + cargo doc --no-deps --workspace --all-features --exclude zebra-utils --exclude zebra-test --target-dir "$(pwd)"/target/external # Setup gcloud CLI - name: Authenticate to Google Cloud