Refactor KeyRegularizer to reduce allocations

Interfaces that return multi values aren't great in hotspot
as they require to allocate a very short lived array and the
Ruby VM isn't yet sophisticated enough to elude it.

But since in the happy path we only need to check if the key
need to be encoded, we can decompose that single method into
two calls, and save more performance on the happy path (one allocation)
than we lose on the slow path (one method call).

Also refactor `multi_get / multi_set / multi_delete` to be generated
by `RequestFormatter` so that they can use its internal helpers to
encode keys.

Author: byroot

.rubocop_todo.yml

@@ -1,31 +1,34 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-04-01 20:25:11 UTC using RuboCop version 1.75.1.
+# on 2026-06-03 14:43:04 UTC using RuboCop version 1.85.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
 Metrics/AbcSize:
-  Max: 20
+  Max: 19
 
-# Offense count: 9
+# Offense count: 7
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 350
+  Max: 338
 
-# Offense count: 4
-# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# Offense count: 1
+# Configuration parameters: CountComments, Max, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 20
   Exclude:
-    - 'lib/dalli/pipelined_getter.rb'
-    - 'lib/dalli/protocol/base.rb'
     - 'lib/dalli/socket.rb'
 
-# Offense count: 1
+# Offense count: 2
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ModuleLength:
-  Max: 108
+  Max: 128
+
+# Offense count: 1
+# Configuration parameters: AllowedClasses.
+Style/OneClassPerFile:
+  Exclude:
+    - 'test/helper.rb'

lib/dalli/protocol/key_regularizer.rb

@@ -9,17 +9,18 @@ class Meta
       # allowed.
       # memcached supports the use of base64 hashes for keys containing
       # whitespace or non-ASCII characters, provided the 'b' flag is included in the request.
-      class KeyRegularizer
-        def self.encode(key)
-          return [key, false] if key.ascii_only? && !/\s/.match?(key)
+      module KeyRegularizer
+        module_function
 
-          strict_base64_encoded = [key].pack('m0')
-          [strict_base64_encoded, true]
+        def required?(key)
+          !key.ascii_only? || /\s/.match?(key)
         end
 
-        def self.decode(encoded_key, base64_encoded)
-          return encoded_key unless base64_encoded
+        def encode(key)
+          [key].pack('m0')
+        end
 
+        def decode(encoded_key)
           strict_base64_decoded = encoded_key.unpack1('m0')
           strict_base64_decoded.force_encoding(Encoding::UTF_8)
         end

lib/dalli/protocol/meta.rb

@@ -24,43 +24,37 @@ def response_processor
 
       # Retrieval Commands
       def get(key, options = nil)
-        encoded_key, base64 = KeyRegularizer.encode(key)
         # Skip bitflags in raw mode - saves 2 bytes per request and skips parsing
         skip_flags = raw_mode? || (options && options[:raw])
-        req = RequestFormatter.meta_get(key: encoded_key, base64: base64, skip_flags: skip_flags)
+        req = RequestFormatter.meta_get(key: key, skip_flags: skip_flags)
         flushed_write(req)
         response_processor.meta_get_with_value(cache_nils: cache_nils?(options))
       end
 
       def quiet_get_request(key)
-        encoded_key, base64 = KeyRegularizer.encode(key)
         # Skip bitflags in raw mode - saves 2 bytes per request and skips parsing
-        RequestFormatter.meta_get(key: encoded_key, return_cas: true, base64: base64, quiet: true,
-                                  skip_flags: raw_mode?)
+        RequestFormatter.meta_get(key: key, return_cas: true, quiet: true, skip_flags: raw_mode?)
       end
 
       def gat(key, ttl, options = nil)
         ttl = TtlSanitizer.sanitize(ttl)
-        encoded_key, base64 = KeyRegularizer.encode(key)
         skip_flags = raw_mode? || (options && options[:raw])
-        req = RequestFormatter.meta_get(key: encoded_key, ttl: ttl, base64: base64, skip_flags: skip_flags)
+        req = RequestFormatter.meta_get(key: key, ttl: ttl, skip_flags: skip_flags)
         flushed_write(req)
         response_processor.meta_get_with_value(cache_nils: cache_nils?(options))
       end
 
       def touch(key, ttl)
         ttl = TtlSanitizer.sanitize(ttl)
-        encoded_key, base64 = KeyRegularizer.encode(key)
-        req = RequestFormatter.meta_get(key: encoded_key, ttl: ttl, value: false, base64: base64)
+        req = RequestFormatter.meta_get(key: key, ttl: ttl, value: false)
         flushed_write(req)
         response_processor.meta_get_without_value
       end
 
       # TODO: This is confusing, as there's a cas command in memcached
       # and this isn't it.  Maybe rename?  Maybe eliminate?
       def cas(key)
-        encoded_key, base64 = KeyRegularizer.encode(key)
-        req = RequestFormatter.meta_get(key: encoded_key, value: true, return_cas: true, base64: base64)
+        req = RequestFormatter.meta_get(key: key, value: true, return_cas: true)
         flushed_write(req)
         response_processor.meta_get_with_value_and_cas
       end
@@ -90,9 +84,8 @@ def cas(key)
       #   - :hit_before - true/false if previously accessed (only if return_hit_status: true)
       #   - :last_access - seconds since last access (only if return_last_access: true)
       def meta_get(key, options = {})
-        encoded_key, base64 = KeyRegularizer.encode(key)
         req = RequestFormatter.meta_get(
-          key: encoded_key, value: true, return_cas: true, base64: base64,
+          key: key, value: true, return_cas: true,
           vivify_ttl: options[:vivify_ttl], recache_ttl: options[:recache_ttl],
           return_hit_status: options[:return_hit_status],
           return_last_access: options[:return_last_access], skip_lru_bump: options[:skip_lru_bump]
@@ -112,8 +105,7 @@ def meta_get(key, options = {})
       # @param cas [Integer] optional CAS value for compare-and-swap
       # @return [Boolean] true if successful
       def delete_stale(key, cas = nil)
-        encoded_key, base64 = KeyRegularizer.encode(key)
-        req = RequestFormatter.meta_delete(key: encoded_key, cas: cas, base64: base64, stale: true)
+        req = RequestFormatter.meta_delete(key: key, cas: cas, stale: true)
         flushed_write(req)
         response_processor.meta_delete
       end
@@ -144,10 +136,9 @@ def replace(key, value, ttl, cas, options)
       def write_storage_req(mode, key, raw_value, ttl = nil, cas = nil, options = {}, quiet: quiet?)
         (value, bitflags) = @value_marshaller.store(key, raw_value, options)
         ttl = TtlSanitizer.sanitize(ttl) if ttl
-        encoded_key, base64 = KeyRegularizer.encode(key)
-        req = RequestFormatter.meta_set(key: encoded_key, value: value,
+        req = RequestFormatter.meta_set(key: key, value: value,
                                         bitflags: bitflags, cas: cas,
-                                        ttl: ttl, mode: mode, quiet: quiet, base64: base64)
+                                        ttl: ttl, mode: mode, quiet: quiet)
         write("#{req}#{value}#{TERMINATOR}")
         @connection_manager.flush unless quiet
       end
@@ -166,8 +157,7 @@ def prepend(key, value)
       # rubocop:disable Metrics/ParameterLists
       def write_append_prepend_req(mode, key, value, ttl = nil, cas = nil, _options = {})
         ttl = TtlSanitizer.sanitize(ttl) if ttl
-        encoded_key, base64 = KeyRegularizer.encode(key)
-        req = RequestFormatter.meta_set(key: encoded_key, value: value, base64: base64,
+        req = RequestFormatter.meta_set(key: key, value: value,
                                         cas: cas, ttl: ttl, mode: mode, quiet: quiet?)
         write("#{req}#{value}#{TERMINATOR}")
         @connection_manager.flush unless quiet?
@@ -176,9 +166,7 @@ def write_append_prepend_req(mode, key, value, ttl = nil, cas = nil, _options =
 
       # Delete Commands
       def delete(key, cas)
-        encoded_key, base64 = KeyRegularizer.encode(key)
-        req = RequestFormatter.meta_delete(key: encoded_key, cas: cas,
-                                           base64: base64, quiet: quiet?)
+        req = RequestFormatter.meta_delete(key: key, cas: cas, quiet: quiet?)
         write(req)
         @connection_manager.flush unless quiet?
         response_processor.meta_delete unless quiet?
@@ -187,8 +175,7 @@ def delete(key, cas)
       # Pipelined delete - writes a quiet delete request without reading response.
       # Used by PipelinedDeleter for bulk operations.
       def pipelined_delete(key)
-        encoded_key, base64 = KeyRegularizer.encode(key)
-        req = RequestFormatter.meta_delete(key: encoded_key, base64: base64, quiet: true)
+        req = RequestFormatter.meta_delete(key: key, quiet: true)
         write(req)
       end
 
@@ -203,9 +190,8 @@ def incr(key, count, ttl, initial)
 
       def decr_incr(incr, key, delta, ttl, initial)
         ttl = initial ? TtlSanitizer.sanitize(ttl) : nil # Only set a TTL if we want to set a value on miss
-        encoded_key, base64 = KeyRegularizer.encode(key)
-        write(RequestFormatter.meta_arithmetic(key: encoded_key, delta: delta, initial: initial, incr: incr, ttl: ttl,
-                                               quiet: quiet?, base64: base64))
+        write(RequestFormatter.meta_arithmetic(key: key, delta: delta, initial: initial, incr: incr, ttl: ttl,
+                                               quiet: quiet?))
         @connection_manager.flush unless quiet?
         response_processor.decr_incr unless quiet?
       end
@@ -248,23 +234,9 @@ def write_noop
       # machinery (IO.select, response buffering, server grouping).
       def read_multi_req(keys)
         is_raw = raw_mode?
-        # Inline request formatting — avoids RequestFormatter.meta_get overhead per key.
-        # In raw mode: "mg <key> v k q s\r\n" (no f flag, key at index 2)
-        # Normal mode: "mg <key> v f k q s\r\n" (key at index 3)
-        post_get = is_raw ? " v k q s\r\n" : " v f k q s\r\n"
-        buffer = ''.b
-        keys.each do |key|
-          encoded_key, base64 = KeyRegularizer.encode(key)
-          if base64
-            buffer << 'mg ' << encoded_key << ' b' << post_get
-          else
-            buffer << 'mg ' << encoded_key << post_get
-          end
-        end
-        buffer << 'mn' << TERMINATOR
+        buffer = RequestFormatter.multi_meta_get(keys, skip_flags: is_raw)
         flushed_write(buffer)
         buffer.clear
-
         read_multi_get_responses(is_raw)
       end
 
@@ -287,49 +259,30 @@ def parse_multi_get_value(line, key_index, is_raw)
         raw_key = tokens[key_index]
         return unless raw_key
 
-        key = KeyRegularizer.decode(raw_key[1..], tokens.include?('b'))
+        key = raw_key[1..]
+        key = KeyRegularizer.decode(key) if tokens.include?('b')
         bitflags = is_raw ? 0 : response_processor.bitflags_from_tokens(tokens)
         [key, @value_marshaller.retrieve(value, bitflags)]
       end
 
-      # rubocop:disable Metrics/AbcSize
-
       # Single-server fast path for set_multi. Inlines request formatting to
       # minimize per-key overhead. Avoids PipelinedSetter server grouping.
       def write_multi_req(pairs, ttl, req_options)
         ttl = TtlSanitizer.sanitize(ttl) if ttl
-        buffer = ''.b
-        pairs.each do |key, raw_value|
-          (value, bitflags) = @value_marshaller.store(key, raw_value, req_options)
-          encoded_key, base64 = KeyRegularizer.encode(key)
-          # Inline format: "ms <key> <size> c [b] F<flags> T<ttl> MS q\r\n"
-          buffer << "ms #{encoded_key} #{value.bytesize} c"
-          buffer << ' b' if base64
-          buffer << " F#{bitflags}" if bitflags
-          buffer << " T#{ttl}" if ttl
-          buffer << ' MS q' << TERMINATOR << value << TERMINATOR
+        entries = pairs.map do |key, raw_value|
+          [key, @value_marshaller.store(key, raw_value, req_options)]
         end
-        buffer << RequestFormatter.meta_noop
+
+        buffer = RequestFormatter.multi_meta_set(entries, ttl: ttl)
         flushed_write(buffer)
         buffer.clear
         response_processor.consume_all_responses_until_mn
       end
-      # rubocop:enable Metrics/AbcSize
 
       # Single-server fast path for delete_multi. Writes all quiet delete requests
       # terminated by a noop, then consumes all responses.
       def delete_multi_req(keys)
-        buffer = ''.b
-        keys.each do |key|
-          encoded_key, base64 = KeyRegularizer.encode(key)
-          # Inline format: "md <key> [b] q\r\n"
-          if base64
-            buffer << 'md ' << encoded_key << ' b q' << TERMINATOR
-          else
-            buffer << 'md ' << encoded_key << ' q' << TERMINATOR
-          end
-        end
-        buffer << RequestFormatter.meta_noop
+        buffer = RequestFormatter.multi_meta_delete(keys)
         flushed_write(buffer)
         buffer.clear
         response_processor.consume_all_responses_until_mn