From 9220f03f3b4d76a002370f72d383039cb5e4eb11 Mon Sep 17 00:00:00 2001
From: Matthew Jackson <1085847+MattJackson@users.noreply.github.com>
Date: Tue, 23 Jun 2026 05:27:01 -0700
Subject: [PATCH] keydb: correct read_capped_to_string doc for non-UTF-8 case

The doc claimed Error::KeydbInvalid for non-UTF-8 input, but the code
returns Error::KeydbParse (KeydbInvalid is reserved for the size-cap
violation). Correct the doc to match behavior and add a regression test
asserting non-UTF-8 yields KeydbParse.
---
 src/keydb.rs | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/keydb.rs b/src/keydb.rs
index bb055e9..54a82e4 100644
--- a/src/keydb.rs
+++ b/src/keydb.rs
@@ -27,8 +27,8 @@ const MAX_REDIRECTS: usize = 5;
 const MAX_KEYDB_BYTES: u64 = 64 * 1024 * 1024;
 
 /// Read a decompressed stream into a String with a hard size ceiling.
-/// Returns `Error::KeydbInvalid` if the input exceeds the cap or is not
-/// valid UTF-8.
+/// Returns `Error::KeydbInvalid` if the input exceeds the cap, or
+/// `Error::KeydbParse` if the bytes are not valid UTF-8.
 fn read_capped_to_string<R: Read>(reader: R) -> Result<String> {
     let mut buf = Vec::new();
     // Read one byte past the cap so an exactly-at-cap stream is accepted
@@ -737,6 +737,21 @@ mod tests {
         );
     }
 
+    /// read_capped_to_string returns KeydbParse (not KeydbInvalid) for
+    /// non-UTF-8 input. Guards the doc/behavior contract: KeydbInvalid is
+    /// reserved for the size-cap violation, a decode failure is a parse error.
+    #[test]
+    fn read_capped_to_string_non_utf8_yields_parse() {
+        // 0xFF is never a valid UTF-8 byte.
+        let cursor = std::io::Cursor::new(vec![0xFFu8, 0xFE, 0xFD]);
+        let result = read_capped_to_string(cursor);
+        assert!(
+            matches!(result, Err(Error::KeydbParse)),
+            "non-UTF-8 input must yield KeydbParse, got: {:?}",
+            result
+        );
+    }
+
     /// read_capped_to_string accepts exactly MAX_KEYDB_BYTES (at-cap is allowed).
     /// Spec: doc says "Read one byte past the cap so an exactly-at-cap stream is accepted."
     /// Mutation: using `>=` instead of `>` in the length check rejects valid at-cap files.