frame/response: document modules and items

Author: wprzytula

scylla-cql/src/frame/response/authenticate.rs

@@ -1,15 +1,19 @@
+//! CQL protocol-level representation of an `AUTHENTICATE` response.
+
 use crate::frame::frame_errors::{
     CqlAuthChallengeParseError, CqlAuthSuccessParseError, CqlAuthenticateParseError,
 };
 use crate::frame::types;
 
-// Implements Authenticate message.
+/// Represents AUTHENTICATE CQL response.
 #[derive(Debug)]
 pub struct Authenticate {
+    /// The name of the authenticator requested by the server to use.
     pub authenticator_name: String,
 }
 
 impl Authenticate {
+    /// Deserializes an `AUTHENTICATE` message from the provided buffer.
     pub fn deserialize(buf: &mut &[u8]) -> Result<Self, CqlAuthenticateParseError> {
         let authenticator_name = types::read_string(buf)
             .map_err(CqlAuthenticateParseError::AuthNameParseError)?
@@ -19,12 +23,15 @@ impl Authenticate {
     }
 }
 
+/// Represents AUTH_SUCCESS CQL response.
 #[derive(Debug)]
 pub struct AuthSuccess {
+    /// Optional success message provided by the server.
     pub success_message: Option<Vec<u8>>,
 }
 
 impl AuthSuccess {
+    /// Deserializes an `AUTH_SUCCESS` message from the provided buffer.
     pub fn deserialize(buf: &mut &[u8]) -> Result<Self, CqlAuthSuccessParseError> {
         let success_message = types::read_bytes_opt(buf)
             .map_err(CqlAuthSuccessParseError::SuccessMessageParseError)?
@@ -34,12 +41,20 @@ impl AuthSuccess {
     }
 }
 
+/// Represents AUTH_CHALLENGE CQL response.
+///
+/// This message is sent by the server to challenge the client to provide
+/// authentication credentials. The client must respond with an `AUTH_RESPONSE`
+/// message containing the credentials.
 #[derive(Debug)]
 pub struct AuthChallenge {
+    /// The challenge sent by the server, whose semantics depend on the
+    /// authenticator being used.
     pub authenticate_message: Option<Vec<u8>>,
 }
 
 impl AuthChallenge {
+    /// Deserializes an `AUTH_CHALLENGE` message from the provided buffer.
     pub fn deserialize(buf: &mut &[u8]) -> Result<Self, CqlAuthChallengeParseError> {
         let authenticate_message = types::read_bytes_opt(buf)
             .map_err(CqlAuthChallengeParseError::AuthMessageParseError)?

scylla-cql/src/frame/response/custom_type_parser.rs

@@ -1,3 +1,5 @@
+//! Implementation of a parser for custom types in the CQL protocol.
+
 use super::result::CollectionType;
 use super::result::NativeType;
 use super::result::{ColumnType, UserDefinedType};

scylla-cql/src/frame/response/error.rs

@@ -1,3 +1,5 @@
+//! CQL protocol-level representation of an `ERROR` response.
+
 use crate::frame::frame_errors::{CqlErrorParseError, LowLevelDeserializationError};
 use crate::frame::protocol_features::ProtocolFeatures;
 use crate::frame::types;
@@ -6,9 +8,14 @@ use byteorder::ReadBytesExt;
 use bytes::Bytes;
 use thiserror::Error;
 
+/// Represents a CQL protocol-level error that is sent by the database in response to a query
+/// that failed to execute successfully.
 #[derive(Debug, Clone)]
 pub struct Error {
+    /// Error code and other context of the error.
     pub error: DbError,
+
+    /// The reason for the error, typically a human-readable message.
     pub reason: String,
 }
 
@@ -25,6 +32,7 @@ fn make_error_field_err(
 }
 
 impl Error {
+    /// Deserializes the error response from the provided buffer.
     pub fn deserialize(
         features: &ProtocolFeatures,
         buf: &mut &[u8],
@@ -327,6 +335,7 @@ pub enum DbError {
 }
 
 impl DbError {
+    /// Returns the error code for this error, as defined in the CQL protocol specification.
     pub fn code(&self, protocol_features: &ProtocolFeatures) -> i32 {
         match self {
             DbError::ServerError => 0x0000,
@@ -456,7 +465,7 @@ pub enum WriteType {
     Cas,
     /// Write involves VIEW update and failure to acquire local view(MV) lock for key within timeout
     View,
-    /// Timeout occurred  when a cdc_total_space_in_mb is exceeded when doing a write to data tracked by cdc
+    /// Timeout occurred when a cdc_total_space_in_mb is exceeded when doing a write to data tracked by cdc
     Cdc,
     /// Other type not specified in the specification
     Other(String),
@@ -495,6 +504,7 @@ impl From<&str> for WriteType {
 }
 
 impl WriteType {
+    /// Returns the string representation of the write type as defined in the CQL protocol specification.
     pub fn as_str(&self) -> &str {
         match self {
             WriteType::Simple => "SIMPLE",

scylla-cql/src/frame/response/event.rs

@@ -1,74 +1,117 @@
+//! CQL protocol-level representation of an `EVENT` response.
+
 use crate::frame::frame_errors::{
     ClusterChangeEventParseError, CqlEventParseError, SchemaChangeEventParseError,
 };
 use crate::frame::server_event_type::EventType;
 use crate::frame::types;
 use std::net::SocketAddr;
 
+/// Event that the server notified the client about.
 #[derive(Debug)]
 // Check triggers because all variants end with "Change".
 // TODO(2.0): Remove the "Change" postfix from variants.
 #[expect(clippy::enum_variant_names)]
 pub enum Event {
+    /// Topology changed.
     TopologyChange(TopologyChangeEvent),
+    /// Status of a node changed.
     StatusChange(StatusChangeEvent),
+    /// Schema changed.
     SchemaChange(SchemaChangeEvent),
 }
 
+/// Event that notifies about changes in the cluster topology.
 #[derive(Debug)]
 pub enum TopologyChangeEvent {
+    /// A new node was added to the cluster.
     NewNode(SocketAddr),
+    /// A node was removed from the cluster.
     RemovedNode(SocketAddr),
 }
 
+/// Event that notifies about changes in the nodes' status.
 #[derive(Debug)]
 pub enum StatusChangeEvent {
+    /// A node went up.
     Up(SocketAddr),
+    /// A node went down.
     Down(SocketAddr),
 }
 
+/// Event that notifies about changes in the cluster topology.
 #[derive(Debug)]
 // Check triggers because all variants end with "Change".
 // TODO(2.0): Remove the "Change" postfix from variants.
 #[expect(clippy::enum_variant_names)]
 pub enum SchemaChangeEvent {
+    /// Keyspace was altered.
     KeyspaceChange {
+        /// Type of change that was made to the keyspace.
         change_type: SchemaChangeType,
+        /// Name of the keyspace that was altered.
         keyspace_name: String,
     },
+    /// Table was altered.
     TableChange {
+        /// Type of change that was made to the table.
         change_type: SchemaChangeType,
+        /// Name of the keyspace that contains the table.
         keyspace_name: String,
+        /// Name of the table that was altered.
         object_name: String,
     },
+    /// Type was altered.
     TypeChange {
+        /// Type of change that was made to the type.
         change_type: SchemaChangeType,
+        /// Name of the keyspace that contains the type.
         keyspace_name: String,
+        /// Name of the type that was altered.
         type_name: String,
     },
+    /// Function was altered.
     FunctionChange {
+        /// Type of change that was made to the function.
         change_type: SchemaChangeType,
+        /// Name of the keyspace that contains the function.
         keyspace_name: String,
+        /// Name of the function that was altered.
         function_name: String,
+        /// List of argument types of the function that was altered.
         arguments: Vec<String>,
     },
+    /// Aggregate was altered.
     AggregateChange {
+        /// Type of change that was made to the aggregate.
         change_type: SchemaChangeType,
+        /// Name of the keyspace that contains the aggregate.
         keyspace_name: String,
+        /// Name of the aggregate that was altered.
         aggregate_name: String,
+        /// List of argument types of the aggregate that was altered.
         arguments: Vec<String>,
     },
 }
 
+/// Type of change that was made to the schema.
 #[derive(Debug)]
 pub enum SchemaChangeType {
+    /// The affected schema item was created.
     Created,
+
+    /// The affected schema item was updated.
     Updated,
+
+    /// The affected schema item was dropped.
     Dropped,
+
+    /// A placeholder for an invalid schema change type.
     Invalid,
 }
 
 impl Event {
+    /// Deserialize an event from the provided buffer.
     pub fn deserialize(buf: &mut &[u8]) -> Result<Self, CqlEventParseError> {
         let event_type: EventType = types::read_string(buf)
             .map_err(CqlEventParseError::EventTypeParseError)?
@@ -88,6 +131,7 @@ impl Event {
 }
 
 impl SchemaChangeEvent {
+    /// Deserialize a schema change event from the provided buffer.
     pub fn deserialize(buf: &mut &[u8]) -> Result<Self, SchemaChangeEventParseError> {
         let type_of_change_string =
             types::read_string(buf).map_err(SchemaChangeEventParseError::TypeOfChangeParseError)?;
@@ -188,6 +232,7 @@ impl SchemaChangeEvent {
 }
 
 impl TopologyChangeEvent {
+    /// Deserialize a topology change event from the provided buffer.
     pub fn deserialize(buf: &mut &[u8]) -> Result<Self, ClusterChangeEventParseError> {
         let type_of_change = types::read_string(buf)
             .map_err(ClusterChangeEventParseError::TypeOfChangeParseError)?;
@@ -205,6 +250,7 @@ impl TopologyChangeEvent {
 }
 
 impl StatusChangeEvent {
+    /// Deserialize a status change event from the provided buffer.
     pub fn deserialize(buf: &mut &[u8]) -> Result<Self, ClusterChangeEventParseError> {
         let type_of_change = types::read_string(buf)
             .map_err(ClusterChangeEventParseError::TypeOfChangeParseError)?;

scylla-cql/src/frame/response/mod.rs

@@ -1,3 +1,5 @@
+//! CQL responses sent by the server.
+
 pub mod authenticate;
 pub mod custom_type_parser;
 pub mod error;
@@ -47,6 +49,7 @@ impl std::fmt::Display for CqlResponseKind {
     }
 }
 
+/// Opcode of a response, used to identify the response type in a CQL frame.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 #[repr(u8)]
 pub enum ResponseOpcode {
@@ -81,19 +84,30 @@ impl TryFrom<u8> for ResponseOpcode {
     }
 }
 
+/// A CQL response that has been received from the server.
 #[derive(Debug)]
 pub enum Response {
+    /// ERROR response, returned by the server when an error occurs.
     Error(Error),
+    /// READY response, indicating that the server is ready to process requests,
+    /// typically after a connection is established.
     Ready,
+    /// RESULT response, containing the result of a statement execution.
     Result(result::Result),
+    /// AUTHENTICATE response, indicating that the server requires authentication.
     Authenticate(authenticate::Authenticate),
+    /// AUTH_SUCCESS response, indicating that the authentication was successful.
     AuthSuccess(authenticate::AuthSuccess),
+    /// AUTH_CHALLENGE response, indicating that the server requires further authentication.
     AuthChallenge(authenticate::AuthChallenge),
+    /// SUPPORTED response, containing the features supported by the server.
     Supported(Supported),
+    /// EVENT response, containing an event that occurred on the server.
     Event(event::Event),
 }
 
 impl Response {
+    /// Returns the kind of this response.
     pub fn to_response_kind(&self) -> CqlResponseKind {
         match self {
             Response::Error(_) => CqlResponseKind::Error,
@@ -107,6 +121,7 @@ impl Response {
         }
     }
 
+    /// Deserialize a response from the given bytes.
     pub fn deserialize(
         features: &ProtocolFeatures,
         opcode: ResponseOpcode,
@@ -136,6 +151,7 @@ impl Response {
         Ok(response)
     }
 
+    /// Converts this response into a `NonErrorResponse`, returning an error if it is an `Error` response.
     pub fn into_non_error_response(self) -> Result<NonErrorResponse, error::Error> {
         let non_error_response = match self {
             Response::Error(e) => return Err(e),
@@ -152,19 +168,29 @@ impl Response {
     }
 }
 
-// A Response which can not be Response::Error
+/// A CQL response that has been received from the server, excluding error responses.
+/// This is used to handle responses that are not errors, allowing for easier processing
+/// of valid responses without need to handle error case any later.
 #[derive(Debug)]
 pub enum NonErrorResponse {
+    /// See [`Response::Ready`].
     Ready,
+    /// See [`Response::Result`].
     Result(result::Result),
+    /// See [`Response::Authenticate`].
     Authenticate(authenticate::Authenticate),
+    /// See [`Response::AuthSuccess`].
     AuthSuccess(authenticate::AuthSuccess),
+    /// See [`Response::AuthChallenge`].
     AuthChallenge(authenticate::AuthChallenge),
+    /// See [`Response::Supported`].
     Supported(Supported),
+    /// See [`Response::Event`].
     Event(event::Event),
 }
 
 impl NonErrorResponse {
+    /// Returns the kind of this non-error response.
     pub fn to_response_kind(&self) -> CqlResponseKind {
         match self {
             NonErrorResponse::Ready => CqlResponseKind::Ready,