docs: add simple comments to pub items (#430)

Author: sunng87

src/api/auth/cleartext.rs

@@ -13,6 +13,7 @@ use crate::error::{PgWireError, PgWireResult};
 use crate::messages::startup::Authentication;
 use crate::messages::{PgWireBackendMessage, PgWireFrontendMessage};
 
+/// Startup handler for cleartext password authentication.
 pub struct CleartextPasswordAuthStartupHandler<A, P> {
     auth_source: A,
     parameter_provider: P,
@@ -21,6 +22,7 @@ pub struct CleartextPasswordAuthStartupHandler<A, P> {
 }
 
 impl<A, P> CleartextPasswordAuthStartupHandler<A, P> {
+    /// Creates a new cleartext password auth handler.
     pub fn new(auth_source: A, parameter_provider: P) -> Self {
         Self {
             auth_source,
@@ -30,6 +32,7 @@ impl<A, P> CleartextPasswordAuthStartupHandler<A, P> {
         }
     }
 
+    /// Sets a custom PID/secret key generator.
     pub fn with_pid_secret_key_generator(
         mut self,
         generator: Arc<dyn PidSecretKeyGenerator>,
@@ -38,6 +41,7 @@ impl<A, P> CleartextPasswordAuthStartupHandler<A, P> {
         self
     }
 
+    /// Sets a connection manager.
     pub fn with_connection_manager(mut self, manager: Arc<ConnectionManager>) -> Self {
         self.connection_manager = Some(manager);
         self

src/api/auth/md5pass.rs

@@ -14,6 +14,7 @@ use crate::error::{PgWireError, PgWireResult};
 use crate::messages::startup::Authentication;
 use crate::messages::{PgWireBackendMessage, PgWireFrontendMessage};
 
+/// Startup handler for MD5 password authentication.
 pub struct Md5PasswordAuthStartupHandler<A, P> {
     auth_source: Arc<A>,
     parameter_provider: Arc<P>,
@@ -23,6 +24,7 @@ pub struct Md5PasswordAuthStartupHandler<A, P> {
 }
 
 impl<A, P> Md5PasswordAuthStartupHandler<A, P> {
+    /// Creates a new MD5 password auth handler.
     pub fn new(auth_source: Arc<A>, parameter_provider: Arc<P>) -> Self {
         Md5PasswordAuthStartupHandler {
             auth_source,
@@ -33,6 +35,7 @@ impl<A, P> Md5PasswordAuthStartupHandler<A, P> {
         }
     }
 
+    /// Sets a custom PID/secret key generator.
     pub fn with_pid_secret_key_generator(
         mut self,
         generator: Arc<dyn PidSecretKeyGenerator>,
@@ -41,6 +44,7 @@ impl<A, P> Md5PasswordAuthStartupHandler<A, P> {
         self
     }
 
+    /// Sets a connection manager.
     pub fn with_connection_manager(mut self, manager: Arc<ConnectionManager>) -> Self {
         self.connection_manager = Some(manager);
         self

src/api/auth/mod.rs

@@ -32,6 +32,7 @@ pub trait StartupHandler: Send + Sync {
         PgWireError: From<<C as Sink<PgWireBackendMessage>>::Error>;
 }
 
+/// Provides server parameters to send to the client during startup.
 pub trait ServerParameterProvider: Send + Sync {
     fn server_parameters<C>(&self, _client: &C) -> Option<HashMap<String, String>>
     where
@@ -185,22 +186,26 @@ impl ServerParameterProvider for DefaultServerParameterProvider {
     }
 }
 
+/// Represents a password with an optional salt.
 #[derive(Debug, new, Clone)]
 pub struct Password {
     salt: Option<Vec<u8>>,
     password: Vec<u8>,
 }
 
 impl Password {
+    /// Returns the salt, if any.
     pub fn salt(&self) -> Option<&[u8]> {
         self.salt.as_deref()
     }
 
+    /// Returns the password bytes.
     pub fn password(&self) -> &[u8] {
         &self.password
     }
 }
 
+/// Login information extracted from the client connection.
 #[derive(Debug, new)]
 pub struct LoginInfo<'a> {
     user: Option<&'a str>,
@@ -209,18 +214,22 @@ pub struct LoginInfo<'a> {
 }
 
 impl LoginInfo<'_> {
+    /// Returns the user name.
     pub fn user(&self) -> Option<&str> {
         self.user
     }
 
+    /// Returns the database name.
     pub fn database(&self) -> Option<&str> {
         self.database
     }
 
+    /// Returns the client host address.
     pub fn host(&self) -> &str {
         &self.host
     }
 
+    /// Creates `LoginInfo` from a client.
     pub fn from_client_info<C>(client: &C) -> LoginInfo<'_>
     where
         C: ClientInfo,
@@ -248,6 +257,7 @@ pub trait AuthSource: Send + Sync + Debug {
     async fn get_password(&self, login: &LoginInfo) -> PgWireResult<Password>;
 }
 
+/// Negotiates the protocol version with the client.
 pub async fn protocol_negotiation<C>(client: &mut C, startup_message: &Startup) -> PgWireResult<()>
 where
     C: ClientInfo + Sink<PgWireBackendMessage> + Unpin,
@@ -280,6 +290,7 @@ where
     }
 }
 
+/// Saves startup message parameters into client metadata.
 pub fn save_startup_parameters_to_metadata<C>(client: &mut C, startup_message: &Startup)
 where
     C: ClientInfo,
@@ -338,6 +349,7 @@ where
     Ok(())
 }
 
+/// Completes authentication by sending `AuthenticationOk`, parameter status, backend key data, and `ReadyForQuery`.
 pub async fn finish_authentication<C, P>(
     client: &mut C,
     server_parameter_provider: &P,

src/api/auth/noop.rs

@@ -13,6 +13,7 @@ use crate::messages::response::{ReadyForQuery, TransactionStatus};
 use crate::messages::{PgWireBackendMessage, PgWireFrontendMessage};
 
 #[async_trait]
+/// A startup handler that performs no authentication.
 pub trait NoopStartupHandler: StartupHandler {
     fn connection_manager(&self) -> Option<Arc<ConnectionManager>> {
         None

src/api/auth/sasl.rs

@@ -19,10 +19,14 @@ use super::{ServerParameterProvider, StartupHandler};
 pub mod oauth;
 pub mod scram;
 
+/// SASL mechanism name for SCRAM-SHA-256.
 pub const SCRAM_SHA_256_METHOD: &str = "SCRAM-SHA-256";
+/// SASL mechanism name for SCRAM-SHA-256-PLUS with channel binding.
 pub const SCRAM_SHA_256_PLUS_METHOD: &str = "SCRAM-SHA-256-PLUS";
+/// SASL mechanism name for OAUTHBEARER.
 pub const OAUTHBEARER_METHOD: &str = "OAUTHBEARER";
 
+/// States of the SASL authentication state machine.
 #[derive(Debug)]
 pub enum SASLState {
     Initial,
@@ -51,6 +55,7 @@ impl SASLState {
     }
 }
 
+/// Startup handler for SASL-based authentication (SCRAM and OAUTHBEARER).
 pub struct SASLAuthStartupHandler<P> {
     parameter_provider: Arc<P>,
     pid_secret_key_generator: Arc<dyn PidSecretKeyGenerator>,
@@ -64,6 +69,7 @@ pub struct SASLAuthStartupHandler<P> {
 }
 
 impl<P> SASLAuthStartupHandler<P> {
+    /// Creates a new SASL auth handler.
     pub fn new(parameter_provider: Arc<P>) -> Self {
         SASLAuthStartupHandler {
             parameter_provider,
@@ -75,16 +81,19 @@ impl<P> SASLAuthStartupHandler<P> {
         }
     }
 
+    /// Configures SCRAM authentication.
     pub fn with_scram(mut self, scram_auth: scram::ScramAuth) -> Self {
         self.scram = Some(scram_auth);
         self
     }
 
+    /// Configures OAuth authentication.
     pub fn with_oauth(mut self, oauth: oauth::Oauth) -> Self {
         self.oauth = Some(oauth);
         self
     }
 
+    /// Sets a custom PID/secret key generator.
     pub fn with_pid_secret_key_generator(
         mut self,
         generator: Arc<dyn PidSecretKeyGenerator>,
@@ -93,6 +102,7 @@ impl<P> SASLAuthStartupHandler<P> {
         self
     }
 
+    /// Sets a connection manager.
     pub fn with_connection_manager(mut self, manager: Arc<ConnectionManager>) -> Self {
         self.connection_manager = Some(manager);
         self

src/api/auth/sasl/oauth.rs

@@ -13,9 +13,11 @@ use crate::{
     messages::startup::{Authentication, PasswordMessageFamily},
 };
 
+/// Re-exports the simple OIDC validator when the feature is enabled.
 #[cfg(feature = "simple-oidc-validator")]
 pub use crate::api::auth::simple_oidc_validator::SimpleOidcValidator;
 
+/// OAuth/OIDC authentication configuration.
 #[derive(Debug)]
 pub struct Oauth {
     pub issuer: String,
@@ -67,6 +69,7 @@ impl Oauth {
         }
     }
 
+    /// Configures whether to skip user mapping.
     pub fn with_skip_usermapping(mut self, skip: bool) -> Self {
         self.skip_usermap = skip;
         self
@@ -259,6 +262,7 @@ impl Oauth {
         Some(token)
     }
 
+    /// Processes an incoming OAuth SASL message and returns the response and new state.
     pub async fn process_oauth_message<C>(
         &self,
         client: &C,

src/api/auth/sasl/scram.rs

@@ -12,6 +12,7 @@ use x509_certificate::SignatureAlgorithm;
 use x509_certificate::certificate::CapturedX509Certificate;
 
 use crate::api::ClientInfo;
+/// Re-exports client-side SCRAM authentication types.
 #[cfg(feature = "client-api")]
 pub use crate::api::auth::sasl::scram::client::*;
 use crate::api::auth::{AuthSource, LoginInfo, Password};
@@ -25,15 +26,18 @@ use aws_lc_rs::{digest, hmac, pbkdf2};
 #[cfg(all(feature = "_ring", not(feature = "_aws-lc-rs")))]
 use ring::{digest, hmac, pbkdf2};
 
+/// Default SCRAM iteration count.
 pub const SCRAM_ITERATIONS: usize = 4096;
 
+/// SCRAM authentication configuration and state.
 #[derive(Debug)]
 pub struct ScramAuth {
     auth_db: Arc<dyn AuthSource>,
     authenticator: ScramServerAuth,
 }
 
 impl ScramAuth {
+    /// Creates a new SCRAM auth instance.
     pub fn new(auth_db: Arc<dyn AuthSource>) -> ScramAuth {
         ScramAuth {
             auth_db,
@@ -62,6 +66,7 @@ impl ScramAuth {
         self.authenticator.set_iterations(iterations);
     }
 
+    /// Returns `true` if channel binding is configured.
     pub fn supports_channel_binding(&self) -> bool {
         self.authenticator.server_cert_sig.is_some()
     }
@@ -84,6 +89,7 @@ pub fn gen_salted_password(password: &str, salt: &[u8], iters: usize) -> Vec<u8>
     hi(pass_bytes, salt, iters)
 }
 
+/// Generates a random nonce for SCRAM authentication.
 pub fn random_nonce() -> String {
     STANDARD.encode(rand::random::<[u8; 18]>())
 }
@@ -149,6 +155,7 @@ impl Default for ScramServerAuth {
 }
 
 impl ScramServerAuth {
+    /// Creates a new SCRAM server authenticator.
     pub fn new() -> Self {
         Self {
             server_cert_sig: None,
@@ -227,6 +234,7 @@ pub struct ScramServerAuthWaitingForClientFinal {
 }
 
 impl ScramServerAuthWaitingForClientFinal {
+    /// Processes the client final message and verifies the proof.
     pub fn on_client_final_message(&self, client_final_message: &[u8]) -> PgWireResult<String> {
         let client_final = ClientFinal::from_str(decode_str(client_final_message)?)?;
 
@@ -267,12 +275,14 @@ mod client {
     use super::*;
     use crate::error::{PgWireClientError, PgWireClientResult};
 
+    /// Client-side SCRAM authenticator.
     pub struct ScramClientAuth {
         username: String,
         password: String,
     }
 
     impl ScramClientAuth {
+        /// Creates a new SCRAM client authenticator.
         pub fn new(username: String, password: String) -> Self {
             Self { username, password }
         }

src/api/auth/simple_oidc_validator.rs

@@ -56,6 +56,7 @@ pub struct SimpleOidcValidator {
 }
 
 impl SimpleOidcValidator {
+    /// Creates a new validator by fetching the JWKS URI from the issuer's discovery endpoint.
     pub async fn new(issuer: impl Into<String>) -> Result<Self, PgWireError> {
         let issuer = issuer.into();
         let client = reqwest::Client::new();

src/api/cancel.rs

@@ -8,9 +8,11 @@ use crate::messages::cancel::CancelRequest;
 /// Handler for Cancel Request
 #[async_trait]
 pub trait CancelHandler: Send + Sync {
+    /// Called when a cancel request is received.
     async fn on_cancel_request(&self, cancel_request: CancelRequest);
 }
 
+/// Default cancel handler that delegates to the connection manager.
 #[derive(Debug, derive_new::new)]
 pub struct DefaultCancelHandler {
     manager: Arc<ConnectionManager>,

src/api/client/auth.rs

@@ -16,13 +16,16 @@ use crate::messages::{PgWireBackendMessage, PgWireFrontendMessage};
 
 use super::{ClientInfo, ReadyState, ServerInformation};
 
+/// Handler trait for the startup/authentication phase of a client connection.
 #[async_trait]
 pub trait StartupHandler: Send {
+    /// Initiate the startup process by sending a startup message.
     async fn startup<C>(&mut self, client: &mut C) -> PgWireClientResult<()>
     where
         C: ClientInfo + Sink<PgWireFrontendMessage> + Unpin + Send,
         PgWireClientError: From<<C as Sink<PgWireFrontendMessage>>::Error>;
 
+    /// Handle a single backend message during startup/authentication.
     async fn on_message<C>(
         &mut self,
         client: &mut C,
@@ -61,6 +64,7 @@ pub trait StartupHandler: Send {
         Ok(ReadyState::Pending)
     }
 
+    /// Handle an authentication message from the server.
     async fn on_authentication<C>(
         &mut self,
         client: &mut C,
@@ -74,6 +78,7 @@ pub trait StartupHandler: Send {
             + Send,
         PgWireClientError: From<<C as Sink<PgWireFrontendMessage>>::Error>;
 
+    /// Handle a parameter status message from the server.
     async fn on_parameter_status<C>(
         &mut self,
         client: &mut C,
@@ -83,6 +88,7 @@ pub trait StartupHandler: Send {
         C: ClientInfo + Sink<PgWireFrontendMessage> + Unpin + Send,
         PgWireClientError: From<<C as Sink<PgWireFrontendMessage>>::Error>;
 
+    /// Handle a backend key data message from the server.
     async fn on_backend_key<C>(
         &mut self,
         client: &mut C,
@@ -92,6 +98,7 @@ pub trait StartupHandler: Send {
         C: ClientInfo + Sink<PgWireFrontendMessage> + Unpin + Send,
         PgWireClientError: From<<C as Sink<PgWireFrontendMessage>>::Error>;
 
+    /// Handle a `ReadyForQuery` message and return the collected server information.
     async fn on_ready_for_query<C>(
         &mut self,
         client: &mut C,
@@ -102,6 +109,7 @@ pub trait StartupHandler: Send {
         PgWireClientError: From<<C as Sink<PgWireFrontendMessage>>::Error>;
 }
 
+/// Default startup handler that supports cleartext, MD5, and SCRAM-SHA-256 authentication.
 #[derive(new, Debug)]
 pub struct DefaultStartupHandler {
     #[new(default)]