feat(cachet): add serialization support with PostcardEncoder/PostcardCodec

.spelling

@@ -31,6 +31,7 @@ Barbosa
 Base64-encoded
 bitflag
 bitwise
+bincode
 bool
 branch_name
 btree_map
@@ -327,6 +328,7 @@ uncategorized
 unconfigured
 Multithreaded
 uncontended
+undecodable
 unhandleable
 unicode
 uniflight

Cargo.toml

@@ -97,6 +97,7 @@ parking_lot = { version = "0.12.5", default-features = false }
 pct-str = { version = "3.0.1", default-features = false }
 pin-project = { version = "1.1.8", default-features = false }
 pin-project-lite = { version = "0.2.13", default-features = false }
+postcard = { version = "1.1.3", default-features = false, features = ["use-std"] }
 pretty_assertions = { version = "1.4.1", default-features = false }
 prettyplease = { version = "0.2.37", default-features = false }
 proc-macro2 = { version = "1.0.103", default-features = false }

crates/bytesbuf/src/view.rs

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+use std::hash::{Hash, Hasher};
 use std::iter;
 use std::num::NonZero;
 use std::ops::{Bound, RangeBounds};
@@ -864,6 +865,24 @@ impl<const LEN: usize> PartialEq<BytesView> for &[u8; LEN] {
 
 impl Eq for BytesView {}
 
+impl Hash for BytesView {
+    fn hash<H: Hasher>(&self, state: &mut H) {
+        // Hash all bytes in logical order, consistent with PartialEq.
+        // We also hash the cached length as an additional input, but equality and hashing are
+        // both defined by the logical byte sequence rather than how it is segmented into spans.
+        //
+        // We iterate over spans_reversed using an index to avoid cloning the view,
+        // which would increment atomic reference counts for every span.
+        self.len.hash(state);
+        let mut span_idx = self.spans_reversed.len();
+        while span_idx > 0 {
+            span_idx -= 1;
+            let span: &[u8] = &self.spans_reversed[span_idx];
+            state.write(span);
+        }
+    }
+}
+
 /// Iterator over the slices of a [`BytesView`] and their metadata.
 ///
 /// Returned by [`BytesView::slices()`] and provides each slice together with its
@@ -1713,4 +1732,55 @@ mod tests {
         // We assume 64-bit pointers - any support for 32-bit is problem for the future.
         assert_eq!(size_of::<BytesView>(), 272);
     }
+
+    #[test]
+    fn hash_equal_views_produce_same_hash() {
+        use std::hash::{DefaultHasher, Hash, Hasher};
+
+        let a = BytesView::from(vec![1, 2, 3, 4, 5]);
+        let b = BytesView::from(vec![1, 2, 3, 4, 5]);
+
+        let hash_of = |v: &BytesView| {
+            let mut h = DefaultHasher::new();
+            v.hash(&mut h);
+            h.finish()
+        };
+
+        assert_eq!(hash_of(&a), hash_of(&b));
+    }
+
+    #[test]
+    fn hash_multi_span_matches_single_span() {
+        use std::hash::{DefaultHasher, Hash, Hasher};
+
+        let single = BytesView::from(vec![1, 2, 3, 4, 5, 6]);
+
+        let mut multi = BytesView::from(vec![1, 2, 3]);
+        multi.append(BytesView::from(vec![4, 5, 6]));
+
+        let hash_of = |v: &BytesView| {
+            let mut h = DefaultHasher::new();
+            v.hash(&mut h);
+            h.finish()
+        };
+
+        assert_eq!(single, multi);
+        assert_eq!(hash_of(&single), hash_of(&multi));
+    }
+
+    #[test]
+    fn hash_different_views_produce_different_hash() {
+        use std::hash::{DefaultHasher, Hash, Hasher};
+
+        let a = BytesView::from(vec![1, 2, 3]);
+        let b = BytesView::from(vec![4, 5, 6]);
+
+        let hash_of = |v: &BytesView| {
+            let mut h = DefaultHasher::new();
+            v.hash(&mut h);
+            h.finish()
+        };
+
+        assert_ne!(hash_of(&a), hash_of(&b));
+    }
 }

crates/cachet/Cargo.toml

@@ -23,14 +23,16 @@ all-features = true
 allowed_external_types = [
     # Workspace sibling crates
     "anyspawn::spawner::Spawner",
+    "bytesbuf::view::BytesView",
     "cachet_memory::*",
     "cachet_service::*",
     "cachet_tier::*",
     "layered::service::Service",
     "tick::clock::Clock",
     # External dependencies
-    "opentelemetry::metrics::meter::Meter",
     "opentelemetry::metrics::meter::MeterProvider",
+    "serde_core::de::DeserializeOwned",
+    "serde_core::ser::Serialize",
 ]
 
 [features]
@@ -40,9 +42,12 @@ test-util = ["cachet_tier/test-util", "tick/test-util"]
 memory = ["dep:cachet_memory"]
 metrics = ["dep:opentelemetry", "opentelemetry/metrics"]
 service = ["dep:cachet_service", "dep:layered"]
+serialize = ["dep:serde", "dep:postcard", "dep:bytesbuf"]
+telemetry = []
 
 [dependencies]
 anyspawn = { workspace = true, features = ["tokio"] }
+bytesbuf = { workspace = true, optional = true }
 cachet_memory = { workspace = true, optional = true }
 cachet_service = { workspace = true, optional = true }
 cachet_tier = { workspace = true }
@@ -52,13 +57,17 @@ ohno = { workspace = true }
 opentelemetry = { workspace = true, optional = true }
 parking_lot = { workspace = true }
 pin-project-lite = { workspace = true }
+postcard = { workspace = true, optional = true }
+serde = { workspace = true, optional = true, features = ["derive"] }
 thread_aware = { workspace = true }
 tick = { workspace = true, features = [] }
 tracing = { workspace = true, optional = true }
 uniflight = { workspace = true }
 
 [dev-dependencies]
 alloc_tracker = { workspace = true }
+bytesbuf = { workspace = true }
+cachet_memory = { workspace = true }
 cachet_tier = { workspace = true, features = ["test-util"] }
 criterion = { workspace = true }
 dynosaur = { workspace = true }
@@ -67,8 +76,10 @@ opentelemetry = { workspace = true, features = [
     "logs",
 ] }
 opentelemetry_sdk = { workspace = true, features = ["logs", "testing"] }
+postcard = { workspace = true }
 recoverable = { workspace = true }
 seatbelt = { path = "../seatbelt", features = ["retry", "tower-service"] }
+serde = { workspace = true, features = ["derive"] }
 testing_aids = { path = "../testing_aids" }
 tick = { workspace = true, features = ["test-util", "tokio"] }
 tokio = { workspace = true, features = ["macros", "rt-multi-thread"] }
@@ -143,5 +154,9 @@ required-features = ["memory", "service"]
 name = "type_mapping"
 required-features = ["memory", "test-util"]
 
+[[example]]
+name = "serialization"
+required-features = ["memory", "serialize"]
+
 [lints]
 workspace = true

crates/cachet/README.md

@@ -165,6 +165,7 @@ most commonly used types from all of them.
 |`metrics`|❌|Enables OpenTelemetry metrics (`cache.event.count`, `cache.operation.duration`, `cache.size`).|
 |`logs`|❌|Enables structured `tracing` log events for every cache activity.|
 |`service`|❌|Enables `ServiceAdapter`, `CacheServiceExt`, and `CacheOperation`/`CacheResponse` types for service middleware integration.|
+|`serialize`|❌|Enables `.serialize()` on builders for automatic postcard serialization of keys and values to `BytesView`.|
 |`test-util`|❌|Enables `MockCache`, frozen-clock utilities, and other test helpers.|
 
 ## Examples
@@ -201,6 +202,31 @@ let cache = Cache::builder::<String, String>(clock)
     .build();
 ```
 
+### Serialization Boundary
+
+When a fallback tier operates on serialized bytes (e.g., Redis), use `.serialize()`
+to add a postcard serialization boundary. Keys and values are automatically serialized
+to [`BytesView`][__link18] before reaching the fallback tier, and
+deserialized on the way back.
+
+```rust
+use cachet::{Cache, FallbackPromotionPolicy};
+use tick::Clock;
+
+let clock = Clock::new_tokio();
+let remote = Cache::builder::<bytesbuf::BytesView, bytesbuf::BytesView>(clock.clone()).memory();
+
+let cache = Cache::builder::<String, String>(clock)
+    .memory()
+    .serialize()
+    .fallback(remote)
+    .promotion_policy(FallbackPromotionPolicy::always())
+    .build();
+
+// Keys and values are String on the outside, BytesView in the fallback tier.
+cache.insert("key".to_string(), "value".to_string()).await?;
+```
+
 ## Telemetry
 
 Enable with `metrics` and/or `logs` features. Configure via `.enable_metrics()` and `.enable_logs()`.
@@ -238,7 +264,7 @@ Event name: `cache.event` with fields `cache.name`, `cache.operation`,
 This crate was developed as part of <a href="../..">The Oxidizer Project</a>. Browse this crate's <a href="https://github.com/microsoft/oxidizer/tree/main/crates/cachet">source code</a>.
 </sub>
 
- [__cargo_doc2readme_dependencies_info]: ggGkYW0CYXSEGy4k8ldDFPOhG2VNeXtD5nnKG6EPY6OfW5wBG8g18NOFNdxpYXKEG8FPUL0qKt72Gy-GD_CgRPCCG9SaPObQ7vYiG4uWqBhKhhTAYWSGgmZjYWNoZXRlMC4yLjCCbWNhY2hldF9tZW1vcnllMC4xLjCCbmNhY2hldF9zZXJ2aWNlZTAuMS4wgmtjYWNoZXRfdGllcmUwLjEuMIJkdGlja2UwLjMuMIJpdW5pZmxpZ2h0ZTAuMS4w
+ [__cargo_doc2readme_dependencies_info]: ggGkYW0CYXSEGy4k8ldDFPOhG2VNeXtD5nnKG6EPY6OfW5wBG8g18NOFNdxpYXKEG1DRY_ouWcOzG58PK1HRUDW5G5JDU0oAlprIG37b8vyW3Z6AYWSHgmhieXRlc2J1ZmUwLjQuMoJmY2FjaGV0ZTAuMi4wgm1jYWNoZXRfbWVtb3J5ZTAuMS4wgm5jYWNoZXRfc2VydmljZWUwLjEuMIJrY2FjaGV0X3RpZXJlMC4xLjCCZHRpY2tlMC4zLjCCaXVuaWZsaWdodGUwLjEuMA
  [__link0]: https://docs.rs/cachet/0.2.0/cachet/?search=TimeToRefresh
  [__link1]: https://crates.io/crates/uniflight/0.1.0
  [__link10]: https://docs.rs/cachet_tier/0.1.0/cachet_tier/?search=CacheTier
@@ -249,6 +275,7 @@ This crate was developed as part of <a href="../..">The Oxidizer Project</a>. Br
  [__link15]: https://crates.io/crates/cachet_memory/0.1.0
  [__link16]: https://docs.rs/moka
  [__link17]: https://crates.io/crates/cachet_service/0.1.0
+ [__link18]: https://docs.rs/bytesbuf/0.4.2/bytesbuf/?search=BytesView
  [__link2]: https://docs.rs/cachet/0.2.0/cachet/?search=CacheBuilder::stampede_protection
  [__link3]: https://docs.rs/cachet_tier/0.1.0/cachet_tier/?search=CacheTier
  [__link4]: https://docs.rs/cachet_tier/0.1.0/cachet_tier/?search=DynamicCache