From 4076349271b02fbb9481860779dc59fd73ac5e10 Mon Sep 17 00:00:00 2001 From: Flavio Castelli Date: Thu, 23 May 2024 19:13:22 +0200 Subject: [PATCH 1/2] docs: handle feature flags When building the docs, provide additional information about which feature makes a module/struct/function/method available. On top of that, fix some warnings returned by `cargo doc`. The warnings were caused by broken internal references. Signed-off-by: Flavio Castelli --- Cargo.toml | 21 ++++++++++++++++++--- src/bundle/mod.rs | 2 ++ src/bundle/verify/verifier.rs | 2 ++ src/cosign/client_builder.rs | 9 +++++---- src/cosign/mod.rs | 6 +++--- src/errors.rs | 4 ++++ src/lib.rs | 8 ++++++++ src/oauth/mod.rs | 2 +- src/registry/config.rs | 7 ++++--- src/trust/mod.rs | 1 + 10 files changed, 48 insertions(+), 14 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 5bce74875f..3c8317cae6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -8,6 +8,9 @@ license = "Apache-2.0" readme = "README.md" repository = "https://github.com/sigstore/sigstore-rs" +[package.metadata.docs.rs] +all-features = true + [features] default = ["full-native-tls", "cached-client", "sigstore-trust-root", "bundle"] wasm = ["getrandom/js", "ring/wasm32_unknown_unknown_js", "chrono/wasmbind"] @@ -44,7 +47,13 @@ sign = ["sigstore_protobuf_specs", "fulcio", "rekor", "cert"] verify = ["sigstore_protobuf_specs", "fulcio", "rekor", "cert"] bundle = ["sign", "verify"] -sigstore-trust-root = ["sigstore_protobuf_specs", "futures-util", "tough", "regex", "tokio/sync"] +sigstore-trust-root = [ + "sigstore_protobuf_specs", + "futures-util", + "tough", + "regex", + "tokio/sync", +] cosign-native-tls = [ "oci-distribution/native-tls", @@ -76,7 +85,10 @@ async-trait = "0.1.52" base64 = "0.22.0" cached = { version = "0.51.3", optional = true, features = ["async"] } cfg-if = "1.0.0" -chrono = { version = "0.4.27", default-features = false, features = ["now", "serde"] } +chrono = { version = "0.4.27", default-features = false, features = [ + "now", + "serde", +] } const-oid = { version = "0.9.6", features = ["db"] } digest = { version = "0.10.3", default-features = false } ecdsa = { version = "0.16.7", features = ["pkcs8", "digest", "der", "signing"] } @@ -113,7 +125,10 @@ rsa = "0.9.2" scrypt = "0.11.0" serde = { version = "1.0.136", features = ["derive"] } serde_json = "1.0.79" -serde_with = { version = "3.4.0", features = ["base64", "json"], optional = true } +serde_with = { version = "3.4.0", features = [ + "base64", + "json", +], optional = true } sha2 = { version = "0.10.6", features = ["oid"] } signature = { version = "2.0" } sigstore_protobuf_specs = { version = "0.3.2", optional = true } diff --git a/src/bundle/mod.rs b/src/bundle/mod.rs index 61ad0c48b3..e89d34f7e8 100644 --- a/src/bundle/mod.rs +++ b/src/bundle/mod.rs @@ -18,8 +18,10 @@ pub use sigstore_protobuf_specs::dev::sigstore::bundle::v1::Bundle; mod models; +#[cfg_attr(docsrs, doc(cfg(feature = "sign")))] #[cfg(feature = "sign")] pub mod sign; +#[cfg_attr(docsrs, doc(cfg(feature = "verify")))] #[cfg(feature = "verify")] pub mod verify; diff --git a/src/bundle/verify/verifier.rs b/src/bundle/verify/verifier.rs index 0f4a4a5526..9005d835a2 100644 --- a/src/bundle/verify/verifier.rs +++ b/src/bundle/verify/verifier.rs @@ -206,6 +206,7 @@ impl Verifier { impl Verifier { /// Constructs an [`Verifier`] against the public-good trust root. #[cfg(feature = "sigstore-trust-root")] + #[cfg_attr(docsrs, doc(cfg(feature = "sigstore-trust-root")))] pub async fn production() -> SigstoreResult { let updater = SigstoreTrustRoot::new(None).await?; @@ -279,6 +280,7 @@ pub mod blocking { impl Verifier { /// Constructs a synchronous [`Verifier`] against the public-good trust root. #[cfg(feature = "sigstore-trust-root")] + #[cfg_attr(docsrs, doc(cfg(feature = "sigstore-trust-root")))] pub fn production() -> SigstoreResult { let rt = tokio::runtime::Builder::new_current_thread() .enable_all() diff --git a/src/cosign/client_builder.rs b/src/cosign/client_builder.rs index 1a688d9139..66239e65b2 100644 --- a/src/cosign/client_builder.rs +++ b/src/cosign/client_builder.rs @@ -30,15 +30,15 @@ use crate::trust::TrustRoot; /// Rekor integration can be enabled by specifying Rekor's public key. /// This can be provided via a [`crate::trust::ManualTrustRoot`]. /// -/// > Note well: the [`sigstore`](crate::sigstore) module provides helper structs and methods +/// > Note well: the [`trust::sigstore`](crate::trust::sigstore) module provides helper structs and methods /// > to obtain this data from the official TUF repository of the Sigstore project. /// /// ## Fulcio integration /// /// Fulcio integration can be enabled by specifying Fulcio's certificate. -/// This can be provided via a [`crate::sigstore::ManualTrustRoot`]. +/// This can be provided via a [`crate::trust::sigstore::ManualTrustRoot`]. /// -/// > Note well: the [`sigstore`](crate::sigstore) module provides helper structs and methods +/// > Note well: the [`trust::sigstore`](crate::trust::sigstore) module provides helper structs and methods /// > to obtain this data from the official TUF repository of the Sigstore project. /// /// ## Registry caching @@ -63,6 +63,7 @@ pub struct ClientBuilder<'a> { impl<'a> ClientBuilder<'a> { /// Enable caching of data returned from remote OCI registries #[cfg(feature = "cached-client")] + #[cfg_attr(docsrs, doc(cfg(feature = "cached-registry")))] pub fn enable_registry_caching(mut self) -> Self { self.enable_registry_caching = true; self @@ -71,7 +72,7 @@ impl<'a> ClientBuilder<'a> { /// Optional - Configures the roots of trust. /// /// Enables Fulcio and Rekor integration with the given trust repository. - /// See [crate::sigstore::TrustRoot] for more details on trust repositories. + /// See [crate::trust::sigstore::TrustRoot] for more details on trust repositories. pub fn with_trust_repository(mut self, repo: &'a R) -> Result { let rekor_keys = repo.rekor_keys()?; if !rekor_keys.is_empty() { diff --git a/src/cosign/mod.rs b/src/cosign/mod.rs index b52e14175b..7d3795b427 100644 --- a/src/cosign/mod.rs +++ b/src/cosign/mod.rs @@ -101,12 +101,12 @@ pub trait CosignCapabilities { /// must be satisfied: /// /// * The [`sigstore::cosign::Client`](crate::cosign::client::Client) must - /// have been created with Rekor integration enabled (see [`crate::sigstore::ManualTrustRoot`]) + /// have been created with Rekor integration enabled (see [`crate::trust::sigstore::ManualTrustRoot`]) /// * The [`sigstore::cosign::Client`](crate::cosign::client::Client) must - /// have been created with Fulcio integration enabled (see [`crate::sigstore::ManualTrustRoot]) + /// have been created with Fulcio integration enabled (see [`crate::trust::sigstore::ManualTrustRoot]) /// * The layer must include a bundle produced by Rekor /// - /// > Note well: the [`sigstore`](crate::sigstore) module provides helper structs and methods + /// > Note well: the [`trust::sigstore`](crate::trust::sigstore) module provides helper structs and methods /// > to obtain this data from the official TUF repository of the Sigstore project. /// /// When the embedded certificate cannot be verified, [`SignatureLayer::certificate_signature`] diff --git a/src/errors.rs b/src/errors.rs index 56a3f93856..7403d24e3a 100644 --- a/src/errors.rs +++ b/src/errors.rs @@ -23,6 +23,7 @@ use crate::cosign::{ }; #[cfg(feature = "cosign")] +#[cfg_attr(docsrs, doc(cfg(feature = "cosign")))] #[derive(Error, Debug)] #[error("Several Signature Layers failed verification")] pub struct SigstoreVerifyConstraintsError<'a> { @@ -30,6 +31,7 @@ pub struct SigstoreVerifyConstraintsError<'a> { } #[cfg(feature = "cosign")] +#[cfg_attr(docsrs, doc(cfg(feature = "cosign")))] #[derive(Error, Debug)] #[error("Several Constraints failed to apply on the SignatureLayer")] pub struct SigstoreApplicationConstraintsError<'a> { @@ -135,6 +137,7 @@ pub enum SigstoreError { // HACK(tnytown): Remove when we rework the Fulcio V2 endpoint. #[cfg(feature = "fulcio")] + #[cfg_attr(docsrs, doc(cfg(feature = "fulcio")))] #[error(transparent)] ReqwestError(#[from] reqwest::Error), @@ -163,6 +166,7 @@ pub enum SigstoreError { SigstoreNoVerifiedLayer, #[cfg(feature = "sigstore-trust-root")] + #[cfg_attr(docsrs, doc(cfg(feature = "sigstore-trust-root")))] #[error(transparent)] TufError(#[from] Box), diff --git a/src/lib.rs b/src/lib.rs index fa336c1029..ad2586060c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -258,29 +258,37 @@ #![forbid(unsafe_code)] #![warn(clippy::unwrap_used, clippy::panic)] +#![cfg_attr(docsrs, feature(doc_cfg))] pub mod crypto; pub mod trust; +#[cfg_attr(docsrs, doc(cfg(feature = "mock-client")))] #[cfg(feature = "mock-client")] mod mock_client; +#[cfg_attr(docsrs, doc(cfg(feature = "cosign")))] #[cfg(feature = "cosign")] pub mod cosign; pub mod errors; +#[cfg_attr(docsrs, doc(cfg(feature = "fulcio")))] #[cfg(feature = "fulcio")] pub mod fulcio; +#[cfg_attr(docsrs, doc(cfg(feature = "oauth")))] #[cfg(feature = "oauth")] pub mod oauth; +#[cfg_attr(docsrs, doc(cfg(feature = "registry")))] #[cfg(feature = "registry")] pub mod registry; +#[cfg_attr(docsrs, doc(cfg(feature = "rekor")))] #[cfg(feature = "rekor")] pub mod rekor; +#[cfg_attr(docsrs, doc(cfg(any(feature = "sign", feature = "verify"))))] #[cfg(any(feature = "sign", feature = "verify"))] pub mod bundle; diff --git a/src/oauth/mod.rs b/src/oauth/mod.rs index a5419e7fce..b78bd78d6c 100644 --- a/src/oauth/mod.rs +++ b/src/oauth/mod.rs @@ -15,5 +15,5 @@ pub mod openidflow; -mod token; +pub mod token; pub use token::IdentityToken; diff --git a/src/registry/config.rs b/src/registry/config.rs index b7dd3d2da1..9bfd9c34db 100644 --- a/src/registry/config.rs +++ b/src/registry/config.rs @@ -147,7 +147,8 @@ pub struct ClientConfig { pub protocol: ClientProtocol, /// Accept invalid hostname. Defaults to false - #[cfg(feature = "native-tls")] + #[cfg_attr(docsrs, doc(cfg(feature = "full-native-tls")))] + #[cfg(feature = "full-native-tls")] pub accept_invalid_hostnames: bool, /// Accept invalid certificates. Defaults to false @@ -162,7 +163,7 @@ impl Default for ClientConfig { fn default() -> Self { ClientConfig { protocol: ClientProtocol::Https, - #[cfg(feature = "native-tls")] + #[cfg(feature = "full-native-tls")] accept_invalid_hostnames: false, accept_invalid_certificates: false, extra_root_certificates: Vec::new(), @@ -175,7 +176,7 @@ impl From for oci_distribution::client::ClientConfig { oci_distribution::client::ClientConfig { protocol: config.protocol.into(), accept_invalid_certificates: config.accept_invalid_certificates, - #[cfg(feature = "native-tls")] + #[cfg(feature = "full-native-tls")] accept_invalid_hostnames: config.accept_invalid_hostnames, extra_root_certificates: config .extra_root_certificates diff --git a/src/trust/mod.rs b/src/trust/mod.rs index 966bb238fc..e0fe98b13f 100644 --- a/src/trust/mod.rs +++ b/src/trust/mod.rs @@ -15,6 +15,7 @@ use webpki::types::CertificateDer; +#[cfg_attr(docsrs, doc(cfg(feature = "sigstore-trust-root")))] #[cfg(feature = "sigstore-trust-root")] pub mod sigstore; From 906b5f6249be367221e808e1971e24e37760dab2 Mon Sep 17 00:00:00 2001 From: Flavio Castelli Date: Tue, 9 Apr 2024 18:58:24 +0200 Subject: [PATCH 2/2] ci: require docs to be fine Build the documentation as part of PRs. Fail when something wrong is found while building the docs. Signed-off-by: Flavio Castelli --- .github/workflows/tests.yml | 13 +++++++++++++ Makefile | 2 +- 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 426a8ddab4..234472691c 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -48,6 +48,19 @@ jobs: command: test args: --workspace --features full-native-tls,test-registry + doc: + name: Build Documentation + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@a5ac7e51b41094c92402da3b24376905380afc29 # v4.1.6 + - uses: actions-rs/toolchain@16499b5e05bf2e26879000db0c1d13f7e13fa3af # v1.0.7 + with: + profile: minimal + toolchain: nightly + override: true + - run: | + make doc + fmt: name: Rustfmt runs-on: ubuntu-latest diff --git a/Makefile b/Makefile index ded4560c9a..c05cbf9a0c 100644 --- a/Makefile +++ b/Makefile @@ -12,7 +12,7 @@ lint: .PHONY: doc doc: - cargo doc + RUSTDOCFLAGS="--cfg docsrs -D warnings" cargo +nightly doc --all-features --no-deps .PHONY: test test: fmt lint doc