multi_json 1.15.0 → 1.21.1

data/lib/multi_json/adapter_selector.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module MultiJSON
+  # Handles adapter discovery, loading, and selection
+  #
+  # Adapters can be specified as:
+  # - Symbol/String: adapter name (e.g., :oj, "json_gem")
+  # - Module: adapter class directly
+  # - nil/false: use default adapter
+  #
+  # @api private
+  module AdapterSelector
+    extend self
+
+    # Per-adapter metadata, in preference order (fastest first). Each
+    # entry maps the adapter symbol to its ``require`` path and the
+    # constant whose presence indicates the backing library is already
+    # loaded. ``loaded`` is a ``::``-separated path so we can walk it
+    # without an explicit ``defined?`` check.
+    #
+    # The hash order is split per platform: on MRI/TruffleRuby the
+    # bundled benchmark suite ranks json_gem ahead of fast_jsonparser/
+    # oj/yajl on Ruby 3.4+; on JRuby the FFI-vs-pure-Ruby tradeoff
+    # hasn't been re-benchmarked yet, so jr_jackson stays first there.
+    # CI re-runs the benchmark with ``--verify-preference`` to fail
+    # if the observed ranking diverges.
+    # :nocov:
+    ADAPTERS = if RUBY_ENGINE == "jruby"
+      {
+        jr_jackson: {require: "jrjackson", loaded: "JrJackson"},
+        json_gem: {require: "json", loaded: "JSON::Ext::Parser"},
+        gson: {require: "gson", loaded: "Gson"},
+        fast_jsonparser: {require: "fast_jsonparser", loaded: "FastJsonparser"},
+        oj: {require: "oj", loaded: "Oj"},
+        yajl: {require: "yajl", loaded: "Yajl"}
+      }.freeze
+    else
+      {
+        json_gem: {require: "json", loaded: "JSON::Ext::Parser"},
+        fast_jsonparser: {require: "fast_jsonparser", loaded: "FastJsonparser"},
+        oj: {require: "oj", loaded: "Oj"},
+        yajl: {require: "yajl", loaded: "Yajl"},
+        jr_jackson: {require: "jrjackson", loaded: "JrJackson"},
+        gson: {require: "gson", loaded: "Gson"}
+      }.freeze
+    end
+    # :nocov:
+    private_constant :ADAPTERS
+
+    # Backwards-compatible view of {ADAPTERS} that exposes only the
+    # require paths. Tests still poke at this constant to stub or break
+    # the require step.
+    REQUIREMENT_MAP = ADAPTERS.transform_values { |meta| meta[:require] }.freeze
+
+    # Returns the default adapter to use
+    #
+    # @api private
+    # @return [Symbol] adapter name
+    # @example
+    #   AdapterSelector.default_adapter  #=> :oj
+    def default_adapter
+      Concurrency.synchronize(:default_adapter) { @default_adapter ||= detect_best_adapter }
+    end
+
+    # Returns the default adapter class, excluding the given adapter name
+    #
+    # Used by adapters that only implement one direction (e.g.
+    # FastJsonparser only parses) so the other direction can be delegated
+    # to whichever library MultiJSON would otherwise pick.
+    #
+    # @api private
+    # @param excluded [Symbol] adapter name to skip during detection
+    # @return [Class] the adapter class
+    # @example
+    #   AdapterSelector.default_adapter_excluding(:fast_jsonparser)  #=> MultiJSON::Adapters::Oj
+    def default_adapter_excluding(excluded)
+      Concurrency.synchronize(:default_adapter) do
+        name = loaded_adapter(excluding: excluded)
+        name ||= installable_adapter(excluding: excluded)
+        name ||= fallback_adapter
+        load_adapter_by_name(name.to_s)
+      end
+    end
+
+    private
+
+    # Detects the best available JSON adapter
+    #
+    # @api private
+    # @return [Symbol] adapter name
+    def detect_best_adapter
+      loaded_adapter || installable_adapter || fallback_adapter
+    end
+
+    # Finds an already-loaded JSON library
+    #
+    # @api private
+    # @param excluding [Symbol, nil] adapter name to skip during detection
+    # @return [Symbol, nil] adapter name if found
+    def loaded_adapter(excluding: nil)
+      ADAPTERS.each do |name, meta|
+        next if name == excluding
+        return name if Object.const_defined?(meta.fetch(:loaded))
+      end
+      nil
+    end
+
+    # Tries to require and use an installable adapter
+    #
+    # @api private
+    # @param excluding [Symbol, nil] adapter name to skip during detection
+    # @return [Symbol, nil] adapter name if successfully required
+    def installable_adapter(excluding: nil)
+      REQUIREMENT_MAP.each_key do |adapter_name|
+        next if adapter_name == excluding
+        return adapter_name if try_require(adapter_name)
+      end
+      nil
+    end
+
+    # Attempts to require a JSON library
+    #
+    # @api private
+    # @param adapter_name [Symbol] adapter to require
+    # @return [Boolean] true if require succeeded
+    def try_require(adapter_name)
+      require REQUIREMENT_MAP.fetch(adapter_name)
+      true
+    rescue ::LoadError
+      false
+    end
+
+    # Returns the fallback adapter when no others available
+    #
+    # The json gem is a Ruby default gem since Ruby 1.9, so in practice
+    # the installable-adapter step always succeeds before reaching this
+    # fallback on any supported Ruby version. The warning below only
+    # fires in tests that deliberately break the require path.
+    #
+    # @api private
+    # @return [Symbol] the json_gem adapter name
+    def fallback_adapter
+      warn_about_fallback unless @default_adapter_warning_shown
+      @default_adapter_warning_shown = true
+      :json_gem
+    end
+
+    # Warns the user about reaching the last-resort fallback
+    #
+    # @api private
+    # @return [void]
+    def warn_about_fallback
+      Kernel.warn(
+        "[WARNING] MultiJSON is falling back to the json_gem adapter " \
+        "because no other JSON library could be loaded."
+      )
+    end
+
+    # Loads an adapter from a specification
+    #
+    # @api private
+    # @param adapter_spec [Symbol, String, Module, nil, false] adapter specification
+    # @return [Class] the adapter class
+    def load_adapter(adapter_spec)
+      adapter = case adapter_spec
+      when ::String then load_adapter_by_name(adapter_spec)
+      when ::Symbol then load_adapter_by_name(adapter_spec.to_s)
+      when nil, false then load_adapter(default_adapter)
+      when ::Module then adapter_spec
+      else raise ::LoadError, "expected adapter to be a Symbol, String, or Module, got #{adapter_spec.inspect}"
+      end
+      validate_adapter!(adapter)
+    rescue ::LoadError => e
+      raise AdapterError.build(e)
+    end
+
+    # Loads an adapter by its string name
+    #
+    # ``jrjackson`` (the JrJackson gem's name) is normalized to
+    # ``jr_jackson`` (the adapter file/class name) for backwards
+    # compatibility with the original gem-name alias.
+    #
+    # @api private
+    # @param name [String] adapter name
+    # @return [Class] the adapter class
+    def load_adapter_by_name(name)
+      normalized = name.downcase
+      normalized = "jr_jackson" if normalized == "jrjackson"
+      require_relative "adapters/#{normalized}"
+
+      class_name = normalized.split("_").map(&:capitalize).join
+      ::MultiJSON::Adapters.const_get(class_name)
+    end
+
+    # Validate that an adapter satisfies the documented contract
+    #
+    # Custom adapters are accepted as modules/classes, so fail fast
+    # during adapter resolution rather than later on the first load or
+    # dump call.
+    #
+    # @api private
+    # @param adapter [Module] adapter class or module
+    # @return [Module] the validated adapter
+    # @raise [AdapterError] when the adapter is missing a required class method
+    #   or ParseError constant
+    def validate_adapter!(adapter)
+      raise AdapterError, "Adapter #{adapter} must respond to .load" unless adapter.respond_to?(:load)
+      raise AdapterError, "Adapter #{adapter} must respond to .dump" unless adapter.respond_to?(:dump)
+
+      MultiJSON.parse_error_class_for(adapter)
+      adapter
+    end
+  end
+end

data/lib/multi_json/adapters/fast_jsonparser.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "fast_jsonparser"
+require_relative "../adapter"
+require_relative "../adapter_selector"
+
+module MultiJSON
+  module Adapters
+    # Use the FastJsonparser library to load, and the fastest other
+    # available adapter to dump.
+    #
+    # FastJsonparser only implements parsing, so the ``dump`` side of
+    # the adapter is delegated to whichever adapter MultiJSON would
+    # pick if FastJsonparser weren't installed (oj → yajl → jr_jackson
+    # → json_gem → gson). The delegate is resolved lazily at the first
+    # ``dump`` call, not at file load time, so load order doesn't lock
+    # in the wrong delegate. Require any preferred dump backend before
+    # the first ``dump`` call (typical applications already have ``oj``
+    # loaded by then).
+    class FastJsonparser < Adapter
+      defaults :load, symbolize_names: false
+
+      # Exception raised when JSON parsing fails
+      ParseError = ::FastJsonparser::ParseError
+
+      class << self
+        # Serialize a Ruby object to JSON via the lazy delegate
+        #
+        # @api private
+        # @param object [Object] object to serialize
+        # @param options [Hash] serialization options
+        # @return [String] JSON string
+        # @example
+        #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
+        def dump(object, options = {})
+          dump_delegate.dump(object, options)
+        end
+
+        private
+
+        # Resolve the dump delegate, caching it across calls
+        #
+        # @api private
+        # @return [Class] delegate adapter class
+        def dump_delegate
+          MultiJSON::Concurrency.synchronize(:dump_delegate) do
+            @dump_delegate ||= MultiJSON::AdapterSelector.default_adapter_excluding(:fast_jsonparser)
+          end
+        end
+      end
+
+      # Parse a JSON string into a Ruby object
+      #
+      # FastJsonparser.parse only accepts ``symbolize_keys`` and raises
+      # on unknown keyword arguments, so the adapter explicitly forwards
+      # MultiJSON's canonical ``:symbolize_names`` option as
+      # FastJsonparser's native ``symbolize_keys:`` kwarg and silently
+      # drops the rest. Pass other options through
+      # ``MultiJSON.parse_options=`` and they'll apply to whichever
+      # adapter MultiJSON selects when fast_jsonparser isn't installed.
+      #
+      # @api private
+      # @param string [String] JSON string to parse
+      # @param options [Hash] parsing options (only :symbolize_names is honored)
+      # @return [Object] parsed Ruby object
+      #
+      # @example Parse JSON string
+      #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
+      def load(string, options = {})
+        ::FastJsonparser.parse(string, symbolize_keys: options[:symbolize_names])
+      end
+    end
+  end
+end

data/lib/multi_json/adapters/json_gem.rb

@@ -1,11 +1,72 @@
-require 'json/ext'
-require 'multi_json/adapters/json_common'
+# frozen_string_literal: true
 
-module MultiJson
+require_relative "../adapter"
+require "json"
+
+module MultiJSON
   module Adapters
     # Use the JSON gem to dump/load.
-    class JsonGem < JsonCommon
+    class JsonGem < Adapter
+      # Exception raised when JSON parsing fails
       ParseError = ::JSON::ParserError
+
+      defaults :load, create_additions: false, quirks_mode: true
+
+      PRETTY_STATE_PROTOTYPE = {
+        indent: "  ",
+        space: " ",
+        object_nl: "\n",
+        array_nl: "\n"
+      }.freeze
+      private_constant :PRETTY_STATE_PROTOTYPE
+
+      # Parse a JSON string into a Ruby object
+      #
+      # Non-UTF-8 strings are re-labeled via ``force_encoding`` (not
+      # transcoded) and then validated. This handles the dominant
+      # real-world case: Ruby HTTP libraries return response bodies
+      # tagged as ``ASCII-8BIT`` even when the bytes are valid UTF-8.
+      # ``encode(Encoding::UTF_8)`` would raise on any multi-byte
+      # sequence in that scenario because it tries to transcode each
+      # byte individually from ASCII-8BIT to UTF-8.
+      #
+      # @api private
+      # @param string [String] JSON string to parse
+      # @param options [Hash] parsing options
+      # @return [Object] parsed Ruby object
+      # @raise [::JSON::ParserError] when the input is not valid UTF-8
+      #
+      # @example Parse JSON string
+      #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
+      def load(string, options = {})
+        if string.encoding != Encoding::UTF_8
+          string = string.dup.force_encoding(Encoding::UTF_8)
+          raise ::JSON::ParserError, "Invalid UTF-8 byte sequence in JSON input" unless string.valid_encoding?
+        end
+
+        ::JSON.parse(string, options)
+      end
+
+      # Serialize a Ruby object to JSON
+      #
+      # @api private
+      # @param object [Object] object to serialize
+      # @param options [Hash] serialization options
+      # @return [String] JSON string
+      #
+      # @example Serialize object to JSON
+      #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
+      def dump(object, options = {})
+        json_object = object.respond_to?(:as_json) ? object.as_json : object
+        return ::JSON.dump(json_object) if options.empty?
+        return ::JSON.generate(json_object, options) unless options.key?(:pretty)
+
+        # Common case: ``pretty: true`` is the only option, so the merge
+        # would just produce a copy of PRETTY_STATE_PROTOTYPE.
+        return ::JSON.pretty_generate(json_object, PRETTY_STATE_PROTOTYPE) if options.size == 1
+
+        ::JSON.pretty_generate(json_object, PRETTY_STATE_PROTOTYPE.merge(options.except(:pretty)))
+      end
     end
   end
 end

data/lib/multi_json/adapters/oj.rb

@@ -1,62 +1,88 @@
-require 'set'
-require 'oj'
-require 'multi_json/adapter'
+# frozen_string_literal: true
 
-module MultiJson
+require "oj"
+require_relative "../adapter"
+require_relative "oj_common"
+
+module MultiJSON
+  # Namespace for JSON adapter implementations
+  #
+  # Each adapter wraps a specific JSON library and provides a consistent
+  # interface for loading and dumping JSON data.
   module Adapters
     # Use the Oj library to dump/load.
     class Oj < Adapter
-      defaults :load, :mode => :strict, :symbolize_keys => false
-      defaults :dump, :mode => :compat, :time_format => :ruby, :use_to_json => true
-
-      # In certain cases OJ gem may throw JSON::ParserError exception instead
-      # of its own class. Also, we can't expect ::JSON::ParserError and
-      # ::Oj::ParseError to always be defined, since it's often not the case.
-      # Because of this, we can't reference those classes directly and have to
-      # do string comparison instead. This will not catch subclasses, but it
-      # shouldn't be a problem since the library is not known to be using it
-      # (at least for now).
+      include OjCommon
+
+      defaults :load, mode: :strict, symbolize_names: false
+      defaults :dump, mode: :compat, time_format: :ruby, use_to_json: true
+
+      # In certain cases the Oj gem may throw a ``JSON::ParserError``
+      # exception instead of its own class. Neither ``::JSON::ParserError``
+      # nor ``::Oj::ParseError`` is guaranteed to be defined, so we can't
+      # reference them directly — match by walking the exception's
+      # ancestry by class name instead. This will not catch subclasses
+      # of those classes, which shouldn't be a problem since neither
+      # library is known to subclass them.
       class ParseError < ::SyntaxError
-        WRAPPED_CLASSES = %w[Oj::ParseError JSON::ParserError].to_set.freeze
+        WRAPPED_CLASSES = %w[Oj::ParseError JSON::ParserError].freeze
+        private_constant :WRAPPED_CLASSES
 
+        # Case equality for exception matching in rescue clauses
+        #
+        # @api private
+        # @param exception [Exception] exception to check
+        # @return [Boolean] true if exception is a parse error
+        #
+        # @example Match parse errors in rescue
+        #   rescue ParseError => e
         def self.===(exception)
-          case exception
-          when ::SyntaxError
-            true
-          else
-            WRAPPED_CLASSES.include?(exception.class.to_s)
-          end
+          exception.class.ancestors.any? { |ancestor| WRAPPED_CLASSES.include?(ancestor.to_s) }
         end
       end
 
+      # Parse a JSON string into a Ruby object
+      #
+      # @api private
+      # @param string [String] JSON string to parse
+      # @param options [Hash] parsing options
+      # @return [Object] parsed Ruby object
+      #
+      # @example Parse JSON string
+      #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
       def load(string, options = {})
-        options[:symbol_keys] = options[:symbolize_keys]
-        ::Oj.load(string, options)
+        ::Oj.load(string, translate_load_options(options))
       end
 
-      case ::Oj::VERSION
-      when /\A2\./
-        def dump(object, options = {})
-          options.merge!(:indent => 2) if options[:pretty]
-          options[:indent] = options[:indent].to_i if options[:indent]
-          ::Oj.dump(object, options)
-        end
-      when /\A3\./
-        PRETTY_STATE_PROTOTYPE = {
-          :indent                => "  ",
-          :space                 => " ",
-          :space_before          => "",
-          :object_nl             => "\n",
-          :array_nl              => "\n",
-          :ascii_only            => false,
-        }
-
-        def dump(object, options = {})
-          options.merge!(PRETTY_STATE_PROTOTYPE.dup) if options.delete(:pretty)
-          ::Oj.dump(object, options)
-        end
-      else
-        fail "Unsupported Oj version: #{::Oj::VERSION}"
+      # Serialize a Ruby object to JSON
+      #
+      # @api private
+      # @param object [Object] object to serialize
+      # @param options [Hash] serialization options
+      # @return [String] JSON string
+      #
+      # @example Serialize object to JSON
+      #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
+      def dump(object, options = {})
+        ::Oj.dump(object, prepare_dump_options(options))
+      end
+
+      private
+
+      # Translate ``:symbolize_names`` into Oj's ``:symbol_keys``
+      #
+      # Returns a new hash without mutating the input.
+      # ``:symbol_keys`` is always set (true or false) so MultiJSON's
+      # behavior is independent of any global ``Oj.default_options``
+      # the host application may have set. The input is the cached hash
+      # returned from {Adapter.merged_load_options}, so in-place edits
+      # would pollute the cache.
+      #
+      # @api private
+      # @param options [Hash] merged load options
+      # @return [Hash] options with ``:symbolize_names`` translated
+      def translate_load_options(options)
+        options.except(:symbolize_names).merge(symbol_keys: options[:symbolize_names] == true)
       end
     end
   end

data/lib/multi_json/adapters/oj_common.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module MultiJSON
+  module Adapters
+    # Shared functionality for the Oj adapter
+    #
+    # Provides option preparation for Oj.dump. Targets Oj 3.x; Oj 2.x is
+    # no longer supported.
+    #
+    # @api private
+    module OjCommon
+      PRETTY_STATE_PROTOTYPE = {
+        indent: "  ",
+        space: " ",
+        space_before: "",
+        object_nl: "\n",
+        array_nl: "\n",
+        ascii_only: false
+      }.freeze
+      private_constant :PRETTY_STATE_PROTOTYPE
+
+      private
+
+      # Prepare options for Oj.dump
+      #
+      # Returns a fresh hash; never mutates the input. The input is the
+      # cached options hash returned from Adapter.merged_dump_options, so
+      # in-place mutation would pollute the cache and corrupt subsequent
+      # dump calls.
+      #
+      # @api private
+      # @param options [Hash] serialization options
+      # @return [Hash] processed options for Oj.dump
+      #
+      # @example Prepare dump options
+      #   prepare_dump_options(pretty: true)
+      def prepare_dump_options(options)
+        return options unless options.key?(:pretty)
+
+        options.except(:pretty).merge(PRETTY_STATE_PROTOTYPE)
+      end
+    end
+  end
+end

data/lib/multi_json/adapters/yajl.rb

@@ -1,16 +1,37 @@
-require 'yajl'
-require 'multi_json/adapter'
+# frozen_string_literal: true
 
-module MultiJson
+require "yajl"
+require_relative "../adapter"
+
+module MultiJSON
   module Adapters
     # Use the Yajl-Ruby library to dump/load.
     class Yajl < Adapter
+      # Exception raised when JSON parsing fails
       ParseError = ::Yajl::ParseError
 
+      # Parse a JSON string into a Ruby object
+      #
+      # @api private
+      # @param string [String] JSON string to parse
+      # @param options [Hash] parsing options
+      # @return [Object] parsed Ruby object
+      #
+      # @example Parse JSON string
+      #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
       def load(string, options = {})
-        ::Yajl::Parser.new(:symbolize_keys => options[:symbolize_keys]).parse(string)
+        ::Yajl::Parser.new(options).parse(string)
       end
 
+      # Serialize a Ruby object to JSON
+      #
+      # @api private
+      # @param object [Object] object to serialize
+      # @param options [Hash] serialization options
+      # @return [String] JSON string
+      #
+      # @example Serialize object to JSON
+      #   adapter.dump({key: "value"}) #=> '{"key":"value"}'
       def dump(object, options = {})
         ::Yajl::Encoder.encode(object, options)
       end

data/lib/multi_json/concurrency.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module MultiJSON
+  # Catalog of process-wide mutexes used to serialize MultiJSON's lazy
+  # initializers and adapter swaps. Each mutex protects a distinct
+  # piece of mutable state. Callers go through {.synchronize} rather
+  # than touching the mutex constants directly so the constants
+  # themselves can stay {.private_constant} and the surface of the
+  # module is documented in one place.
+  #
+  # @api private
+  module Concurrency
+    # Catalog of mutexes keyed by symbolic name. Each entry maps the
+    # public name passed to {.synchronize} to the underlying mutex
+    # instance. The names are documented inline so callers can find
+    # what each mutex protects without leaving this file.
+    MUTEXES = {
+      # Guards the {DEPRECATION_WARNINGS_SHOWN} set in `MultiJSON` so the
+      # check-then-add pair in `warn_deprecation_once` doesn't race.
+      deprecation_warnings: Mutex.new,
+      # Guards the process-wide `@adapter` swap in `MultiJSON.use` so two
+      # threads can't interleave their `OptionsCache.reset` and adapter
+      # assignment.
+      adapter: Mutex.new,
+      # Guards the lazy `@default_adapter` initializer and the
+      # `default_adapter_excluding` detection chain in `AdapterSelector`,
+      # so the chain runs at most once and `fallback_adapter`'s one-time
+      # warning fires at most once.
+      default_adapter: Mutex.new,
+      # Guards the lazy `default_load_options` / `default_dump_options`
+      # initializers in `MultiJSON::Options`.
+      default_options: Mutex.new,
+      # Guards the lazy dump-delegate resolution in
+      # `MultiJSON::Adapters::FastJsonparser`.
+      dump_delegate: Mutex.new
+    }.freeze
+    private_constant :MUTEXES
+
+    # Run a block while holding the named mutex
+    #
+    # The ``name`` symbol must be one of the keys in the internal
+    # ``MUTEXES`` table; an unknown name raises ``KeyError`` so a
+    # typo at the call site fails fast instead of silently dropping
+    # synchronization on the floor.
+    #
+    # @api private
+    # @param name [Symbol] mutex identifier
+    # @yield block to execute while holding the mutex
+    # @return [Object] the block's return value
+    # @raise [KeyError] when ``name`` does not match a known mutex
+    # @example
+    #   MultiJSON::Concurrency.synchronize(:adapter) { ... }
+    def self.synchronize(name, &)
+      MUTEXES.fetch(name).synchronize(&)
+    end
+  end
+end