codewide: deprecate legacy serialization API's items

Items constituting the legacy serialization API hadn't been marked with the #[deprecated] attribute. As we're going to remove them soon, let's warn users about that explicitly.
scylladb · Dec 9, 2024 · da6102a · da6102a
1 parent 8f5eb2f
commit da6102a
Show file tree

Hide file tree

Showing 9 changed files with 203 additions and 2 deletions.
diff --git a/scylla-cql/src/frame/response/result.rs b/scylla-cql/src/frame/response/result.rs
@@ -2475,6 +2475,7 @@ mod tests {
         );
     }
 
+    #[allow(deprecated)]
     #[test]
     fn test_serialize_empty() {
         use crate::frame::value::Value;

diff --git a/scylla-cql/src/frame/value.rs b/scylla-cql/src/frame/value.rs
@@ -14,12 +14,17 @@ use super::types::RawValue;
 
 #[derive(Debug, Error, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 #[error("Value too big to be sent in a request - max 2GiB allowed")]
+#[deprecated(
+    since = "0.15.1",
+    note = "Legacy serialization API is not type-safe and is going to be removed soon"
+)]
 pub struct ValueTooBig;
 
 #[derive(Debug, Error, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 #[error("Value is too large to fit in the CQL type")]
 pub struct ValueOverflow;
 
+#[allow(deprecated)]
 #[derive(Debug, Error, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub enum SerializeValuesError {
     #[error("Too many values to add, max 65,535 values can be sent in a request")]
@@ -664,11 +669,21 @@ pub struct CqlDuration {
     pub nanoseconds: i64,
 }
 
+#[deprecated(
+    since = "0.15.1",
+    note = "Legacy serialization API is not type-safe and is going to be removed soon"
+)]
 mod legacy {
+    #![allow(deprecated)]
+
     use super::*;
 
     /// Every value being sent in a query must implement this trait
     /// serialize() should write the Value as [bytes] to the provided buffer
+    #[deprecated(
+        since = "0.15.1",
+        note = "Legacy serialization API is not type-safe and is going to be removed soon"
+    )]
     pub trait Value {
         fn serialize(&self, buf: &mut Vec<u8>) -> Result<(), ValueTooBig>;
     }
@@ -682,10 +697,18 @@ mod legacy {
         contains_names: bool,
     }
 
+    #[deprecated(
+        since = "0.15.1",
+        note = "Legacy serialization API is not type-safe and is going to be removed soon"
+    )]
     pub type SerializedResult<'a> = Result<Cow<'a, LegacySerializedValues>, SerializeValuesError>;
 
     /// Represents list of values to be sent in a query
     /// gets serialized and but into request
+    #[deprecated(
+        since = "0.15.1",
+        note = "Legacy serialization API is not type-safe and is going to be removed soon"
+    )]
     pub trait ValueList {
         /// Provides a view of ValueList as LegacySerializedValues
         /// returns `Cow<LegacySerializedValues>` to make impl ValueList for LegacySerializedValues efficient
@@ -707,6 +730,10 @@ mod legacy {
 
     impl LegacySerializedValues {
         /// Creates empty value list
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         pub const fn new() -> Self {
             LegacySerializedValues {
                 serialized_values: Vec::new(),
@@ -715,6 +742,10 @@ mod legacy {
             }
         }
 
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         pub fn with_capacity(capacity: usize) -> Self {
             LegacySerializedValues {
                 serialized_values: Vec::with_capacity(capacity),
@@ -723,14 +754,26 @@ mod legacy {
             }
         }
 
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         pub fn has_names(&self) -> bool {
             self.contains_names
         }
 
         /// A const empty instance, useful for taking references
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         pub const EMPTY: &'static LegacySerializedValues = &LegacySerializedValues::new();
 
         /// Serializes value and appends it to the list
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         pub fn add_value(&mut self, val: &impl Value) -> Result<(), SerializeValuesError> {
             if self.contains_names {
                 return Err(SerializeValuesError::MixingNamedAndNotNamedValues);
@@ -750,6 +793,10 @@ mod legacy {
             Ok(())
         }
 
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         pub fn add_named_value(
             &mut self,
             name: &str,
@@ -777,30 +824,54 @@ mod legacy {
             Ok(())
         }
 
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         pub fn iter(&self) -> impl Iterator<Item = RawValue> {
             LegacySerializedValuesIterator {
                 serialized_values: &self.serialized_values,
                 contains_names: self.contains_names,
             }
         }
 
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         pub fn write_to_request(&self, buf: &mut impl BufMut) {
             buf.put_u16(self.values_num);
             buf.put(&self.serialized_values[..]);
         }
 
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         pub fn is_empty(&self) -> bool {
             self.values_num == 0
         }
 
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         pub fn len(&self) -> u16 {
             self.values_num
         }
 
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         pub fn size(&self) -> usize {
             self.serialized_values.len()
         }
 
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         pub fn iter_name_value_pairs(&self) -> impl Iterator<Item = (Option<&str>, RawValue)> {
             let mut buf = &self.serialized_values[..];
             (0..self.values_num).map(move |_| {
@@ -815,6 +886,10 @@ mod legacy {
         }
     }
 
+    #[deprecated(
+        since = "0.15.1",
+        note = "Legacy serialization API is not type-safe and is going to be removed soon"
+    )]
     #[derive(Clone, Copy)]
     pub struct LegacySerializedValuesIterator<'a> {
         serialized_values: &'a [u8],
@@ -839,6 +914,10 @@ mod legacy {
         }
     }
 
+    #[deprecated(
+        since = "0.15.1",
+        note = "Legacy serialization API is not type-safe and is going to be removed soon"
+    )]
     /// Represents List of ValueList for Batch statement
     pub trait LegacyBatchValues {
         /// For some unknown reason, this type, when not resolved to a concrete type for a given async function,
@@ -859,13 +938,36 @@ mod legacy {
     /// It's just essentially making methods from `ValueList` accessible instead of being an actual iterator because of
     /// compiler limitations that would otherwise be very complex to overcome.
     /// (specifically, types being different would require yielding enums for tuple impls)
+    #[deprecated(
+        since = "0.15.1",
+        note = "Legacy serialization API is not type-safe and is going to be removed soon"
+    )]
     pub trait LegacyBatchValuesIterator<'a> {
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         fn next_serialized(&mut self) -> Option<SerializedResult<'a>>;
+
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         fn write_next_to_request(
             &mut self,
             buf: &mut impl BufMut,
         ) -> Option<Result<(), SerializeValuesError>>;
+
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         fn skip_next(&mut self) -> Option<()>;
+
+        #[deprecated(
+            since = "0.15.1",
+            note = "Legacy serialization API is not type-safe and is going to be removed soon"
+        )]
         fn count(mut self) -> usize
         where
             Self: Sized,
@@ -882,6 +984,10 @@ mod legacy {
     ///
     /// Essentially used internally by this lib to provide implementers of `BatchValuesIterator` for cases
     /// that always serialize the same concrete `ValueList` type
+    #[deprecated(
+        since = "0.15.1",
+        note = "Legacy serialization API is not type-safe and is going to be removed soon"
+    )]
     pub struct LegacyBatchValuesIteratorFromIterator<IT: Iterator> {
         it: IT,
     }
@@ -1634,6 +1740,10 @@ mod legacy {
     /// The underlying iterator will always be cloned at least once, once to compute the length if it can't be known
     /// in advance, and be re-cloned at every retry.
     /// It is consequently expected that the provided iterator is cheap to clone (e.g. `slice.iter().map(...)`).
+    #[deprecated(
+        since = "0.15.1",
+        note = "Legacy serialization API is not type-safe and is going to be removed soon"
+    )]
     pub struct LegacyBatchValuesFromIter<'a, IT> {
         it: IT,
         _spooky: std::marker::PhantomData<&'a ()>,
@@ -1710,6 +1820,10 @@ mod legacy {
         }
     }
 
+    #[deprecated(
+        since = "0.15.1",
+        note = "Legacy serialization API is not type-safe and is going to be removed soon"
+    )]
     pub struct TupleValuesIter<'a, T> {
         tuple: &'a T,
         idx: usize,
@@ -1808,6 +1922,10 @@ mod legacy {
     /// Once that is done, we can use that instead of re-serializing.
     ///
     /// This struct implements both `BatchValues` and `BatchValuesIterator` for that purpose
+    #[deprecated(
+        since = "0.15.1",
+        note = "Legacy serialization API is not type-safe and is going to be removed soon"
+    )]
     pub struct LegacyBatchValuesFirstSerialized<'f, T> {
         first: Option<&'f LegacySerializedValues>,
         rest: T,
@@ -1872,6 +1990,7 @@ mod legacy {
         }
     }
 }
+#[allow(deprecated)]
 pub use legacy::{
     LegacyBatchValues, LegacyBatchValuesFirstSerialized, LegacyBatchValuesFromIter,
     LegacyBatchValuesIterator, LegacyBatchValuesIteratorFromIterator, LegacySerializedValues,

diff --git a/scylla-cql/src/frame/value_tests.rs b/scylla-cql/src/frame/value_tests.rs
@@ -1,3 +1,6 @@
+// TODO: remove this once deprecated items are deleted.
+#![allow(deprecated)]
+
 use crate::frame::value::{CqlTimeuuid, CqlVarint};
 use crate::frame::{response::result::CqlValue, types::RawValue, value::LegacyBatchValuesIterator};
 use crate::types::serialize::batch::{BatchValues, BatchValuesIterator, LegacyBatchValuesAdapter};

diff --git a/scylla-cql/src/lib.rs b/scylla-cql/src/lib.rs
@@ -16,7 +16,9 @@ pub mod macros {
     #[allow(deprecated)]
     pub use crate::impl_from_cql_value_from_method;
 
+    #[allow(deprecated)]
     pub use crate::impl_serialize_row_via_value_list;
+    #[allow(deprecated)]
     pub use crate::impl_serialize_value_via_value;
 }
 
@@ -35,6 +37,7 @@ pub mod _macro_internal {
         FromCqlVal, FromCqlValError, FromRow, FromRowError,
     };
     pub use crate::frame::response::result::{ColumnSpec, ColumnType, CqlValue, Row};
+    #[allow(deprecated)]
     pub use crate::frame::value::{
         LegacySerializedValues, SerializedResult, Value, ValueList, ValueTooBig,
     };

diff --git a/scylla-cql/src/types/serialize/batch.rs b/scylla-cql/src/types/serialize/batch.rs
@@ -4,6 +4,7 @@
 // Note: When editing above doc-comment edit the corresponding comment on
 // re-export module in scylla crate too.
 
+#[allow(deprecated)]
 use crate::frame::value::{LegacyBatchValues, LegacyBatchValuesIterator};
 
 use super::row::{RowSerializationContext, SerializeRow};
@@ -332,8 +333,13 @@ impl<T: BatchValues + ?Sized> BatchValues for &T {
 /// Note that the [`LegacyBatchValues`] trait is deprecated and will be
 /// removed in the future, and you should prefer using [`BatchValues`] as it is
 /// more type-safe.
+#[deprecated(
+    since = "0.15.1",
+    note = "Legacy serialization API is not type-safe and is going to be removed soon"
+)]
 pub struct LegacyBatchValuesAdapter<T>(pub T);
 
+#[allow(deprecated)]
 impl<T> BatchValues for LegacyBatchValuesAdapter<T>
 where
     T: LegacyBatchValues,
@@ -351,8 +357,13 @@ where
 
 /// A newtype wrapper which adjusts an existing types that implement
 /// [`LegacyBatchValuesIterator`] to the current [`BatchValuesIterator`] API.
+#[deprecated(
+    since = "0.15.1",
+    note = "Legacy serialization API is not type-safe and is going to be removed soon"
+)]
 pub struct LegacyBatchValuesIteratorAdapter<T>(pub T);
 
+#[allow(deprecated)]
 impl<'r, T> BatchValuesIterator<'r> for LegacyBatchValuesIteratorAdapter<T>
 where
     T: LegacyBatchValuesIterator<'r>,
-Original file line number
+Diff line change
@@ Expand Up / @@ -2475,6 +2475,7 @@ mod tests { @@
             );
         }
+        #[allow(deprecated)]
         #[test]
         fn test_serialize_empty() {
             use crate::frame::value::Value;
@@ Expand Down @@