dalli 5.0.5 → 5.1.0

data/lib/dalli/pipelined_getter.rb

@@ -20,13 +20,18 @@ module Dalli
     ##
     # Yields, one at a time, keys and their values+attributes.
     #
-    def process(keys, &block)
+    # `req_options` accepts :p_token/:l_token, applied to every key in the batch.
+    #
+    # A transient network error is retried automatically. If a server remains
+    # unreachable after retrying, raises Dalli::NetworkError.
+    #
+    def process(keys, req_options = nil, &block)
       return {} if keys.empty?
 
       @ring.lock do
         # Stores partial results collected during interleaved send phase
         @partial_results = {}
-        servers = setup_requests(keys)
+        servers = setup_requests(keys, req_options)
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
         # First yield any partial results collected during interleaved send
@@ -40,6 +45,40 @@ module Dalli
       retry
     end
 
+    ##
+    # Stale-aware bulk get across servers.  Returns { key => metadata Hash } for
+    # the keys that were found; see Protocol::Meta#read_multi_with_metadata_req
+    # for why misses are absent rather than present with miss: true.
+    #
+    # Unlike #process this issues one request per server and reads its full
+    # response before moving on, rather than pipelining across servers: the
+    # metadata path has no interleaving support, and the stale-aware callers it
+    # serves fetch far smaller batches than get_multi does.
+    #
+    # `req_options` accepts :p_token/:l_token, applied to every key in the batch.
+    #
+    def process_with_metadata(keys, req_options = nil)
+      return {} if keys.empty?
+
+      @ring.lock do
+        results = {}
+        groups_for_keys(keys).each do |server, keys_for_server|
+          results.merge!(server.request(:read_multi_with_metadata_req, keys_for_server, req_options))
+        rescue Dalli::RetryableNetworkError
+          raise
+        rescue DalliError, NetworkError => e
+          Dalli.logger.debug { e.inspect }
+          Dalli.logger.debug { "unable to get keys for server #{server.name}" }
+        end
+        results.transform_keys! { |key| @key_manager.key_without_namespace(key) }
+        results
+      end
+    rescue Dalli::RetryableNetworkError => e
+      Dalli.logger.debug { e.inspect }
+      Dalli.logger.debug { 'retrying pipelined get with metadata because of network error' }
+      retry
+    end
+
     private
 
     def yield_partial_results
@@ -49,9 +88,9 @@ module Dalli
       @partial_results.clear
     end
 
-    def setup_requests(keys)
+    def setup_requests(keys, req_options = nil)
       groups = groups_for_keys(keys)
-      make_getkq_requests(groups)
+      make_getkq_requests(groups, req_options)
 
       # TODO: How does this exit on a NetworkError
       finish_queries(groups.keys)
@@ -65,17 +104,27 @@ module Dalli
     # on the wire by switching from getkq to getq, and using
     # the opaque value to match requests to responses.
     ##
-    def make_getkq_requests(groups)
+    def make_getkq_requests(groups, req_options = nil)
       groups.each do |server, keys_for_server|
         if keys_for_server.size <= INTERLEAVE_THRESHOLD
           # Small batch - send all at once (existing behavior)
-          server.request(:pipelined_get, keys_for_server)
+          server.request(:pipelined_get, keys_for_server, req_options)
         else
           # Large batch - interleave sends with response draining
           # Pass @partial_results directly to avoid hash allocation/merge overhead
-          server.request(:pipelined_get_interleaved, keys_for_server, CHUNK_SIZE, @partial_results)
+          server.request(:pipelined_get_interleaved, keys_for_server, CHUNK_SIZE, @partial_results, req_options)
         end
-      rescue DalliError, NetworkError => e
+      # NetworkError (which RetryableNetworkError subclasses) must propagate:
+      # #process's top-level rescue retries the whole pipelined get on it. This
+      # rescue used to catch DalliError and NetworkError together -- since
+      # NetworkError < DalliError, that silently swallowed RetryableNetworkError
+      # too, dropping this server's keys from the result on a transient hiccup
+      # instead of retrying, with nothing surfaced above debug-level logging.
+      # Only a non-network DalliError (this server genuinely can't serve these
+      # keys) should be swallowed here.
+      rescue Dalli::NetworkError
+        raise
+      rescue DalliError => e
         Dalli.logger.debug { e.inspect }
         Dalli.logger.debug { "unable to get keys for server #{server.name}" }
       end

data/lib/dalli/pipelined_setter.rb

@@ -14,7 +14,9 @@ module Dalli
 
     ##
     # Writes multiple key-value pairs to memcached.
-    # Raises an error if any server is unavailable.
+    #
+    # A transient network error is retried automatically. If a server remains
+    # unreachable after retrying, raises Dalli::NetworkError.
     #
     # @param hash [Hash] key-value pairs to set
     # @param ttl [Integer] time-to-live in seconds
@@ -46,13 +48,21 @@ module Dalli
     # Loop through the server-grouped sets of keys, writing
     # the corresponding quiet set requests to the appropriate servers
     ##
+    # NetworkError (which RetryableNetworkError subclasses) must propagate: the
+    # top-level rescue in #process retries the whole pipelined set on it. A
+    # combined `rescue DalliError, NetworkError` would silently swallow
+    # RetryableNetworkError too -- since NetworkError < DalliError -- dropping
+    # this server's keys on a transient hiccup instead of retrying. Only a
+    # non-network DalliError should be swallowed here.
     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
+        rescue Dalli::NetworkError
+          raise
+        rescue DalliError => e
           Dalli.logger.debug { e.inspect }
           Dalli.logger.debug { "unable to set key #{key} for server #{server.name}" }
         end
@@ -65,7 +75,9 @@ module Dalli
     def finish_requests(servers)
       servers.each do |server|
         server.request(:noop)
-      rescue DalliError, NetworkError => e
+      rescue Dalli::NetworkError
+        raise
+      rescue DalliError => e
         Dalli.logger.debug { e.inspect }
         Dalli.logger.debug { "unable to complete pipelined set on server #{server.name}" }
       end

data/lib/dalli/protocol/base.rb

@@ -40,12 +40,14 @@ module Dalli
         verify_state(opkey)
 
         begin
+          request_completed = false
           @connection_manager.start_request!
           response = send(opkey, *args)
 
           # pipelined_get/pipelined_get_interleaved emit query but don't read the response(s)
           @connection_manager.finish_request! unless %i[pipelined_get pipelined_get_interleaved].include?(opkey)
 
+          request_completed = true
           response
         rescue Dalli::MarshalError => e
           log_marshal_err(args.first, e)
@@ -56,6 +58,18 @@ module Dalli
           log_unexpected_err(e)
           close
           raise
+        ensure
+          # If the begin block didn't complete -- any exception, including a
+          # non-StandardError such as Async::Stop or Thread#kill, which the
+          # rescue clauses above never see -- tear down the connection so a
+          # half-used client isn't returned to the pool.
+          #
+          # The local flag is deliberate: reading $ERROR_INFO here would see
+          # the *outer* exception when `request` is called from inside a
+          # rescue clause (a common cache-fallback shape), and would then
+          # falsely tear down the pipelined_get happy path, which leaves
+          # @request_in_progress true on purpose until the caller drains.
+          close unless request_completed
         end
       end
 
@@ -64,6 +78,19 @@ module Dalli
       # particular memcached instance is available for use.
       def alive?
         ensure_connected!
+      rescue Dalli::RetryableNetworkError => e
+        # A single connection attempt failure is retryable -- the same
+        # contract #request enforces on the send/receive path. Retrying here
+        # lets error_on_request!'s own fail-count threshold decide when to
+        # give up: it keeps raising RetryableNetworkError until
+        # socket_max_failures is reached, then raises a terminal
+        # NetworkError via down!, which the next rescue converts to false.
+        # Without this, a single transient hiccup during the liveness check
+        # itself -- as opposed to an actual request -- would report this
+        # server as not alive even though it would have reconnected fine.
+        Dalli.logger.debug { e.inspect }
+        Dalli.logger.debug { "retrying connection attempt to #{name} because of network error" }
+        retry
       rescue Dalli::NetworkError
         # ensure_connected! raises a NetworkError if connection fails.  We
         # want to capture that error and convert it to a boolean value here.
@@ -95,7 +122,6 @@ module Dalli
       # When a block is given, yields (key, value, cas) for each response,
       # avoiding intermediate Hash allocation. Returns nil.
       # Without a block, returns a Hash of { key => [value, cas] }.
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def pipeline_next_responses(&block)
         reconnect_on_pipeline_complete!
         values = nil
@@ -224,13 +250,44 @@ module Dalli
         opts[:cache_nils] ? true : false
       end
 
+      # Extracts opaque routing-token kwargs (:p_token, :l_token) from a
+      # request-options Hash so they can be splatted into a RequestFormatter
+      # call. Returns {} when neither is set, so the splat is a no-op on the
+      # common path. Validation (type, forbidden bytes) happens at the
+      # wire-formatter level, where it can raise uniformly regardless of how
+      # the token reached the formatter.
+      def routing_token_kwargs(opts)
+        return {} unless opts.is_a?(Hash)
+        return {} unless opts[:p_token] || opts[:l_token]
+
+        { p_token: opts[:p_token], l_token: opts[:l_token] }
+      end
+
+      # Maps the client-facing meta-delete options onto RequestFormatter's flag
+      # names, so they can be splatted into a meta_delete call.  Returns {} when
+      # none are set, keeping the splat a no-op on the common path.
+      #
+      # :tombstone_ttl becomes the T flag, which is the same TTL the formatter
+      # already accepted -- deliberately not a second TTL parameter, since two
+      # would allow emitting two T tokens in one request.  It is sanitized like
+      # every other TTL Dalli sends.
+      def tombstone_kwargs(opts)
+        return {} unless opts.is_a?(Hash)
+
+        kwargs = {}
+        kwargs[:stale] = true if opts[:invalidate]
+        kwargs[:ttl] = TtlSanitizer.sanitize(Integer(opts[:tombstone_ttl])) if opts[:tombstone_ttl]
+        kwargs[:drop_value] = true if opts[:drop_value]
+        kwargs
+      end
+
       def connect
         @connection_manager.establish_connection
         @version = version
         up!
       end
 
-      def pipelined_get(keys)
+      def pipelined_get(keys, options = nil)
         # Clear buffer to remove any stale data from interrupted operations.
         # Use clear (not reset) to keep pipeline_complete? = true, which is
         # the expected state before pipeline_response_setup is called.
@@ -238,7 +295,7 @@ module Dalli
 
         req = +''
         keys.each do |key|
-          req << quiet_get_request(key)
+          req << quiet_get_request(key, options)
         end
         # Could send noop here instead of in pipeline_response_setup
         write(req)
@@ -247,7 +304,7 @@ module Dalli
       # For large batches, interleave writing requests with draining responses.
       # This prevents socket buffer deadlock when sending many keys.
       # Populates the provided results hash with any responses drained during send.
-      def pipelined_get_interleaved(keys, chunk_size, results)
+      def pipelined_get_interleaved(keys, chunk_size, results, options = nil)
         # Initialize the response buffer for draining during send phase
         response_buffer.ensure_ready
 
@@ -255,7 +312,7 @@ module Dalli
           # Build and write this chunk of requests
           req = +''
           chunk.each do |key|
-            req << quiet_get_request(key)
+            req << quiet_get_request(key, options)
           end
           write(req)
           @connection_manager.flush

data/lib/dalli/protocol/connection_manager.rb

@@ -4,8 +4,6 @@ require 'English'
 require 'socket'
 require 'timeout'
 
-require 'dalli/pid_cache'
-
 module Dalli
   module Protocol
     ##
@@ -54,7 +52,7 @@ module Dalli
 
         @sock = memcached_socket
         @sock.sync = false # Enable buffered I/O for better performance
-        @pid = PIDCache.pid
+        @pid = Process.pid
         @request_in_progress = false
       rescue SystemCallError, *TIMEOUT_ERRORS, EOFError, SocketError => e
         # SocketError = DNS resolution failure
@@ -117,10 +115,16 @@ module Dalli
           @sock.close
         rescue StandardError
           nil
+        ensure
+          # A non-StandardError (e.g. a second Async::Stop fired into the
+          # fiber while it is already inside this cleanup) can escape
+          # @sock.close; run the state cleanup unconditionally so the client
+          # isn't returned to the pool with a half-closed socket and
+          # @request_in_progress == true.
+          @sock = nil
+          @pid = nil
+          abort_request!
         end
-        @sock = nil
-        @pid = nil
-        abort_request!
       end
 
       def connected?
@@ -165,12 +169,16 @@ module Dalli
         end
       else
         def read(count)
-          @sock.read(count)
+          read_bytes(count)
         rescue SystemCallError, *TIMEOUT_ERRORS, *SSL_ERRORS, EOFError => e
           error_on_request!(e)
         end
       end
 
+      # Alias for callers that want to make the exact-length contract explicit
+      # at the call site.
+      alias read_exact read
+
       def write(bytes)
         @sock.write(bytes)
       rescue SystemCallError, *TIMEOUT_ERRORS, *SSL_ERRORS, IOError => e
@@ -193,8 +201,8 @@ module Dalli
 
       # Non-blocking read.  Here to support the operation
       # of the get_multi operation
-      def read_nonblock
-        @sock.read_available
+      def read_available(...)
+        @sock.read_available(...)
       end
 
       def max_allowed_failures
@@ -252,7 +260,7 @@ module Dalli
       end
 
       def fork_detected?
-        @pid && @pid != PIDCache.pid
+        @pid && @pid != Process.pid
       end
 
       def log_down_detected
@@ -273,6 +281,22 @@ module Dalli
         time = Time.now - @down_at
         Dalli.logger.warn { format('%<name>s is back (downtime was %<time>.3f seconds)', name: name, time: time) }
       end
+
+      private
+
+      # Reads exactly `count` bytes. IO#read(count) on a blocking socket blocks
+      # until it has `count` bytes, accumulating across TCP chunks internally,
+      # and only hands back a shorter (or nil) buffer when the stream hits EOF.
+      # So a short read means the peer closed mid-response: raise EOFError and
+      # let read's existing `rescue EOFError` route it through
+      # error_on_request!, which closes the dirty socket for a retry on a fresh
+      # connection (and preserves the $ERROR_INFO context down! relies on).
+      def read_bytes(count)
+        buffer = @sock.read(count)
+        return buffer if buffer && buffer.bytesize == count
+
+        raise EOFError, "EOF reading #{count} bytes; received #{buffer ? buffer.bytesize : 0}"
+      end
     end
   end
 end

data/lib/dalli/protocol/key_regularizer.rb

@@ -9,19 +9,35 @@ module Dalli
       # 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
-        WHITESPACE = /\s/
+      module KeyRegularizer
+        module_function
 
-        def self.encode(key)
-          return [key, false] if key.ascii_only? && !WHITESPACE.match(key)
-
-          strict_base64_encoded = [key].pack('m0')
-          [strict_base64_encoded, true]
+        # protocol.txt requires that a key "must not include control
+        # characters or whitespace" -- \p{Cntrl} is C0 (0x00-0x1F) plus DEL
+        # (0x7F). \s alone misses NUL and the rest of that range: a key
+        # containing one of those bytes but no whitespace is ASCII-only, so
+        # it would otherwise be written to the wire unencoded. Not a
+        # protocol-injection risk (the text protocol splits on CRLF, not
+        # other control bytes), but a downstream consumer that treats the key
+        # specially at one of those bytes (a C string terminating at NUL, a
+        # terminal or log line interpreting an escape byte) could silently
+        # act on a different key than Dalli believes it sent.
+        #
+        # Written as \p{Cntrl} rather than the POSIX [:cntrl:] bracket class:
+        # \s and [:cntrl:] overlap (tab, newline, CR are in both), and Ruby
+        # warns "character class has duplicated range" when they're combined
+        # in one -- fatal here, since this suite's -w run treats warnings as
+        # errors (see test_strict_warnings.rb). \p{Cntrl} matches the same
+        # bytes without the overlap warning.
+        def required?(key)
+          !key.ascii_only? || /[\p{Cntrl}\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