[Speculative] Exploring if caching the uncommon header key...

jasnell · jasnell · commit 0a4c8f09428e · 2025-10-23T12:41:29.000-07:00
... helps further improve performance at all.

... Unlikely to keep this unless we see measurable gain.
diff --git a/src/workerd/api/headers.c++ b/src/workerd/api/headers.c++
@@ -236,6 +236,42 @@ inline void requireValidHeaderValue(kj::StringPtr value) {
 }
 }  // namespace
 
+struct Headers::HeaderKeyCache {
+  // Small cache.. most headers are common anyway.
+  static constexpr size_t CACHE_SIZE = 20;
+  struct Entry final {
+    kj::String originalName;
+    Headers::HeaderKey cachedKey;
+    Entry(kj::String name, Headers::HeaderKey key)
+        : originalName(kj::mv(name)),
+          cachedKey(kj::mv(key)) {}
+  };
+
+  kj::FixedArray<kj::Maybe<Entry>, CACHE_SIZE> entries;
+  size_t nextSlot = 0;
+
+  HeaderKeyCache(): entries() {}
+
+  HeaderKey& getOrCreateKey(kj::StringPtr name) {
+    for (auto& maybeEntry: entries) {
+      KJ_IF_SOME(entry, maybeEntry) {
+        if (entry.originalName.size() != name.size()) continue;
+        if (strncasecmp(entry.originalName.begin(), name.begin(), name.size()) == 0) {
+          return entry.cachedKey;
+        }
+      }
+    }
+
+    // Not found, create new entry
+    auto slot = nextSlot;
+    nextSlot = (nextSlot + 1) % CACHE_SIZE;
+    entries[slot] = Entry(kj::str(name), getHeaderKeyFor(name));
+    return KJ_ASSERT_NONNULL(entries[slot]).cachedKey;
+  }
+};
+
+thread_local Headers::HeaderKeyCache headerKeyCache{};
+
 Headers::UncommonHeaderKey::UncommonHeaderKey(kj::String name)
     : name(kj::mv(name)),
       hash(kj::hashCode(this->name)) {}
@@ -262,16 +298,16 @@ Headers::HeaderKey Headers::getHeaderKeyFor(kj::StringPtr name) {
   }
 
   // Not a common header, so allocate lowercase copy for uncommon header
-  return UncommonHeaderKey(toLower(name));
+  return kj::rc<UncommonHeaderKey>(toLower(name));
 }
 
-Headers::HeaderKey Headers::cloneHeaderKey(const HeaderKey& key) {
+Headers::HeaderKey Headers::cloneHeaderKey(HeaderKey& key) {
   KJ_SWITCH_ONEOF(key) {
     KJ_CASE_ONEOF(commonId, uint) {
       return commonId;
     }
-    KJ_CASE_ONEOF(uncommonKey, UncommonHeaderKey) {
-      return uncommonKey.clone();
+    KJ_CASE_ONEOF(uncommonKey, kj::Rc<UncommonHeaderKey>) {
+      return uncommonKey.addRef();
     }
   }
   KJ_UNREACHABLE;
@@ -282,10 +318,10 @@ bool Headers::isSetCookie(const HeaderKey& key) {
     KJ_CASE_ONEOF(commonId, uint) {
       return commonId == static_cast<uint>(capnp::CommonHeaderName::SET_COOKIE);
     }
-    KJ_CASE_ONEOF(uncommonKey, UncommonHeaderKey) {
+    KJ_CASE_ONEOF(uncommonKey, kj::Rc<UncommonHeaderKey>) {
       // This case really shouldn't happen since "set-cookie" is a common header,
       // but just in case...
-      return uncommonKey.equals("set-cookie");
+      return uncommonKey->equals("set-cookie");
     }
   }
   KJ_UNREACHABLE;
@@ -299,9 +335,9 @@ bool Headers::headerKeyEquals(const HeaderKey& a, const HeaderKey& b) {
       }
       return false;
     }
-    KJ_CASE_ONEOF(aUncommonKey, UncommonHeaderKey) {
-      KJ_IF_SOME(bUncommonKey, b.tryGet<UncommonHeaderKey>()) {
-        return aUncommonKey.equals(bUncommonKey);
+    KJ_CASE_ONEOF(aUncommonKey, kj::Rc<UncommonHeaderKey>) {
+      KJ_IF_SOME(bUncommonKey, b.tryGet<kj::Rc<UncommonHeaderKey>>()) {
+        return aUncommonKey->equals(*bUncommonKey.get());
       }
       return false;
     }
@@ -310,7 +346,7 @@ bool Headers::headerKeyEquals(const HeaderKey& a, const HeaderKey& b) {
 }
 
 Headers::Header::Header(jsg::ByteString name, kj::Vector<jsg::ByteString> values)
-    : key(getHeaderKeyFor(name)),
+    : key(cloneHeaderKey(headerKeyCache.getOrCreateKey(name))),
       values(kj::mv(values)) {
   if (getKeyName() != name) {
     // The casing of the provided name does not match the lower-cased version
@@ -321,7 +357,7 @@ Headers::Header::Header(jsg::ByteString name, kj::Vector<jsg::ByteString> values
 }
 
 Headers::Header::Header(jsg::ByteString name, jsg::ByteString value)
-    : key(getHeaderKeyFor(name)),
+    : key(cloneHeaderKey(headerKeyCache.getOrCreateKey(name))),
       values(1) {
   values.add(kj::mv(value));
   if (getKeyName() != name) {
@@ -352,8 +388,8 @@ kj::StringPtr Headers::Header::Header::getKeyName() const {
     KJ_CASE_ONEOF(commonId, uint) {
       return COMMON_HEADER_NAMES[commonId];
     }
-    KJ_CASE_ONEOF(uncommonKey, UncommonHeaderKey) {
-      return uncommonKey.getName();
+    KJ_CASE_ONEOF(uncommonKey, kj::Rc<UncommonHeaderKey>) {
+      return uncommonKey->getName();
     }
   }
   KJ_UNREACHABLE;
@@ -366,7 +402,7 @@ kj::StringPtr Headers::Header::getHeaderName() const {
   return getKeyName();
 }
 
-Headers::Header Headers::Header::clone() const {
+Headers::Header Headers::Header::clone() {
   return Header(cloneHeaderKey(key),
       name.map([](const kj::String& n) { return jsg::ByteString(kj::str(n)); }),
       KJ_MAP(value, values) { return jsg::ByteString(kj::str(value)); });
@@ -377,7 +413,7 @@ bool Headers::HeaderCallbacks::matches(Header& header, const HeaderKey& other) {
 }
 
 bool Headers::HeaderCallbacks::matches(Header& header, kj::StringPtr otherName) {
-  return matches(header, getHeaderKeyFor(otherName));
+  return matches(header, headerKeyCache.getOrCreateKey(otherName));
 }
 
 bool Headers::HeaderCallbacks::matches(Header& header, capnp::CommonHeaderName commondId) {
@@ -392,8 +428,8 @@ kj::uint Headers::HeaderCallbacks::hashCode(const HeaderKey& key) {
     KJ_CASE_ONEOF(commonId, uint) {
       return kj::hashCode(commonId);
     }
-    KJ_CASE_ONEOF(uncommonKey, UncommonHeaderKey) {
-      return uncommonKey.hashCode();
+    KJ_CASE_ONEOF(uncommonKey, kj::Rc<UncommonHeaderKey>) {
+      return uncommonKey->hashCode();
     }
   }
   KJ_UNREACHABLE;
@@ -405,14 +441,19 @@ kj::uint Headers::HeaderCallbacks::hashCode(capnp::CommonHeaderName commondId) {
 
 Headers::Headers(jsg::Lock& js, jsg::Dict<jsg::ByteString, jsg::ByteString> dict)
     : guard(Guard::NONE) {
-  headers.reserve(dict.fields.size());
+  // Reserve enough space for all headers + 50% extra to extraneous rehashes
+  // In the typical case, users won't be adding a large number of additional
+  // headers after construction but just in case, we add some extra slack.
+  size_t size = dict.fields.size();
+  headers.reserve(kj::max(10, size + (size >> 1)));
   for (auto& field: dict.fields) {
     append(js, kj::mv(field.name), kj::mv(field.value));
   }
 }
 
-Headers::Headers(jsg::Lock& js, const Headers& other): guard(Guard::NONE) {
-  headers.reserve(other.headers.size());
+Headers::Headers(jsg::Lock& js, Headers& other): guard(Guard::NONE) {
+  size_t size = other.headers.size();
+  headers.reserve(kj::max(10, size + (size >> 1)));
   for (auto& header: other.headers) {
     // There really shouldn't be any duplicate headers in other, but just in case, use upsert
     // and we'll just ignore duplicates.
@@ -421,18 +462,44 @@ Headers::Headers(jsg::Lock& js, const Headers& other): guard(Guard::NONE) {
 }
 
 Headers::Headers(jsg::Lock& js, const kj::HttpHeaders& other, Guard guard): guard(Guard::NONE) {
-  headers.reserve(other.size());
-  other.forEach([this, &js](auto name, auto value) {
+  size_t size = other.size();
+  headers.reserve(kj::max(10, size + (size >> 1)));
+
+  other.forEach([this](auto name, auto value) {
     // We have to copy the strings here but we can avoid normalizing and validating since
     // they presumably already went through that process when they were added to the
     // kj::HttpHeader instance.
-    appendUnguarded(js, jsg::ByteString(kj::str(name)), jsg::ByteString(kj::str(value)));
+    auto& key = headerKeyCache.getOrCreateKey(name);
+
+    auto valueStr = jsg::ByteString(kj::str(value));
+    KJ_IF_SOME(found, headers.find(key)) {
+      found.values.add(kj::mv(valueStr));
+    } else {
+      kj::Maybe<jsg::ByteString> preservedName = kj::none;
+      auto nameStr = ([&]() -> kj::StringPtr {
+        KJ_SWITCH_ONEOF(key) {
+          KJ_CASE_ONEOF(commonId, uint) {
+            return COMMON_HEADER_NAMES[commonId];
+          }
+          KJ_CASE_ONEOF(uncommonKey, kj::Rc<UncommonHeaderKey>) {
+            return uncommonKey->getName();
+          }
+        }
+        KJ_UNREACHABLE;
+      })();
+      if (nameStr != name) {
+        preservedName = jsg::ByteString(kj::str(name));
+      }
+      kj::Vector<jsg::ByteString> values(1);
+      values.add(kj::mv(valueStr));
+      headers.insert(Header(cloneHeaderKey(key), kj::mv(preservedName), kj::mv(values)));
+    }
   });
 
   this->guard = guard;
 }
 
-jsg::Ref<Headers> Headers::clone(jsg::Lock& js) const {
+jsg::Ref<Headers> Headers::clone(jsg::Lock& js) {
   auto result = js.alloc<Headers>(js, *this);
   result->guard = guard;
   return kj::mv(result);
@@ -454,7 +521,7 @@ bool Headers::hasLowerCase(kj::StringPtr name) {
     KJ_DREQUIRE(!('A' <= c && c <= 'Z'));
   }
 #endif
-  return headers.find(getHeaderKeyFor(name)) != kj::none;
+  return headers.find(headerKeyCache.getOrCreateKey(name)) != kj::none;
 }
 
 kj::Array<Headers::DisplayedHeader> Headers::getDisplayedHeaders(jsg::Lock& js) {
@@ -554,7 +621,7 @@ kj::Maybe<jsg::ByteString> Headers::get(jsg::Lock& js, jsg::ByteString name) {
 }
 
 kj::Maybe<jsg::ByteString> Headers::getNoChecks(jsg::Lock&, kj::StringPtr name) {
-  KJ_IF_SOME(found, headers.find(getHeaderKeyFor(name))) {
+  KJ_IF_SOME(found, headers.find(headerKeyCache.getOrCreateKey(name))) {
     return jsg::ByteString(kj::strArray(found.values, ", "));
   }
   return kj::none;
@@ -590,7 +657,7 @@ kj::ArrayPtr<jsg::ByteString> Headers::getAll(jsg::ByteString name) {
 
 bool Headers::has(jsg::ByteString name) {
   requireValidHeaderName(name);
-  return headers.find(getHeaderKeyFor(name)) != kj::none;
+  return headers.find(headerKeyCache.getOrCreateKey(name)) != kj::none;
 }
 
 bool Headers::hasCommon(capnp::CommonHeaderName idx) {
@@ -631,7 +698,7 @@ void Headers::append(jsg::Lock& js, jsg::ByteString name, jsg::ByteString value)
 
 void Headers::appendUnguarded(jsg::Lock& js, jsg::ByteString name, jsg::ByteString value) {
   // If the header already exists, we just add to its values.
-  auto key = getHeaderKeyFor(name);
+  auto& key = headerKeyCache.getOrCreateKey(name);
   KJ_IF_SOME(found, headers.find(key)) {
     found.values.add(kj::mv(value));
   } else {
@@ -642,7 +709,7 @@ void Headers::appendUnguarded(jsg::Lock& js, jsg::ByteString name, jsg::ByteStri
 void Headers::delete_(jsg::ByteString name) {
   checkGuard();
   requireValidHeaderName(name);
-  headers.eraseMatch(getHeaderKeyFor(name));
+  headers.eraseMatch(headerKeyCache.getOrCreateKey(name));
 }
 
 // There are a couple implementation details of the Headers iterators worth calling out.
@@ -774,7 +841,7 @@ void Headers::serialize(jsg::Lock& js, jsg::Serializer& serializer) {
         KJ_CASE_ONEOF(commonId, uint) {
           serializer.writeRawUint32(commonId);
         }
-        KJ_CASE_ONEOF(uncommonKey, UncommonHeaderKey) {
+        KJ_CASE_ONEOF(_, kj::Rc<UncommonHeaderKey>) {
           serializer.writeRawUint32(0);
           serializer.writeLengthDelimited(header.getHeaderName());
         }
diff --git a/src/workerd/api/headers.h b/src/workerd/api/headers.h
@@ -32,14 +32,17 @@ class Headers final: public jsg::Object {
     jsg::ByteString value; // comma-concatenation of all values seen
   };
 
-  Headers(): guard(Guard::NONE) {}
+  Headers(): guard(Guard::NONE) {
+    // Pre-allocate some space for headers to avoid rehashes in the common cases.
+    headers.reserve(10);
+  }
   explicit Headers(jsg::Lock& js, jsg::Dict<jsg::ByteString, jsg::ByteString> dict);
-  explicit Headers(jsg::Lock& js, const Headers& other);
+  explicit Headers(jsg::Lock& js, Headers& other);
   explicit Headers(jsg::Lock& js, const kj::HttpHeaders& other, Guard guard);
   KJ_DISALLOW_COPY_AND_MOVE(Headers);
 
   // Make a copy of this Headers object, and preserve the guard.
-  jsg::Ref<Headers> clone(jsg::Lock& js) const;
+  jsg::Ref<Headers> clone(jsg::Lock& js);
 
   // Fill in the given HttpHeaders with these headers. Note that strings are inserted by
   // reference, so the output must be consumed immediately.
@@ -164,13 +167,13 @@ class Headers final: public jsg::Object {
 
   void visitForMemoryInfo(jsg::MemoryTracker& tracker) const;
 
+  struct HeaderKeyCache;
+
 private:
   // The header key can be stored either as a common header ID (uint)
-  class UncommonHeaderKey final {
+  class UncommonHeaderKey final: public kj::Refcounted {
    public:
-    UncommonHeaderKey(UncommonHeaderKey&&) = default;
-    UncommonHeaderKey& operator=(UncommonHeaderKey&&) = default;
-    KJ_DISALLOW_COPY(UncommonHeaderKey);
+    KJ_DISALLOW_COPY_AND_MOVE(UncommonHeaderKey);
 
     bool equals(const UncommonHeaderKey& other) const;
 
@@ -186,38 +189,35 @@ class Headers final: public jsg::Object {
       tracker.trackField("name", name);
     }
 
-    UncommonHeaderKey clone() const {
-      return UncommonHeaderKey(kj::str(name), hash);
-    }
+    UncommonHeaderKey(kj::String name);
+    UncommonHeaderKey(kj::StringPtr name);
+    UncommonHeaderKey(kj::String name, kj::uint hash): name(kj::mv(name)), hash(hash) {}
 
    private:
     // The name is expected to be stored in lower-case form, but we do not
-    // enforce that actually within the struct. It is the responsibility of
+    // enforce that actually within this class. It is the responsibility of
     // the caller to ensure it is appropriately lower-cased.
     kj::String name;
     kj::uint hash;
 
     // Critically, because of hash collisions, we must still compare the full string
     // to determine equality but we can use the hash code to avoid unnecessary string
     // comparisons.
-    UncommonHeaderKey(kj::String name);
-    UncommonHeaderKey(kj::StringPtr name);
-    UncommonHeaderKey(kj::String name, kj::uint hash): name(kj::mv(name)), hash(hash) {}
     friend class Headers;
   };
 
-  // A header is identified by either a common header ID or an uncommon header name.
-  // The header key name is always identifed in lower-case form, while the original
+  // A header is identified by either a common header ID or an UncommonHeaderKey.
+  // The header key name is always stored in lower-case form, while the original
   // casing is preserved in the actual Header struct to support case-preserving display.
-  using HeaderKey = kj::OneOf<uint, UncommonHeaderKey>;
+  using HeaderKey = kj::OneOf<uint, kj::Rc<UncommonHeaderKey>>;
 
-  static HeaderKey getHeaderKeyFor(kj::StringPtr name);
-  static bool headerKeyEquals(const HeaderKey& a, const HeaderKey& b);
-  static HeaderKey cloneHeaderKey(const HeaderKey& key);
-  static bool isSetCookie(const HeaderKey& key);
+  static inline HeaderKey getHeaderKeyFor(kj::StringPtr name);
+  static inline bool headerKeyEquals(const HeaderKey& a, const HeaderKey& b);
+  static inline HeaderKey cloneHeaderKey(HeaderKey& key);
+  static inline bool isSetCookie(const HeaderKey& key);
 
   struct Header final {
-    // The header key, either a common header ID or an uncommon header name.
+    // The header key, either a common header ID or an UncommonHeaderKey.
     HeaderKey key;
     // If the casing of the header name does not match the lower-cased version, we
     // store the original casing here for display purposes. If the casing matches, this
@@ -248,10 +248,12 @@ class Headers final: public jsg::Object {
                     kj::Vector<jsg::ByteString> values);
     explicit Header(HeaderKey key, jsg::ByteString name, jsg::ByteString value);
 
-    Header clone() const;
+    Header clone();
 
     JSG_MEMORY_INFO(Header) {
-      tracker.trackField("key", key.tryGet<UncommonHeaderKey>());
+      KJ_IF_SOME(uncommonKey, key.tryGet<kj::Rc<UncommonHeaderKey>>()) {
+        tracker.trackFieldWithSize("key", uncommonKey->getName().size());
+      }
       tracker.trackField("name", name);
       for (const auto& value : values) {
         tracker.trackField(nullptr, value);
@@ -268,6 +270,7 @@ class Headers final: public jsg::Object {
     static kj::uint hashCode(const HeaderKey& key);
     static kj::uint hashCode(capnp::CommonHeaderName commondId);
   };
+  friend struct HeaderKeyCache;
 
   kj::Table<Header, kj::HashIndex<HeaderCallbacks>> headers;
 
