dalli 3.2.8 → 5.0.5

data/lib/dalli/protocol/meta.rb

@@ -25,21 +25,26 @@ module Dalli
       # Retrieval Commands
       def get(key, options = nil)
         encoded_key, base64 = KeyRegularizer.encode(key)
-        req = RequestFormatter.meta_get(key: encoded_key, base64: base64)
-        write(req)
+        # 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)
+        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)
-        RequestFormatter.meta_get(key: encoded_key, return_cas: true, base64: base64, quiet: true)
+        # 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?)
       end
 
       def gat(key, ttl, options = nil)
         ttl = TtlSanitizer.sanitize(ttl)
         encoded_key, base64 = KeyRegularizer.encode(key)
-        req = RequestFormatter.meta_get(key: encoded_key, ttl: ttl, base64: base64)
-        write(req)
+        skip_flags = raw_mode? || (options && options[:raw])
+        req = RequestFormatter.meta_get(key: encoded_key, ttl: ttl, base64: base64, skip_flags: skip_flags)
+        flushed_write(req)
         response_processor.meta_get_with_value(cache_nils: cache_nils?(options))
       end
 
@@ -47,7 +52,7 @@ module Dalli
         ttl = TtlSanitizer.sanitize(ttl)
         encoded_key, base64 = KeyRegularizer.encode(key)
         req = RequestFormatter.meta_get(key: encoded_key, ttl: ttl, value: false, base64: base64)
-        write(req)
+        flushed_write(req)
         response_processor.meta_get_without_value
       end
 
@@ -56,16 +61,75 @@ module Dalli
       def cas(key)
         encoded_key, base64 = KeyRegularizer.encode(key)
         req = RequestFormatter.meta_get(key: encoded_key, value: true, return_cas: true, base64: base64)
-        write(req)
+        flushed_write(req)
         response_processor.meta_get_with_value_and_cas
       end
 
+      # Comprehensive meta get with support for all metadata flags.
+      # @note Requires memcached 1.6+ (meta protocol feature)
+      #
+      # This is the full-featured get method that supports:
+      # - Thundering herd protection (vivify_ttl, recache_ttl)
+      # - Item metadata (hit_status, last_access)
+      # - LRU control (skip_lru_bump)
+      #
+      # @param key [String] the key to retrieve
+      # @param options [Hash] options controlling what metadata to return
+      #   - :vivify_ttl [Integer] creates a stub on miss with this TTL (N flag)
+      #   - :recache_ttl [Integer] wins recache race if remaining TTL is below this (R flag)
+      #   - :return_hit_status [Boolean] return whether item was previously accessed (h flag)
+      #   - :return_last_access [Boolean] return seconds since last access (l flag)
+      #   - :skip_lru_bump [Boolean] don't bump LRU or update access stats (u flag)
+      #   - :cache_nils [Boolean] whether to cache nil values
+      # @return [Hash] containing:
+      #   - :value - the cached value (or nil on miss)
+      #   - :cas - the CAS value
+      #   - :won_recache - true if client won recache race (W flag)
+      #   - :stale - true if item is stale (X flag)
+      #   - :lost_recache - true if another client is recaching (Z flag)
+      #   - :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,
+          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]
+        )
+        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]
+        )
+      end
+
+      # Delete with stale invalidation instead of actual deletion.
+      # Used with thundering herd protection to mark items as stale rather than removing them.
+      # @note Requires memcached 1.6+ (meta protocol feature)
+      #
+      # @param key [String] the key to invalidate
+      # @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)
+        flushed_write(req)
+        response_processor.meta_delete
+      end
+
       # Storage Commands
       def set(key, value, ttl, cas, options)
         write_storage_req(:set, key, value, ttl, cas, options)
         response_processor.meta_set_with_cas unless quiet?
       end
 
+      # Pipelined set - writes a quiet set request without reading response.
+      # Used by PipelinedSetter for bulk operations.
+      def pipelined_set(key, value, ttl, options)
+        write_storage_req(:set, key, value, ttl, nil, options, quiet: true)
+      end
+
       def add(key, value, ttl, options)
         write_storage_req(:add, key, value, ttl, nil, options)
         response_processor.meta_set_with_cas unless quiet?
@@ -77,14 +141,15 @@ module Dalli
       end
 
       # rubocop:disable Metrics/ParameterLists
-      def write_storage_req(mode, key, raw_value, ttl = nil, cas = nil, 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,
                                         bitflags: bitflags, cas: cas,
-                                        ttl: ttl, mode: mode, quiet: quiet?, base64: base64)
-        write(req)
+                                        ttl: ttl, mode: mode, quiet: quiet, base64: base64)
+        write("#{req}#{value}#{TERMINATOR}")
+        @connection_manager.flush unless quiet
       end
       # rubocop:enable Metrics/ParameterLists
 
@@ -104,7 +169,8 @@ module Dalli
         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?)
-        write(req)
+        write("#{req}#{value}#{TERMINATOR}")
+        @connection_manager.flush unless quiet?
       end
       # rubocop:enable Metrics/ParameterLists
 
@@ -114,9 +180,18 @@ module Dalli
         req = RequestFormatter.meta_delete(key: encoded_key, cas: cas,
                                            base64: base64, quiet: quiet?)
         write(req)
+        @connection_manager.flush unless quiet?
         response_processor.meta_delete unless quiet?
       end
 
+      # 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)
+        write(req)
+      end
+
       # Arithmetic Commands
       def decr(key, count, ttl, initial)
         decr_incr false, key, count, ttl, initial
@@ -131,12 +206,14 @@ module Dalli
         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))
+        @connection_manager.flush unless quiet?
         response_processor.decr_incr unless quiet?
       end
 
       # Other Commands
       def flush(delay = 0)
         write(RequestFormatter.flush(delay: delay))
+        @connection_manager.flush unless quiet?
         response_processor.flush unless quiet?
       end
 
@@ -148,31 +225,119 @@ module Dalli
       end
 
       def stats(info = nil)
-        write(RequestFormatter.stats(info))
+        flushed_write(RequestFormatter.stats(info))
         response_processor.stats
       end
 
       def reset_stats
-        write(RequestFormatter.stats('reset'))
+        flushed_write(RequestFormatter.stats('reset'))
         response_processor.reset
       end
 
       def version
-        write(RequestFormatter.version)
+        flushed_write(RequestFormatter.version)
         response_processor.version
       end
 
       def write_noop
-        write(RequestFormatter.meta_noop)
+        flushed_write(RequestFormatter.meta_noop)
+      end
+
+      # 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)
+        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
+        flushed_write(buffer)
+        buffer.clear
+
+        read_multi_get_responses(is_raw)
+      end
+
+      def read_multi_get_responses(is_raw)
+        hash = {}
+        key_index = is_raw ? 2 : 3
+        while (line = @connection_manager.read_line)
+          break if line.start_with?('MN')
+          next unless line.start_with?('VA ')
+
+          key, value = parse_multi_get_value(line, key_index, is_raw)
+          hash[key] = value if key
+        end
+        hash
+      end
+
+      def parse_multi_get_value(line, key_index, is_raw)
+        tokens = line.chomp!(TERMINATOR).split
+        value = @connection_manager.read(tokens[1].to_i + TERMINATOR.bytesize)&.chomp!(TERMINATOR)
+        raw_key = tokens[key_index]
+        return unless raw_key
+
+        key = KeyRegularizer.decode(raw_key[1..], 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
+        end
+        buffer << RequestFormatter.meta_noop
+        flushed_write(buffer)
+        buffer.clear
+        response_processor.consume_all_responses_until_mn
       end
+      # rubocop:enable Metrics/AbcSize
 
-      def authenticate_connection
-        raise Dalli::DalliError, 'Authentication not supported for the meta protocol.'
+      # 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
+        flushed_write(buffer)
+        buffer.clear
+        response_processor.consume_all_responses_until_mn
       end
 
-      require_relative 'meta/key_regularizer'
-      require_relative 'meta/request_formatter'
-      require_relative 'meta/response_processor'
+      require_relative 'key_regularizer'
+      require_relative 'request_formatter'
+      require_relative 'response_processor'
     end
   end
 end

data/lib/dalli/protocol/{meta/request_formatter.rb → request_formatter.rb}

@@ -13,17 +13,46 @@ module Dalli
         # and introducing an intermediate object seems like overkill.
         #
         # rubocop:disable Metrics/CyclomaticComplexity
-        # rubocop:disable Metrics/MethodLength
         # rubocop:disable Metrics/ParameterLists
         # rubocop:disable Metrics/PerceivedComplexity
-        def self.meta_get(key:, value: true, return_cas: false, ttl: nil, base64: false, quiet: false)
+        #
+        # Meta get flags:
+        #
+        # Thundering herd protection:
+        # - vivify_ttl (N flag): On miss, create a stub item and return W flag. The TTL
+        #   specifies how long the stub lives. Other clients see X (stale) and Z (lost race).
+        # - recache_ttl (R flag): If item's remaining TTL is below this threshold, return W
+        #   flag to indicate this client should recache. Other clients get Z (lost race).
+        #
+        # Metadata flags:
+        # - return_hit_status (h flag): Return whether item has been hit before (0 or 1)
+        # - return_last_access (l flag): Return seconds since item was last accessed
+        # - skip_lru_bump (u flag): Don't bump item in LRU, don't update hit status or last access
+        #
+        # Response flags (parsed by response processor):
+        # - W: Client won the right to recache this item
+        # - X: Item is stale (another client is regenerating)
+        # - 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}"
-          cmd << ' v f' if value
+          # 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 << ' k q s' if quiet # Return the key in the response if quiet
-          cmd + TERMINATOR
+          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 << ' 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)
@@ -36,17 +65,19 @@ module Dalli
           cmd << " M#{mode_to_token(mode)}"
           cmd << ' q' if quiet
           cmd << TERMINATOR
-          cmd << value
-          cmd + TERMINATOR
         end
 
-        def self.meta_delete(key:, cas: nil, ttl: nil, base64: false, quiet: false)
+        # 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
           cmd << cas_string(cas)
           cmd << " T#{ttl}" if ttl
+          cmd << ' I' if stale # Mark stale instead of deleting
           cmd << ' q' if quiet
-          cmd + TERMINATOR
+          cmd << TERMINATOR
         end
 
         def self.meta_arithmetic(key:, delta:, initial:, incr: true, cas: nil, ttl: nil, base64: false, quiet: false)
@@ -59,15 +90,15 @@ module Dalli
           cmd << cas_string(cas)
           cmd << ' q' if quiet
           cmd << " M#{incr ? 'I' : 'D'}"
-          cmd + TERMINATOR
+          cmd << TERMINATOR
         end
         # rubocop:enable Metrics/CyclomaticComplexity
-        # rubocop:enable Metrics/MethodLength
         # rubocop:enable Metrics/ParameterLists
         # rubocop:enable Metrics/PerceivedComplexity
 
+        META_NOOP = "mn#{TERMINATOR}".freeze
         def self.meta_noop
-          "mn#{TERMINATOR}"
+          META_NOOP
         end
 
         def self.version
@@ -78,16 +109,19 @@ module Dalli
           cmd = +'flush_all'
           cmd << " #{parse_to_64_bit_int(delay, 0)}" if delay
           cmd << ' noreply' if quiet
-          cmd + TERMINATOR
+          cmd << TERMINATOR
         end
 
+        ALLOWED_STATS_ARGS = [nil, '', 'items', 'slabs', 'settings', 'reset'].freeze
+
         def self.stats(arg = nil)
+          raise ArgumentError, "Invalid stats argument: #{arg.inspect}" unless ALLOWED_STATS_ARGS.include?(arg)
+
           cmd = +'stats'
-          cmd << " #{arg}" if arg
-          cmd + TERMINATOR
+          cmd << " #{arg}" if arg && !arg.empty?
+          cmd << TERMINATOR
         end
 
-        # rubocop:disable Metrics/MethodLength
         def self.mode_to_token(mode)
           case mode
           when :add
@@ -102,7 +136,6 @@ module Dalli
             'S'
           end
         end
-        # rubocop:enable Metrics/MethodLength
 
         def self.cas_string(cas)
           cas = parse_to_64_bit_int(cas, nil)

data/lib/dalli/protocol/response_buffer.rb

@@ -7,48 +7,72 @@ module Dalli
   module Protocol
     ##
     # Manages the buffer for responses from memcached.
+    # Uses an offset-based approach to avoid string allocations
+    # when advancing through parsed responses.
     ##
     class ResponseBuffer
+      # Compact the buffer when the consumed portion exceeds this
+      # threshold and represents more than half the buffer
+      COMPACT_THRESHOLD = 4096
+
       def initialize(io_source, response_processor)
         @io_source = io_source
         @response_processor = response_processor
         @buffer = nil
+        @offset = 0
       end
 
       def read
         @buffer << @io_source.read_nonblock
       end
 
-      # Attempts to process a single response from the buffer.  Starts
-      # by advancing the buffer to the specified start position
+      # Attempts to process a single response from the buffer,
+      # advancing the offset past the consumed bytes.
       def process_single_getk_response
-        bytes, status, cas, key, value = @response_processor.getk_response_from_buffer(@buffer)
-        advance(bytes)
+        bytes, status, cas, key, value = @response_processor.getk_response_from_buffer(@buffer, @offset)
+        @offset += bytes
+        compact_if_needed
         [status, cas, key, value]
       end
 
-      # Advances the internal response buffer by bytes_to_advance
-      # bytes.  The
-      def advance(bytes_to_advance)
-        return unless bytes_to_advance.positive?
-
-        @buffer = @buffer.byteslice(bytes_to_advance..-1)
-      end
-
       # Resets the internal buffer to an empty state,
       # so that we're ready to read pipelined responses
       def reset
         @buffer = ''.b
+        @offset = 0
+      end
+
+      # Ensures the buffer is initialized for reading without discarding
+      # existing data. Used by interleaved pipelined get which may have
+      # already buffered partial responses during the send phase.
+      def ensure_ready
+        return if in_progress?
+
+        @buffer = ''.b
+        @offset = 0
       end
 
       # Clear the internal response buffer
       def clear
         @buffer = nil
+        @offset = 0
       end
 
       def in_progress?
         !@buffer.nil?
       end
+
+      private
+
+      # Only compact when we've consumed a significant portion of the buffer.
+      # This avoids per-response string allocation while preventing unbounded
+      # memory growth for large pipelines.
+      def compact_if_needed
+        return unless @offset > COMPACT_THRESHOLD && @offset > @buffer.bytesize / 2
+
+        @buffer = @buffer.byteslice(@offset..)
+        @offset = 0
+      end
     end
   end
 end