6.0.0 (#37)

* feat: encode integers without allocating
* feat: add int_as_blobstring options
* feat: add borrowed frame variants

Author: aembke

Cargo.toml

@@ -7,7 +7,7 @@ license = "MIT"
 name = "redis-protocol"
 readme = "README.md"
 repository = "https://github.com/aembke/redis-protocol.rs"
-version = "5.0.1"
+version = "6.0.0"
 edition = "2021"
 exclude = ["fuzz", ".circleci", "benches"]
 

README.md

@@ -30,9 +30,9 @@ use redis_protocol::resp2::{
 
 fn main() {
   let frame = Frame::BulkString("foobar".into());
-  let mut buf = vec![0; frame.encode_len()];
+  let mut buf = vec![0; frame.encode_len(false)];
 
-  let len = encode(&mut buf, &frame).expect("Error encoding frame");
+  let len = encode(&mut buf, &frame, false).expect("Error encoding frame");
   println!("Encoded {} bytes into buffer with contents {:?}", len, buf);
 
   // ["Foo", nil, "Bar"]
@@ -167,3 +167,62 @@ fn decode_borrowed(buf: &[u8]) -> Option<MyBorrowedFrame> {
   }
 }
 ```
+
+## Encoding
+
+Similar to the decoding interface, there are 3 frame types available to callers for encoding use cases.
+
+* `OwnedFrame` - See above. Callers that use this interface often have to allocate additional containers on the heap,
+  and often have to move or copy the contents into these frame types from other types, such as `RedisValue` in `fred`.
+* `BytesFrame` - See above. This frame type often avoids the need to copy or move the contents from upstream types such
+  as `RedisValue`, but still requires callers to allocate containers on the heap (i.e. the `Vec` in the `Array`
+  variant).
+* `BorrowedFrame` - This frame type serves a similar purpose to the `RangeFrame` type in the decoding interface in that
+  it can be used when callers want to entirely avoid heap allocations. In practice this often requires the caller to
+  create some intermediate reference-based types, but significantly outperforms other approaches that require
+  allocations.
+
+### Options
+
+All encoding interfaces expose an additional parameter, `int_as_bulkstring` for RESP2 or `int_as_blobstring` for RESP3,
+that can be used to encode integers as `BulkString` or `BlobString` using a more optimized code path that avoids heap
+allocations.
+
+In practice Redis expects all incoming frames to be an array of blob or bulk strings. This option can be used to
+automatically convert integers to byte arrays without additional allocations.
+
+### Buffer Management
+
+In some cases this library can automatically extend buffers while encoding. The `extend_encode_*` family of functions
+operate on `BytesMut` types and can automatically resize buffers while encoding, whereas the `encode_*` family of
+functions require the caller to allocate the correct amount beforehand.
+
+```rust
+use redis_protocol::resp2::{
+  encode,
+  types::{OwnedFrame, BytesFrame, BorrowedFrame, Resp2Frame}
+};
+use bytes::BytesMut;
+
+fn main() {
+  // using OwnedFrame variants, manually allocating the buffer
+  let frame = OwnedFrame::BulkString("foobar".into());
+  let mut buf = vec![0; frame.encode_len(false)];
+  let len = encode::encode(&mut buf, &frame, false).expect("Error encoding frame");
+  println!("Encoded {} bytes into buffer with contents {:?}", len, buf);
+
+  // using BytesFrame variants
+  let frame = BytesFrame::BulkString("foobar".into());
+  let mut buf = BytesMut::new();
+  let len = encode::extend_encode(&mut buf, &frame, false).expect("Error encoding frame");
+  println!("Encoded {} bytes into buffer with contents {:?}", len, buf);
+
+  // using BorrowedFrame variants
+  let value: String = "foobar".into();
+  let frame = BorrowedFrame::BulkString(value.as_bytes());
+  let mut buf = BytesMut::new();
+  let len = encode::extend_encode_borrowed(&mut buf, &frame, false).expect("Error encoding frame");
+  println!("Encoded {} bytes into buffer with contents {:?}", len, buf);
+}
+
+```

benches/resp2_decode.rs

@@ -10,7 +10,7 @@ use bytes::{BufMut, Bytes, BytesMut};
 
 #[cfg(feature = "bytes")]
 fn gen_bulkstring_bytes(len: usize, buf: Option<BytesMut>) -> BytesMut {
-  let digits = redis_protocol::digits_in_number(len);
+  let digits = redis_protocol::digits_in_usize(len);
   let mut v = buf.unwrap_or_else(|| BytesMut::with_capacity(1 + digits + 2 + len + 2));
 
   v.put_u8(b'$');
@@ -30,8 +30,8 @@ fn gen_null_bytes(buf: Option<BytesMut>) -> BytesMut {
 
 #[cfg(feature = "bytes")]
 fn gen_array_bytes(len: usize, null_every: usize, str_len: usize) -> BytesMut {
-  let arr_len_digits = redis_protocol::digits_in_number(len);
-  let str_len_digits = redis_protocol::digits_in_number(str_len);
+  let arr_len_digits = redis_protocol::digits_in_usize(len);
+  let str_len_digits = redis_protocol::digits_in_usize(str_len);
   let buf = BytesMut::with_capacity(1 + arr_len_digits + 2 + (len * (1 + str_len_digits + 2 + str_len + 2)));
 
   (0 .. len).fold(buf, |buf, i| {
@@ -44,7 +44,7 @@ fn gen_array_bytes(len: usize, null_every: usize, str_len: usize) -> BytesMut {
 }
 
 fn gen_bulkstring_owned(len: usize, buf: Option<Vec<u8>>) -> Vec<u8> {
-  let digits = redis_protocol::digits_in_number(len);
+  let digits = redis_protocol::digits_in_usize(len);
   let mut v = buf.unwrap_or_else(|| Vec::with_capacity(1 + digits + 2 + len + 2));
 
   v.push(b'$');
@@ -62,8 +62,8 @@ fn gen_null_owned(buf: Option<Vec<u8>>) -> Vec<u8> {
 }
 
 fn gen_array_owned(len: usize, null_every: usize, str_len: usize) -> Vec<u8> {
-  let arr_len_digits = redis_protocol::digits_in_number(len);
-  let str_len_digits = redis_protocol::digits_in_number(str_len);
+  let arr_len_digits = redis_protocol::digits_in_usize(len);
+  let str_len_digits = redis_protocol::digits_in_usize(str_len);
   let buf = Vec::with_capacity(1 + arr_len_digits + 2 + (len * (1 + str_len_digits + 2 + str_len + 2)));
 
   (0 .. len).fold(buf, |buf, i| {

src/codec.rs

@@ -4,8 +4,8 @@ mod resp3 {
     error::{RedisProtocolError, RedisProtocolErrorKind},
     resp3::{
       decode::streaming::decode_bytes_mut as resp3_decode,
-      encode::complete::extend_encode as resp3_encode,
-      types::{BytesFrame as Resp3Frame, StreamedFrame},
+      encode::complete::{extend_encode as resp3_encode, extend_encode_borrowed as resp3_encode_borrowed},
+      types::{BorrowedFrame, BytesFrame as Resp3Frame, StreamedFrame},
     },
   };
   use bytes::BytesMut;
@@ -40,10 +40,10 @@ mod resp3 {
   ///   let socket = TcpStream::connect("127.0.0.1:6379").await.unwrap();
   ///   let mut framed = Framed::new(socket, Resp3::default());
   ///
-  ///   let hello = Resp3Frame::Hello {
-  ///     version:  RespVersion::RESP3,
-  ///     username: Some("foo".into()),
-  ///     password: Some("bar".into()),
+  ///   let hello = BytesFrame::Hello {
+  ///     version: RespVersion::RESP3,
+  ///     auth:    Some(("foo".into(), "bar".into())),
+  ///     setname: None,
   ///   };
   ///   // or use the shorthand, but this likely only works for simple use cases
   ///   let get_foo = resp3_encode_command("GET foo");
@@ -60,14 +60,38 @@ mod resp3 {
   /// ```
   #[derive(Debug, Default)]
   pub struct Resp3 {
-    streaming: Option<StreamedFrame<Resp3Frame>>,
+    streaming:         Option<StreamedFrame<Resp3Frame>>,
+    int_as_blobstring: bool,
+  }
+
+  impl Resp3 {
+    /// Create a new codec with the provided flag describing whether the encoder logic should send integers as blob
+    /// strings.
+    pub fn new(int_as_blobstring: bool) -> Resp3 {
+      Resp3 {
+        int_as_blobstring,
+        streaming: None,
+      }
+    }
   }
 
   impl Encoder<Resp3Frame> for Resp3 {
     type Error = RedisProtocolError;
 
     fn encode(&mut self, item: Resp3Frame, dst: &mut BytesMut) -> Result<(), Self::Error> {
-      resp3_encode(dst, &item).map(|_| ()).map_err(RedisProtocolError::from)
+      resp3_encode(dst, &item, self.int_as_blobstring)
+        .map(|_| ())
+        .map_err(RedisProtocolError::from)
+    }
+  }
+
+  impl Encoder<BorrowedFrame<'_>> for Resp3 {
+    type Error = RedisProtocolError;
+
+    fn encode(&mut self, item: BorrowedFrame, dst: &mut BytesMut) -> Result<(), Self::Error> {
+      resp3_encode_borrowed(dst, &item, self.int_as_blobstring)
+        .map(|_| ())
+        .map_err(RedisProtocolError::from)
     }
   }
 
@@ -125,8 +149,8 @@ mod resp2 {
     error::RedisProtocolError,
     resp2::{
       decode::decode_bytes_mut as resp2_decode,
-      encode::extend_encode as resp2_encode,
-      types::BytesFrame as Resp2Frame,
+      encode::{extend_encode as resp2_encode, extend_encode_borrowed as resp2_encode_borrowed},
+      types::{BorrowedFrame, BytesFrame as Resp2Frame},
     },
   };
   use bytes::BytesMut;
@@ -169,13 +193,35 @@ mod resp2 {
   /// }
   /// ```
   #[derive(Clone, Debug, Default)]
-  pub struct Resp2;
+  pub struct Resp2 {
+    int_as_bulkstring: bool,
+  }
+
+  impl Resp2 {
+    /// Create a new codec with the provided flag describing whether the encoder logic should send integers as blob
+    /// strings.
+    pub fn new(int_as_bulkstring: bool) -> Resp2 {
+      Resp2 { int_as_bulkstring }
+    }
+  }
 
   impl Encoder<Resp2Frame> for Resp2 {
     type Error = RedisProtocolError;
 
     fn encode(&mut self, item: Resp2Frame, dst: &mut BytesMut) -> Result<(), Self::Error> {
-      resp2_encode(dst, &item).map(|_| ()).map_err(RedisProtocolError::from)
+      resp2_encode(dst, &item, self.int_as_bulkstring)
+        .map(|_| ())
+        .map_err(RedisProtocolError::from)
+    }
+  }
+
+  impl Encoder<BorrowedFrame<'_>> for Resp2 {
+    type Error = RedisProtocolError;
+
+    fn encode(&mut self, item: BorrowedFrame, dst: &mut BytesMut) -> Result<(), Self::Error> {
+      resp2_encode_borrowed(dst, &item, self.int_as_bulkstring)
+        .map(|_| ())
+        .map_err(RedisProtocolError::from)
     }
   }