Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

fix docs #366

Merged
merged 2 commits into from
May 24, 2024
Merged

fix docs #366

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4076349
docs: handle feature flags
flavio May 23, 2024
906b5f6
ci: require docs to be fine
flavio Apr 9, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .github/workflows/tests.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
21 changes: 18 additions & 3 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
Expand Down Expand Up @@ -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 = [
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not any suggestions to here, just wonder: which tool/how do you re-format the toml format here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm using taplo, I've got enabled inside of my vim setup

"sigstore_protobuf_specs",
"futures-util",
"tough",
"regex",
"tokio/sync",
]

cosign-native-tls = [
"oci-distribution/native-tls",
Expand Down Expand Up @@ -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"] }
Expand Down Expand Up @@ -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 }
Expand Down
2 changes: 1 addition & 1 deletion Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions src/bundle/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
2 changes: 2 additions & 0 deletions src/bundle/verify/verifier.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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<Verifier> {
let updater = SigstoreTrustRoot::new(None).await?;

Expand Down Expand Up @@ -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<Verifier> {
let rt = tokio::runtime::Builder::new_current_thread()
.enable_all()
Expand Down
9 changes: 5 additions & 4 deletions src/cosign/client_builder.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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<R: TrustRoot + ?Sized>(mut self, repo: &'a R) -> Result<Self> {
let rekor_keys = repo.rekor_keys()?;
if !rekor_keys.is_empty() {
Expand Down
6 changes: 3 additions & 3 deletions src/cosign/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`]
Expand Down
4 changes: 4 additions & 0 deletions src/errors.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,15 @@ 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> {
pub unsatisfied_constraints: VerificationConstraintRefVec<'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> {
Expand Down Expand Up @@ -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),

Expand Down Expand Up @@ -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<tough::error::Error>),

Expand Down
8 changes: 8 additions & 0 deletions src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
2 changes: 1 addition & 1 deletion src/oauth/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,5 +15,5 @@

pub mod openidflow;

mod token;
pub mod token;
pub use token::IdentityToken;
7 changes: 4 additions & 3 deletions src/registry/config.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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(),
Expand All @@ -175,7 +176,7 @@ impl From<ClientConfig> 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
Expand Down
1 change: 1 addition & 0 deletions src/trust/mod.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
Loading