multi_json 1.20.0-java

data/lib/multi_json/adapters/oj.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+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
+      include OjCommon
+
+      defaults :load, mode: :strict, symbolize_keys: 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].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)
+          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 = {})
+        ::Oj.load(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 = {})
+        ::Oj.dump(object, prepare_dump_options(options))
+      end
+
+      private
+
+      # Translate ``:symbolize_keys`` 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_keys`` translated
+      def translate_load_options(options)
+        options.except(:symbolize_keys).merge(symbol_keys: options[:symbolize_keys] == true)
+      end
+    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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+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(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
+    end
+  end
+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

data/lib/multi_json/deprecated.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# Deprecated public API kept around for one major release
+#
+# Each method here emits a one-time deprecation warning on first call and
+# delegates to its current-API counterpart. The whole file is loaded by
+# {MultiJson} so the deprecation surface stays out of the main module
+# definition.
+#
+# @api private
+module MultiJson
+  class << self
+    private
+
+    # Define a deprecated alias that delegates to a new method name
+    #
+    # The generated singleton method emits a one-time deprecation
+    # warning naming the replacement, then forwards all positional and
+    # keyword arguments plus any block to ``replacement``. Used for the
+    # ``decode`` / ``encode`` / ``engine*`` / ``with_engine`` /
+    # ``default_engine`` aliases that are scheduled for removal in v2.0.
+    #
+    # @api private
+    # @param name [Symbol] deprecated method name
+    # @param replacement [Symbol] current-API method to delegate to
+    # @return [Symbol] the defined method name
+    # @example
+    #   deprecate_alias :decode, :load
+    def deprecate_alias(name, replacement)
+      message = "MultiJson.#{name} is deprecated and will be removed in v2.0. Use MultiJson.#{replacement} instead."
+      define_singleton_method(name) do |*args, **kwargs, &block|
+        warn_deprecation_once(name, message)
+        public_send(replacement, *args, **kwargs, &block)
+      end
+    end
+
+    # Define a deprecated method whose body needs custom delegation
+    #
+    # Used for the ``default_options`` / ``default_options=`` pair
+    # whose body fans out to multiple replacement methods, and for the
+    # ``cached_options`` / ``reset_cached_options!`` no-op stubs that
+    # have no current-API counterpart at all. The block runs in its
+    # own lexical ``self``, which is the ``MultiJson`` module since
+    # every call site sits inside ``module MultiJson`` below.
+    #
+    # @api private
+    # @param name [Symbol] deprecated method name
+    # @param message [String] warning to emit on first call
+    # @yield body to evaluate after the warning
+    # @return [Symbol] the defined method name
+    # @example
+    #   deprecate_method(:cached_options, "...") { nil }
+    def deprecate_method(name, message, &body)
+      define_singleton_method(name) do |*args, **kwargs|
+        warn_deprecation_once(name, message)
+        body.call(*args, **kwargs)
+      end
+    end
+  end
+
+  deprecate_alias :decode, :load
+  deprecate_alias :encode, :dump
+  deprecate_alias :engine, :adapter
+  deprecate_alias :engine=, :adapter=
+  deprecate_alias :default_engine, :default_adapter
+  deprecate_alias :with_engine, :with_adapter
+
+  deprecate_method(
+    :default_options=,
+    "MultiJson.default_options setter is deprecated\n" \
+    "Use MultiJson.load_options and MultiJson.dump_options instead"
+  ) { |value| self.load_options = self.dump_options = value }
+
+  deprecate_method(
+    :default_options,
+    "MultiJson.default_options is deprecated\n" \
+    "Use MultiJson.load_options or MultiJson.dump_options instead"
+  ) { load_options }
+
+  %i[cached_options reset_cached_options!].each do |name|
+    deprecate_method(name, "MultiJson.#{name} method is deprecated and no longer used.") { nil }
+  end
+
+  private
+
+  # Instance-method delegate for the deprecated default_options setter
+  #
+  # @api private
+  # @deprecated Use {MultiJson.load_options=} and {MultiJson.dump_options=} instead
+  # @param value [Hash] options hash
+  # @return [Hash] the options hash
+  # @example
+  #   class Foo; include MultiJson; end
+  #   Foo.new.send(:default_options=, symbolize_keys: true)
+  def default_options=(value)
+    MultiJson.default_options = value
+  end
+
+  # Instance-method delegate for the deprecated default_options getter
+  #
+  # @api private
+  # @deprecated Use {MultiJson.load_options} or {MultiJson.dump_options} instead
+  # @return [Hash] the current load options
+  # @example
+  #   class Foo; include MultiJson; end
+  #   Foo.new.send(:default_options)
+  def default_options
+    MultiJson.default_options
+  end
+end

data/lib/multi_json/options.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module MultiJson
+  # Mixin providing configurable load/dump options
+  #
+  # Supports static hashes or dynamic callables (procs/lambdas).
+  # Extended by both MultiJson (global options) and Adapter classes.
+  #
+  # @api private
+  module Options
+    # Steep needs an inline `#:` annotation here because `{}.freeze`
+    # would be inferred as `Hash[untyped, untyped]` and trip
+    # `UnannotatedEmptyCollection`. The annotation requires
+    # `Hash.new.freeze` (not the `{}.freeze` rubocop would prefer)
+    # because the `#:` cast only applies to method-call results.
+    EMPTY_OPTIONS = Hash.new.freeze #: options # rubocop:disable Style/EmptyLiteral
+
+    # Set options for load operations
+    #
+    # @api public
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
+    # @example
+    #   MultiJson.load_options = {symbolize_keys: true}
+    def load_options=(options)
+      OptionsCache.reset
+      @load_options = options
+    end
+
+    # Set options for dump operations
+    #
+    # @api public
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
+    # @example
+    #   MultiJson.dump_options = {pretty: true}
+    def dump_options=(options)
+      OptionsCache.reset
+      @dump_options = options
+    end
+
+    # Get options for load operations
+    #
+    # When `@load_options` is a callable (proc/lambda), it's invoked
+    # with `args` as positional arguments — typically the merged
+    # options hash from `Adapter.merged_load_options`. When it's a
+    # plain hash, `args` is ignored.
+    #
+    # @api public
+    # @param args [Array<Object>] forwarded to the callable, ignored otherwise
+    # @return [Hash] resolved options hash
+    # @example
+    #   MultiJson.load_options  #=> {}
+    def load_options(*args)
+      resolve_options(@load_options, *args) || default_load_options
+    end
+
+    # Get options for dump operations
+    #
+    # @api public
+    # @param args [Array<Object>] forwarded to the callable, ignored otherwise
+    # @return [Hash] resolved options hash
+    # @example
+    #   MultiJson.dump_options  #=> {}
+    def dump_options(*args)
+      resolve_options(@dump_options, *args) || default_dump_options
+    end
+
+    # Get default load options
+    #
+    # @api private
+    # @return [Hash] frozen empty hash
+    def default_load_options
+      Concurrency.synchronize(:default_options) { @default_load_options ||= EMPTY_OPTIONS }
+    end
+
+    # Get default dump options
+    #
+    # @api private
+    # @return [Hash] frozen empty hash
+    def default_dump_options
+      Concurrency.synchronize(:default_options) { @default_dump_options ||= EMPTY_OPTIONS }
+    end
+
+    private
+
+    # Resolves options from a hash or callable
+    #
+    # @api private
+    # @param options [Hash, Proc, nil] options configuration
+    # @param args [Array<Object>] arguments forwarded to a callable provider
+    # @return [Hash, nil] resolved options hash
+    def resolve_options(options, *args)
+      if options.respond_to?(:call)
+        # @type var options: options_proc
+        return invoke_callable(options, *args)
+      end
+
+      options.to_hash if options.respond_to?(:to_hash)
+    end
+
+    # Invokes a callable options provider
+    #
+    # @api private
+    # @param callable [Proc] options provider
+    # @param args [Array<Object>] arguments forwarded when the callable is non-arity-zero
+    # @return [Hash] options returned by the callable
+    def invoke_callable(callable, *args)
+      callable.arity.zero? ? callable.call : callable.call(*args)
+    end
+  end
+end

data/lib/multi_json/options_cache/concurrent_store.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "concurrent/map"
+
+module MultiJson
+  module OptionsCache
+    # Thread-safe cache store backed by Concurrent::Map
+    #
+    # Used on JRuby (via the java-platform gem's concurrent-ruby runtime
+    # dependency). JRuby has true parallelism, so the plain Hash + Mutex
+    # backend on MRI/TruffleRuby is replaced here with Concurrent::Map,
+    # which provides lock-free reads and atomic compute_if_absent without
+    # needing to serialize the entire fetch path.
+    #
+    # @api private
+    class Store
+      # Create a new cache store
+      #
+      # @api private
+      # @return [Store] new store instance
+      def initialize
+        @cache = Concurrent::Map.new
+        @eviction_mutex = Mutex.new
+      end
+
+      # Clear all cached entries
+      #
+      # Held under {@eviction_mutex} so a concurrent JRuby thread inside
+      # the {fetch} miss path cannot interleave its evict-then-insert
+      # sequence with a clear and leave the cache in a partially
+      # populated state. Mirrors {MutexStore#reset}'s mutex usage.
+      #
+      # @api private
+      # @return [void]
+      def reset
+        @eviction_mutex.synchronize { @cache.clear }
+      end
+
+      # Fetch a value from cache or compute it
+      #
+      # When called with a block, returns the cached value or computes a
+      # new one. When called without a block, returns the cached value or
+      # the supplied default if the key is missing.
+      #
+      # The fast path (cache hit) is lock-free. The miss path takes a small
+      # mutex around the evict-then-insert sequence so concurrent inserts
+      # cannot both pass the size check and exceed ``max_cache_size``.
+      #
+      # @api private
+      # @param key [Object] cache key
+      # @param default [Object] value to return when key is missing and no
+      #   block is given
+      # @yield block to compute value if not cached
+      # @return [Object] cached, computed, or default value
+      def fetch(key, default = nil, &block)
+        return @cache[key] || default unless block
+
+        cached = @cache[key]
+        return cached if cached
+
+        @eviction_mutex.synchronize do
+          evict_one_if_full
+          @cache.compute_if_absent(key, &block)
+        end
+      end
+
+      private
+
+      # Drop a single arbitrary entry when the cache is at capacity
+      #
+      # Concurrent::Map has no built-in size cap. We approximate LRU by
+      # evicting whichever key Map#keys surfaces first; deterministic
+      # ordering is not required, only memory bounding. Iteration must
+      # happen outside ``compute_if_absent`` because that block holds the
+      # internal cache mutex.
+      #
+      # @api private
+      # @return [void]
+      def evict_one_if_full
+        return if @cache.size < OptionsCache.max_cache_size
+
+        @cache.delete(@cache.keys.first)
+      end
+    end
+  end
+end

data/lib/multi_json/options_cache.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module MultiJson
+  # Thread-safe bounded cache for merged options hashes
+  #
+  # Caches are separated for load and dump operations. Each cache is
+  # bounded to prevent unbounded memory growth when options are
+  # generated dynamically. The ``Store`` backend is chosen at load time
+  # based on ``RUBY_ENGINE``: JRuby uses Concurrent::Map (shipped as a
+  # runtime dependency of the java-platform gem); MRI and TruffleRuby
+  # use a Hash guarded by a Mutex.
+  #
+  # @api private
+  module OptionsCache
+    # Default bound on the number of cached entries per store. Applications
+    # that dynamically generate many distinct option hashes can raise this
+    # via {.max_cache_size=}.
+    DEFAULT_MAX_CACHE_SIZE = 1000
+
+    class << self
+      # Get the dump options cache
+      #
+      # @api private
+      # @return [Store] dump cache store
+      attr_reader :dump
+
+      # Get the load options cache
+      #
+      # @api private
+      # @return [Store] load cache store
+      attr_reader :load
+
+      # Maximum number of entries per cache store
+      #
+      # Applies to both the dump and load caches. Existing entries are
+      # left in place until normal eviction trims them below a lowered
+      # limit; call {.reset} if you need to evict immediately.
+      #
+      # @api public
+      # @return [Integer] current cache size limit
+      # @example
+      #   MultiJson::OptionsCache.max_cache_size = 5000
+      #   MultiJson::OptionsCache.max_cache_size  #=> 5000
+      attr_accessor :max_cache_size
+
+      # Reset both caches
+      #
+      # @api private
+      # @return [void]
+      def reset
+        @dump = Store.new
+        @load = Store.new
+      end
+    end
+
+    self.max_cache_size = DEFAULT_MAX_CACHE_SIZE
+  end
+end
+
+module MultiJson
+  module OptionsCache
+    # Dynamic require path so MRI (mutex_store) and JRuby
+    # (concurrent_store) execute the same physical line, avoiding a
+    # dead-branch ``require_relative`` that would otherwise drop
+    # JRuby's line coverage below 100%.
+    BACKENDS = {"jruby" => "concurrent_store"}.freeze
+    private_constant :BACKENDS
+  end
+end
+
+require_relative "options_cache/#{MultiJson::OptionsCache.send(:const_get, :BACKENDS).fetch(RUBY_ENGINE, "mutex_store")}"
+MultiJson::OptionsCache.reset