dalli 5.0.5 → 5.1.0

data/lib/dalli/protocol/meta.rb

@@ -24,43 +24,38 @@ module Dalli
 
       # 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, **routing_token_kwargs(options))
         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)
+      def quiet_get_request(key, options = nil)
         # 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?,
+                                  **routing_token_kwargs(options))
       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, **routing_token_kwargs(options))
         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)
+      def cas(key, options = nil)
+        req = RequestFormatter.meta_get(key: key, value: true, return_cas: true, **routing_token_kwargs(options))
         flushed_write(req)
         response_processor.meta_get_with_value_and_cas
       end
@@ -90,17 +85,20 @@ module Dalli
       #   - :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]
+          return_last_access: options[:return_last_access],
+          return_ttl_remaining: options[:return_ttl_remaining],
+          skip_lru_bump: options[:skip_lru_bump],
+          **routing_token_kwargs(options)
         )
         flushed_write(req)
         response_processor.meta_get_with_metadata(
           cache_nils: cache_nils?(options), return_hit_status: options[:return_hit_status],
-          return_last_access: options[:return_last_access]
+          return_last_access: options[:return_last_access],
+          return_ttl_remaining: options[:return_ttl_remaining]
         )
       end
 
@@ -112,8 +110,7 @@ module Dalli
       # @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
@@ -140,45 +137,46 @@ module Dalli
         response_processor.meta_set_with_cas unless quiet?
       end
 
-      # rubocop:disable Metrics/ParameterLists
       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,
+                                        **routing_token_kwargs(options))
         write("#{req}#{value}#{TERMINATOR}")
         @connection_manager.flush unless quiet
       end
       # rubocop:enable Metrics/ParameterLists
 
-      def append(key, value)
-        write_append_prepend_req(:append, key, value)
+      def append(key, value, options = nil)
+        write_append_prepend_req(:append, key, value, nil, nil, options)
         response_processor.meta_set_append_prepend unless quiet?
       end
 
-      def prepend(key, value)
-        write_append_prepend_req(:prepend, key, value)
+      def prepend(key, value, options = nil)
+        write_append_prepend_req(:prepend, key, value, nil, nil, options)
         response_processor.meta_set_append_prepend unless quiet?
       end
 
       # rubocop:disable Metrics/ParameterLists
-      def write_append_prepend_req(mode, key, value, ttl = nil, cas = nil, _options = {})
+      def write_append_prepend_req(mode, key, value, ttl = nil, cas = nil, options = nil)
         ttl = TtlSanitizer.sanitize(ttl) if ttl
-        encoded_key, base64 = KeyRegularizer.encode(key)
-        req = RequestFormatter.meta_set(key: encoded_key, value: value, base64: base64,
-                                        cas: cas, ttl: ttl, mode: mode, quiet: quiet?)
+        req = RequestFormatter.meta_set(key: key, value: value,
+                                        cas: cas, ttl: ttl, mode: mode, quiet: quiet?,
+                                        **routing_token_kwargs(options))
         write("#{req}#{value}#{TERMINATOR}")
         @connection_manager.flush unless quiet?
       end
       # rubocop:enable Metrics/ParameterLists
 
       # 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?)
+      #
+      # `options` supports the meta-delete keys :invalidate, :tombstone_ttl and
+      # :drop_value, plus :p_token/:l_token; see Dalli::Client#delete.
+      def delete(key, cas, options = nil)
+        req = RequestFormatter.meta_delete(key: key, cas: cas, quiet: quiet?,
+                                           **tombstone_kwargs(options), **routing_token_kwargs(options))
         write(req)
         @connection_manager.flush unless quiet?
         response_processor.meta_delete unless quiet?
@@ -186,29 +184,35 @@ module Dalli
 
       # 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)
+      def pipelined_delete(key, req_options = nil)
+        req = RequestFormatter.meta_delete(key: key, quiet: true,
+                                           **tombstone_kwargs(req_options), **routing_token_kwargs(req_options))
         write(req)
       end
 
+      def finish_pipelined_delete(sent)
+        write_noop
+        sent - response_processor.pipelined_delete_non_deletions
+      end
+
       # Arithmetic Commands
-      def decr(key, count, ttl, initial)
-        decr_incr false, key, count, ttl, initial
+      def decr(key, count, ttl, initial, options = nil)
+        decr_incr false, key, count, ttl, initial, options
       end
 
-      def incr(key, count, ttl, initial)
-        decr_incr true, key, count, ttl, initial
+      def incr(key, count, ttl, initial, options = nil)
+        decr_incr true, key, count, ttl, initial, options
       end
 
-      def decr_incr(incr, key, delta, ttl, initial)
+      # rubocop:disable Metrics/ParameterLists
+      def decr_incr(incr, key, delta, ttl, initial, options = nil)
         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?, **routing_token_kwargs(options)))
         @connection_manager.flush unless quiet?
         response_processor.decr_incr unless quiet?
       end
+      # rubocop:enable Metrics/ParameterLists
 
       # Other Commands
       def flush(delay = 0)
@@ -246,28 +250,52 @@ module Dalli
       # Single-server fast path for get_multi. Inlines request formatting and
       # response parsing to minimize per-key overhead. Avoids the PipelinedGetter
       # machinery (IO.select, response buffering, server grouping).
-      def read_multi_req(keys)
+      def read_multi_req(keys, options = nil)
         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, **routing_token_kwargs(options))
         flushed_write(buffer)
         buffer.clear
-
         read_multi_get_responses(is_raw)
       end
 
+      # Stale-aware bulk get.  Returns { key => { value:, cas:, stale:, miss: } }
+      # for the keys the server returned.  Keys that were not found are absent
+      # from the hash, matching read_multi_req and the get_multi family; a
+      # tombstoned item is present (it answers VA with the X flag) with
+      # stale: true, which is the distinction callers need.
+      #
+      # Shared by both the single-server fast path and PipelinedGetter's
+      # per-server-group request, so this one change covers both routes.
+      def read_multi_with_metadata_req(keys, options = nil)
+        is_raw = raw_mode?
+        buffer = RequestFormatter.multi_meta_get(keys, skip_flags: is_raw, return_cas: true,
+                                                       **routing_token_kwargs(options))
+        flushed_write(buffer)
+        buffer.clear
+        read_multi_metadata_responses(is_raw)
+      end
+
+      # Unlike read_multi_get_responses this locates tokens by flag rather than
+      # by position, because the c flag shifts the key's index.
+      def read_multi_metadata_responses(is_raw)
+        hash = {}
+        while (line = @connection_manager.read_line)
+          break if line.start_with?('MN')
+          next unless line.start_with?('VA ')
+
+          tokens = line.chomp!(TERMINATOR).split
+          value = @connection_manager.read(tokens[1].to_i + TERMINATOR.bytesize)&.chomp!(TERMINATOR)
+          stale = response_processor.stale_from_tokens(tokens)
+          cas = response_processor.cas_from_tokens(tokens)
+          bitflags = is_raw ? 0 : response_processor.bitflags_from_tokens(tokens)
+          key = response_processor.key_from_tokens(tokens)
+          next if key.nil?
+
+          hash[key] = { value: @value_marshaller.retrieve(value, bitflags), cas: cas, stale: stale, miss: false }
+        end
+        hash
+      end
+
       def read_multi_get_responses(is_raw)
         hash = {}
         key_index = is_raw ? 2 : 3
@@ -287,52 +315,34 @@ module Dalli
         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, **routing_token_kwargs(req_options))
         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
+      def delete_multi_req(keys, req_options = nil)
+        buffer = RequestFormatter.multi_meta_delete(keys, **tombstone_kwargs(req_options),
+                                                    **routing_token_kwargs(req_options))
         flushed_write(buffer)
         buffer.clear
-        response_processor.consume_all_responses_until_mn
+        keys.size - response_processor.pipelined_delete_non_deletions
       end
 
       require_relative 'key_regularizer'

data/lib/dalli/protocol/request_formatter.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: false
+# frozen_string_literal: true
 
 module Dalli
   module Protocol
@@ -7,14 +7,13 @@ module Dalli
       # Class that encapsulates logic for formatting meta protocol requests
       # to memcached.
       ##
-      class RequestFormatter
+      module RequestFormatter
+        extend self
+
         # Since these are string construction methods, we're going to disable these
         # Rubocop directives.  We really can't make this construction much simpler,
         # and introducing an intermediate object seems like overkill.
         #
-        # rubocop:disable Metrics/CyclomaticComplexity
-        # rubocop:disable Metrics/ParameterLists
-        # rubocop:disable Metrics/PerceivedComplexity
         #
         # Meta get flags:
         #
@@ -35,54 +34,142 @@ module Dalli
         # - Z: Client lost the recache race (another client is already regenerating)
         # - h0/h1: Hit status (0 = first access, 1 = previously accessed)
         # - l<N>: Seconds since last access
-        def self.meta_get(key:, value: true, return_cas: false, ttl: nil, base64: false, quiet: false,
-                          vivify_ttl: nil, recache_ttl: nil,
-                          return_hit_status: false, return_last_access: false, skip_lru_bump: false,
-                          skip_flags: false)
-          cmd = "mg #{key}"
+        def meta_get(key:, value: true, return_cas: false, ttl: nil, quiet: false,
+                     vivify_ttl: nil, recache_ttl: nil,
+                     return_hit_status: false, return_last_access: false, return_ttl_remaining: false,
+                     skip_lru_bump: false, skip_flags: false, p_token: nil, l_token: nil)
+          cmd = "mg #{encoded_key(key)}"
           # In raw mode (skip_flags: true), we don't request bitflags since they're not used.
           # This saves 2 bytes per request and skips parsing on response.
           cmd << (skip_flags ? ' v' : ' v f') if value
           cmd << ' c' if return_cas
-          cmd << ' b' if base64
           cmd << " T#{ttl}" if ttl
+          cmd << routing_tokens(p_token: p_token, l_token: l_token)
           cmd << ' k q s' if quiet # Return the key in the response if quiet
           cmd << " N#{vivify_ttl}" if vivify_ttl # Thundering herd: vivify on miss
           cmd << " R#{recache_ttl}" if recache_ttl # Thundering herd: win recache if TTL below threshold
           cmd << ' h' if return_hit_status # Return hit status (0 or 1)
           cmd << ' l' if return_last_access # Return seconds since last access
+          cmd << ' t' if return_ttl_remaining # Return seconds of TTL remaining (-1 = no TTL)
           cmd << ' u' if skip_lru_bump # Don't bump LRU or update access stats
           cmd << TERMINATOR
         end
 
-        def self.meta_set(key:, value:, bitflags: nil, cas: nil, ttl: nil, mode: :set, base64: false, quiet: false)
+        def multi_meta_get(keys, skip_flags: false, return_cas: false, p_token: nil, l_token: nil)
+          # 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)
+          # With return_cas a "c" flag follows, which shifts those indexes --
+          # callers of that variant locate tokens by flag rather than position.
+          # Routing tokens apply to every key in the batch, so the suffix is
+          # built once rather than per key.
+          post_get = if return_cas
+                       skip_flags ? ' v c' : ' v f c'
+                     else
+                       skip_flags ? ' v' : ' v f'
+                     end
+          post_get += routing_tokens(p_token: p_token, l_token: l_token)
+          post_get += " k q s#{TERMINATOR}"
+
+          buffer = ''.b
+          keys.each do |key|
+            buffer << 'mg ' << encoded_key(key) << post_get
+          end
+          buffer << 'mn' << TERMINATOR
+        end
+
+        def meta_set(key:, value:, bitflags: nil, cas: nil, ttl: nil, mode: :set, quiet: false,
+                     p_token: nil, l_token: nil)
+          base64 = KeyRegularizer.required?(key)
+          key = KeyRegularizer.encode(key) if base64
           cmd = "ms #{key} #{value.bytesize}"
-          cmd << ' c' unless %i[append prepend].include?(mode)
+          # Skip the cas-return flag in quiet mode: the response is suppressed,
+          # so requesting it only adds bytes to the request.
+          cmd << ' c' if !quiet && !%i[append prepend].include?(mode)
           cmd << ' b' if base64
           cmd << " F#{bitflags}" if bitflags
           cmd << cas_string(cas)
           cmd << " T#{ttl}" if ttl
           cmd << " M#{mode_to_token(mode)}"
           cmd << ' q' if quiet
+          cmd << routing_tokens(p_token: p_token, l_token: l_token)
           cmd << TERMINATOR
         end
 
+        def multi_meta_set(entries, ttl: nil, p_token: nil, l_token: nil)
+          # Routing tokens apply to every entry in the batch, so the suffix is
+          # built once rather than per entry.
+          token_suffix = routing_tokens(p_token: p_token, l_token: l_token)
+
+          buffer = ''.b
+          entries.each do |key, pair|
+            value, bitflags = pair
+
+            base64 = KeyRegularizer.required?(key)
+            key = KeyRegularizer.encode(key) if base64
+
+            # Inline format: "ms <key> <size> c [b] F<flags> T<ttl> MS q [P/L]\r\n"
+            buffer << "ms #{key} #{value.bytesize} c"
+            buffer << ' b' if base64
+            buffer << " F#{bitflags}" if bitflags
+            buffer << " T#{ttl}" if ttl
+            buffer << ' MS q' << token_suffix << TERMINATOR << value << TERMINATOR
+          end
+          buffer << META_NOOP
+        end
+
         # Thundering herd protection flag:
         # - stale (I flag): Instead of deleting the item, mark it as stale. Other clients
         #   using N/R flags will see the X flag and know the item is being regenerated.
-        def self.meta_delete(key:, cas: nil, ttl: nil, base64: false, quiet: false, stale: false)
-          cmd = "md #{key}"
-          cmd << ' b' if base64
+        # Tombstone flags:
+        # - stale (I flag): mark the item stale instead of removing it.  Readers
+        #   using N/R flags, or get_with_metadata, see the X flag and know the
+        #   item is being regenerated.
+        # - ttl (T flag): how long the stale marker lives.  memcached only honors
+        #   T on a delete when it is paired with I, so this raises rather than
+        #   emitting a request the server would apply differently than intended.
+        # - drop_value (x flag): remove the item's value but leave the item, so a
+        #   tombstone can be left without retaining the old payload.
+        def meta_delete(key:, cas: nil, ttl: nil, quiet: false, stale: false, drop_value: false,
+                        p_token: nil, l_token: nil)
+          # Message uses this method's own parameter names (ttl/stale), not the
+          # client-facing tombstone_ttl/invalidate names Dalli::Client validates
+          # against -- this guard is also reachable by internal callers (tests,
+          # direct RequestFormatter use) that never go through the client.
+          raise ArgumentError, 'ttl requires stale: true' if ttl && !stale
+
+          cmd = "md #{encoded_key(key)}"
           cmd << cas_string(cas)
-          cmd << " T#{ttl}" if ttl
           cmd << ' I' if stale # Mark stale instead of deleting
+          cmd << " T#{Integer(ttl)}" if ttl
+          cmd << ' x' if drop_value # Drop the value but keep the item
           cmd << ' q' if quiet
+          cmd << routing_tokens(p_token: p_token, l_token: l_token)
           cmd << TERMINATOR
         end
 
-        def self.meta_arithmetic(key:, delta:, initial:, incr: true, cas: nil, ttl: nil, base64: false, quiet: false)
-          cmd = "ma #{key} v"
-          cmd << ' b' if base64
+        # Tombstone and routing-token flags apply to every key in the batch;
+        # see meta_delete.
+        def multi_meta_delete(keys, stale: false, ttl: nil, drop_value: false, p_token: nil, l_token: nil)
+          raise ArgumentError, 'tombstone_ttl requires invalidate: true' if ttl && !stale
+
+          suffix = +''
+          suffix << ' I' if stale
+          suffix << " T#{Integer(ttl)}" if ttl
+          suffix << ' x' if drop_value
+          suffix << ' q'
+          suffix << routing_tokens(p_token: p_token, l_token: l_token)
+          suffix << TERMINATOR
+
+          buffer = ''.b
+          keys.each do |key|
+            buffer << 'md ' << encoded_key(key) << suffix
+          end
+          buffer << META_NOOP
+        end
+
+        def meta_arithmetic(key:, delta:, initial:, incr: true, cas: nil, ttl: nil, quiet: false,
+                            p_token: nil, l_token: nil)
+          cmd = "ma #{encoded_key(key)} v"
           cmd << " D#{delta}" if delta
           cmd << " J#{initial}" if initial
           # Always set a TTL if an initial value is specified
@@ -90,22 +177,53 @@ module Dalli
           cmd << cas_string(cas)
           cmd << ' q' if quiet
           cmd << " M#{incr ? 'I' : 'D'}"
+          cmd << routing_tokens(p_token: p_token, l_token: l_token)
           cmd << TERMINATOR
         end
+
+        # Builds the wire-format suffix for opaque routing tokens (P and L).
+        # memcached itself ignores these; they exist as hints for a proxy or
+        # router sitting between the client and memcached. See protocol.txt:
+        # "All commands accept tokens 'P' and 'L' which are completely ignored.
+        # The arguments to 'P' and 'L' can be used as hints or path
+        # specifications to a proxy or router inbetween a client and a
+        # memcached daemon."
+        #
+        # Empty / nil tokens are treated as no-ops. CRLF and null bytes are
+        # rejected with ArgumentError to prevent the token from being used as a
+        # wire-protocol injection vector (e.g. "foo\r\nflush_all\r\n" would
+        # otherwise be parsed as a second command by memcached or any
+        # intermediate proxy/LB).
+        def routing_tokens(p_token: nil, l_token: nil)
+          # Only an empty *String* is a no-op. Checking respond_to?(:empty?)
+          # instead would also swallow p_token: [] / {} before the type check
+          # below ever runs, silently dropping caller mistakes that should
+          # raise "must be a String".
+          p_token = nil if p_token.is_a?(String) && p_token.empty?
+          l_token = nil if l_token.is_a?(String) && l_token.empty?
+          validate_routing_token!('p_token', p_token)
+          validate_routing_token!('l_token', l_token)
+          return '' unless p_token || l_token
+
+          s = +''
+          s << " P#{p_token}" if p_token
+          s << " L#{l_token}" if l_token
+          s
+        end
         # rubocop:enable Metrics/CyclomaticComplexity
         # rubocop:enable Metrics/ParameterLists
         # rubocop:enable Metrics/PerceivedComplexity
 
         META_NOOP = "mn#{TERMINATOR}".freeze
-        def self.meta_noop
+        def meta_noop
           META_NOOP
         end
 
-        def self.version
+        def version
           "version#{TERMINATOR}"
         end
 
-        def self.flush(delay: nil, quiet: false)
+        def flush(delay: nil, quiet: false)
           cmd = +'flush_all'
           cmd << " #{parse_to_64_bit_int(delay, 0)}" if delay
           cmd << ' noreply' if quiet
@@ -114,7 +232,7 @@ module Dalli
 
         ALLOWED_STATS_ARGS = [nil, '', 'items', 'slabs', 'settings', 'reset'].freeze
 
-        def self.stats(arg = nil)
+        def stats(arg = nil)
           raise ArgumentError, "Invalid stats argument: #{arg.inspect}" unless ALLOWED_STATS_ARGS.include?(arg)
 
           cmd = +'stats'
@@ -122,7 +240,28 @@ module Dalli
           cmd << TERMINATOR
         end
 
-        def self.mode_to_token(mode)
+        def encoded_key(key)
+          if KeyRegularizer.required?(key)
+            KeyRegularizer.encode(key) << ' b'
+          else
+            key
+          end
+        end
+
+        private
+
+        # Disallowed bytes: CR, LF, NUL. Any of these embedded in a routing
+        # token would let the caller inject a second wire-protocol command.
+        ROUTING_TOKEN_FORBIDDEN = /[\r\n\0]/
+        private_constant :ROUTING_TOKEN_FORBIDDEN
+
+        def validate_routing_token!(name, value)
+          return if value.nil?
+          raise ArgumentError, "#{name} must be a String, got #{value.class}" unless value.is_a?(String)
+          raise ArgumentError, "#{name} must not contain CRLF or null bytes" if value.match?(ROUTING_TOKEN_FORBIDDEN)
+        end
+
+        def mode_to_token(mode)
           case mode
           when :add
             'E'
@@ -137,12 +276,12 @@ module Dalli
           end
         end
 
-        def self.cas_string(cas)
+        def cas_string(cas)
           cas = parse_to_64_bit_int(cas, nil)
           cas.nil? || cas.zero? ? '' : " C#{cas}"
         end
 
-        def self.parse_to_64_bit_int(val, default)
+        def parse_to_64_bit_int(val, default)
           val.nil? ? nil : Integer(val)
         rescue ArgumentError
           # Sanitize to default if it isn't parsable as an integer