multi_json 1.20.0-java

data/lib/multi_json/adapter.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "singleton"
+require_relative "options"
+
+module MultiJson
+  # Base class for JSON adapter implementations
+  #
+  # Each adapter wraps a specific JSON library (Oj, JSON gem, etc.) and
+  # provides a consistent interface. Uses Singleton pattern so each adapter
+  # class has exactly one instance.
+  #
+  # Subclasses must implement:
+  # - #load(string, options) -> parsed object
+  # - #dump(object, options) -> JSON string
+  #
+  # @api private
+  class Adapter
+    extend Options
+    include Singleton
+
+    class << self
+      BLANK_PATTERN = /\A\s*\z/
+      VALID_DEFAULTS_ACTIONS = %i[load dump].freeze
+      private_constant :BLANK_PATTERN, :VALID_DEFAULTS_ACTIONS
+
+      # Get default load options, walking the superclass chain
+      #
+      # Returns the closest ancestor's `@default_load_options` ivar so a
+      # parent class calling {.defaults} after a subclass has been
+      # defined still propagates to the subclass. Falls back to the
+      # shared frozen empty hash when no ancestor has defaults set.
+      #
+      # @api private
+      # @return [Hash] frozen options hash
+      def default_load_options
+        walk_default_options(:@default_load_options)
+      end
+
+      # Get default dump options, walking the superclass chain
+      #
+      # @api private
+      # @return [Hash] frozen options hash
+      def default_dump_options
+        walk_default_options(:@default_dump_options)
+      end
+
+      # DSL for setting adapter-specific default options
+      #
+      # ``action`` must be ``:load`` or ``:dump``; ``value`` must be a
+      # Hash. Both arguments are validated up front so a typo at the
+      # adapter's class definition fails fast instead of producing a
+      # silent no-op default that crashes later in the merge path.
+      #
+      # @api private
+      # @param action [Symbol] :load or :dump
+      # @param value [Hash] default options for the action
+      # @return [Hash] the frozen options hash
+      # @raise [ArgumentError] when action is anything other than :load
+      #   or :dump, or when value isn't a Hash
+      # @example Set load defaults for an adapter
+      #   class MyAdapter < MultiJson::Adapter
+      #     defaults :load, symbolize_keys: false
+      #   end
+      def defaults(action, value)
+        raise ArgumentError, "expected action to be :load or :dump, got #{action.inspect}" unless VALID_DEFAULTS_ACTIONS.include?(action)
+        raise ArgumentError, "expected value to be a Hash, got #{value.class}" unless value.is_a?(Hash)
+
+        instance_variable_set(:"@default_#{action}_options", value.freeze)
+      end
+
+      # Parse a JSON string into a Ruby object
+      #
+      # @api private
+      # @param string [String, #read] JSON string or IO-like object
+      # @param options [Hash] parsing options
+      # @return [Object, nil] parsed object or nil for blank input
+      def load(string, options = {})
+        string = string.read if string.respond_to?(:read)
+        return nil if blank?(string)
+
+        instance.load(string, merged_load_options(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
+      def dump(object, options = {})
+        instance.dump(object, merged_dump_options(options))
+      end
+
+      private
+
+      # Walk the superclass chain looking for a default options ivar
+      #
+      # Stops at the first ancestor whose ``ivar`` is set and returns
+      # that value. Returns {Options::EMPTY_OPTIONS} when no ancestor
+      # has the ivar set, so adapters without defaults always observe a
+      # frozen empty hash instead of nil.
+      #
+      # @api private
+      # @param ivar [Symbol] ivar name (`:@default_load_options` or `:@default_dump_options`)
+      # @return [Hash] frozen options hash
+      def walk_default_options(ivar)
+        # @type var klass: Class?
+        klass = self
+        while klass
+          return klass.instance_variable_get(ivar) if klass.instance_variable_defined?(ivar)
+
+          klass = klass.superclass
+        end
+        Options::EMPTY_OPTIONS
+      end
+
+      # Checks if the input is blank (nil, empty, or whitespace-only)
+      #
+      # The dominant call path arrives with a non-blank string starting
+      # with ``{`` or ``[`` (the JSON object/array sigils), so a
+      # ``start_with?`` short-circuit skips the regex entirely on the
+      # hot path. Falls through to the full check for everything else
+      # — strings, numbers, booleans, ``null``, whitespace-prefixed
+      # input — at which point ``String#scrub`` is only invoked when
+      # the input has invalid encoding so the common valid-UTF-8 path
+      # doesn't allocate a scrubbed copy on every call. Scrubbing
+      # replaces invalid bytes with U+FFFD before the regex runs so a
+      # string with bad bytes is still treated as non-blank without a
+      # broad rescue.
+      #
+      # @api private
+      # @param input [String, nil] input to check
+      # @return [Boolean] true if input is blank
+      def blank?(input)
+        return true if input.nil? || input.empty?
+        return false if input.start_with?("{", "[")
+
+        BLANK_PATTERN.match?(input.valid_encoding? ? input : input.scrub)
+      end
+
+      # Merges dump options from adapter, global, and call-site
+      #
+      # @api private
+      # @param options [Hash] call-site options
+      # @return [Hash] merged options hash
+      def merged_dump_options(options)
+        cache_key = strip_adapter_key(options)
+        OptionsCache.dump.fetch(cache_key) do
+          dump_options(cache_key).merge(MultiJson.dump_options(cache_key)).merge!(cache_key)
+        end
+      end
+
+      # Merges load options from adapter, global, and call-site
+      #
+      # @api private
+      # @param options [Hash] call-site options
+      # @return [Hash] merged options hash
+      def merged_load_options(options)
+        cache_key = strip_adapter_key(options)
+        OptionsCache.load.fetch(cache_key) do
+          load_options(cache_key).merge(MultiJson.load_options(cache_key)).merge!(cache_key)
+        end
+      end
+
+      # Removes the :adapter key from options for cache key
+      #
+      # Returns a shared frozen empty hash for the common no-options call
+      # path so the hot path avoids allocating a fresh hash on every call.
+      #
+      # @api private
+      # @param options [Hash, #to_h] original options (may be JSON::State or similar)
+      # @return [Hash] frozen options without :adapter key
+      def strip_adapter_key(options)
+        options = options.to_h unless options.is_a?(Hash)
+        return Options::EMPTY_OPTIONS if options.empty? || (options.size == 1 && options.key?(:adapter))
+
+        options.except(:adapter).freeze
+      end
+    end
+  end
+end

data/lib/multi_json/adapter_error.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module MultiJson
+  # Raised when an adapter cannot be loaded or is not recognized
+  #
+  # @api public
+  class AdapterError < ArgumentError
+    # Create a new AdapterError
+    #
+    # @api public
+    # @param message [String, nil] error message
+    # @param cause [Exception, nil] the original exception
+    # @return [AdapterError] new error instance
+    # @example
+    #   AdapterError.new("Unknown adapter", cause: original_error)
+    def initialize(message = nil, cause: nil)
+      super(message)
+      set_backtrace(cause.backtrace) if cause
+    end
+
+    # Build an AdapterError from an original exception
+    #
+    # The original exception's class name is included in the message
+    # so a downstream consumer reading just the AdapterError can tell
+    # whether the underlying failure was a `LoadError`, an
+    # `ArgumentError` from the spec validator, or some other class
+    # without having to look at `error.cause` separately.
+    #
+    # @api public
+    # @param original_exception [Exception] the original load error
+    # @return [AdapterError] new error with formatted message
+    # @example
+    #   AdapterError.build(LoadError.new("cannot load such file"))
+    def self.build(original_exception)
+      new(
+        "Did not recognize your adapter specification " \
+        "(#{original_exception.class}: #{original_exception.message}).",
+        cause: original_exception
+      )
+    end
+  end
+end

data/lib/multi_json/adapter_selector.rb

@@ -0,0 +1,174 @@
+# 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.
+    ADAPTERS = {
+      fast_jsonparser: {require: "fast_jsonparser", loaded: "FastJsonparser"},
+      oj: {require: "oj", loaded: "Oj"},
+      yajl: {require: "yajl", loaded: "Yajl"},
+      jr_jackson: {require: "jrjackson", loaded: "JrJackson"},
+      json_gem: {require: "json", loaded: "JSON::Ext::Parser"},
+      gson: {require: "gson", loaded: "Gson"}
+    }.freeze
+    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)
+      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
+    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
+  end
+end

data/lib/multi_json/adapters/fast_jsonparser.rb

@@ -0,0 +1,72 @@
+# 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_keys: 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
+      # only that option and silently drops the rest. Pass other options
+      # through ``MultiJson.load_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_keys 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_keys])
+      end
+    end
+  end
+end

data/lib/multi_json/adapters/gson.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "gson"
+require_relative "../adapter"
+
+module MultiJson
+  module Adapters
+    # Use the gson.rb library to dump/load.
+    class Gson < Adapter
+      # Exception raised when JSON parsing fails
+      ParseError = ::Gson::DecodeError
+
+      # Pre-allocated zero-options decoder/encoder for the dominant call
+      # path. Without an explicit ``defaults :load`` / ``defaults :dump``
+      # block on this adapter, ``MultiJson.load(json)`` and
+      # ``MultiJson.dump(obj)`` arrive here with the shared frozen empty
+      # hash from {Adapter.strip_adapter_key}, so reusing a single
+      # decoder/encoder instance avoids the per-call ``Decoder.new`` /
+      # ``Encoder.new`` allocation that the previous implementation
+      # incurred. Java Gson is documented thread-safe, so sharing the
+      # underlying handle across threads is safe.
+      DEFAULT_DECODER = ::Gson::Decoder.new({})
+      DEFAULT_ENCODER = ::Gson::Encoder.new({})
+      private_constant :DEFAULT_DECODER, :DEFAULT_ENCODER
+
+      # 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 = {})
+        decoder = options.empty? ? DEFAULT_DECODER : ::Gson::Decoder.new(options)
+        decoder.decode(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 = {})
+        encoder = options.empty? ? DEFAULT_ENCODER : ::Gson::Encoder.new(options)
+        encoder.encode(object)
+      end
+    end
+  end
+end

data/lib/multi_json/adapters/jr_jackson.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "jrjackson" unless defined?(JrJackson)
+require_relative "../adapter"
+
+module MultiJson
+  module Adapters
+    # Use the jrjackson.rb library to dump/load.
+    class JrJackson < Adapter
+      # Exception raised when JSON parsing fails
+      ParseError = ::JrJackson::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 = {})
+        ::JrJackson::Json.load(string, options)
+      end
+
+      # Serialize a Ruby object to JSON
+      #
+      # Requires JrJackson >= 0.4.18, which accepts an options hash as
+      # the second argument to ``Json.dump``.
+      #
+      # @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 = {})
+        ::JrJackson::Json.dump(object, options)
+      end
+    end
+  end
+end

data/lib/multi_json/adapters/json_gem.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "../adapter"
+require "json"
+
+module MultiJson
+  module Adapters
+    # Use the JSON gem to dump/load.
+    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
+      #
+      # @api private
+      # @param string [String] JSON string to parse
+      # @param options [Hash] parsing options
+      # @return [Object] parsed Ruby object
+      # @raise [::JSON::ParserError] when input contains invalid bytes that
+      #   cannot be transcoded to UTF-8
+      #
+      # @example Parse JSON string
+      #   adapter.load('{"key":"value"}') #=> {"key" => "value"}
+      def load(string, options = {})
+        if string.encoding != Encoding::UTF_8
+          begin
+            string = string.encode(Encoding::UTF_8)
+          rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError => e
+            raise ::JSON::ParserError, e.message
+          end
+        end
+
+        ::JSON.parse(string, translate_load_options(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
+
+      private
+
+      # Translate ``:symbolize_keys`` into JSON gem's ``:symbolize_names``
+      #
+      # Returns a new hash without mutating the input. ``options`` is the
+      # cached hash returned from {Adapter.merged_load_options}, so in-place
+      # edits would pollute the cache and corrupt subsequent calls.
+      #
+      # @api private
+      # @param options [Hash] merged load options
+      # @return [Hash] options with ``:symbolize_keys`` translated
+      def translate_load_options(options)
+        return options unless options[:symbolize_keys]
+
+        options.except(:symbolize_keys).merge(symbolize_names: true)
+      end
+    end
+  end
+end