Token: add constructor and normalization

`i64::MIN` turns out to be an invalid value for a token:
https://github.com/scylladb/scylladb/blob/4be70bfc2bc7f133cab492b4aac7bab9c790a48c/dht/token.hh#L32
Hashing algorithm should change `i64::MIN` result to `i64::MAX`.
In order to have this check in one place and make sure we always perform
it I made `value` field of `Token` non-public and created constructor and
getter for it.

Author: Lorak-mmk

examples/compare-tokens.rs

@@ -33,13 +33,13 @@ async fn main() -> Result<()> {
             )
             .await?;
 
-        let t = prepared.calculate_token(&(pk,))?.unwrap().value;
+        let t = prepared.calculate_token(&(pk,))?.unwrap().value();
 
         println!(
             "Token endpoints for query: {:?}",
             session
                 .get_cluster_data()
-                .get_token_endpoints("examples_ks", Token { value: t })
+                .get_token_endpoints("examples_ks", Token::new(t))
                 .iter()
                 .map(|(node, _shard)| node.address)
                 .collect::<Vec<NodeAddr>>()

scylla/src/routing.rs

@@ -5,8 +5,42 @@ use std::num::NonZeroU16;
 use thiserror::Error;
 
 #[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Debug)]
+
+/// Token is a result of computing a hash of a primary key
+///
+/// It is basically an i64 with one caveat: i64::MIN is not
+/// a valid token. It is used to represent infinity.
+/// For this reason tokens are normalized - i64::MIN
+/// is replaced with i64::MAX. See this fragment of
+/// Scylla code for more information:
+/// <https://github.com/scylladb/scylladb/blob/4be70bfc2bc7f133cab492b4aac7bab9c790a48c/dht/token.hh#L32>
+///
+/// This struct is a wrapper over i64 that performs this normalization
+/// when initialized using `new()` method.
 pub struct Token {
-    pub value: i64,
+    value: i64,
+}
+
+impl Token {
+    /// Creates a new token with given value, normalizing the value if necessary
+    #[inline]
+    pub fn new(value: i64) -> Self {
+        Self {
+            value: if value == i64::MIN { i64::MAX } else { value },
+        }
+    }
+
+    /// Invalid Token - contains i64::MIN as value.
+    ///
+    /// This is (currently) only required by CDCPartitioner.
+    /// See the following comment:
+    /// https://github.com/scylladb/scylla-rust-driver/blob/049dc3546d24e45106fed0fdb985ec2511ab5192/scylla/src/transport/partitioner.rs#L312-L322
+    pub(crate) const INVALID: Self = Token { value: i64::MIN };
+
+    #[inline]
+    pub fn value(&self) -> i64 {
+        self.value
+    }
 }
 
 pub type Shard = u32;