frame/request: document modules and items

Author: wprzytula

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>>,
 }
 

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

@@ -1,3 +1,5 @@
+//! CQL protocol-level representation of a `BATCH` request.
+
 use bytes::{Buf, BufMut};
 use std::{borrow::Cow, convert::TryInto, num::TryFromIntError};
 use thiserror::Error;
@@ -20,30 +22,56 @@ const FLAG_WITH_SERIAL_CONSISTENCY: u8 = 0x10;
 const FLAG_WITH_DEFAULT_TIMESTAMP: u8 = 0x20;
 const ALL_FLAGS: u8 = FLAG_WITH_SERIAL_CONSISTENCY | FLAG_WITH_DEFAULT_TIMESTAMP;
 
+/// CQL protocol-level representation of a `BATCH` request, used to execute
+/// a batch of statements (prepared, unprepared, or a mix of both).
 #[cfg_attr(test, derive(Debug, PartialEq, Eq))]
 pub struct Batch<'b, Statement, Values>
 where
     BatchStatement<'b>: From<&'b Statement>,
     Statement: Clone,
     Values: RawBatchValues,
 {
+    /// The statements in the batch.
     pub statements: Cow<'b, [Statement]>,
+
+    /// The type of the batch.
     pub batch_type: BatchType,
+
+    /// The consistency level for the batch.
     pub consistency: types::Consistency,
+
+    /// The serial consistency level for the batch, if any.
     pub serial_consistency: Option<types::SerialConsistency>,
+
+    /// The client-side-assigned timestamp for the batch, if any.
     pub timestamp: Option<i64>,
+
+    /// The bound values for the batch statements.
     pub values: Values,
 }
 
 /// The type of a batch.
 #[derive(Clone, Copy)]
 #[cfg_attr(test, derive(Debug, PartialEq, Eq))]
 pub enum BatchType {
+    /// By default, all operations in the batch are performed as logged, to ensure all mutations
+    /// eventually complete (or none will). See the notes on [UNLOGGED](BatchType::Unlogged) batches for more details.
+    /// A `LOGGED` batch to a single partition will be converted to an `UNLOGGED` batch as an optimization.
     Logged = 0,
+
+    /// By default, ScyllaDB uses a batch log to ensure all operations in a batch eventually complete or none will
+    /// (note, however, that operations are only isolated within a single partition).
+    /// There is a performance penalty for batch atomicity when a batch spans multiple partitions. If you do not want
+    /// to incur this penalty, you can tell Scylla to skip the batchlog with the `UNLOGGED` option. If the `UNLOGGED`
+    /// option is used, a failed batch might leave the batch only partly applied.
     Unlogged = 1,
+
+    /// Use the `COUNTER` option for batched counter updates. Unlike other updates in ScyllaDB, counter updates
+    /// are not idempotent.
     Counter = 2,
 }
 
+/// Encountered a malformed batch type.
 #[derive(Debug, Error)]
 #[error("Malformed batch type: {value}")]
 pub struct BatchTypeParseError {
@@ -63,10 +91,19 @@ impl TryFrom<u8> for BatchType {
     }
 }
 
+/// A single statement in a batch, which can either be a statement string or a prepared statement ID.
 #[derive(Debug, Clone, Eq, PartialEq, PartialOrd, Ord)]
 pub enum BatchStatement<'a> {
-    Query { text: Cow<'a, str> },
-    Prepared { id: Cow<'a, [u8]> },
+    /// Unprepared CQL statement.
+    Query {
+        /// CQL statement string.
+        text: Cow<'a, str>,
+    },
+    /// Prepared CQL statement.
+    Prepared {
+        /// Prepared CQL statement's ID.
+        id: Cow<'a, [u8]>,
+    },
 }
 
 impl<Statement, Values> Batch<'_, Statement, Values>

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

@@ -1,3 +1,5 @@
+//! CQL protocol-level representation of a `EXECUTE` request.
+
 use std::num::TryFromIntError;
 
 use crate::frame::frame_errors::CqlRequestSerializationError;
@@ -14,9 +16,14 @@ use super::{
     DeserializableRequest, RequestDeserializationError,
 };
 
+/// CQL protocol-level representation of an `EXECUTE` request,
+/// used to execute a single prepared statement.
 #[cfg_attr(test, derive(Debug, PartialEq, Eq))]
 pub struct Execute<'a> {
+    /// ID of the prepared statement to execute.
     pub id: Bytes,
+
+    /// Various parameters controlling the execution of the statement.
     pub parameters: query::QueryParameters<'a>,
 }
 

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

@@ -1,3 +1,5 @@
+//! CQL requests sent by the client.
+
 pub mod auth_response;
 pub mod batch;
 pub mod execute;
@@ -59,6 +61,7 @@ impl std::fmt::Display for CqlRequestKind {
     }
 }
 
+/// Opcode of a request, used to identify the request type in a CQL frame.
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord)]
 #[repr(u8)]
 pub enum RequestOpcode {
@@ -93,21 +96,28 @@ impl TryFrom<u8> for RequestOpcode {
     }
 }
 
+/// Requests that can be serialized into a CQL frame.
 pub trait SerializableRequest {
+    /// Opcode of the request, used to identify the request type in the CQL frame.
     const OPCODE: RequestOpcode;
 
+    /// Serializes the request into the provided buffer.
     fn serialize(&self, buf: &mut Vec<u8>) -> Result<(), CqlRequestSerializationError>;
 
+    /// Serializes the request into a heap-allocated `Bytes` object.
     fn to_bytes(&self) -> Result<Bytes, CqlRequestSerializationError> {
         let mut v = Vec::new();
         self.serialize(&mut v)?;
         Ok(v.into())
     }
 }
 
+/// Requests that can be deserialized from a CQL frame.
+///
 /// Not intended for driver's direct usage (as driver has no interest in deserialising CQL requests),
 /// but very useful for testing (e.g. asserting that the sent requests have proper parameters set).
 pub trait DeserializableRequest: SerializableRequest + Sized {
+    /// Deserializes the request from the provided buffer.
     fn deserialize(buf: &mut &[u8]) -> Result<Self, RequestDeserializationError>;
 }
 
@@ -133,14 +143,20 @@ pub enum RequestDeserializationError {
     UnexpectedBatchStatementKind(u8),
 }
 
+/// A CQL request that can be sent to the server.
 #[non_exhaustive] // TODO: add remaining request types
 pub enum Request<'r> {
+    /// QUERY request, used to execute a single unprepared statement.
     Query(Query<'r>),
+    /// EXECUTE request, used to execute a single prepared statement.
     Execute(Execute<'r>),
+    /// BATCH request, used to execute a batch of (prepared, unprepared, or mix of both)
+    /// statements.
     Batch(Batch<'r, BatchStatement<'r>, Vec<SerializedValues>>),
 }
 
 impl Request<'_> {
+    /// Deserializes the request from the provided buffer.
     pub fn deserialize(
         buf: &mut &[u8],
         opcode: RequestOpcode,

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

@@ -1,7 +1,11 @@
+//! CQL protocol-level representation of a `OPTIONS` request.
+
 use crate::frame::frame_errors::CqlRequestSerializationError;
 
 use crate::frame::request::{RequestOpcode, SerializableRequest};
 
+/// The CQL protocol-level representation of an `OPTIONS` request,
+/// used to retrieve the server's supported options.
 pub struct Options;
 
 impl SerializableRequest for Options {

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

@@ -1,3 +1,5 @@
+//! CQL protocol-level representation of a `PREPARE` request.
+
 use std::num::TryFromIntError;
 
 use thiserror::Error;
@@ -9,7 +11,10 @@ use crate::{
     frame::types,
 };
 
+/// CQL protocol-level representation of an `PREPARE` request,
+/// used to prepare a single statement for further execution.
 pub struct Prepare<'a> {
+    /// CQL statement string to prepare.
     pub query: &'a str,
 }
 

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

@@ -1,3 +1,5 @@
+//! CQL protocol-level representation of a `QUERY` request.
+
 use std::{borrow::Cow, num::TryFromIntError, ops::ControlFlow, sync::Arc};
 
 use crate::frame::{frame_errors::CqlRequestSerializationError, types::SerialConsistency};
@@ -28,9 +30,14 @@ const ALL_FLAGS: u8 = FLAG_VALUES
     | FLAG_WITH_DEFAULT_TIMESTAMP
     | FLAG_WITH_NAMES_FOR_VALUES;
 
+/// CQL protocol-level representation of an `QUERY` request,
+/// used to execute a single unprepared statement.
 #[cfg_attr(test, derive(Debug, PartialEq, Eq))]
 pub struct Query<'q> {
+    /// CQL statement string to execute.
     pub contents: Cow<'q, str>,
+
+    /// Various parameters controlling the execution of the statement.
     pub parameters: QueryParameters<'q>,
 }
 
@@ -59,14 +66,36 @@ impl DeserializableRequest for Query<'_> {
     }
 }
 
+/// Various parameters controlling the execution of the statement.
 #[cfg_attr(test, derive(Debug, PartialEq, Eq))]
 pub struct QueryParameters<'a> {
+    /// Consistency level for the query.
     pub consistency: types::Consistency,
+
+    /// Serial consistency level for the query, if specified.
     pub serial_consistency: Option<types::SerialConsistency>,
+
+    /// Client-side-assigned timestamp for the query, if specified.
     pub timestamp: Option<i64>,
+
+    /// Maximum number of rows to return for the query, if specified.
+    /// If not specified, the server will not page the result, and instead return all rows
+    /// in a single response. This is not recommended for large result sets, as it puts
+    /// a lot of pressure on the server and network, as well as brings high memory usage
+    /// on both client and server sides.
     pub page_size: Option<i32>,
+
+    /// Paging state for the query, used to resume fetching results from a previous query.
+    /// If empty paging state is provided, the query will start from the beginning.
     pub paging_state: PagingState,
+
+    /// Whether to skip metadata for the values in the result set.
+    /// This is an optimisation that can be used when the client does not need
+    /// the metadata for the values, because it has already been fetched upon
+    /// preparing the statement.
     pub skip_metadata: bool,
+
+    /// Values bound to the statements.
     pub values: Cow<'a, SerializedValues>,
 }
 
@@ -85,6 +114,7 @@ impl Default for QueryParameters<'_> {
 }
 
 impl QueryParameters<'_> {
+    /// Serializes the parameters into the provided buffer.
     pub fn serialize(
         &self,
         buf: &mut impl BufMut,
@@ -145,6 +175,7 @@ impl QueryParameters<'_> {
 }
 
 impl QueryParameters<'_> {
+    /// Deserializes the parameters from the provided buffer.
     pub fn deserialize(buf: &mut &[u8]) -> Result<Self, RequestDeserializationError> {
         let consistency = types::read_consistency(buf)?;
 
@@ -209,9 +240,19 @@ impl QueryParameters<'_> {
     }
 }
 
+/// A response containing the paging state of a paged query,
+/// i.e. whether there are more pages to fetch or not, and if so,
+/// what is the state to use for resuming the query from the next page.
 #[derive(Debug, Clone)]
 pub enum PagingStateResponse {
-    HasMorePages { state: PagingState },
+    /// Indicates that there are more pages to fetch, and provides the
+    /// [PagingState] to use for resuming the query from the next page.
+    HasMorePages {
+        /// The paging state to use for resuming the query from the next page.
+        state: PagingState,
+    },
+
+    /// Indicates that there are no more pages to fetch, and the query has finished.
     NoMorePages,
 }
 

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

@@ -1,3 +1,5 @@
+//! CQL protocol-level representation of a `REGISTER` request.
+
 use std::num::TryFromIntError;
 
 use thiserror::Error;
@@ -9,7 +11,10 @@ use crate::frame::{
     types,
 };
 
+/// The CQL protocol-level representation of an `REGISTER` request,
+/// used to subscribe for server events.
 pub struct Register {
+    /// A list of event types to register for.
     pub event_types_to_register_for: Vec<EventType>,
 }
 

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

@@ -1,3 +1,5 @@
+//! CQL protocol-level representation of a `STARTUP` request.
+
 use thiserror::Error;
 
 use crate::frame::frame_errors::CqlRequestSerializationError;
@@ -11,7 +13,10 @@ use crate::{
 
 use super::DeserializableRequest;
 
+/// The CQL protocol-level representation of an `STARTUP` request,
+/// used to finalise connection negotiation phase and establish the CQL connection.
 pub struct Startup<'a> {
+    /// The protocol options that were suggested by the server and accepted by the client.
     pub options: HashMap<Cow<'a, str>, Cow<'a, str>>,
 }