multi_json 1.15.0 → 1.21.2

data/lib/multi_json/deprecated.rb

@@ -0,0 +1,113 @@
+# 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
+    # ``load`` / ``dump`` / ``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 :load, :parse
+    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 :load, :parse
+  deprecate_alias :dump, :generate
+  deprecate_alias :decode, :parse
+  deprecate_alias :encode, :generate
+  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.parse_options and MultiJSON.generate_options instead"
+  ) { |value| self.parse_options = self.generate_options = value }
+
+  deprecate_method(
+    :default_options,
+    "MultiJSON.default_options is deprecated\n" \
+    "Use MultiJSON.parse_options or MultiJSON.generate_options instead"
+  ) { parse_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/legacy_constant.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# Backward-compatible alias for the legacy ``MultiJson`` constant name
+#
+# Downstream code that still writes ``MultiJson.parse(...)`` or
+# ``rescue MultiJson::ParseError`` continues to work, but emits a
+# one-time deprecation warning pointing at ``MultiJSON``. Each public
+# method on {MultiJSON} gets an explicit forwarder defined on this
+# module, and constant access resolves via {.const_missing}, so both
+# dotted calls and ``::`` constant lookups (including rescue clauses)
+# route through the canonical module.
+#
+# This file is loaded last by the ``multi_json`` entry point so the
+# forwarder snapshot below sees the complete {MultiJSON} public API,
+# including the deprecated aliases defined in ``deprecated.rb``.
+#
+# @api public
+# @deprecated Use {MultiJSON} (all-caps) instead. Will be removed in v2.0.
+module MultiJson
+  # Forward every public method MultiJSON exposes through an explicit
+  # singleton method on the legacy MultiJson module, so callers that
+  # capture the method as a Method object (``MultiJson.method(:load)``)
+  # find this forwarder instead of falling back to inherited methods like
+  # ``Kernel#load``. The earlier ``method_missing``-based shim left
+  # ``MultiJson.method(:load)`` resolving to ``Kernel#load`` (because
+  # ``Module#method`` doesn't consult ``method_missing``) and broke
+  # libraries (Sawyer, Octokit, Danger) that capture decoders as Method
+  # objects. Forwarding eagerly fixes the capture path while preserving
+  # the one-time deprecation warning each call emits.
+  (::MultiJSON.public_methods - ::Module.public_methods).each do |forwarded|
+    define_singleton_method(forwarded) do |*args, **kwargs, &block|
+      ::MultiJSON.warn_deprecation_once(:multi_json_constant,
+        "The MultiJson constant is deprecated and will be removed in v2.0. Use MultiJSON instead.")
+      ::MultiJSON.public_send(forwarded, *args, **kwargs, &block)
+    end
+  end
+
+  class << self
+    # Resolve missing constants to their {MultiJSON} counterparts
+    #
+    # Enables ``rescue MultiJson::ParseError`` and
+    # ``MultiJson::Adapters::Oj`` to keep working during the
+    # deprecation cycle.
+    #
+    # @api public
+    # @param name [Symbol] constant name
+    # @return [Object] the resolved constant from {MultiJSON}
+    # @example
+    #   MultiJson::ParseError  # returns MultiJSON::ParseError
+    def const_missing(name)
+      ::MultiJSON.warn_deprecation_once(:multi_json_constant,
+        "The MultiJson constant is deprecated and will be removed in v2.0. Use MultiJSON instead.")
+      ::MultiJSON.const_get(name)
+    end
+  end
+end

data/lib/multi_json/options.rb

@@ -1,39 +1,186 @@
-module MultiJson
+# frozen_string_literal: true
+
+module MultiJSON
+  # Mixin providing configurable parse/generate options
+  #
+  # Supports static hashes or dynamic callables (procs/lambdas).
+  # Extended by both MultiJSON (global options) and Adapter classes.
+  #
+  # @api private
   module Options
-    def load_options=(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 parse operations
+    #
+    # @api public
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
+    # @example
+    #   MultiJSON.parse_options = {symbolize_keys: true}
+    def parse_options=(options)
       OptionsCache.reset
-      @load_options = options
+      @parse_options = options
     end
 
-    def dump_options=(options)
+    # Set options for generate operations
+    #
+    # @api public
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
+    # @example
+    #   MultiJSON.generate_options = {pretty: true}
+    def generate_options=(options)
       OptionsCache.reset
-      @dump_options = options
+      @generate_options = options
+    end
+
+    # Get options for parse operations
+    #
+    # When `@parse_options` is a callable (proc/lambda), it's invoked
+    # with `args` as positional arguments — typically the merged
+    # options hash from `Adapter.merged_parse_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.parse_options  #=> {}
+    def parse_options(*args)
+      resolve_options(@parse_options, *args) || default_parse_options
     end
 
+    # Get options for generate operations
+    #
+    # @api public
+    # @param args [Array<Object>] forwarded to the callable, ignored otherwise
+    # @return [Hash] resolved options hash
+    # @example
+    #   MultiJSON.generate_options  #=> {}
+    def generate_options(*args)
+      resolve_options(@generate_options, *args) || default_generate_options
+    end
+
+    # Get default parse options
+    #
+    # @api private
+    # @return [Hash] frozen empty hash
+    def default_parse_options
+      Concurrency.synchronize(:default_options) { @default_parse_options ||= EMPTY_OPTIONS }
+    end
+
+    # Get default generate options
+    #
+    # @api private
+    # @return [Hash] frozen empty hash
+    def default_generate_options
+      Concurrency.synchronize(:default_options) { @default_generate_options ||= EMPTY_OPTIONS }
+    end
+
+    # Set options for parse operations
+    #
+    # @api public
+    # @deprecated Use {#parse_options=} instead. Will be removed in v2.0.
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
+    # @example
+    #   MultiJSON.load_options = {symbolize_keys: true}
+    def load_options=(options)
+      MultiJSON.warn_deprecation_once(:load_options=,
+        "MultiJSON.load_options= is deprecated and will be removed in v2.0. Use MultiJSON.parse_options= instead.")
+      self.parse_options = options
+    end
+
+    # Set options for generate operations
+    #
+    # @api public
+    # @deprecated Use {#generate_options=} instead. Will be removed in v2.0.
+    # @param options [Hash, Proc] options hash or callable
+    # @return [Hash, Proc] the options
+    # @example
+    #   MultiJSON.dump_options = {pretty: true}
+    def dump_options=(options)
+      MultiJSON.warn_deprecation_once(:dump_options=,
+        "MultiJSON.dump_options= is deprecated and will be removed in v2.0. Use MultiJSON.generate_options= instead.")
+      self.generate_options = options
+    end
+
+    # Get options for parse operations
+    #
+    # @api public
+    # @deprecated Use {#parse_options} instead. Will be removed in v2.0.
+    # @param args [Array<Object>] forwarded to the callable, ignored otherwise
+    # @return [Hash] resolved options hash
+    # @example
+    #   MultiJSON.load_options  #=> {}
     def load_options(*args)
-      defined?(@load_options) && get_options(@load_options, *args) || default_load_options
+      MultiJSON.warn_deprecation_once(:load_options,
+        "MultiJSON.load_options is deprecated and will be removed in v2.0. Use MultiJSON.parse_options instead.")
+      parse_options(*args)
     end
 
+    # Get options for generate operations
+    #
+    # @api public
+    # @deprecated Use {#generate_options} instead. Will be removed in v2.0.
+    # @param args [Array<Object>] forwarded to the callable, ignored otherwise
+    # @return [Hash] resolved options hash
+    # @example
+    #   MultiJSON.dump_options  #=> {}
     def dump_options(*args)
-      defined?(@dump_options) && get_options(@dump_options, *args) || default_dump_options
+      MultiJSON.warn_deprecation_once(:dump_options,
+        "MultiJSON.dump_options is deprecated and will be removed in v2.0. Use MultiJSON.generate_options instead.")
+      generate_options(*args)
     end
 
+    # Get default parse options
+    #
+    # @api private
+    # @deprecated Use {#default_parse_options} instead. Will be removed in v2.0.
+    # @return [Hash] frozen empty hash
     def default_load_options
-      @default_load_options ||= {}
+      default_parse_options
     end
 
+    # Get default generate options
+    #
+    # @api private
+    # @deprecated Use {#default_generate_options} instead. Will be removed in v2.0.
+    # @return [Hash] frozen empty hash
     def default_dump_options
-      @default_dump_options ||= {}
+      default_generate_options
     end
 
-  private
+    private
 
-    def get_options(options, *args)
-      if options.respond_to?(:call) && options.arity
-        options.arity == 0 ? options[] : options[*args]
-      elsif options.respond_to?(:to_hash)
-        options.to_hash
+    # 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/mutex_store.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module MultiJSON
+  module OptionsCache
+    # Thread-safe cache store backed by a Hash guarded by a Mutex
+    #
+    # Used on MRI and TruffleRuby, where a runtime dependency on
+    # concurrent-ruby would be overkill: the GVL on MRI makes single
+    # lookups atomic, and locking on both reads and writes keeps the
+    # small perf cost predictable across engines without adding a
+    # runtime dependency.
+    #
+    # @api private
+    class Store
+      # Create a new cache store
+      #
+      # @api private
+      # @return [Store] new store instance
+      def initialize
+        @cache = {}
+        @mutex = Mutex.new
+      end
+
+      # Clear all cached entries
+      #
+      # Held under the mutex because TruffleRuby (which also uses this
+      # backend via the ruby-platform gem) has true parallelism: a
+      # concurrent ``fetch`` racing with ``Hash#clear`` could corrupt
+      # iteration in a way that MRI's GVL would otherwise prevent.
+      #
+      # @api private
+      # @return [void]
+      def reset
+        @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. Nil cached values are
+      # preserved because ``Hash#fetch`` only falls through to the default
+      # block when the key is truly missing. The ``block_given?`` check
+      # is hoisted out of the mutex so the no-block read path runs the
+      # check once per call instead of once inside the critical section.
+      #
+      # @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)
+        return @mutex.synchronize { @cache.fetch(key) { default } } unless block_given?
+
+        @mutex.synchronize do
+          @cache.fetch(key) do
+            @cache.shift if @cache.size >= OptionsCache.max_cache_size
+            @cache[key] = yield
+          end
+        end
+      end
+    end
+  end
+end

data/lib/multi_json/options_cache.rb

@@ -1,29 +1,82 @@
-module MultiJson
+# 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
-    extend self
+    # 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
 
-    def reset
-      @dump_cache = {}
-      @load_cache = {}
-    end
+    # 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
 
-    def fetch(type, key, &block)
-      cache = instance_variable_get("@#{type}_cache")
-      cache.key?(key) ? cache[key] : write(cache, key, &block)
-    end
+    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
 
-    private
+      # 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_reader :max_cache_size
 
-    # Normally MultiJson is used with a few option sets for both dump/load
-    # methods. When options are generated dynamically though, every call would
-    # cause a cache miss and the cache would grow indefinitely. To prevent
-    # this, we just reset the cache every time the number of keys outgrows
-    # 1000.
-    MAX_CACHE_SIZE = 1000
+      # Set the maximum number of entries per cache store
+      #
+      # @api public
+      # @param value [Integer] positive entry cap
+      # @return [Integer] the validated value
+      # @raise [ArgumentError] when value is not a positive Integer
+      # @example
+      #   MultiJSON::OptionsCache.max_cache_size = 5000
+      def max_cache_size=(value)
+        raise ArgumentError, "max_cache_size must be a positive Integer, got #{value.inspect}" unless Integer === value && value.positive? # rubocop:disable Style/CaseEquality
 
-    def write(cache, key)
-      cache.clear if cache.length >= MAX_CACHE_SIZE
-      cache[key] = yield
+        @max_cache_size = value
+      end
+
+      # 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
+
+require_relative "options_cache/#{MultiJSON::OptionsCache.send(:const_get, :BACKENDS).fetch(RUBY_ENGINE, "mutex_store")}"
+MultiJSON::OptionsCache.reset

data/lib/multi_json/parse_error.rb

@@ -1,17 +1,108 @@
-module MultiJson
+# frozen_string_literal: true
+
+module MultiJSON
+  # Raised when JSON parsing fails
+  #
+  # Wraps the underlying adapter's parse error with the original input
+  # data, plus best-effort line and column extraction from the adapter's
+  # error message. Line/column are populated for adapters that include
+  # them in their messages (Oj, the json gem) and remain nil for
+  # adapters that don't (Yajl, fast_jsonparser).
+  #
+  # @api public
   class ParseError < StandardError
-    attr_reader :data, :cause
+    # Regex that matches the "line N[, ]column M" fragment inside an
+    # adapter error message. The separator between line and column is
+    # permissive — Oj emits ``"line 1, column 3"`` while the json gem
+    # emits ``"line 1 column 2"`` — so ``[,\s]+`` covers both. Column
+    # is optional so messages like ``"at line 5"`` still yield a line.
+    LOCATION_PATTERN = /line\s+(\d+)(?:[,\s]+column\s+(\d+))?/i
+    private_constant :LOCATION_PATTERN
+
+    # The input string that failed to parse
+    #
+    # @api public
+    # @return [String, nil] the original input data
+    # @example
+    #   error.data  #=> "{invalid json}"
+    attr_reader :data
+
+    # The 1-based line number reported by the adapter
+    #
+    # @api public
+    # @return [Integer, nil] line number, or nil if the adapter's message
+    #   did not include one
+    # @example
+    #   error.line  #=> 1
+    attr_reader :line
+
+    # The 1-based column reported by the adapter
+    #
+    # @api public
+    # @return [Integer, nil] column number, or nil if the adapter's message
+    #   did not include one
+    # @example
+    #   error.column  #=> 3
+    attr_reader :column
+
+    # Create a new ParseError
+    #
+    # @api public
+    # @param message [String, nil] error message
+    # @param data [String, nil] the input that failed to parse
+    # @param cause [Exception, nil] the original exception
+    # @return [ParseError] new error instance
+    # @example
+    #   ParseError.new("unexpected token at line 1 column 2", data: "{}")
+    def initialize(message = nil, data: nil, cause: nil)
+      super(message)
+      @data = data
+      match = location_match(message)
+      @line = match && Integer(match[1])
+      @column = match && match[2] && Integer(match[2])
+      set_backtrace(cause.backtrace) if cause
+    end
 
+    # Build a ParseError from an original exception
+    #
+    # @api public
+    # @param original_exception [Exception] the adapter's parse error
+    # @param data [String] the input that failed to parse
+    # @return [ParseError] new error with formatted message
+    # @example
+    #   ParseError.build(JSON::ParserError.new("..."), "{bad json}")
     def self.build(original_exception, data)
-      new(original_exception.message).tap do |exception|
-        exception.instance_eval do
-          @cause = original_exception
-          set_backtrace original_exception.backtrace
-          @data = data
-        end
-      end
+      new(original_exception.message, data: data, cause: original_exception)
+    end
+
+    private
+
+    # Match an adapter error message against the line/column pattern
+    #
+    # Adapter error messages sometimes embed bytes from the failing
+    # input (e.g., the json gem's ``"invalid byte sequence in UTF-8"``
+    # error). The pattern is pure ASCII so it's compatible with any
+    # encoding, but a UTF-8 string with invalid bytes still trips the
+    # regex engine — ``String#scrub`` replaces those bytes so the
+    # match can proceed. Strings in binary (ASCII-8BIT) or any valid
+    # encoding pass through scrub untouched.
+    #
+    # The parameter is deliberately not named ``message``: that would
+    # shadow ``Exception#message``, which holds the same string once
+    # ``super`` has run, and mutation testing could not tell the two
+    # apart.
+    #
+    # @api private
+    # @param text [String, nil] the adapter's error message
+    # @return [MatchData, nil] the regex match, or nil if no message or
+    #   no location fragment was found
+    def location_match(text)
+      return unless text
+
+      LOCATION_PATTERN.match(text.scrub)
     end
   end
 
-  DecodeError = LoadError = ParseError # Legacy support
+  # Legacy aliases for backward compatibility
+  DecodeError = LoadError = ParseError
 end