From 1a64ac90f95fa7d52de74e06eac4d929dd75a214 Mon Sep 17 00:00:00 2001 From: Floris Bruynooghe Date: Mon, 30 Sep 2024 14:52:51 +0200 Subject: [PATCH] docs(iroh-net): Document cargo features needed for APIs This uses the feature of docs.rs to enable showing which cargo features need to be enabled for APIs. --- Cargo.toml | 10 ++++++++++ iroh-net/Cargo.toml | 1 + iroh-net/src/defaults.rs | 1 + iroh-net/src/discovery.rs | 1 + iroh-net/src/discovery/dns.rs | 1 + iroh-net/src/discovery/pkarr.rs | 1 + iroh-net/src/endpoint.rs | 3 +++ iroh-net/src/lib.rs | 2 ++ iroh-net/src/magicsock.rs | 2 ++ iroh-net/src/metrics.rs | 1 + iroh-net/src/relay.rs | 1 + iroh-net/src/relay/client.rs | 3 +++ iroh-net/src/relay/codec.rs | 4 ++++ iroh-net/src/relay/http.rs | 3 +++ iroh-net/src/relay/server.rs | 1 + 15 files changed, 35 insertions(+) diff --git a/Cargo.toml b/Cargo.toml index aaa48b79e7..4e4aeed480 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -34,5 +34,15 @@ incremental = false [workspace.lints.rust] missing_debug_implementations = "warn" +# We use this --cfg for documenting the cargo features on which an API +# is available. To preview this locally use: RUSTFLAGS="--cfg +# iroh_docsrs cargo +nightly doc --all-features". We use our own +# iroh_docsrs instead of the common docsrs to avoid also enabling this +# feature in any dependencies, because some indirect dependencies +# require a feature enabled when using `--cfg docsrs` which we can not +# do. To enable for a crate set `#![cfg_attr(iroh_docsrs, +# feature(doc_cfg))]` in the crate. +unexpected_cfgs = { level = "warn", check-cfg = ["cfg(iroh_docsrs)"] } + [workspace.lints.clippy] unused-async = "warn" diff --git a/iroh-net/Cargo.toml b/iroh-net/Cargo.toml index ae2a74c345..c8bf330fe3 100644 --- a/iroh-net/Cargo.toml +++ b/iroh-net/Cargo.toml @@ -154,6 +154,7 @@ required-features = ["iroh-relay"] [package.metadata.docs.rs] all-features = true +rustdoc-args = ["--cfg", "iroh_docsrs"] [[example]] name = "listen" diff --git a/iroh-net/src/defaults.rs b/iroh-net/src/defaults.rs index 2bcd02fd76..95ab102953 100644 --- a/iroh-net/src/defaults.rs +++ b/iroh-net/src/defaults.rs @@ -196,6 +196,7 @@ pub(crate) mod timeouts { /// Maximum time the server will attempt to get a successful write to the connection. #[cfg(feature = "iroh-relay")] + #[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))] pub(crate) const SERVER_WRITE_TIMEOUT: Duration = Duration::from_secs(2); } } diff --git a/iroh-net/src/discovery.rs b/iroh-net/src/discovery.rs index ddd2c2b7bb..ee55e5885e 100644 --- a/iroh-net/src/discovery.rs +++ b/iroh-net/src/discovery.rs @@ -52,6 +52,7 @@ use crate::{AddrInfo, Endpoint, NodeId}; pub mod dns; #[cfg(feature = "discovery-local-network")] +#[cfg_attr(iroh_docsrs, doc(cfg(feature = "discovery-local-network")))] pub mod local_swarm_discovery; pub mod pkarr; diff --git a/iroh-net/src/discovery/dns.rs b/iroh-net/src/discovery/dns.rs index 5d88f4ca8b..556869a30c 100644 --- a/iroh-net/src/discovery/dns.rs +++ b/iroh-net/src/discovery/dns.rs @@ -15,6 +15,7 @@ pub const N0_DNS_NODE_ORIGIN_PROD: &str = "dns.iroh.link"; pub const N0_DNS_NODE_ORIGIN_STAGING: &str = "staging-dns.iroh.link"; /// Testing DNS node origin, must run server from [`crate::test_utils::DnsPkarrServer`]. #[cfg(any(test, feature = "test-utils"))] +#[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))] pub const TEST_DNS_NODE_ORIGIN: &str = "dns.iroh.test"; const DNS_STAGGERING_MS: &[u64] = &[200, 300]; diff --git a/iroh-net/src/discovery/pkarr.rs b/iroh-net/src/discovery/pkarr.rs index cfb6a0bf18..aeef1c025c 100644 --- a/iroh-net/src/discovery/pkarr.rs +++ b/iroh-net/src/discovery/pkarr.rs @@ -22,6 +22,7 @@ use crate::{ AddrInfo, Endpoint, NodeId, }; #[cfg(feature = "discovery-pkarr-dht")] +#[cfg_attr(iroh_docsrs, doc(cfg(feature = "discovery-pkarr-dht")))] pub mod dht; /// The pkarr relay run by n0, for production. diff --git a/iroh-net/src/endpoint.rs b/iroh-net/src/endpoint.rs index 52f9b540fc..931746d928 100644 --- a/iroh-net/src/endpoint.rs +++ b/iroh-net/src/endpoint.rs @@ -59,6 +59,7 @@ const DISCOVERY_WAIT_PERIOD: Duration = Duration::from_millis(500); /// Environment variable to force the use of staging relays. #[cfg(not(any(test, feature = "test-utils")))] +#[cfg_attr(iroh_docsrs, doc(cfg(not(any(test, feature = "test-utils")))))] const ENV_FORCE_STAGING_RELAYS: &str = "IROH_FORCE_STAGING_RELAYS"; /// Builder for [`Endpoint`]. @@ -80,6 +81,7 @@ pub struct Builder { node_map: Option>, dns_resolver: Option, #[cfg(any(test, feature = "test-utils"))] + #[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))] insecure_skip_relay_cert_verify: bool, addr_v4: Option, addr_v6: Option, @@ -288,6 +290,7 @@ impl Builder { /// /// May only be used in tests. #[cfg(any(test, feature = "test-utils"))] + #[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))] pub fn insecure_skip_relay_cert_verify(mut self, skip_verify: bool) -> Self { self.insecure_skip_relay_cert_verify = skip_verify; self diff --git a/iroh-net/src/lib.rs b/iroh-net/src/lib.rs index 11cb17f2b1..2adb4532d3 100644 --- a/iroh-net/src/lib.rs +++ b/iroh-net/src/lib.rs @@ -120,6 +120,7 @@ #![recursion_limit = "256"] #![deny(missing_docs, rustdoc::broken_intra_doc_links)] +#![cfg_attr(iroh_docsrs, feature(doc_cfg))] pub mod defaults; pub mod dialer; @@ -146,4 +147,5 @@ pub use iroh_base::key; pub use iroh_base::key::NodeId; #[cfg(any(test, feature = "test-utils"))] +#[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))] pub mod test_utils; diff --git a/iroh-net/src/magicsock.rs b/iroh-net/src/magicsock.rs index fc7cd7d449..53e7da1256 100644 --- a/iroh-net/src/magicsock.rs +++ b/iroh-net/src/magicsock.rs @@ -128,6 +128,7 @@ pub(crate) struct Options { /// /// May only be used in tests. #[cfg(any(test, feature = "test-utils"))] + #[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))] pub(crate) insecure_skip_relay_cert_verify: bool, } @@ -242,6 +243,7 @@ pub(crate) struct MagicSock { /// /// May only be used in tests. #[cfg(any(test, feature = "test-utils"))] + #[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))] insecure_skip_relay_cert_verify: bool, } diff --git a/iroh-net/src/metrics.rs b/iroh-net/src/metrics.rs index 1bd5d09480..02108ec6e4 100644 --- a/iroh-net/src/metrics.rs +++ b/iroh-net/src/metrics.rs @@ -3,4 +3,5 @@ pub use crate::magicsock::Metrics as MagicsockMetrics; pub use crate::netcheck::Metrics as NetcheckMetrics; pub use crate::portmapper::Metrics as PortmapMetrics; #[cfg(feature = "iroh-relay")] +#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))] pub use crate::relay::server::Metrics as RelayMetrics; diff --git a/iroh-net/src/relay.rs b/iroh-net/src/relay.rs index 4c7f5c6dc0..73d727c388 100644 --- a/iroh-net/src/relay.rs +++ b/iroh-net/src/relay.rs @@ -15,6 +15,7 @@ pub(crate) mod codec; pub mod http; mod map; #[cfg(feature = "iroh-relay")] +#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))] pub mod server; pub use self::client::conn::{Conn as RelayConn, ReceivedMessage}; diff --git a/iroh-net/src/relay/client.rs b/iroh-net/src/relay/client.rs index 01b8b0f770..3b276a8329 100644 --- a/iroh-net/src/relay/client.rs +++ b/iroh-net/src/relay/client.rs @@ -219,6 +219,7 @@ pub struct ClientBuilder { protocol: Protocol, /// Allow self-signed certificates from relay servers #[cfg(any(test, feature = "test-utils"))] + #[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))] insecure_skip_cert_verify: bool, /// HTTP Proxy proxy_url: Option, @@ -291,6 +292,7 @@ impl ClientBuilder { /// /// May only be used in tests. #[cfg(any(test, feature = "test-utils"))] + #[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))] pub fn insecure_skip_cert_verify(mut self, skip: bool) -> Self { self.insecure_skip_cert_verify = skip; self @@ -1049,6 +1051,7 @@ async fn resolve_host( /// Used to allow self signed certificates in tests #[cfg(any(test, feature = "test-utils"))] +#[cfg_attr(iroh_docsrs, doc(cfg(any(test, feature = "test-utils"))))] #[derive(Debug)] struct NoCertVerifier; diff --git a/iroh-net/src/relay/codec.rs b/iroh-net/src/relay/codec.rs index a83debd3ea..722c5c690e 100644 --- a/iroh-net/src/relay/codec.rs +++ b/iroh-net/src/relay/codec.rs @@ -24,9 +24,11 @@ const MAX_FRAME_SIZE: usize = 1024 * 1024; const MAGIC: &str = "RELAY🔑"; #[cfg(feature = "iroh-relay")] +#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))] pub(super) const KEEP_ALIVE: Duration = Duration::from_secs(60); // TODO: what should this be? #[cfg(feature = "iroh-relay")] +#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))] pub(super) const SERVER_CHANNEL_SIZE: usize = 1024 * 100; /// The number of packets buffered for sending per client pub(super) const PER_CLIENT_SEND_QUEUE_DEPTH: usize = 512; //32; @@ -166,6 +168,7 @@ pub(crate) async fn send_client_key + Unp /// Reads the `FrameType::ClientInfo` frame from the client (its proof of identity) /// upon it's initial connection. #[cfg(feature = "iroh-relay")] +#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))] pub(super) async fn recv_client_key> + Unpin>( stream: S, ) -> anyhow::Result<(PublicKey, ClientInfo)> { @@ -536,6 +539,7 @@ impl Encoder for DerpCodec { /// Receives the next frame and matches the frame type. If the correct type is found returns the content, /// otherwise an error. #[cfg(feature = "iroh-relay")] +#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))] pub(super) async fn recv_frame> + Unpin>( frame_type: FrameType, mut stream: S, diff --git a/iroh-net/src/relay/http.rs b/iroh-net/src/relay/http.rs index 83199befeb..25474e8567 100644 --- a/iroh-net/src/relay/http.rs +++ b/iroh-net/src/relay/http.rs @@ -3,6 +3,7 @@ pub(crate) const HTTP_UPGRADE_PROTOCOL: &str = "iroh derp http"; pub(crate) const WEBSOCKET_UPGRADE_PROTOCOL: &str = "websocket"; #[cfg(feature = "iroh-relay")] // only used in the server for now +#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))] pub(crate) const SUPPORTED_WEBSOCKET_VERSION: &str = "13"; /// The HTTP path under which the relay accepts relaying connections @@ -13,10 +14,12 @@ pub const RELAY_PROBE_PATH: &str = "/relay/probe"; /// The legacy HTTP path under which the relay used to accept relaying connections. /// We keep this for backwards compatibility. #[cfg(feature = "iroh-relay")] // legacy paths only used on server-side for backwards compat +#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))] pub(crate) const LEGACY_RELAY_PATH: &str = "/derp"; /// The legacy HTTP path under which the relay used to allow latency queries. /// We keep this for backwards compatibility. #[cfg(feature = "iroh-relay")] // legacy paths only used on server-side for backwards compat +#[cfg_attr(iroh_docsrs, doc(cfg(feature = "iroh-relay")))] pub(crate) const LEGACY_RELAY_PROBE_PATH: &str = "/derp/probe"; /// The HTTP upgrade protocol used for relaying. diff --git a/iroh-net/src/relay/server.rs b/iroh-net/src/relay/server.rs index 1d98cc08d5..9bc54192dc 100644 --- a/iroh-net/src/relay/server.rs +++ b/iroh-net/src/relay/server.rs @@ -82,6 +82,7 @@ pub struct ServerConfig { pub stun: Option, /// Socket to serve metrics on. #[cfg(feature = "metrics")] + #[cfg_attr(iroh_docsrs, doc(cfg(feature = "metrics")))] pub metrics_addr: Option, }