dalli 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86e39b2869b7c916472e88e6cbbfb6aa1f6533aa35c9e1f1c704cffcbc680f8a
-  data.tar.gz: bf2e56610c6bae187d561ccf09105e6f5b4a29eed1308d089745ef22cf5b673b
+  metadata.gz: e342d39d58d552607783486a9c9f0ffa23d9c479079c62cb760ec84a97d064da
+  data.tar.gz: 1ae923ede204d0a3e82426404cfb4882f4414a12cb351cf3d04b9ef8653051ce
 SHA512:
-  metadata.gz: e2faab814abb4b25a53d87048f7e4e81e49c609bd64725cb18607670110da3d5b8038544598c44575831b9038500f9d8220a56ec28c16b9517a21d442212d12b
-  data.tar.gz: 3e5a7c326c908d72d2d8ce2211b27f67acebbbf97c279c5faf3ba2914ec7409df7f259a9082d82903cc9ae6b6716a137994aba849321546b8d3d3a35f8f7f5af
+  metadata.gz: aeb1bec84092f4e07db884b415d6b25375dc995fff04cc58a1764d9ad0937986ba7ff5db5a665a831bd8ab488b3fa4868fce79834e93a26848bc37ac1c9f9855
+  data.tar.gz: 8c5a4e21f4b0a86279bf28edc729c0a1981964438342117f3bc180d15d5cdfc93e395913267db7af66b3907416051be7629e687708c163f4d4015d4e2a768508

data/CHANGELOG.md

@@ -1,6 +1,37 @@
 Dalli Changelog
 =====================
 
+4.1.0
+==========
+
+New Features:
+
+- Add `set_multi` for efficient bulk set operations using pipelined requests
+- Add `delete_multi` for efficient bulk delete operations using pipelined requests
+- Add `fetch_with_lock` for thundering herd protection using meta protocol's vivify/recache flags (requires memcached 1.6+)
+- Add thundering herd protection support to meta protocol (requires memcached 1.6+):
+  - `N` (vivify) flag for creating stubs on cache miss
+  - `R` (recache) flag for winning recache race when TTL is below threshold
+  - Response flags `W` (won recache), `X` (stale), `Z` (lost race)
+  - `delete_stale` method for marking items as stale instead of deleting
+- Add `get_with_metadata` for advanced cache operations with metadata retrieval (requires memcached 1.6+):
+  - Returns hash with `:value`, `:cas`, `:won_recache`, `:stale`, `:lost_recache`
+  - Optional `:return_hit_status` returns `:hit_before` (true/false for previous access)
+  - Optional `:return_last_access` returns `:last_access` (seconds since last access)
+  - Optional `:skip_lru_bump` prevents LRU update on access
+  - Optional `:vivify_ttl` and `:recache_ttl` for thundering herd protection
+
+Deprecations:
+
+- Binary protocol is deprecated and will be removed in Dalli 5.0. Use `protocol: :meta` instead (requires memcached 1.6+)
+- SASL authentication is deprecated and will be removed in Dalli 5.0. Consider using network-level security or memcached's TLS support
+
+4.0.1
+==========
+
+- Add `:raw` client option to skip serialization entirely, returning raw byte strings
+- Handle `OpenSSL::SSL::SSLError` in connection manager
+
 4.0.0
 ==========
 

data/Gemfile

@@ -5,11 +5,18 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
+  gem 'benchmark'
   gem 'cgi'
   gem 'connection_pool'
   gem 'debug' unless RUBY_PLATFORM == 'java'
-  gem 'minitest', '~> 5'
-  gem 'rack', '~> 2.0', '>= 2.2.0'
+  if RUBY_VERSION >= '3.2'
+    gem 'minitest', '~> 6'
+    gem 'minitest-mock'
+  else
+    gem 'minitest', '~> 5'
+  end
+  gem 'rack', '~> 3'
+  gem 'rack-session'
   gem 'rake', '~> 13.0'
   gem 'rubocop'
   gem 'rubocop-minitest'

data/README.md

@@ -14,6 +14,32 @@ Dalli supports:
 
 The name is a variant of Salvador Dali for his famous painting [The Persistence of Memory](http://en.wikipedia.org/wiki/The_Persistence_of_Memory).
 
+## Requirements
+
+* Ruby 3.1 or later
+* memcached 1.4 or later (1.6+ recommended for meta protocol support)
+
+## Protocol Options
+
+Dalli supports two protocols for communicating with memcached:
+
+* `:binary` (default) - Works with all memcached versions, supports SASL authentication
+* `:meta` - Requires memcached 1.6+, better performance for some operations, no authentication support
+
+```ruby
+Dalli::Client.new('localhost:11211', protocol: :meta)
+```
+
+## Security Note
+
+By default, Dalli uses Ruby's Marshal for serialization. Deserializing untrusted data with Marshal can lead to remote code execution. If you cache user-controlled data, consider using a safer serializer:
+
+```ruby
+Dalli::Client.new('localhost:11211', serializer: JSON)
+```
+
+See the [4.0-Upgrade.md](4.0-Upgrade.md) guide for more information.
+
 ![Persistence of Memory](https://upload.wikimedia.org/wikipedia/en/d/dd/The_Persistence_of_Memory.jpg)
 
 

data/lib/dalli/client.rb

@@ -41,6 +41,11 @@ module Dalli
     # - :compressor - defaults to Dalli::Compressor, a Zlib-based implementation
     # - :cache_nils - defaults to false, if true Dalli will not treat cached nil values as 'not found' for
     #                 #fetch operations.
+    # - :raw        - If set, disables serialization and compression entirely at the client level.
+    #                 Only String values are supported. This is useful when the caller handles its own
+    #                 serialization (e.g., Rails' ActiveSupport::Cache). Note: this is different from
+    #                 the per-request :raw option which converts values to strings but still uses the
+    #                 serialization pipeline.
     # - :digest_class - defaults to Digest::MD5, allows you to pass in an object that responds to the hexdigest method,
     #                   useful for injecting a FIPS compliant hash object.
     # - :protocol - one of either :binary or :meta, defaulting to :binary.  This sets the protocol that Dalli uses
@@ -51,6 +56,7 @@ module Dalli
       @options = normalize_options(options)
       @key_manager = ::Dalli::KeyManager.new(@options)
       @ring = nil
+      emit_deprecation_warnings
     end
 
     #
@@ -91,6 +97,51 @@ module Dalli
       yield value, cas
     end
 
+    ##
+    # Get value with extended metadata using the meta protocol.
+    #
+    # IMPORTANT: This method requires memcached 1.6+ and the meta protocol (protocol: :meta).
+    # It will raise an error if used with the binary protocol.
+    #
+    # @param key [String] the cache key
+    # @param options [Hash] options controlling what metadata to return
+    #   - :return_cas [Boolean] return the CAS value (default: true)
+    #   - :return_hit_status [Boolean] return whether item was previously accessed
+    #   - :return_last_access [Boolean] return seconds since last access
+    #   - :skip_lru_bump [Boolean] don't bump LRU or update access stats
+    #
+    # @return [Hash] containing:
+    #   - :value - the cached value (or nil on miss)
+    #   - :cas - the CAS value
+    #   - :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)
+    #
+    # @example Get with hit status
+    #   result = client.get_with_metadata('key', return_hit_status: true)
+    #   # => { value: "data", cas: 123, hit_before: true }
+    #
+    # @example Get with all metadata without affecting LRU
+    #   result = client.get_with_metadata('key',
+    #     return_hit_status: true,
+    #     return_last_access: true,
+    #     skip_lru_bump: true
+    #   )
+    #   # => { value: "data", cas: 123, hit_before: true, last_access: 42 }
+    #
+    def get_with_metadata(key, options = {})
+      raise_unless_meta_protocol!
+
+      key = key.to_s
+      key = @key_manager.validate_key(key)
+
+      server = ring.server_for_key(key)
+      server.request(:meta_get, key, options)
+    rescue NetworkError => e
+      Dalli.logger.debug { e.inspect }
+      Dalli.logger.debug { 'retrying get_with_metadata with new server' }
+      retry
+    end
+
     ##
     # Fetch multiple keys efficiently.
     # If a block is given, yields key/value pairs one at a time.
@@ -144,6 +195,69 @@ module Dalli
       new_val
     end
 
+    ##
+    # Fetch the value with thundering herd protection using the meta protocol's
+    # N (vivify) and R (recache) flags.
+    #
+    # This method prevents multiple clients from simultaneously regenerating the same
+    # cache entry (the "thundering herd" problem). Only one client wins the right to
+    # regenerate; other clients receive the stale value (if available) or wait.
+    #
+    # IMPORTANT: This method requires memcached 1.6+ and the meta protocol (protocol: :meta).
+    # It will raise an error if used with the binary protocol.
+    #
+    # @param key [String] the cache key
+    # @param ttl [Integer] time-to-live for the cached value in seconds
+    # @param lock_ttl [Integer] how long the lock/stub lives (default: 30 seconds)
+    #   This is the maximum time other clients will return stale data while
+    #   waiting for regeneration. Should be longer than your expected regeneration time.
+    # @param recache_threshold [Integer, nil] if set, win the recache race when the
+    #   item's remaining TTL is below this threshold. Useful for proactive recaching.
+    # @param req_options [Hash] options passed to set operations (e.g., raw: true)
+    #
+    # @yield Block to regenerate the value (only called if this client won the race)
+    # @return [Object] the cached value (may be stale if another client is regenerating)
+    #
+    # @example Basic usage
+    #   client.fetch_with_lock('expensive_key', ttl: 300, lock_ttl: 30) do
+    #     expensive_database_query
+    #   end
+    #
+    # @example With proactive recaching (recache before expiry)
+    #   client.fetch_with_lock('key', ttl: 300, lock_ttl: 30, recache_threshold: 60) do
+    #     expensive_operation
+    #   end
+    #
+    def fetch_with_lock(key, ttl: nil, lock_ttl: 30, recache_threshold: nil, req_options: nil)
+      raise ArgumentError, 'Block is required for fetch_with_lock' unless block_given?
+
+      raise_unless_meta_protocol!
+
+      key = key.to_s
+      key = @key_manager.validate_key(key)
+
+      server = ring.server_for_key(key)
+      result = server.request(:meta_get, key, {
+                                vivify_ttl: lock_ttl,
+                                recache_ttl: recache_threshold
+                              })
+
+      if result[:won_recache]
+        # This client won the race - regenerate the value
+        new_val = yield
+        set(key, new_val, ttl_or_default(ttl), req_options)
+        new_val
+      else
+        # Another client is regenerating, or value exists and isn't stale
+        # Return the existing value
+        result[:value]
+      end
+    rescue NetworkError => e
+      Dalli.logger.debug { e.inspect }
+      Dalli.logger.debug { 'retrying fetch_with_lock with new server' }
+      retry
+    end
+
     ##
     # compare and swap values using optimistic locking.
     # Fetch the existing value for key.
@@ -201,6 +315,24 @@ module Dalli
       set_cas(key, value, 0, ttl, req_options)
     end
 
+    ##
+    # Set multiple keys and values efficiently using pipelining.
+    # This method is more efficient than calling set() in a loop because
+    # it batches requests by server and uses quiet mode.
+    #
+    # @param hash [Hash] key-value pairs to set
+    # @param ttl [Integer] time-to-live in seconds (optional, uses default if not provided)
+    # @param req_options [Hash] options passed to each set operation
+    # @return [void]
+    #
+    # Example:
+    #   client.set_multi({ 'key1' => 'value1', 'key2' => 'value2' }, 300)
+    def set_multi(hash, ttl = nil, req_options = nil)
+      return if hash.empty?
+
+      pipelined_setter.process(hash, ttl_or_default(ttl), req_options)
+    end
+
     ##
     # Set the key-value pair, verifying existing CAS.
     # Returns the resulting CAS value if succeeded, and falsy otherwise.
@@ -240,6 +372,22 @@ module Dalli
       delete_cas(key, 0)
     end
 
+    ##
+    # Delete multiple keys efficiently using pipelining.
+    # This method is more efficient than calling delete() in a loop because
+    # it batches requests by server and uses quiet mode.
+    #
+    # @param keys [Array<String>] keys to delete
+    # @return [void]
+    #
+    # Example:
+    #   client.delete_multi(['key1', 'key2', 'key3'])
+    def delete_multi(keys)
+      return if keys.empty?
+
+      pipelined_deleter.process(keys)
+    end
+
     ##
     # Append value to the value already stored on the server for 'key'.
     # Appending only works for values stored with :raw => true.
@@ -440,5 +588,23 @@ module Dalli
     def pipelined_getter
       PipelinedGetter.new(ring, @key_manager)
     end
+
+    def pipelined_setter
+      PipelinedSetter.new(ring, @key_manager)
+    end
+
+    def pipelined_deleter
+      PipelinedDeleter.new(ring, @key_manager)
+    end
+
+    def raise_unless_meta_protocol!
+      return if protocol_implementation == Dalli::Protocol::Meta
+
+      raise Dalli::DalliError,
+            'This operation requires the meta protocol (memcached 1.6+). ' \
+            'Use protocol: :meta when creating the client.'
+    end
+
+    include ProtocolDeprecations
   end
 end

data/lib/dalli/pipelined_deleter.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Dalli
+  ##
+  # Contains logic for the pipelined delete operations implemented by the client.
+  # Efficiently deletes multiple keys by grouping requests by server
+  # and using quiet mode to minimize round trips.
+  ##
+  class PipelinedDeleter
+    def initialize(ring, key_manager)
+      @ring = ring
+      @key_manager = key_manager
+    end
+
+    ##
+    # Deletes multiple keys from memcached.
+    #
+    # @param keys [Array<String>] keys to delete
+    # @return [void]
+    ##
+    def process(keys)
+      return if keys.empty?
+
+      @ring.lock do
+        servers = setup_requests(keys)
+        finish_requests(servers)
+      end
+    rescue NetworkError => e
+      Dalli.logger.debug { e.inspect }
+      Dalli.logger.debug { 'retrying pipelined deletes because of network error' }
+      retry
+    end
+
+    private
+
+    def setup_requests(keys)
+      groups = groups_for_keys(keys)
+      make_delete_requests(groups)
+      groups.keys
+    end
+
+    ##
+    # Loop through the server-grouped sets of keys, writing
+    # the corresponding quiet delete requests to the appropriate servers
+    ##
+    def make_delete_requests(groups)
+      groups.each do |server, keys_for_server|
+        keys_for_server.each do |key|
+          server.request(:pipelined_delete, key)
+        rescue DalliError, NetworkError => e
+          Dalli.logger.debug { e.inspect }
+          Dalli.logger.debug { "unable to delete key #{key} for server #{server.name}" }
+        end
+      end
+    end
+
+    ##
+    # Sends noop to each server to flush responses and ensure all deletes complete.
+    ##
+    def finish_requests(servers)
+      servers.each do |server|
+        server.request(:noop)
+      rescue DalliError, NetworkError => e
+        Dalli.logger.debug { e.inspect }
+        Dalli.logger.debug { "unable to complete pipelined delete on server #{server.name}" }
+      end
+    end
+
+    def groups_for_keys(keys)
+      validated_keys = keys.map { |k| @key_manager.validate_key(k.to_s) }
+      groups = @ring.keys_grouped_by_server(validated_keys)
+
+      if (unfound_keys = groups.delete(nil))
+        Dalli.logger.debug do
+          "unable to delete #{unfound_keys.length} keys because no matching server was found"
+        end
+      end
+
+      groups
+    end
+  end
+end

data/lib/dalli/pipelined_setter.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Dalli
+  ##
+  # Contains logic for the pipelined set operations implemented by the client.
+  # Efficiently writes multiple key-value pairs by grouping requests by server
+  # and using quiet mode to minimize round trips.
+  ##
+  class PipelinedSetter
+    def initialize(ring, key_manager)
+      @ring = ring
+      @key_manager = key_manager
+    end
+
+    ##
+    # Writes multiple key-value pairs to memcached.
+    # Raises an error if any server is unavailable.
+    #
+    # @param hash [Hash] key-value pairs to set
+    # @param ttl [Integer] time-to-live in seconds
+    # @param req_options [Hash] options passed to each set operation
+    # @return [void]
+    ##
+    def process(hash, ttl, req_options)
+      return if hash.empty?
+
+      @ring.lock do
+        servers = setup_requests(hash, ttl, req_options)
+        finish_requests(servers)
+      end
+    rescue NetworkError => e
+      Dalli.logger.debug { e.inspect }
+      Dalli.logger.debug { 'retrying pipelined sets because of network error' }
+      retry
+    end
+
+    private
+
+    def setup_requests(hash, ttl, req_options)
+      groups = groups_for_keys(hash.keys)
+      make_set_requests(groups, hash, ttl, req_options)
+      groups.keys
+    end
+
+    ##
+    # Loop through the server-grouped sets of keys, writing
+    # the corresponding quiet set requests to the appropriate servers
+    ##
+    def make_set_requests(groups, hash, ttl, req_options)
+      groups.each do |server, keys_for_server|
+        keys_for_server.each do |key|
+          original_key = @key_manager.key_without_namespace(key)
+          value = hash[original_key]
+          server.request(:pipelined_set, key, value, ttl, req_options)
+        rescue DalliError, NetworkError => e
+          Dalli.logger.debug { e.inspect }
+          Dalli.logger.debug { "unable to set key #{key} for server #{server.name}" }
+        end
+      end
+    end
+
+    ##
+    # Sends noop to each server to flush responses and ensure all writes complete.
+    ##
+    def finish_requests(servers)
+      servers.each do |server|
+        server.request(:noop)
+      rescue DalliError, NetworkError => e
+        Dalli.logger.debug { e.inspect }
+        Dalli.logger.debug { "unable to complete pipelined set on server #{server.name}" }
+      end
+    end
+
+    def groups_for_keys(keys)
+      validated_keys = keys.map { |k| @key_manager.validate_key(k.to_s) }
+      groups = @ring.keys_grouped_by_server(validated_keys)
+
+      if (unfound_keys = groups.delete(nil))
+        Dalli.logger.debug do
+          "unable to set #{unfound_keys.length} keys because no matching server was found"
+        end
+      end
+
+      groups
+    end
+  end
+end

data/lib/dalli/protocol/base.rb

@@ -23,7 +23,7 @@ module Dalli
       def initialize(attribs, client_options = {})
         hostname, port, socket_type, @weight, user_creds = ServerConfigParser.parse(attribs)
         @options = client_options.merge(user_creds)
-        @value_marshaller = ValueMarshaller.new(@options)
+        @value_marshaller = client_options[:raw] ? StringMarshaller.new(@options) : ValueMarshaller.new(@options)
         @connection_manager = ConnectionManager.new(hostname, port, socket_type, @options)
       end
 
@@ -106,7 +106,7 @@ module Dalli
         end
 
         values
-      rescue SystemCallError, *TIMEOUT_ERRORS, EOFError => e
+      rescue SystemCallError, *TIMEOUT_ERRORS, *SSL_ERRORS, EOFError => e
         @connection_manager.error_on_request!(e)
       end
 

data/lib/dalli/protocol/binary.rb

@@ -56,6 +56,12 @@ module Dalli
         storage_req(opkey, key, value, ttl, cas, options)
       end
 
+      # Pipelined set - writes a quiet set request without reading response.
+      # Used by PipelinedSetter for bulk operations.
+      def pipelined_set(key, value, ttl, options)
+        storage_req(:setq, key, value, ttl, 0, options)
+      end
+
       def add(key, value, ttl, options)
         opkey = quiet? ? :addq : :add
         storage_req(opkey, key, value, ttl, 0, options)
@@ -102,6 +108,13 @@ module Dalli
         response_processor.delete unless quiet?
       end
 
+      # Pipelined delete - writes a quiet delete request without reading response.
+      # Used by PipelinedDeleter for bulk operations.
+      def pipelined_delete(key)
+        req = RequestFormatter.standard_request(opkey: :deleteq, key: key, cas: 0)
+        write(req)
+      end
+
       # Arithmetic Commands
       def decr(key, count, ttl, initial)
         opkey = quiet? ? :decrq : :decr

data/lib/dalli/protocol/connection_manager.rb

@@ -150,19 +150,19 @@ module Dalli
         data = @sock.gets("\r\n")
         error_on_request!('EOF in read_line') if data.nil?
         data
-      rescue SystemCallError, *TIMEOUT_ERRORS, EOFError => e
+      rescue SystemCallError, *TIMEOUT_ERRORS, *SSL_ERRORS, EOFError => e
         error_on_request!(e)
       end
 
       def read(count)
         @sock.readfull(count)
-      rescue SystemCallError, *TIMEOUT_ERRORS, EOFError => e
+      rescue SystemCallError, *TIMEOUT_ERRORS, *SSL_ERRORS, EOFError => e
         error_on_request!(e)
       end
 
       def write(bytes)
         @sock.write(bytes)
-      rescue SystemCallError, *TIMEOUT_ERRORS => e
+      rescue SystemCallError, *TIMEOUT_ERRORS, *SSL_ERRORS => e
         error_on_request!(e)
       end
 

data/lib/dalli/protocol/meta/request_formatter.rb

@@ -15,13 +15,40 @@ module Dalli
         # rubocop:disable Metrics/CyclomaticComplexity
         # 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)
           cmd = "mg #{key}"
           cmd << ' 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 << " 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
 
@@ -37,11 +64,15 @@ module Dalli
           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
         end

data/lib/dalli/protocol/meta/response_processor.rb

@@ -51,6 +51,41 @@ module Dalli
           tokens.first == EN ? nil : true
         end
 
+        # Returns a hash with all requested metadata:
+        # - :value - the cached value (or nil if miss)
+        # - :cas - the CAS value (if return_cas was requested)
+        # - :won_recache - true if client won the right to recache (W flag)
+        # - :stale - true if the item is stale (X flag)
+        # - :lost_recache - true if another client is already recaching (Z flag)
+        # - :hit_before - true/false if item was previously accessed (h flag, if requested)
+        # - :last_access - seconds since last access (l flag, if requested)
+        #
+        # Used by meta_get for comprehensive metadata retrieval.
+        # Supports thundering herd protection (N/R flags) and metadata flags (h/l/u).
+        def meta_get_with_metadata(cache_nils: false, return_hit_status: false, return_last_access: false)
+          tokens = error_on_unexpected!([VA, EN, HD])
+          result = build_metadata_result(tokens)
+          result[:hit_before] = hit_status_from_tokens(tokens) if return_hit_status
+          result[:last_access] = last_access_from_tokens(tokens) if return_last_access
+          result[:value] = parse_value_from_tokens(tokens, cache_nils)
+          result
+        end
+
+        def build_metadata_result(tokens)
+          {
+            value: nil, cas: cas_from_tokens(tokens),
+            won_recache: tokens.include?('W'), stale: tokens.include?('X'),
+            lost_recache: tokens.include?('Z')
+          }
+        end
+
+        def parse_value_from_tokens(tokens, cache_nils)
+          return cache_nils ? ::Dalli::NOT_FOUND : nil if tokens.first == EN
+          return unless tokens.first == VA
+
+          @value_marshaller.retrieve(read_data(tokens[1].to_i), bitflags_from_tokens(tokens))
+        end
+
         def meta_set_with_cas
           tokens = error_on_unexpected!([HD, NS, NF, EX])
           return false unless tokens.first == HD
@@ -190,6 +225,21 @@ module Dalli
           KeyRegularizer.decode(encoded_key, base64_encoded)
         end
 
+        # Returns true if item was previously hit, false if first access, nil if not requested
+        # The h flag returns h0 (first access) or h1 (previously accessed)
+        def hit_status_from_tokens(tokens)
+          hit_token = tokens.find { |t| t.start_with?('h') && t.length == 2 }
+          return nil unless hit_token
+
+          hit_token[1] == '1'
+        end
+
+        # Returns seconds since last access, or nil if not requested
+        # The l flag returns l<seconds>
+        def last_access_from_tokens(tokens)
+          value_from_tokens(tokens, 'l')&.to_i
+        end
+
         def body_len_from_tokens(tokens)
           value_from_tokens(tokens, 's')&.to_i
         end

data/lib/dalli/protocol/meta.rb

@@ -60,12 +60,71 @@ module Dalli
         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]
+        )
+        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)
+        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,13 +136,13 @@ 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)
+                                        ttl: ttl, mode: mode, quiet: quiet, base64: base64)
         write(req)
         write(value)
         write(TERMINATOR)
@@ -121,6 +180,14 @@ module Dalli
         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

data/lib/dalli/protocol/string_marshaller.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Dalli
+  module Protocol
+    ##
+    # Dalli::Protocol::StringMarshaller is a pass-through marshaller for use with
+    # the :raw client option. It bypasses serialization and compression entirely,
+    # expecting values to already be strings (e.g., pre-serialized by Rails'
+    # ActiveSupport::Cache). It still enforces the maximum value size limit.
+    ##
+    class StringMarshaller
+      DEFAULTS = {
+        # max size of value in bytes (default is 1 MB, can be overriden with "memcached -I <size>")
+        value_max_bytes: 1024 * 1024
+      }.freeze
+
+      attr_reader :value_max_bytes
+
+      def initialize(client_options)
+        @value_max_bytes = client_options.fetch(:value_max_bytes) do
+          DEFAULTS.fetch(:value_max_bytes)
+        end.to_i
+      end
+
+      def store(key, value, _options = nil)
+        raise MarshalError, "Dalli in :raw mode only supports strings, got: #{value.class}" unless value.is_a?(String)
+
+        error_if_over_max_value_bytes(key, value)
+        [value, 0]
+      end
+
+      def retrieve(value, _flags)
+        value
+      end
+
+      # Interface compatibility methods - these return nil since
+      # StringMarshaller bypasses serialization and compression entirely.
+
+      def serializer
+        nil
+      end
+
+      def compressor
+        nil
+      end
+
+      def compression_min_size
+        nil
+      end
+
+      def compress_by_default?
+        false
+      end
+
+      private
+
+      def error_if_over_max_value_bytes(key, value)
+        return if value.bytesize <= value_max_bytes
+
+        message = "Value for #{key} over max size: #{value_max_bytes} <= #{value.bytesize}"
+        raise Dalli::ValueOverMaxSize, message
+      end
+    end
+  end
+end

data/lib/dalli/protocol.rb

@@ -15,5 +15,15 @@ module Dalli
       else
         [Timeout::Error]
       end
+
+    # SSL errors that occur during read/write operations (not during initial
+    # handshake) should trigger reconnection. These indicate transient network
+    # issues, not configuration problems.
+    SSL_ERRORS =
+      if defined?(OpenSSL::SSL::SSLError)
+        [OpenSSL::SSL::SSLError]
+      else
+        []
+      end
   end
 end

data/lib/dalli/protocol_deprecations.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Dalli
+  ##
+  # Handles deprecation warnings for protocol and authentication features
+  # that will be removed in Dalli 5.0.
+  ##
+  module ProtocolDeprecations
+    BINARY_PROTOCOL_DEPRECATION_MESSAGE = <<~MSG.chomp
+      [DEPRECATION] The binary protocol is deprecated and will be removed in Dalli 5.0. \
+      Please use `protocol: :meta` instead. The meta protocol requires memcached 1.6+. \
+      See https://github.com/petergoldstein/dalli for migration details.
+    MSG
+
+    SASL_AUTH_DEPRECATION_MESSAGE = <<~MSG.chomp
+      [DEPRECATION] SASL authentication is deprecated and will be removed in Dalli 5.0. \
+      SASL is only supported by the binary protocol, which is being removed. \
+      Consider using network-level security (firewall rules, VPN) or memcached's TLS support instead.
+    MSG
+
+    private
+
+    def emit_deprecation_warnings
+      emit_binary_protocol_deprecation_warning
+      emit_sasl_auth_deprecation_warning
+    end
+
+    def emit_binary_protocol_deprecation_warning
+      protocol = @options[:protocol]
+      # Binary is used when protocol is nil, :binary, or 'binary'
+      return if protocol.to_s == 'meta'
+
+      warn BINARY_PROTOCOL_DEPRECATION_MESSAGE
+      Dalli.logger.warn(BINARY_PROTOCOL_DEPRECATION_MESSAGE)
+    end
+
+    def emit_sasl_auth_deprecation_warning
+      username = @options[:username] || ENV.fetch('MEMCACHE_USERNAME', nil)
+      return unless username
+
+      warn SASL_AUTH_DEPRECATION_MESSAGE
+      Dalli.logger.warn(SASL_AUTH_DEPRECATION_MESSAGE)
+    end
+  end
+end

data/lib/dalli/version.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Dalli
-  VERSION = '4.0.0'
+  VERSION = '4.1.0'
 
   MIN_SUPPORTED_MEMCACHED_VERSION = '1.4'
 end

data/lib/dalli.rb

@@ -58,9 +58,12 @@ end
 require_relative 'dalli/version'
 
 require_relative 'dalli/compressor'
+require_relative 'dalli/protocol_deprecations'
 require_relative 'dalli/client'
 require_relative 'dalli/key_manager'
 require_relative 'dalli/pipelined_getter'
+require_relative 'dalli/pipelined_setter'
+require_relative 'dalli/pipelined_deleter'
 require_relative 'dalli/ring'
 require_relative 'dalli/protocol'
 require_relative 'dalli/protocol/base'
@@ -72,6 +75,7 @@ require_relative 'dalli/protocol/server_config_parser'
 require_relative 'dalli/protocol/ttl_sanitizer'
 require_relative 'dalli/protocol/value_compressor'
 require_relative 'dalli/protocol/value_marshaller'
+require_relative 'dalli/protocol/string_marshaller'
 require_relative 'dalli/protocol/value_serializer'
 require_relative 'dalli/servers_arg_normalizer'
 require_relative 'dalli/socket'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dalli
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - Peter M. Goldstein
@@ -43,7 +43,9 @@ files:
 - lib/dalli/key_manager.rb
 - lib/dalli/options.rb
 - lib/dalli/pid_cache.rb
+- lib/dalli/pipelined_deleter.rb
 - lib/dalli/pipelined_getter.rb
+- lib/dalli/pipelined_setter.rb
 - lib/dalli/protocol.rb
 - lib/dalli/protocol/base.rb
 - lib/dalli/protocol/binary.rb
@@ -58,10 +60,12 @@ files:
 - lib/dalli/protocol/meta/response_processor.rb
 - lib/dalli/protocol/response_buffer.rb
 - lib/dalli/protocol/server_config_parser.rb
+- lib/dalli/protocol/string_marshaller.rb
 - lib/dalli/protocol/ttl_sanitizer.rb
 - lib/dalli/protocol/value_compressor.rb
 - lib/dalli/protocol/value_marshaller.rb
 - lib/dalli/protocol/value_serializer.rb
+- lib/dalli/protocol_deprecations.rb
 - lib/dalli/ring.rb
 - lib/dalli/servers_arg_normalizer.rb
 - lib/dalli/socket.rb
@@ -88,7 +92,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.4
 specification_version: 4
 summary: High performance memcached client for Ruby
 test_files: []