Merge pull request #1398 from wprzytula/scylla-cql-more-docs

scylla-cql: Write missing docstrings - part 1

Author: wprzytula

scylla-cql/Cargo.toml

@@ -3,7 +3,7 @@ name = "scylla-cql"
 version = "1.3.0"
 edition = "2021"
 rust-version = "1.70"
-description = "CQL data types and primitives, for interacting with Scylla."
+description = "CQL data types and primitives, for interacting with ScyllaDB."
 repository = "https://github.com/scylladb/scylla-rust-driver"
 readme = "../README.md"
 keywords = ["database", "scylla", "cql", "cassandra"]

scylla-cql/src/deserialize/frame_slice.rs

@@ -1,9 +1,11 @@
+//! Defines `FrameSlice`, a borrowed reference to a part of the frame.
+
 use bytes::Bytes;
 
 use crate::frame::frame_errors::LowLevelDeserializationError;
 use crate::frame::types;
 
-/// A reference to a part of the frame.
+/// A borrowed reference to a part of the frame.
 //
 // # Design justification
 //

scylla-cql/src/deserialize/result.rs

@@ -1,3 +1,8 @@
+//! Provides types for dealing with query result deserialization.
+//!
+//! Those yield raw rows, whose deserialization is handled by
+//! the `row` module.
+
 use bytes::Bytes;
 
 use crate::frame::response::result::{
@@ -209,6 +214,9 @@ impl RawRowLendingIterator {
         Some(Ok(iter))
     }
 
+    /// Returns the bounds on the remaining length of the iterator.
+    ///
+    /// This is analogous to [Iterator::size_hint].
     #[inline]
     pub fn size_hint(&self) -> (usize, Option<usize>) {
         // next() is written in a way that it does not progress on error, so once an error

scylla-cql/src/deserialize/row.rs

@@ -1,4 +1,7 @@
 //! Provides types for dealing with row deserialization.
+//!
+//! Those yield raw values, whose deserialization is handled by
+//! the `value` module.
 
 use std::fmt::Display;
 
@@ -12,8 +15,14 @@ use crate::value::{CqlValue, Row};
 /// Represents a raw, unparsed column value.
 #[non_exhaustive]
 pub struct RawColumn<'frame, 'metadata> {
+    /// Index of the column in the row.
     pub index: usize,
+
+    /// Specification of the column, including its name and type.
     pub spec: &'metadata ColumnSpec<'metadata>,
+
+    /// Slice of the frame that contains the serialized value of the column.
+    /// None means that the column is null.
     pub slice: Option<FrameSlice<'frame>>,
 }
 

scylla-cql/src/deserialize/value.rs

@@ -1451,6 +1451,7 @@ impl<'frame, 'metadata> UdtIterator<'frame, 'metadata> {
         }
     }
 
+    /// Returns remaining (i.e., not yet deserialized) fields of the UDT.
     #[inline]
     pub fn fields(&self) -> &'metadata [(Cow<'metadata, str>, ColumnType<'metadata>)] {
         self.remaining_fields

scylla-cql/src/frame/frame_errors.rs

@@ -1,3 +1,5 @@
+//! Low-level errors that can occur during CQL frame parsing and serialization.
+
 use std::error::Error;
 use std::sync::Arc;
 
@@ -67,6 +69,8 @@ pub enum FrameHeaderParseError {
     #[error("Received frame marked as coming from a client")]
     FrameFromClient,
 
+    /// Received a frame marked as coming from a server, while expecting a frame
+    /// coming from a client.
     // FIXME: this should not belong here. User always expects a frame from server.
     // This variant is only used in scylla-proxy - need to investigate it later.
     #[error("Received frame marked as coming from the server")]
@@ -151,6 +155,7 @@ pub enum CqlResponseParseError {
 }
 
 impl CqlResponseParseError {
+    /// Retrieves the kind of CQL response that this error corresponds to.
     pub fn to_response_kind(&self) -> CqlResponseKind {
         match self {
             CqlResponseParseError::CqlErrorParseError(_) => CqlResponseKind::Error,

scylla-cql/src/frame/mod.rs

@@ -1,3 +1,13 @@
+//! Abstractions of the CQL wire protocol:
+//! - request and response frames' representation and ser/de;
+//! - frame header and body;
+//! - serialization and deserialization of low-level CQL protocol types;
+//! - protocol features negotiation;
+//! - compression, tracing, custom payload support;
+//! - consistency levels;
+//! - errors that can occur during the above operations.
+//!
+
 pub mod frame_errors;
 pub mod protocol_features;
 pub mod request;
@@ -25,13 +35,21 @@ const HEADER_SIZE: usize = 9;
 
 pub mod flag {
     //! Frame flags
+
+    /// The frame contains a compressed body.
     pub const COMPRESSION: u8 = 0x01;
+
+    /// The frame contains tracing ID.
     pub const TRACING: u8 = 0x02;
+
+    /// The frame contains a custom payload.
     pub const CUSTOM_PAYLOAD: u8 = 0x04;
+
+    /// The frame contains warnings.
     pub const WARNING: u8 = 0x08;
 }
 
-/// All of the Authenticators supported by Scylla
+/// All of the Authenticators supported by ScyllaDB
 #[derive(Debug, PartialEq, Eq, Clone)]
 // Check triggers because all variants end with "Authenticator".
 // TODO(2.0): Remove the "Authenticator" postfix from variants.
@@ -54,6 +72,7 @@ pub enum Compression {
 }
 
 impl Compression {
+    /// Returns the string representation of the compression algorithm.
     pub fn as_str(&self) -> &'static str {
         match self {
             Compression::Lz4 => "lz4",
@@ -89,11 +108,21 @@ impl Display for Compression {
     }
 }
 
+/// A serialized CQL request frame, nearly ready to be sent over the wire.
+///
+/// The only difference from a real frame is that it does not contain the stream number yet.
+/// The stream number is set by the `set_stream` method before sending.
 pub struct SerializedRequest {
     data: Vec<u8>,
 }
 
 impl SerializedRequest {
+    /// Creates a new serialized request frame from a request object.
+    ///
+    /// # Parameters
+    /// - `req`: The request object to serialize. Must implement `SerializableRequest`.
+    /// - `compression`: An optional compression algorithm to use for the request body.
+    /// - `tracing`: A boolean indicating whether to request tracing information in the response.
     pub fn make<R: SerializableRequest>(
         req: &R,
         compression: Option<Compression>,
@@ -125,20 +154,32 @@ impl SerializedRequest {
         Ok(Self { data })
     }
 
+    /// Sets the stream number for this request frame.
+    /// Intended to be called before sending the request,
+    /// once a stream ID has been assigned.
     pub fn set_stream(&mut self, stream: i16) {
         self.data[2..4].copy_from_slice(&stream.to_be_bytes());
     }
 
+    /// Returns the serialized frame data, including the header and body.
     pub fn get_data(&self) -> &[u8] {
         &self.data[..]
     }
 }
 
-// Parts of the frame header which are not determined by the request/response type.
+/// Parts of the frame header which are not determined by the request/response type.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 pub struct FrameParams {
+    /// The version of the frame protocol. Currently, only version 4 is supported.
+    /// The most significant bit (0x80) is treated specially:
+    /// it indicates whether the frame is from the client or server.
     pub version: u8,
+
+    /// Flags for the frame, indicating features like compression, tracing, etc.
     pub flags: u8,
+
+    /// The stream ID for this frame, which allows matching requests and responses
+    /// in a multiplexed connection.
     pub stream: i16,
 }
 
@@ -152,6 +193,8 @@ impl Default for FrameParams {
     }
 }
 
+/// Reads a response frame from the provided reader (usually, a socket).
+/// Then parses and validates the frame header and extracts the body.
 pub async fn read_response_frame(
     reader: &mut (impl AsyncRead + Unpin),
 ) -> Result<(FrameParams, ResponseOpcode, Bytes), FrameHeaderParseError> {
@@ -203,13 +246,29 @@ pub async fn read_response_frame(
     Ok((frame_params, opcode, raw_body.into_inner().into()))
 }
 
+/// Represents the already parsed response body extensions,
+/// including trace ID, warnings, and custom payload,
+/// and the remaining body raw data.
 pub struct ResponseBodyWithExtensions {
+    /// The trace ID if tracing was requested in the request.
+    ///
+    /// This can be used to issue a follow-up request to the server
+    /// to get detailed tracing information about the request.
     pub trace_id: Option<Uuid>,
+
+    /// Warnings returned by the server, if any.
     pub warnings: Vec<String>,
-    pub body: Bytes,
+
+    /// Custom payload (see [the CQL protocol description of the feature](https://github.com/apache/cassandra/blob/a39f3b066f010d465a1be1038d5e06f1e31b0391/doc/native_protocol_v4.spec#L276))
+    /// returned by the server, if any.
     pub custom_payload: Option<HashMap<String, Bytes>>,
+
+    /// The remaining body data after parsing the extensions.
+    pub body: Bytes,
 }
 
+/// Decompresses the response body if compression is enabled,
+/// and parses any extensions like trace ID, warnings, and custom payload.
 pub fn parse_response_body_extensions(
     flags: u8,
     compression: Option<Compression>,
@@ -260,11 +319,13 @@ pub fn parse_response_body_extensions(
     Ok(ResponseBodyWithExtensions {
         trace_id,
         warnings,
-        body,
         custom_payload,
+        body,
     })
 }
 
+/// Compresses the request body using the specified compression algorithm,
+/// appending the compressed data to the provided output buffer.
 pub fn compress_append(
     uncomp_body: &[u8],
     compression: Compression,
@@ -291,6 +352,8 @@ pub fn compress_append(
     }
 }
 
+/// Deompresses the response body using the specified compression algorithm
+/// and returns the decompressed data as an owned buffer.
 pub fn decompress(
     mut comp_body: &[u8],
     compression: Compression,

scylla-cql/src/frame/protocol_features.rs

@@ -1,22 +1,56 @@
+//! Implementation and negotiation of extensions to the CQL protocol.
+
 use std::borrow::Cow;
 use std::collections::HashMap;
 
 const RATE_LIMIT_ERROR_EXTENSION: &str = "SCYLLA_RATE_LIMIT_ERROR";
+/// The extension used to add metadata for LWT optimization.
+/// See [ProtocolFeatures::lwt_optimization_meta_bit_mask] and
+/// [related issue](https://github.com/scylladb/scylla-rust-driver/issues/100)
+/// for more details.
 pub const SCYLLA_LWT_ADD_METADATA_MARK_EXTENSION: &str = "SCYLLA_LWT_ADD_METADATA_MARK";
+/// The key of the single entry of the LWT optimization extension,
+/// which entry is a bit mask for the frame flags used to mark LWT frames.
 pub const LWT_OPTIMIZATION_META_BIT_MASK_KEY: &str = "LWT_OPTIMIZATION_META_BIT_MASK";
 const TABLETS_ROUTING_V1_KEY: &str = "TABLETS_ROUTING_V1";
 
+/// Which protocol extensions are supported by the server.
+///
+/// This is used to inform the server about the features that the client supports,
+/// so that the server can adjust its behavior accordingly.
+///
+/// So to draw the picture:
+/// - server responds to an `OPTIONS` frame with a `SUPPORTED` frame with the list of
+///   protocol features it supports;
+/// - client parses the `SUPPORTED` frame by extracting extensions it recognizes (supports)
+///   and creates a `ProtocolFeatures` instance;
+/// - from now on, client uses this instance to determine how to handle certain frames,
+///   e.g. whether to expect a rate limit error or how to handle LWT operations;
+/// - client also adds the features it supports to the `STARTUP` frame and sends it to
+///   the server, which finishes the extensions negotiation process.
 #[derive(Default, Clone, Copy, Debug, PartialEq, Eq)]
 #[non_exhaustive]
 pub struct ProtocolFeatures {
+    /// The error code to use for rate limit errors, if negotiated.
     pub rate_limit_error: Option<i32>,
+
+    /// The bit mask used for the LWT optimization, if negotiated.
+    /// This is used to mark PREPARED response frames as related to LWT operations
+    /// in order to to optimize the handling of LWT requests.
+    ///
+    /// The mask is ANDed with the flags of the PREPARED response frame,
+    /// and if the result is equal to the mask, it means that the frame is related
+    /// to an LWT operation.
     pub lwt_optimization_meta_bit_mask: Option<u32>,
+
+    /// Whether the server supports tablets routing v1.
     pub tablets_v1_supported: bool,
 }
 
 // TODO: Log information about options which failed to parse
 
 impl ProtocolFeatures {
+    /// Parses the supported protocol features from the `supported` map.
     pub fn parse_from_supported(supported: &HashMap<String, Vec<String>>) -> Self {
         Self {
             rate_limit_error: Self::maybe_parse_rate_limit_error(supported),
@@ -52,6 +86,7 @@ impl ProtocolFeatures {
             .find_map(|v| v.as_str().strip_prefix(key)?.strip_prefix('='))
     }
 
+    /// Adds the protocol features as STARTUP options.
     pub fn add_startup_options(&self, options: &mut HashMap<Cow<'_, str>, Cow<'_, str>>) {
         if self.rate_limit_error.is_some() {
             options.insert(Cow::Borrowed(RATE_LIMIT_ERROR_EXTENSION), Cow::Borrowed(""));
@@ -68,6 +103,9 @@ impl ProtocolFeatures {
         }
     }
 
+    /// Checks if the given flags of a PREPARED response contain the LWT optimization mark.
+    ///
+    /// If the extension was not negotiated, it conservatively returns `false`.
     pub fn prepared_flags_contain_lwt_mark(&self, flags: u32) -> bool {
         self.lwt_optimization_meta_bit_mask
             .map(|mask| (flags & mask) == mask)

scylla-cql/src/frame/request/auth_response.rs

@@ -1,3 +1,5 @@
+//! CQL protocol-level representation of a `AUTH_RESPONSE` request.
+
 use std::num::TryFromIntError;
 
 use thiserror::Error;
@@ -7,8 +9,11 @@ use crate::frame::frame_errors::CqlRequestSerializationError;
 use crate::frame::request::{RequestOpcode, SerializableRequest};
 use crate::frame::types::write_bytes_opt;
 
-// Implements Authenticate Response
+/// Represents AUTH_RESPONSE CQL request.
+///
+/// This request is sent by the client to respond to an authentication challenge.
 pub struct AuthResponse {
+    /// Raw response bytes.
     pub response: Option<Vec<u8>>,
 }