Deny missing docs in the config crates

crates/config/src/lib.rs

@@ -14,6 +14,7 @@
 
 #![forbid(unsafe_code)]
 #![deny(clippy::all)]
+#![deny(missing_docs)]
 #![deny(rustdoc::broken_intra_doc_links)]
 #![warn(clippy::pedantic)]
 #![allow(clippy::module_name_repetitions)]

crates/config/src/schema.rs

@@ -12,11 +12,14 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Useful JSON Schema definitions
+
 use schemars::{
     gen::SchemaGenerator,
     schema::{InstanceType, NumberValidation, Schema, SchemaObject},
 };
 
+/// A network port
 pub fn port(_gen: &mut SchemaGenerator) -> Schema {
     Schema::Object(SchemaObject {
         instance_type: Some(InstanceType::Integer.into()),
@@ -29,6 +32,7 @@ pub fn port(_gen: &mut SchemaGenerator) -> Schema {
     })
 }
 
+/// A network hostname
 pub fn hostname(_gen: &mut SchemaGenerator) -> Schema {
     Schema::Object(SchemaObject {
         instance_type: Some(InstanceType::String.into()),

crates/config/src/sections/clients.rs

@@ -48,24 +48,51 @@ impl From<JsonWebKeySet> for JwksOrJwksUri {
     }
 }
 
+/// Authentication method used by clients
 #[derive(JsonSchema, Serialize, Deserialize, Clone, Debug)]
 #[serde(tag = "client_auth_method", rename_all = "snake_case")]
 pub enum ClientAuthMethodConfig {
+    /// `none`: No authentication
     None,
-    ClientSecretBasic { client_secret: String },
+
-    ClientSecretPost { client_secret: String },
+    /// `client_secret_basic`: `client_id` and `client_secret` used as basic
-    ClientSecretJwt { client_secret: String },
+    /// authorization credentials
+    ClientSecretBasic {
+        /// The client secret
+        client_secret: String,
+    },
+
+    /// `client_secret_post`: `client_id` and `client_secret` sent in the
+    /// request body
+    ClientSecretPost {
+        /// The client secret
+        client_secret: String,
+    },
+
+    /// `client_secret_basic`: a `client_assertion` sent in the request body and
+    /// signed using the `client_secret`
+    ClientSecretJwt {
+        /// The client secret
+        client_secret: String,
+    },
+
+    /// `client_secret_basic`: a `client_assertion` sent in the request body and
+    /// signed by an asymetric key
     PrivateKeyJwt(JwksOrJwksUri),
 }
 
+/// An OAuth 2.0 client configuration
 #[skip_serializing_none]
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 pub struct ClientConfig {
+    /// The client ID
     pub client_id: String,
 
+    /// Authentication method used for this client
     #[serde(flatten)]
     pub client_auth_method: ClientAuthMethodConfig,
 
+    /// List of allowed redirect URIs
     #[serde(default)]
     pub redirect_uris: Vec<Url>,
 }
@@ -75,6 +102,7 @@ pub struct ClientConfig {
 pub struct InvalidRedirectUriError;
 
 impl ClientConfig {
+    #[doc(hidden)]
     pub fn resolve_redirect_uri<'a>(
         &'a self,
         suggested_uri: &'a Option<Url>,
@@ -85,7 +113,7 @@ impl ClientConfig {
         )
     }
 
-    pub fn check_redirect_uri<'a>(
+    fn check_redirect_uri<'a>(
         &self,
         redirect_uri: &'a Url,
     ) -> Result<&'a Url, InvalidRedirectUriError> {
@@ -97,6 +125,7 @@ impl ClientConfig {
     }
 }
 
+/// List of OAuth 2.0/OIDC clients config
 #[derive(Debug, Clone, Default, Serialize, Deserialize, JsonSchema)]
 #[serde(transparent)]
 pub struct ClientsConfig(Vec<ClientConfig>);

crates/config/src/sections/secrets.rs

@@ -34,12 +34,14 @@ use tracing::info;
 
 use super::ConfigurationSection;
 
+/// Helps encrypting and decrypting data
 #[derive(Clone)]
 pub struct Encrypter {
     aead: Arc<ChaCha20Poly1305>,
 }
 
 impl Encrypter {
+    /// Creates an [`Encrypter`] out of an encryption key
     #[must_use]
     pub fn new(key: &[u8; 32]) -> Self {
         let key = GenericArray::from_slice(key);
@@ -48,12 +50,14 @@ impl Encrypter {
         Self { aead }
     }
 
+    /// Encrypt a payload
     pub fn encrypt(&self, nonce: &[u8; 12], decrypted: &[u8]) -> anyhow::Result<Vec<u8>> {
         let nonce = GenericArray::from_slice(&nonce[..]);
         let encrypted = self.aead.encrypt(nonce, decrypted)?;
         Ok(encrypted)
     }
 
+    /// Decrypts a payload
     pub fn decrypt(&self, nonce: &[u8; 12], encrypted: &[u8]) -> anyhow::Result<Vec<u8>> {
         let nonce = GenericArray::from_slice(&nonce[..]);
         let encrypted = self.aead.decrypt(nonce, encrypted)?;
@@ -86,6 +90,7 @@ pub struct KeyConfig {
     key: KeyOrPath,
 }
 
+/// Application secrets
 #[serde_as]
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 pub struct SecretsConfig {
@@ -104,6 +109,7 @@ pub struct SecretsConfig {
 }
 
 impl SecretsConfig {
+    /// Derive a signing and verifying keystore out of the config
     pub async fn key_store(&self) -> anyhow::Result<StaticKeystore> {
         let mut store = StaticKeystore::new();
 
@@ -158,6 +164,7 @@ impl SecretsConfig {
         Ok(store)
     }
 
+    /// Derive an [`Encrypter`] out of the config
     #[must_use]
     pub fn encrypter(&self) -> Encrypter {
         Encrypter::new(&self.encryption)