dalli 5.0.5 → 5.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5c110d569b03993cefe140fdc4b54fb5720ef407e15c0fe100e4a49f90b5ce36
-  data.tar.gz: 8a3967c3d9d82dd3a28172fdb06e7f235a8ebb6598fd742e04770b458d24d041
+  metadata.gz: 10a8b21fed4728b6f98929e983262dc1fc32c59711fce78a84b0df82b0348ca1
+  data.tar.gz: 0253d48293d3b482e8362830acd9323873302e202cb230bca3fc1b1e09b1b457
 SHA512:
-  metadata.gz: 486715371411ddcf9118f87296abaaf7a30597a340bba41f26d26a750268d85751fef62be52f332662d427fa79e0ed3ea9bf0e503747203f5039194875a878de
-  data.tar.gz: d1bdf88817ba281d7b88525b1e0579c6efefdd68cb1b437dbbc0cf4fa2f386a6d9612e579cbfc409b1c1458a05ee5b4c7af841599e1930433912a909550b84f1
+  metadata.gz: bda1d416cf1f88514d0181ed2e7f7b53e1b935fb07901398cb91183f63e42d0ab7c9e54c177264cf77fc793ead7b8183d79cf3c335d8dee11aae5049a6f0fff9
+  data.tar.gz: d81bec09db2c23cdc95204b0bec5c491fbcb60e12823245b9d9d338502c98b2e6af5f6e58a12b11c081889ea5d63cb079b6e8ef2fb869db147f67219db86ac55

data/CHANGELOG.md

@@ -4,6 +4,132 @@ Dalli Changelog
 Unreleased
 ==========
 
+5.0.7
+==========
+
+Security:
+
+- Fix memcached command injection through numeric arguments (GHSA-6wmv-xq9m-fmp7)
+  - The `default` argument of `incr`/`decr`, and `fetch_with_lock`'s `lock_ttl` and `recache_threshold`, were written into the meta protocol command without conversion, so a String containing CRLF injected additional memcached commands (e.g. `set`, `flush_all`) on the connection
+  - These arguments must now be Integers, or Strings of decimal digits; anything else raises `ArgumentError` before a request is sent
+  - As defense in depth, `RequestFormatter` now converts every numeric flag it writes (`D`, `J`, `N`, `R`, `T`) to an Integer
+  - Thanks to oss-security-shop for the report
+
+5.0.6
+==========
+
+Performance:
+
+- Skip the cas-return flag on quiet `meta_set` requests (#1131)
+  - In quiet mode memcached suppresses the `ms` response entirely, so the CAS requested by the `c` flag can never be read; sending it only added two bytes to every request
+  - Applies to the bulk-write paths, where quiet sets are emitted: `Dalli::Client#multi` blocks and the pipelined setter
+  - Extracted from #1130; thanks to Jianbin Chen for this contribution
+
+- Reduce allocations in `KeyRegularizer` and multi-key request paths (#1120)
+  - Decomposed `KeyRegularizer#encode` into separate `needs_encoding?` and `encode` calls so the common happy path avoids allocating an intermediate array for the two-element return value
+  - Refactored `multi_get`/`multi_set`/`multi_delete` command generation into `RequestFormatter` to share its key-encoding helpers
+  - Thanks to Jean Boussier for this contribution
+
+- Reduce allocations in `ResponseBuffer` pipelined getk parsing (#1117)
+  - `process_single_getk_response` was building a fresh array to return results alongside the updated offset; refactored to store the offset as the last element of the existing tokens array and pop it, saving one allocation per response
+  - Also skips trailing nils in the token array
+  - Thanks to Jean Boussier for this contribution
+
+- Enable frozen string literals in `RequestFormatter` (#1118)
+  - Frozen string literals had been inadvertently disabled; re-enabling reduces allocations by ~300,000 objects in a 10,000-iteration `get_multi_cas` benchmark (562 MB → 550 MB total allocated)
+  - Thanks to Jean Boussier for this contribution
+
+- Reduce allocations in `ResponseProcessor#value_from_tokens` (#1113)
+  - `token[1..].to_i` was allocating a new string for every token parsed; replaced with in-place `slice!` followed by a token reset to avoid poisoning subsequent token comparisons
+  - Saves 4 allocations per entry in `get_multi_cas` workloads (a hotspot for IdentityCache)
+  - Thanks to Jean Boussier for this contribution
+
+- Reduce allocations in common operation paths (#1111)
+  - Use `Symbol#name` over `Symbol#to_s` to return a frozen string without allocation
+  - Skip trace attribute hash construction when OpenTelemetry instrumentation is disabled
+  - Use argument forwarding (`...`) in `Client#perform` and `Threadsafe#request` to avoid splat array allocation
+  - Use `match?` in `KeyRegularizer#encode` to avoid `MatchData` object allocation
+  - Reduces objects allocated by ~26% and memory by ~6% for a simple `get` workload
+  - Thanks to Jean Boussier for this contribution
+
+- Fix pathological memory behavior in `ResponseBuffer` (#1114)
+  - `compact_if_needed` was intended to reclaim memory by slicing off consumed bytes, but `buffer.byteslice(@offset..)` on an unfrozen string causes Ruby to allocate a hidden third string as the copy-on-write owner rather than freeing the original
+  - Redesigns buffer management to pass reusable buffer objects directly to `read`/`read_nonblock`, avoiding reallocation on each response read
+  - Reduces allocations from ~2.38 GB to ~649 MB in a `get_multi_cas` benchmark over 10,000 iterations
+  - Accompanied by new unit tests for `ResponseBuffer` (#1115)
+  - Thanks to Jean Boussier for this contribution
+
+Features:
+
+- `delete_multi` now returns the number of keys found and deleted (#1126)
+  - Previously the return value was unspecified; callers (e.g. Rails, see rails/rails#58071) had no way to tell how many keys were actually removed
+  - The count is derived from the meta protocol's quiet-mode delete responses with no extra round-trips: successful deletes are suppressed while misses report `NF`, so any response received before the terminator is a key that was not deleted
+  - The single-server fast path now shares the pipelined path's bounded retry on transient (`RetryableNetworkError`) network errors, so both paths behave consistently; the returned count is best-effort and may under-report if a network error triggers a retry, since keys deleted before the error are not recounted
+  - Thanks to Iliana Hadzhiatanasova for this contribution
+
+Bug Fixes:
+
+- Raise instead of returning a truncated value when the peer closes mid-response (#1135)
+  - `IO#read(count)` on a blocking socket accumulates across TCP chunks and hands back a shorter buffer (or `nil`) in only one case: the stream hit EOF. That short buffer was passed through as the response body, so a memcached restart, proxy drop, or load balancer timeout partway through a response could surface a truncated but still decodable value to the caller, indistinguishable from a real one
+  - A short read is now treated as the premature EOF it is, raising and closing the dirty socket so the request is retried on a fresh connection
+  - CRuby only; the JRuby path already used `Socket#readfull`, which enforces the same contract
+  - Extracted from #1130; thanks to Ian Ker-Seymer for the original fix and Jianbin Chen for the port
+
+- Tear down the connection when a non-`StandardError` aborts a request (#1136)
+  - `Async::Stop` and `Thread#kill` descend from `Exception` rather than `StandardError`, so the rescue clauses in `Protocol::Base#request` never saw them; a scheduler cancelling a fiber parked on a response read skipped `close` entirely, leaving the connection marked as having a request in progress with partial response bytes still unread on the wire, and returning that half-used client to the pool under `connection_pool`
+  - `Protocol::Base#request` now closes in an `ensure` unless the request ran to completion, and `ConnectionManager#close` performs its state cleanup in an `ensure` so a second cancellation landing inside `@sock.close` cannot leave the socket non-nil with the request still marked in progress
+  - `Dalli::DalliError` and `Dalli::MarshalError` now close the connection at the point of failure rather than at the start of the next request; those paths already left the request in progress and `ConnectionManager#confirm_ready!` closed on the next call, so this changes when the close happens rather than adding one
+  - Extracted from #1130; thanks to Dan Mayer for the original fix and Jianbin Chen for the port
+
+- Fix `ResponseBuffer` compaction logic (#1119)
+  - `COMPACT_THRESHOLD` was removed in #1116 as apparently unused, but the constant was referenced by the compaction guard; its absence silently disabled buffer compaction
+  - Restored the constant, corrected the compaction condition, and improved the buffer-shrinking implementation to use `String#bytesplice` (backed by `memmove`) for true in-place compaction
+  - Adds targeted tests covering the compaction threshold and shrink behavior
+  - Thanks to Jean Boussier for this contribution
+
+Maintenance:
+
+- Scope `StrictWarnings` to Dalli's own source (#1134)
+  - The test suite runs under `-w` and prepends a hook to `Warning.singleton_class` that turns warnings into failures, but that hook is global: a warning emitted while loading any third-party gem aborted the whole suite before a single test ran
+  - `json` 2.21.2's pure-Ruby generator (used on JRuby, where the C extension is unavailable) warns `method redefined; discarding old to_hash` at require time, which took the `jruby-10` CI job red with no change to Dalli
+  - Warnings are now attributed to a source file and only raise for `lib/` and `test/`; attribution prefers the location Ruby embeds in the message, since the stack at that point describes the require chain rather than the offending code
+  - Portable attribution of `Kernel#warn` callers also required walking the stack rather than indexing it (Ruby 3.3/3.4 push an `<internal:warning>` frame that 4.0 does not), skipping RubyGems' `Kernel#warn` shim (active on JRuby but not CRuby), and resolving relative backtrace paths
+
+- Make raw and namespace fast path tests actually use those options (#1129)
+  - Followup to #1127: the `raw` and `namespace` variants passed those options to the helper that starts memcached, which configures the client the tests then discarded, so neither option was ever exercised
+  - Passes the options to the client under test and adds assertions that fail if they are absent
+  - Thanks to Iliana Hadzhiatanasova for this contribution
+
+- Benchmark `set_multi` and add a `delete_multi` target (#1132)
+  - Enables the two `set_multi` reports that were commented out pending the arrival of `set_multi`, resolving the accompanying TODO
+  - Adds a `delete_multi` target comparing the pipelined path against N single deletes
+  - Extracted from #1130; thanks to Jianbin Chen for this contribution
+
+- Bump CI memcached to 1.6.41 and run benchmarks on pull requests (#1133)
+  - The tests workflow moves from 1.6.40 to 1.6.41; the benchmarks and profile workflows had drifted back on 1.6.23
+  - Extracted from #1130; thanks to Jianbin Chen for this contribution
+
+- Disable RuboCop metrics cops (#1128)
+  - Thanks to Jean Boussier for this contribution
+
+- Remove `PIDCache` module (#1125)
+  - `Process.pid` is cached natively by Ruby 3.3+ (via https://bugs.ruby-lang.org/issues/19443), making the manual cache unnecessary now that Dalli requires Ruby 3.3+
+  - Thanks to Jean Boussier for this contribution
+
+- Remove unused `COMPACT_THRESHOLD` constant from `ResponseBuffer` (#1116)
+  - Followup cleanup after the buffer management redesign in #1114
+  - Note: subsequently found to be in use; restored and corrected in #1119
+  - Thanks to Jean Boussier for this contribution
+
+- Use `String#byteindex` instead of `String#index` when searching for the response terminator in `getk_response_from_buffer` (#1112)
+  - The result feeds directly into `byteslice`; `byteindex` makes the intent explicit, though both return the same value since the buffer encoding is always `BINARY`
+  - Thanks to Jean Boussier for this contribution
+
+- Make single-server fast path tests actually exercise the fast path (#1127)
+  - The batch-operation tests built clients through a helper that registers two address aliases for the same memcached process, so every client had a 2-server ring and the tests always ran through the pipelined path instead of the single-server fast path
+  - Adds a `single_server_client` test helper that builds a client with a single address, and uses it in the affected `get_multi`, `set_multi`, and `delete_multi` tests
+  - Thanks to Iliana Hadzhiatanasova for this contribution
+
 5.0.5
 ==========
 

data/lib/dalli/client.rb

@@ -225,6 +225,8 @@ module Dalli
     def fetch_with_lock(key, ttl: nil, lock_ttl: 30, recache_threshold: nil, req_options: nil, &block)
       raise ArgumentError, 'Block is required for fetch_with_lock' unless block_given?
 
+      validate_integer!(:lock_ttl, lock_ttl)
+      validate_integer!(:recache_threshold, recache_threshold)
       key = key.to_s
       key = @key_manager.validate_key(key)
 
@@ -364,12 +366,15 @@ module Dalli
     # it batches requests by server and uses quiet mode.
     #
     # @param keys [Array<String>] keys to delete
-    # @return [void]
+    # @return [Integer] the number of keys that were found and deleted. This is
+    #   best-effort: on a network error the operation is retried, and keys
+    #   deleted before the error are not recounted, so the result may
+    #   under-report the number actually removed when a failure occurs.
     #
     # Example:
     #   client.delete_multi(['key1', 'key2', 'key3'])
     def delete_multi(keys)
-      return if keys.empty?
+      return 0 if keys.empty?
 
       Instrumentation.trace('delete_multi', multi_trace_attrs('delete_multi', keys.size, keys)) do
         if ring.servers.size == 1
@@ -397,6 +402,8 @@ module Dalli
     ##
     # Incr adds the given amount to the counter on the memcached server.
     # Amt must be a positive integer value.
+    # Default, if given, must be an Integer (or a String of decimal digits);
+    # anything else raises ArgumentError.
     #
     # If default is nil, the counter must already exist or the operation
     # will fail and will return nil.  Otherwise this method will return
@@ -409,6 +416,7 @@ module Dalli
     # If the value already exists, it must have been set with raw: true
     def incr(key, amt = 1, ttl = nil, default = nil)
       check_positive!(amt)
+      validate_integer!(:default, default)
 
       perform(:incr, key, amt.to_i, ttl_or_default(ttl), default)
     end
@@ -416,6 +424,8 @@ module Dalli
     ##
     # Decr subtracts the given amount from the counter on the memcached server.
     # Amt must be a positive integer value.
+    # Default, if given, must be an Integer (or a String of decimal digits);
+    # anything else raises ArgumentError.
     #
     # memcached counters are unsigned and cannot hold negative values.  Calling
     # decr on a counter which is 0 will just return 0.
@@ -431,6 +441,7 @@ module Dalli
     # If the value already exists, it must have been set with raw: true
     def decr(key, amt = 1, ttl = nil, default = nil)
       check_positive!(amt)
+      validate_integer!(:default, default)
 
       perform(:decr, key, amt.to_i, ttl_or_default(ttl), default)
     end
@@ -569,11 +580,18 @@ module Dalli
 
     def single_server_delete_multi(keys)
       validated_keys = keys.map { |k| @key_manager.validate_key(k.to_s) }
-      return unless (server = single_server)
+      return 0 unless (server = single_server)
 
       server.request(:delete_multi_req, validated_keys)
+    rescue Dalli::RetryableNetworkError => e
+      # Mirror the pipelined path: retry transient errors so a momentary blip
+      # still yields a real count. Bounded by the server's socket_max_failures,
+      # after which a hard NetworkError is raised and handled below.
+      Dalli.logger.debug { e.inspect }
+      Dalli.logger.debug { 'retrying single-server delete_multi because of network error' }
+      retry
     rescue Dalli::NetworkError
-      nil
+      0
     end
 
     def get_multi_attributes(keys)
@@ -607,6 +625,19 @@ module Dalli
       raise ArgumentError, "Positive values only: #{amt}" if amt.negative?
     end
 
+    # Numeric arguments that become meta protocol flags (GHSA-6wmv-xq9m-fmp7).
+    # RequestFormatter converts them to Integer as the wire-level backstop;
+    # checking here too raises a clean ArgumentError before the request
+    # starts, instead of Protocol::Base#request logging it as unexpected and
+    # closing the connection.
+    def validate_integer!(name, value)
+      return if value.nil?
+
+      value.is_a?(String) ? Integer(value, 10) : Integer(value)
+    rescue ArgumentError, TypeError, FloatDomainError
+      raise ArgumentError, "#{name} must be an Integer, got #{value.inspect}"
+    end
+
     def cas_core(key, always_set, ttl = nil, req_options = nil)
       (value, cas) = perform(:cas, key)
       return if value.nil? && !always_set
@@ -651,7 +682,7 @@ module Dalli
     # operation times out.
     ##
     # rubocop:disable Naming/MethodParameterName
-    def perform(op, key, *args)
+    def perform(op, key, ...)
       # rubocop:enable Naming/MethodParameterName
       return yield if block_given?
 
@@ -659,8 +690,14 @@ module Dalli
       key = @key_manager.validate_key(key)
 
       server = ring.server_for_key(key)
-      Instrumentation.trace(op.to_s, trace_attrs(op.to_s, key, server)) do
-        server.request(op, key, *args)
+
+      if Instrumentation.enabled?
+        op_name = op.name
+        Instrumentation.trace(op_name, trace_attrs(op_name, key, server)) do
+          server.request(op, key, ...)
+        end
+      else
+        server.request(op, key, ...)
       end
     rescue RetryableNetworkError => e
       Dalli.logger.debug { e.inspect }

data/lib/dalli/options.rb

@@ -13,7 +13,7 @@ module Dalli
       obj.init_threadsafe
     end
 
-    def request(opcode, *args)
+    def request(...)
       @lock.synchronize do
         super
       end

data/lib/dalli/pipelined_deleter.rb

@@ -16,16 +16,19 @@ module Dalli
     # Deletes multiple keys from memcached.
     #
     # @param keys [Array<String>] keys to delete
-    # @return [void]
+    # @return [Integer] the number of keys that were deleted. This is
+    #   best-effort: on a network error the operation is retried, and keys
+    #   deleted before the error are not recounted, so the result may
+    #   under-report the number actually removed when a failure occurs.
     ##
     def process(keys)
-      return if keys.empty?
+      return 0 if keys.empty?
 
       @ring.lock do
-        servers = setup_requests(keys)
-        finish_requests(servers)
+        groups = setup_requests(keys)
+        finish_requests(groups)
       end
-    rescue NetworkError => e
+    rescue Dalli::RetryableNetworkError => e
       Dalli.logger.debug { e.inspect }
       Dalli.logger.debug { 'retrying pipelined deletes because of network error' }
       retry
@@ -36,7 +39,7 @@ module Dalli
     def setup_requests(keys)
       groups = groups_for_keys(keys)
       make_delete_requests(groups)
-      groups.keys
+      groups
     end
 
     ##
@@ -45,24 +48,28 @@ module Dalli
     ##
     def make_delete_requests(groups)
       groups.each do |server, keys_for_server|
-        keys_for_server.each do |key|
+        keys_for_server.select! do |key|
           server.request(:pipelined_delete, key)
+          true
         rescue DalliError, NetworkError => e
           Dalli.logger.debug { e.inspect }
           Dalli.logger.debug { "unable to delete key #{key} for server #{server.name}" }
+          false
         end
       end
     end
 
     ##
     # Sends noop to each server to flush responses and ensure all deletes complete.
+    # Returns the total successful deletes across servers.
     ##
-    def finish_requests(servers)
-      servers.each do |server|
-        server.request(:noop)
+    def finish_requests(groups)
+      groups.sum do |server, keys_for_server|
+        server.request(:finish_pipelined_delete, keys_for_server.size)
       rescue DalliError, NetworkError => e
         Dalli.logger.debug { e.inspect }
         Dalli.logger.debug { "unable to complete pipelined delete on server #{server.name}" }
+        0
       end
     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
 
@@ -95,7 +109,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

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,18 @@ 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]
+        def required?(key)
+          !key.ascii_only? || /\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