dalli 3.2.8 → 5.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7d8b3dd9e76a224d876f901dc44c3cf8016326209df3efc7fe522053a4a3c22
-  data.tar.gz: 0ced058a6a170cadd4b74268de5417c4a1e700baf5767fc8f260db9477e2b735
+  metadata.gz: 5c110d569b03993cefe140fdc4b54fb5720ef407e15c0fe100e4a49f90b5ce36
+  data.tar.gz: 8a3967c3d9d82dd3a28172fdb06e7f235a8ebb6598fd742e04770b458d24d041
 SHA512:
-  metadata.gz: 3e316a4d60c3327cecec46a0a34c52536130199124035c375bf1933676d85fbf09e99a985ae44faf4e27b0fb1f8b8faef1656a812e6bdfc387406c5e18874461
-  data.tar.gz: bce3e0e41c280e99889bea6835c1b2f701cbcb5e4f398203ae2b4d6ebc05cdc505ee5955365715f8e00441d69701ceac84de37a98eac8581d003d1ab411a33e9
+  metadata.gz: 486715371411ddcf9118f87296abaaf7a30597a340bba41f26d26a750268d85751fef62be52f332662d427fa79e0ed3ea9bf0e503747203f5039194875a878de
+  data.tar.gz: d1bdf88817ba281d7b88525b1e0579c6efefdd68cb1b437dbbc0cf4fa2f386a6d9612e579cbfc409b1c1458a05ee5b4c7af841599e1930433912a909550b84f1

data/CHANGELOG.md

@@ -4,6 +4,311 @@ Dalli Changelog
 Unreleased
 ==========
 
+5.0.5
+==========
+
+Performance:
+
+- Batch multi-key commands into a single write to reduce packet overhead (#1107)
+  - With `TCP_NODELAY` set on sockets, each `write` call emits a separate packet; the meta protocol was calling `write` up to 3 times per key in multi-key operations (`get_multi`, `set_multi`, `delete_multi`), significantly increasing network traffic compared to the old binary protocol
+  - Multi-key request paths now buffer all per-key commands into a single binary string and flush once; single-key paths combine the write and flush into one `flushed_write` call
+  - Thanks to Jean Boussier for this contribution
+
+- Avoid repeated `RUBY_ENGINE` checks on every socket read (#1103)
+  - Moved the JRuby branch from a runtime `if` inside `ConnectionManager#read` to a class-level conditional method definition, so the check happens once at load time rather than on every read call
+  - Thanks to Jean Boussier for this contribution
+
+- Eliminate per-call array allocations in `ResponseProcessor` (#1104)
+  - Token sets passed to `error_on_unexpected!` (e.g. `[VA, EN, HD]`) were allocated as new arrays on every invocation; replaced with frozen constants defined once at class load time
+  - Thanks to Jean Boussier for this contribution
+
+- Avoid string copies when building request commands in `RequestFormatter` (#1106)
+  - Changed `cmd + TERMINATOR` to `cmd << TERMINATOR`; since `cmd` is always a mutable string, the in-place append avoids copying the entire command string just to append two bytes
+  - Thanks to Jean Boussier for this contribution
+
+5.0.4
+==========
+
+Bug fixes:
+
+- Fix `string_fastpath` flag collision with compression (#1099)
+  - `ValueSerializer::FLAG_UTF8` and `ValueCompressor::FLAG_COMPRESSED` were both `0x2`, causing `Dalli::UnmarshalError` on any UTF-8 string written with `string_fastpath: true` when compression is enabled, and silent encoding corruption for binary strings
+  - Introduces `Dalli::Flags` to centralise bit flag constants; UTF8 is reassigned to `0x4`
+  - Adds regression test covering short/long UTF-8, binary, and cross-client read scenarios
+  - Thanks to Jean Boussier and Mikael Henriksson for the fix and regression test
+
+- Fix client-level `string_fastpath: true` being silently ignored (#1101)
+  - `Dalli::Client.new(servers, string_fastpath: true)` had no effect; the fast path was only taken when `string_fastpath: true` was passed as a per-request option on each `set` call
+  - Per-request option continues to take precedence over the client-level setting in both directions
+
+5.0.3
+==========
+
+Performance:
+
+- Eliminate double array allocation in `Client#perform` (#1093)
+  - Changed method signature from `perform(*all_args)` with destructuring to `perform(op, key, *args)`, letting Ruby decompose arguments directly without intermediate array allocations
+  - Reduces benchmark time by ~39% across all Dalli operations (get, set, delete, etc.)
+  - Thanks to Sam Obeid for this contribution
+
+Features:
+
+- Support `connect_timeout:` keyword argument with `resolv-replace` >= 0.2.0, which now correctly forwards keyword arguments through its `TCPSocket` patch (#1096)
+
+- Add `Dalli::Instrumentation.disable!` to allow disabling OpenTelemetry instrumentation at runtime (#1088)
+  - Also exposes `Dalli::Instrumentation.tracer=` for setting a custom tracer
+
+5.0.2
+==========
+
+Performance:
+
+- Add single-server fast path for `get_multi`, `set_multi`, and `delete_multi` (#1077)
+  - When only one memcached server is configured, bypass the `Pipelined*` machinery (IO.select, response buffering, server grouping) and issue all quiet meta requests inline followed by a noop terminator
+  - `get_multi` shows ~1.5x improvement at 10 keys and ~1.75x at 100–500 keys compared to the `PipelinedGetter` path
+  - Thanks to Dan Mayer (Shopify) for this contribution
+
+Development:
+
+- Add `bin/benchmark_branch` script for benchmarking against the current branch
+
+5.0.1
+==========
+
+Performance:
+
+- Reduce object allocations in pipelined get response processing (#1072, #1078)
+  - Offset-based `ResponseBuffer`: track a read offset instead of slicing a new string after every parsed response; compact only when the consumed portion exceeds 4KB and more than half the buffer
+  - Inline response processor parsing: avoid intermediate array allocations from `split`-based header parsing
+  - Block-based `pipeline_next_responses`: yield `(key, value, cas)` directly when a block is given, avoiding per-call Hash allocation
+  - `PipelinedGetter`: replace Hash-based socket-to-server mapping with linear scan (faster for typical 1-5 server counts); use `Process.clock_gettime(CLOCK_MONOTONIC)` instead of `Time.now`
+- Add cross-version benchmark script (`bin/compare_versions`) for reproducible performance comparisons across Dalli versions
+
+Bug Fixes:
+
+- Rescue `IOError` in connection manager `write`/`flush` methods (#1075)
+  - Prevents unhandled exceptions when a connection is closed mid-operation
+  - Thanks to Graham Cooper (Shopify) for this fix
+
+Development:
+
+- Add `rubocop-thread_safety` for detecting thread-safety issues (#1076)
+- Add CONTRIBUTING.md with AI contribution policy (#1074)
+
+5.0.0
+==========
+
+**Breaking Changes:**
+
+- **Removed binary protocol** - The meta protocol is now the only supported protocol
+  - The `:protocol` option is no longer used
+  - Requires memcached 1.6+ (for meta protocol support)
+  - Users on older memcached versions must upgrade or stay on Dalli 4.x
+
+- **Removed SASL authentication** - The meta protocol does not support authentication
+  - Use network-level security (firewall rules, VPN) or memcached's TLS support instead
+  - Users requiring SASL authentication must stay on Dalli 4.x with binary protocol
+
+- **Ruby 3.3+ required** - Dropped support for Ruby 3.1 and 3.2
+  - Ruby 3.2 reached end-of-life in March 2026
+  - JRuby remains supported
+
+Performance:
+
+- **~7% read performance improvement** (CRuby only)
+  - Use native `IO#read` instead of custom `readfull` implementation
+  - Enabled by Ruby 3.3's `IO#timeout=` support
+  - JRuby continues to use `readfull` for compatibility
+
+OpenTelemetry:
+
+- Migrate to stable OTel semantic conventions (#1070)
+  - `db.system` renamed to `db.system.name`
+  - `db.operation` renamed to `db.operation.name`
+  - `server.address` now contains hostname only; `server.port` is a separate integer attribute
+  - `get_with_metadata` and `fetch_with_lock` now include `server.address`/`server.port`
+- Add `db.query.text` span attribute with configurable modes
+  - `:otel_db_statement` option: `:include`, `:obfuscate`, or `nil` (default: omitted)
+- Add `peer.service` span attribute
+  - `:otel_peer_service` option for logical service naming
+
+Internal:
+
+- Simplified protocol directory structure: moved `lib/dalli/protocol/meta/*` to `lib/dalli/protocol/`
+- Removed deprecated binary protocol files and SASL authentication code
+- Removed `require 'set'` (autoloaded in Ruby 3.3+)
+
+4.3.3
+==========
+
+Performance:
+
+- Reduce object allocations in pipelined get response processing (#1072)
+  - Offset-based `ResponseBuffer`: track a read offset instead of slicing a new string after every parsed response; compact only when the consumed portion exceeds 4KB and more than half the buffer
+  - Inline response processor parsing: avoid intermediate array allocations from `split`-based header parsing in both binary and meta protocols
+  - Block-based `pipeline_next_responses`: yield `(key, value, cas)` directly when a block is given, avoiding per-call Hash allocation
+  - `PipelinedGetter`: replace Hash-based socket-to-server mapping with linear scan (faster for typical 1-5 server counts); use `Process.clock_gettime(CLOCK_MONOTONIC)` instead of `Time.now`
+- Add cross-version benchmark script (`bin/compare_versions`) for reproducible performance comparisons across Dalli versions
+
+Bug Fixes:
+
+- Skip OTel integration tests when meta protocol is unavailable (#1072)
+
+4.3.2
+==========
+
+OpenTelemetry:
+
+- Migrate to stable OTel semantic conventions
+  - `db.system` renamed to `db.system.name`
+  - `db.operation` renamed to `db.operation.name`
+  - `server.address` now contains hostname only; `server.port` is a separate integer attribute
+  - `get_with_metadata` and `fetch_with_lock` now include `server.address`/`server.port`
+- Add `db.query.text` span attribute with configurable modes
+  - `:otel_db_statement` option: `:include`, `:obfuscate`, or `nil` (default: omitted)
+- Add `peer.service` span attribute
+  - `:otel_peer_service` option for logical service naming
+
+4.3.1
+==========
+
+Bug Fixes:
+
+- Fix socket compatibility with gems that monkey-patch TCPSocket (#996, #1012)
+  - Gems like `socksify` and `resolv-replace` modify `TCPSocket#initialize`, breaking Ruby 3.0+'s `connect_timeout:` keyword argument
+  - Detection now uses parameter signature checking instead of gem-specific method detection
+  - Falls back to `Timeout.timeout` when monkey-patching is detected
+  - Detection result is cached for performance
+
+- Fix network retry bug with `socket_max_failures: 0` (#1065)
+  - Previously, setting `socket_max_failures: 0` could still cause retries due to error handling
+  - Introduced `RetryableNetworkError` subclass to distinguish retryable vs non-retryable errors
+  - `down!` now raises non-retryable `NetworkError`, `reconnect!` raises `RetryableNetworkError`
+  - Thanks to Graham Cooper (Shopify) for this fix
+
+- Fix "character class has duplicated range" Ruby warning (#1067)
+  - Fixed regex in `KeyManager::VALID_NAMESPACE_SEPARATORS` that caused warnings on newer Ruby versions
+  - Thanks to Hartley McGuire for this fix
+
+Improvements:
+
+- Add StrictWarnings test helper to catch Ruby warnings early (#1067)
+
+- Use bulk attribute setter for OpenTelemetry spans (#1068)
+  - Reduces lock acquisitions when setting span attributes
+  - Thanks to Robert Laurin (Shopify) for this optimization
+
+- Fix double recording of exceptions on OpenTelemetry spans (#1069)
+  - OpenTelemetry's `in_span` method already records exceptions and sets error status automatically
+  - Removed redundant explicit exception recording that caused exceptions to appear twice in traces
+  - Thanks to Robert Laurin (Shopify) for this fix
+
+4.3.0
+==========
+
+New Features:
+
+- Add `namespace_separator` option to customize the separator between namespace and key (#1019)
+  - Default is `:` for backward compatibility
+  - Must be a single non-alphanumeric character (e.g., `:`, `/`, `|`, `.`)
+  - Example: `Dalli::Client.new(servers, namespace: 'myapp', namespace_separator: '/')`
+
+Bug Fixes:
+
+- Fix architecture-dependent struct timeval packing for socket timeouts (#1034)
+  - Detects correct pack format for time_t and suseconds_t on each platform
+  - Fixes timeout issues on architectures with 64-bit time_t
+
+- Fix get_multi hanging with large key counts (#776, #941)
+  - Add interleaved read/write for pipelined gets to prevent socket buffer deadlock
+  - For batches over 10,000 keys per server, requests are now sent in chunks
+
+- **Breaking:** Enforce string-only values in raw mode (#1022)
+  - `set(key, nil, raw: true)` now raises `MarshalError` instead of storing `""`
+  - `set(key, 123, raw: true)` now raises `MarshalError` instead of storing `"123"`
+  - This matches the behavior of client-level `raw: true` mode
+  - To store counters, use string values: `set('counter', '0', raw: true)`
+
+CI:
+
+- Add TruffleRuby to CI test matrix (#988)
+
+4.2.0
+==========
+
+Performance:
+
+- Buffered I/O: Use `socket.sync = false` with explicit flush to reduce syscalls for pipelined operations
+- get_multi optimizations: Use Set for O(1) server tracking lookups
+- Raw mode optimization: Skip bitflags request in meta protocol when in raw mode (saves 2 bytes per request)
+
+New Features:
+
+- OpenTelemetry tracing support: Automatically instruments operations when OpenTelemetry SDK is present
+  - Zero overhead when OpenTelemetry is not loaded
+  - Traces `get`, `set`, `delete`, `get_multi`, `set_multi`, `delete_multi`, `get_with_metadata`, and `fetch_with_lock`
+  - Spans include `db.system: memcached` and `db.operation` attributes
+  - Single-key operations include `server.address` attribute
+  - Multi-key operations include `db.memcached.key_count` attribute
+  - `get_multi` spans include `db.memcached.hit_count` and `db.memcached.miss_count` for cache efficiency metrics
+  - Exceptions are automatically recorded on spans with error status
+
+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
+==========
+
+BREAKING CHANGES:
+
+- Require Ruby 3.1+ (dropped support for Ruby 2.6, 2.7, and 3.0)
+- Removed `Dalli::Server` deprecated alias - use `Dalli::Protocol::Binary` instead
+- Removed `:compression` option - use `:compress` instead
+- Removed `close_on_fork` method - use `reconnect_on_fork` instead
+
+Other changes:
+
+- Add security warning when using default Marshal serializer (silence with `silence_marshal_warning: true`)
+- Add defense-in-depth input validation for stats command arguments
+- Add `string_fastpath` option to skip serialization for simple strings (byroot)
+- Meta protocol set performance improvement (danmayer)
+- Fix connection_pool 3.0 compatibility for Rack session store
+- Fix session recovery after deletion (stengineering0)
+- Fix cannot read response data included terminator `\r\n` when use meta protocol (matsubara0507)
+- Support SERVER_ERROR response from Memcached as per the [memcached spec](https://github.com/memcached/memcached/blob/e43364402195c8e822bb8f88755a60ab8bbed62a/doc/protocol.txt#L172) (grcooper)
+- Update Socket timeout handling to use Socket#timeout= when available (nickamorim)
+- Serializer: reraise all .load errors as UnmarshalError (olleolleolle)
+- Reconnect gracefully when a fork is detected instead of crashing (PatrickTulskie)
+- Update CI to test against memcached 1.6.40
+
 3.2.8
 ==========
 

data/Gemfile

@@ -5,17 +5,31 @@ source 'https://rubygems.org'
 gemspec
 
 group :development, :test do
+  gem 'benchmark'
+  gem 'cgi'
   gem 'connection_pool'
-  gem 'minitest', '~> 5'
-  gem 'rack', '~> 2.0', '>= 2.2.0'
+  gem 'debug' unless RUBY_PLATFORM == 'java'
+  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'
   gem 'rubocop-performance'
   gem 'rubocop-rake'
+  gem 'rubocop-thread_safety'
   gem 'simplecov'
 end
 
 group :test do
   gem 'ruby-prof', platform: :mri
+
+  # For socket compatibility testing (these gems monkey-patch TCPSocket)
+  gem 'resolv-replace', require: false
+  gem 'socksify', require: false
 end

data/README.md

@@ -10,10 +10,104 @@ Dalli supports:
 * Fine-grained control of data serialization and compression
 * Thread-safe operation (either through use of a connection pool, or by using the Dalli client in threadsafe mode)
 * SSL/TLS connections to memcached
-* SASL authentication
+* OpenTelemetry distributed tracing (automatic when SDK is present)
 
 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.3 or later (JRuby also supported)
+* memcached 1.6 or later
+
+## Configuration Options
+
+### Namespace
+
+Use namespaces to partition your cache and avoid key collisions between different applications or environments:
+
+```ruby
+# All keys will be prefixed with "myapp:"
+Dalli::Client.new('localhost:11211', namespace: 'myapp')
+
+# Dynamic namespace using a Proc (evaluated on each operation)
+Dalli::Client.new('localhost:11211', namespace: -> { "tenant:#{Thread.current[:tenant_id]}" })
+```
+
+### Namespace Separator
+
+By default, the namespace and key are joined with a colon (`:`). You can customize this with the `namespace_separator` option:
+
+```ruby
+# Keys will be prefixed with "myapp/" instead of "myapp:"
+Dalli::Client.new('localhost:11211', namespace: 'myapp', namespace_separator: '/')
+```
+
+The separator must be a single non-alphanumeric character. Valid examples: `:`, `/`, `|`, `.`, `-`, `_`, `#`
+
+## 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 [5.0-Upgrade.md](5.0-Upgrade.md) guide for upgrade information.
+
+## OpenTelemetry Tracing
+
+Dalli automatically instruments operations with [OpenTelemetry](https://opentelemetry.io/) when the SDK is present. No configuration is required - just add the OpenTelemetry gems to your application:
+
+```ruby
+# Gemfile
+gem 'opentelemetry-sdk'
+gem 'opentelemetry-exporter-otlp' # or your preferred exporter
+```
+
+When OpenTelemetry is loaded, Dalli creates spans for:
+- Single key operations: `get`, `set`, `delete`, `add`, `replace`, `incr`, `decr`, etc.
+- Multi-key operations: `get_multi`, `set_multi`, `delete_multi`
+- Advanced operations: `get_with_metadata`, `fetch_with_lock`
+
+### Span Attributes
+
+All spans include:
+- `db.system`: `memcached`
+- `db.operation`: The operation name (e.g., `get`, `set_multi`)
+
+Single-key operations also include:
+- `server.address`: The memcached server that handled the request (e.g., `localhost:11211`)
+
+Multi-key operations include cache efficiency metrics:
+- `db.memcached.key_count`: Number of keys in the request
+- `db.memcached.hit_count`: Number of keys found (for `get_multi`)
+- `db.memcached.miss_count`: Number of keys not found (for `get_multi`)
+
+### Error Handling
+
+Exceptions are automatically recorded on spans with error status. When an operation fails:
+1. The exception is recorded on the span via `span.record_exception(e)`
+2. The span status is set to error with the exception message
+3. The exception is re-raised to the caller
+
+### Disabling Instrumentation
+
+To disable instrumentation at runtime (e.g., in tests or specific environments):
+
+```ruby
+Dalli::Instrumentation.disable!
+```
+
+You can also assign a custom tracer directly:
+
+```ruby
+Dalli::Instrumentation.tracer = my_custom_tracer
+```
+
+### Zero Overhead
+
+When OpenTelemetry is not present, there is zero overhead - the tracing code checks once at startup and bypasses all instrumentation logic entirely when the SDK is not loaded.
+
 ![Persistence of Memory](https://upload.wikimedia.org/wikipedia/en/d/dd/The_Persistence_of_Memory.jpg)
 
 
@@ -33,7 +127,7 @@ To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 
-If you have a fix you wish to provide, please fork the code, fix in your local project and then send a pull request on github.  Please ensure that you include a test which verifies your fix and update the [changelog](CHANGELOG.md) with a one sentence description of your fix so you get credit as a contributor.
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute, including our policy on AI-authored contributions.
 
 ## Appreciation