string: add LineReader

Matthew Zipkin · pinheadmz · commit ea993ff2af1f · 2026-01-09T12:54:12.000-05:00
This is a helper struct to parse HTTP messages from data in buffers from sockets. HTTP messages begin with headers which are CRLF-terminated lines (\n or \r\n) followed by an arbitrary amount of body data. Whitespace is trimmed from the field lines but not the body. https://httpwg.org/specs/rfc9110.html#rfc.section.5
diff --git a/src/test/util_string_tests.cpp b/src/test/util_string_tests.cpp
@@ -180,4 +180,72 @@ BOOST_AUTO_TEST_CASE(ascii_case_insensitive_hash_test)
     BOOST_CHECK_EQUAL(hsh("Ab"), hsh("aB"));
 }
 
+BOOST_AUTO_TEST_CASE(line_reader_test)
+{
+    {
+        // Check three lines terminated by \n, \r\n, and end of buffer, trimming whitespace
+        const std::vector<std::byte> input{StringToBuffer("once upon a time\n there was a dog \r\nwho liked food")};
+        LineReader reader(input, /*max_read=*/128);
+        std::optional<std::string> line1{reader.ReadLine()};
+        BOOST_CHECK_EQUAL(reader.Left(), 33);
+        std::optional<std::string> line2{reader.ReadLine()};
+        BOOST_CHECK_EQUAL(reader.Left(), 14);
+        std::optional<std::string> line3{reader.ReadLine()};
+        std::optional<std::string> line4{reader.ReadLine()};
+        BOOST_CHECK(line1);
+        BOOST_CHECK(line2);
+        BOOST_CHECK(line3);
+        BOOST_CHECK(!line4);
+        BOOST_CHECK_EQUAL(line1.value(), "once upon a time");
+        BOOST_CHECK_EQUAL(line2.value(), "there was a dog");
+        BOOST_CHECK_EQUAL(line3.value(), "who liked food");
+    }
+    {
+        // Do not exceed max_read while searching for \n
+        // Test with 22-character line + \n + 23-character line + \n
+        const std::vector<std::byte> input{StringToBuffer("once upon a time there\nwas a dog who liked tea\n")};
+
+        LineReader reader1(input, /*max_read=*/22);
+        // First line is exactly the length of max_read
+        BOOST_CHECK_EQUAL(reader1.ReadLine(), "once upon a time there");
+        // Second line is +1 character too long
+        BOOST_CHECK_THROW(reader1.ReadLine(), std::runtime_error);
+
+        // Increase max_read by 1
+        LineReader reader2(input, /*max_read=*/23);
+        // Both lines fit within limit
+        BOOST_CHECK_EQUAL(reader2.ReadLine(), "once upon a time there");
+        BOOST_CHECK_EQUAL(reader2.ReadLine(), "was a dog who liked tea");
+        // End of buffer reached
+        BOOST_CHECK(!reader2.ReadLine());
+    }
+    {
+        // The end of the buffer (EOB) acts exactly like \n
+        const std::vector<std::byte> input{StringToBuffer("once upon a time there")};
+
+        LineReader reader1(input, /*max_read=*/22);
+        // First line is exactly the length of max_read
+        BOOST_CHECK_EQUAL(reader1.ReadLine(), "once upon a time there");
+        // End of buffer reached
+        BOOST_CHECK(!reader1.ReadLine());
+
+        // Increase max_read by 1
+        LineReader reader2(input, /*max_read=*/23);
+        // The line fits within limit
+        BOOST_CHECK_EQUAL(reader2.ReadLine(), "once upon a time there");
+        // End of buffer reached
+        BOOST_CHECK(!reader2.ReadLine());
+    }
+    {
+        // Read specific number of bytes regardless of max_read or \n unless buffer is too short
+        const std::vector<std::byte> input{StringToBuffer("once upon a time\n there was a dog \r\nwho liked food")};
+        LineReader reader(input, /*max_read=*/1);
+        BOOST_CHECK_EQUAL(reader.ReadLength(0), "");
+        BOOST_CHECK_EQUAL(reader.ReadLength(3), "onc");
+        BOOST_CHECK_EQUAL(reader.ReadLength(8), "e upon a");
+        BOOST_CHECK_EQUAL(reader.ReadLength(8), " time\n t");
+        BOOST_CHECK_THROW(reader.ReadLength(128), std::runtime_error);
+    }
+}
+
 BOOST_AUTO_TEST_SUITE_END()
diff --git a/src/util/strencodings.cpp b/src/util/strencodings.cpp
@@ -427,3 +427,9 @@ std::optional<uint64_t> ParseByteUnits(std::string_view str, ByteUnit default_mu
     }
     return *parsed_num * unit_amount;
 }
+
+std::vector<std::byte> StringToBuffer(const std::string& str)
+{
+    auto span = std::as_bytes(std::span(str));
+    return {span.begin(), span.end()};
+}
diff --git a/src/util/strencodings.h b/src/util/strencodings.h
@@ -326,6 +326,15 @@ std::string Capitalize(std::string str);
  */
 std::optional<uint64_t> ParseByteUnits(std::string_view str, ByteUnit default_multiplier);
 
+/**
+ * Returns a byte vector filled with data from a string. Used to test string-
+ * encoded data from a socket like HTTP headers.
+ *
+ * @param[in] str                  the string to convert into bytes
+ * @returns                        byte vector
+ */
+std::vector<std::byte> StringToBuffer(const std::string& str);
+
 namespace util {
 /** consteval version of HexDigit() without the lookup table. */
 consteval uint8_t ConstevalHexDigit(const char c)
diff --git a/src/util/string.cpp b/src/util/string.cpp
@@ -13,4 +13,49 @@ void ReplaceAll(std::string& in_out, const std::string& search, const std::strin
     if (search.empty()) return;
     in_out = std::regex_replace(in_out, std::regex(search), substitute);
 }
+
+LineReader::LineReader(std::span<const std::byte> buffer, size_t max_read)
+    : start(buffer.begin()), end(buffer.end()), max_read(max_read), it(buffer.begin()) {}
+
+std::optional<std::string> LineReader::ReadLine()
+{
+    if (it == end) {
+        return std::nullopt;
+    }
+
+    auto line_start = it;
+    size_t count = 0;
+    while (it != end) {
+        // Read a character from the incoming buffer and increment the iterator
+        auto c = static_cast<char>(*it);
+        ++it;
+        ++count;
+        // If the character we just consumed was \n, the line is terminated
+        if (c == '\n') break;
+        // If we are at the end of the incoming buffer, the line is terminated
+        if (it == end) break;
+        // If the character we just consumed gives us a line length greater
+        // than max_read, and we are not at the end of the line (or buffer) yet,
+        // that means the line we are currently reading is too long, and we throw.
+        if (count > max_read) throw std::runtime_error("max_read exceeded by LineReader");
+    }
+    const std::string_view untrimmed_line(reinterpret_cast<const char *>(std::to_address(line_start)), count);
+    const std::string_view line = TrimStringView(untrimmed_line); // delete trailing \r and/or \n
+    return std::string(line);
+}
+
+// Ignores max_read but won't overflow
+std::string LineReader::ReadLength(size_t len)
+{
+    if (len == 0) return "";
+    if (Left() < len) throw std::runtime_error("Not enough data in buffer");
+    std::string out(reinterpret_cast<const char*>(std::to_address(it)), len);
+    it += len;
+    return out;
+}
+
+size_t LineReader::Left() const
+{
+    return std::distance(it, end);
+}
 } // namespace util
diff --git a/src/util/string.h b/src/util/string.h
@@ -11,6 +11,7 @@
 #include <cstdint>
 #include <cstring>
 #include <locale>
+#include <optional>
 #include <sstream>
 #include <string>      // IWYU pragma: export
 #include <string_view> // IWYU pragma: export
@@ -260,6 +261,37 @@ template <typename T1, size_t PREFIX_LEN>
     return obj.size() >= PREFIX_LEN &&
            std::equal(std::begin(prefix), std::end(prefix), std::begin(obj));
 }
+
+struct LineReader {
+    const std::span<const std::byte>::iterator start;
+    const std::span<const std::byte>::iterator end;
+    const size_t max_read;
+    std::span<const std::byte>::iterator it;
+
+    explicit LineReader(std::span<const std::byte> buffer, size_t max_read);
+
+    /**
+     * Returns a string from current iterator position up to next \n (or end of the buffer)
+     * and advances iterator to the character following the \n, if present.
+     * Returned string does not include the trailing \n or \r.
+     * Will throw if the line is longer than max_read (up to but not including \n or end of buffer).
+     */
+    std::optional<std::string> ReadLine();
+
+    /**
+     * Returns string from current iterator position of specified length
+     * and advances iterator. May exceed max_read but will not read past end of buffer.
+     * @param[in]   len     The number of bytes to read from the buffer
+     * @returns a string of the expected length.
+     * @throws a std::runtime_error if there is not enough data in the buffer.
+     */
+    std::string ReadLength(size_t len);
+
+    /**
+     * Returns remaining size of bytes in buffer
+     */
+    size_t Left() const;
+};
 } // namespace util
 
 #endif // BITCOIN_UTIL_STRING_H

Original file line number	Diff line number	Diff line change
`@@ -427,3 +427,9 @@ std::optional<uint64_t> ParseByteUnits(std::string_view str, ByteUnit default_mu`
`427`	`427`	`}`
`428`	`428`	`return parsed_num unit_amount;`
`429`	`429`	`}`
	`430`	`+`
	`431`	`+std::vector<std::byte> StringToBuffer(const std::string& str)`
	`432`	`+{`
	`433`	`+ auto span = std::as_bytes(std::span(str));`
	`434`	`+ return {span.begin(), span.end()};`
	`435`	`+}`