oj 3.10.7

data/pages/Rails.md

@@ -0,0 +1,155 @@
+# Oj Rails Compatibility
+
+The `:rails` mode mimics the ActiveSupport version 5 encoder. Rails and
+ActiveSupport are built around the use of the `as_json(*)` method defined for
+a class. Oj attempts to provide the same functionality by being a drop in
+replacement with a few exceptions.
+
+```ruby
+require 'oj'
+
+Oj::Rails.set_encoder()
+Oj::Rails.set_decoder()
+Oj::Rails.optimize()
+Oj::Rails.mimic_JSON()
+```
+
+or simply call
+
+```ruby
+Oj.optimize_rails()
+```
+
+Either of those steps will setup Oj to mimic Rails but it will not change the
+default mode type as the mode type is only used when calling the Oj encoding
+directly. If Rails mode is also desired then use the `Oj.default_options` to
+change the default mode.
+
+Some of the Oj options are supported as arguments to the encoder if called
+from `Oj::Rails.encode()` but when using the `Oj::Rails::Encoder` class the
+`encode()` method does not support optional arguments as required by the
+ActiveSupport compliance guidelines. The general approach Rails takes for
+configuring encoding options is to either set global values or to create a new
+instance of the Encoder class and provide options in the initializer.
+
+The globals that ActiveSupport uses for encoding are:
+
+ * `ActiveSupport::JSON::Encoding.use_standard_json_time_format`
+ * `ActiveSupport::JSON::Encoding.escape_html_entities_in_json`
+ * `ActiveSupport::JSON::Encoding.time_precision`
+ * `ActiveSupport::JSON::Encoding.json_encoder`
+
+Those globals are aliased to also be accessed from the ActiveSupport module
+directly so `ActiveSupport::JSON::Encoding.time_precision` can also be accessed
+from `ActiveSupport.time_precision`. Oj makes use of these globals in mimicing
+Rails after the `Oj::Rails.set_encode()` method is called. That also sets the
+`ActiveSupport.json_encoder` to the `Oj::Rails::Encoder` class.
+
+Options passed into a call to `to_json()` are passed to the `as_json()`
+methods. These are mostly ignored by Oj and simply passed on without
+modifications as per the guidelines. The exception to this are the options
+specific to Oj such as the `:circular` option which it used to detect circular
+references while encoding.
+
+By default Oj acts like the ActiveSupport encoder and honors any changes in
+the `as_json()` methods. There are some optimized Oj encoders for some
+classes. When the optimized encoder it toggled the `as_json()` methods will not
+be called for that class but instead the optimized version will be called. The
+optimized version is the same as the ActiveSupport default encoding for a
+given class. The optimized versions are toggled with the `optimize()` and
+`deoptimize()` methods. There is a default optimized version for every class
+that takes the visible attributes and encodes them but that may not be the
+same as what Rails uses. Trial and error is the best approach for classes not
+listed here.
+
+The classes that can be put in optimized mode and are optimized when
+`Oj::Rails.optimize` is called with no arguments are:
+
+ * Array
+ * BigDecimal
+ * Float
+ * Hash
+ * Range
+ * Regexp
+ * Time
+ * ActiveSupport::TimeWithZone
+ * ActionController::Parameters
+ * any class inheriting from ActiveRecord::Base
+ * any other class where all attributes should be dumped
+
+The ActiveSupport decoder is the `JSON.parse()` method. Calling the
+`Oj::Rails.set_decoder()` method replaces that method with the Oj equivalent.
+
+### Usage in Rails 3
+
+To support Rails 3 you can create a new module mixin to prepend to controllers:
+
+```ruby
+require 'oj'
+
+module OjJsonEncoder
+  def render(options = nil, extra_options = {}, &block)
+    if options && options.is_a?(Hash) && options[:json]
+      obj = options.delete(:json)
+      obj = Oj.dump(obj, :mode => :rails) unless obj.is_a?(String)
+      options[:text] = obj
+      response.content_type ||= Mime::JSON
+    end
+    super
+  end
+end
+```
+
+Usage:
+
+```ruby
+class MyController < ApplicationController
+  prepend OjJsonEncoder
+  def index
+    render :json => { :hello => 'world' }
+  end
+end
+```
+
+### Older Ruby Version Support (Pre 2.3.0)
+
+If you are using an older version of Ruby, you can pin `oj` to an earlier version in your Gemfile:
+
+```ruby
+gem 'oj', '3.7.12'
+```
+
+### Notes:
+
+1. Optimized Floats set the significant digits to 16. This is different than
+   Ruby which is used by the json gem and by Rails. Ruby varies the
+   significant digits which can be either 16 or 17 depending on the value.
+
+2. Optimized Hashs do not collapse keys that become the same in the output. As
+   an example, a non-String object that has a `to_s()` method will become the
+   return value of the `to_s()` method in the output without checking to see if
+   that has already been used. This could occur is a mix of String and Symbols
+   are used as keys or if a other non-String objects such as Numerics are mixed
+   with numbers as Strings.
+
+3. To verify Oj is being used turn on the Oj `:trace` option. Similar to the
+   Ruby Tracer Oj will then print out trace information. Another approach is
+   to turn on C extension tracing.  Set `tracer = TracePoint.new(:c_call) do
+   |tp| p [tp.lineno, tp.event, tp.defined_class, tp.method_id] end` or, in
+   older Rubies, set `Tracer.display_c_call = true`.
+
+   For example:
+
+     ```
+     require 'active_support/core_ext'
+     require 'active_support/json'
+     require 'oj'
+     Oj.optimize_rails
+     tracer.enable { Time.now.to_json }
+     # prints output including
+     ....
+     [20, :c_call, #<Class:Oj::Rails::Encoder>, :new]
+     [20, :c_call, Oj::Rails::Encoder, :encode]
+     ....
+     => "\"2018-02-23T12:13:42.493-06:00\""
+     ```

data/pages/Security.md

@@ -0,0 +1,20 @@
+# Security and Optimization
+
+Two settings in Oj are useful for parsing but do expose a vulnerability if used
+from an untrusted source. Symbolized keys can cause memory to be filled with
+previous versions of ruby. Ruby 2.1 and below does not garbage collect
+Symbols. The same is true for auto defining classes in all versions of ruby;
+memory will also be exhausted if too many classes are automatically
+defined. Auto defining is a useful feature during development and from trusted
+sources but it allows too many classes to be created in the object load mode and
+auto defined is used with an untrusted source. The `Oj.safe_load()` method
+sets and uses the most strict and safest options. It should be used by
+developers who find it difficult to understand the options available in Oj.
+
+The options in Oj are designed to provide flexibility to the developer. This
+flexibility allows Objects to be serialized and deserialized. No methods are
+ever called on these created Objects but that does not stop the developer from
+calling methods on them. As in any system, check your inputs before working with
+them. Taking an arbitrary `String` from a user and evaluating it is never a good
+idea from an unsecure source. The same is true for `Object` attributes as they
+are not more than `String`s. Always check inputs from untrusted sources.

data/pages/WAB.md

@@ -0,0 +1,13 @@
+# WAB mode
+
+The `:wab` mode ignores all options except the indent option. Performance of
+this mode is slightly faster than the :strict and :null modes. It is included
+to support the [WABuR](https://github.com/ohler55/wabur) project.
+
+Options other than the indentation are not supported since the encoding and
+formats are defined by the API that is used to encode data being passed from
+one components in a WAB system and allowing an option that would break the
+data exchange is best not supported.
+
+The mode encodes like the strict mode except the URI, Time, WAB::UUID, and
+BigDecimal are supported.

data/test/_test_active.rb

@@ -0,0 +1,76 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+$: << File.dirname(__FILE__)
+%w(lib ext test).each do |dir|
+  $LOAD_PATH.unshift File.expand_path("../../#{dir}", __FILE__)
+end
+
+require 'minitest'
+require 'minitest/autorun'
+
+require 'sqlite3'
+require 'active_record'
+require 'oj'
+
+#Oj.mimic_JSON()
+Oj.default_options = {mode: :compat, indent: 2}
+
+#ActiveRecord::Base.logger = Logger.new(STDERR)
+
+ActiveRecord::Base.establish_connection(
+  :adapter => "sqlite3",
+  :database => ":memory:"
+)
+
+ActiveRecord::Schema.define do
+  create_table :users do |table|
+    table.column :first_name, :string
+    table.column :last_name, :string
+    table.column :email, :string
+  end
+end
+
+class User < ActiveRecord::Base
+end
+
+class ActiveTest < Minitest::Test
+
+  def test_active
+    User.find_or_create_by(first_name: "John", last_name: "Smith", email: "john@example.com")
+    User.find_or_create_by(first_name: "Joan", last_name: "Smith", email: "joan@example.com")
+
+    # Single instance.
+    assert_equal(%|{
+  "id":1,
+  "first_name":"John",
+  "last_name":"Smith",
+  "email":"john@example.com"
+}
+|, Oj.dump(User.first))
+
+    # Array of instances.
+    assert_equal(%|[
+  {
+    "id":1,
+    "first_name":"John",
+    "last_name":"Smith",
+    "email":"john@example.com"
+  },
+  {
+    "id":2,
+    "first_name":"Joan",
+    "last_name":"Smith",
+    "email":"joan@example.com"
+  }
+]
+|, Oj.dump(User.all))
+
+    # Single instance as json. (not Oj)
+    assert_equal(%|{"id":1,"first_name":"John","last_name":"Smith","email":"john@example.com"}|, User.first.to_json)
+
+    # Array of instances as json. (not Oj)
+    assert_equal(%|[{"id":1,"first_name":"John","last_name":"Smith","email":"john@example.com"},{"id":2,"first_name":"Joan","last_name":"Smith","email":"joan@example.com"}]|, User.all.to_json)
+
+  end
+end

data/test/_test_active_mimic.rb

@@ -0,0 +1,96 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+$: << File.dirname(__FILE__)
+%w(lib ext test).each do |dir|
+  $LOAD_PATH.unshift File.expand_path("../../#{dir}", __FILE__)
+end
+
+require 'minitest'
+require 'minitest/autorun'
+
+require 'sqlite3'
+require 'active_record'
+require 'oj'
+
+Oj.mimic_JSON()
+Oj.default_options = {mode: :compat, indent: 2}
+
+#ActiveRecord::Base.logger = Logger.new(STDERR)
+
+ActiveRecord::Base.establish_connection(
+  :adapter => "sqlite3",
+  :database => ":memory:"
+)
+
+ActiveRecord::Schema.define do
+  create_table :users do |table|
+    table.column :first_name, :string
+    table.column :last_name, :string
+    table.column :email, :string
+  end
+end
+
+class User < ActiveRecord::Base
+end
+
+class ActiveTest < Minitest::Test
+
+  def test_active
+    User.find_or_create_by(first_name: "John", last_name: "Smith", email: "john@example.com")
+    User.find_or_create_by(first_name: "Joan", last_name: "Smith", email: "joan@example.com")
+
+    # Single instance.
+    assert_equal(%|{
+  "id":1,
+  "first_name":"John",
+  "last_name":"Smith",
+  "email":"john@example.com"
+}
+|, Oj.dump(User.first))
+
+    # Array of instances.
+    assert_equal(%|[
+  {
+    "id":1,
+    "first_name":"John",
+    "last_name":"Smith",
+    "email":"john@example.com"
+  },
+  {
+    "id":2,
+    "first_name":"Joan",
+    "last_name":"Smith",
+    "email":"joan@example.com"
+  }
+]
+|, Oj.dump(User.all))
+
+    # Single instance as json. (not Oj)
+    assert_equal(%|{
+  "id":1,
+  "first_name":"John",
+  "last_name":"Smith",
+  "email":"john@example.com"
+}
+|, User.first.to_json)
+
+    # Array of instances as json. (not Oj)
+    assert_equal(%|[
+  {
+    "id":1,
+    "first_name":"John",
+    "last_name":"Smith",
+    "email":"john@example.com"
+  },
+  {
+    "id":2,
+    "first_name":"Joan",
+    "last_name":"Smith",
+    "email":"joan@example.com"
+  }
+]
+|, User.all.to_json)
+
+  end
+end

data/test/_test_mimic_rails.rb

@@ -0,0 +1,126 @@
+#!/usr/bin/env ruby
+# encoding: UTF-8
+
+$: << File.dirname(__FILE__)
+
+require 'helper'
+#Oj.mimic_JSON
+require 'rails/all'
+
+require 'active_model'
+require 'active_model_serializers'
+require 'active_support/json'
+require 'active_support/time'
+require 'active_support/all'
+
+require 'oj/active_support_helper'
+
+Oj.mimic_JSON
+
+class Category
+  include ActiveModel::Model
+  include ActiveModel::SerializerSupport
+
+  attr_accessor :id, :name
+
+  def initialize(id, name)
+    @id   = id
+    @name = name
+  end
+end
+
+class CategorySerializer < ActiveModel::Serializer
+  attributes :id, :name
+end
+
+class MimicRails < Minitest::Test
+
+  def test_mimic_exception
+    begin
+      ActiveSupport::JSON.decode("{")
+      puts "Failed"
+    rescue ActiveSupport::JSON.parse_error
+      assert(true)
+    rescue Exception
+      assert(false, 'Expected a JSON::ParserError')
+    end
+  end
+
+  def test_dump_string
+    Oj.default_options= {:indent => 2}
+    json = ActiveSupport::JSON.encode([1, true, nil])
+    assert_equal(%{[
+  1,
+  true,
+  null
+]
+}, json)
+  end
+
+  def test_dump_rational
+    Oj.default_options= {:indent => 2}
+    json = ActiveSupport::JSON.encode([1, true, Rational(1)])
+    assert_equal(%{[
+  1,
+  true,
+  "1/1"
+]
+}, json)
+  end
+
+  def test_dump_range
+    Oj.default_options= {:indent => 2}
+    json = ActiveSupport::JSON.encode([1, true, '01'..'12'])
+    assert_equal(%{[
+  1,
+  true,
+  "01..12"
+]
+}, json)
+  end
+
+  def test_dump_object
+    Oj.default_options= {:indent => 2}
+    category = Category.new(1, 'test')
+    serializer = CategorySerializer.new(category)
+
+    json = serializer.to_json()
+    puts "*** serializer.to_json() #{serializer.to_json()}"
+    json = serializer.as_json()
+    puts "*** serializer.as_json() #{serializer.as_json()}"
+    json = JSON.dump(serializer)
+    puts "*** JSON.dump(serializer) #{JSON.dump(serializer)}"
+
+    puts "*** category.to_json() #{category.to_json()}"
+    puts "*** category.as_json() #{category.as_json()}"
+    puts "*** JSON.dump(serializer) #{JSON.dump(category)}"
+    puts "*** Oj.dump(serializer) #{Oj.dump(category)}"
+
+  end
+
+  def test_dump_object_array
+    Oj.default_options= {:indent => 2}
+    cat1 = Category.new(1, 'test')
+    cat2 = Category.new(2, 'test')
+    a = Array.wrap([cat1, cat2])
+
+    #serializer = CategorySerializer.new(a)
+
+    puts "*** a.to_json() #{a.to_json()}"
+    puts "*** a.as_json() #{a.as_json()}"
+    puts "*** JSON.dump(a) #{JSON.dump(a)}"
+    puts "*** Oj.dump(a) #{Oj.dump(a)}"
+  end
+
+  def test_dump_time
+    Oj.default_options= {:indent => 2}
+    now = ActiveSupport::TimeZone['America/Chicago'].parse("2014-11-01 13:20:47")
+    json = Oj.dump(now, mode: :object, time_format: :xmlschema)
+    #puts "*** json: #{json}"
+
+    oj_dump = Oj.load(json, mode: :object, time_format: :xmlschema)
+    #puts "Now: #{now}\n Oj: #{oj_dump}"
+    assert_equal("2014-11-01T13:20:47-05:00", oj_dump.xmlschema)
+  end
+
+end # MimicRails