active_model_serializers 0.8.3 → 0.10.0

data/bin/bench_regression

@@ -0,0 +1,316 @@
+#!/usr/bin/env ruby
+require 'fileutils'
+require 'pathname'
+require 'shellwords'
+require 'English'
+
+############################
+# USAGE
+#
+# bundle exec bin/bench_regression <ref1> <ref2>
+#   <ref1> defaults to the current branch
+#   <ref2> defaults to the master branch
+# bundle exec bin/bench_regression current                    # will run on the current branch
+# bundle exec bin/bench_regression revisions 792fb8a90 master # every revision inclusive
+# bundle exec bin/bench_regression           792fb8a90 master --repeat-count 2 --env CACHE_ON=off
+# bundle exec bin/bench_regression vendor
+###########################
+
+class BenchRegression
+  ROOT = Pathname File.expand_path(File.join(*['..', '..']), __FILE__)
+  TMP_DIR_NAME = File.join('tmp', 'bench')
+  TMP_DIR = File.join(ROOT, TMP_DIR_NAME)
+  E_TMP_DIR = Shellwords.shellescape(TMP_DIR)
+  load ROOT.join('bin', 'bench')
+
+  attr_reader :source_stasher
+
+  def initialize
+    @source_stasher = SourceStasher.new
+  end
+
+  class SourceStasher
+    attr_reader :gem_require_paths, :gem_paths
+    attr_writer :vendor
+
+    def initialize
+      @gem_require_paths = []
+      @gem_paths = []
+      refresh_temp_dir
+      @vendor = false
+    end
+
+    def temp_dir_empty?
+      File.directory?(TMP_DIR) &&
+        Dir[File.join(TMP_DIR, '*')].none?
+    end
+
+    def empty_temp_dir
+      return if @vendor
+      return if temp_dir_empty?
+      FileUtils.mkdir_p(TMP_DIR)
+      Dir[File.join(TMP_DIR, '*')].each do |file|
+        if File.directory?(file)
+          FileUtils.rm_rf(file)
+        else
+          FileUtils.rm(file)
+        end
+      end
+    end
+
+    def fill_temp_dir
+      vendor_files(Dir[File.join(ROOT, 'test', 'benchmark', '*.{rb,ru}')])
+      # vendor_file(File.join('bin', 'bench'))
+      housekeeping { empty_temp_dir }
+      vendor_gem('benchmark-ips')
+    end
+
+    def vendor_files(files)
+      files.each do |file|
+        vendor_file(file)
+      end
+    end
+
+    def vendor_file(file)
+      FileUtils.cp(file, File.join(TMP_DIR, File.basename(file)))
+    end
+
+    def vendor_gem(gem_name)
+      directory_name = `bundle exec gem unpack benchmark-ips --target=#{E_TMP_DIR}`[/benchmark-ips.+\d/]
+      gem_paths << File.join(TMP_DIR, directory_name)
+      gem_require_paths << File.join(TMP_DIR_NAME, directory_name, 'lib')
+      housekeeping { remove_vendored_gems }
+    end
+
+    def remove_vendored_gems
+      return if @vendor
+      FileUtils.rm_rf(*gem_paths)
+    end
+
+    def refresh_temp_dir
+      empty_temp_dir
+      fill_temp_dir
+    end
+
+    def housekeeping
+      at_exit { yield }
+    end
+  end
+
+  module RevisionMethods
+    module_function
+    def current_branch
+      @current_branch ||= `cat .git/HEAD | cut -d/ -f3,4,5`.chomp
+    end
+
+    def current_revision
+      `git rev-parse --short HEAD`.chomp
+    end
+
+    def revision_description(rev)
+      `git log --oneline -1 #{rev}`.chomp
+    end
+
+    def revisions(start_ref, end_ref)
+      cmd = "git rev-list --reverse #{start_ref}..#{end_ref}"
+      `#{cmd}`.chomp.split("\n")
+    end
+
+    def checkout_ref(ref)
+      `git checkout #{ref}`.chomp
+      if $CHILD_STATUS
+        STDERR.puts "Checkout failed: #{ref}, #{$CHILD_STATUS.exitstatus}" unless $CHILD_STATUS.success?
+        $CHILD_STATUS.success?
+      else
+        true
+      end
+    end
+
+    def clean_head
+      system('git reset --hard --quiet')
+    end
+  end
+  module ShellMethods
+
+    def sh(cmd)
+      puts cmd
+      # system(cmd)
+      run(cmd)
+      # env = {}
+      # # out = STDOUT
+      # pid = spawn(env, cmd)
+      # Process.wait(pid)
+      # pid = fork do
+      #   exec cmd
+      # end
+      # Process.waitpid2(pid)
+      # puts $CHILD_STATUS.exitstatus
+    end
+
+    require 'pty'
+    # should consider trapping SIGINT in here
+    def run(cmd)
+      puts cmd
+      child_process = ''
+      result = ''
+      # http://stackoverflow.com/a/1162850
+      # stream output of subprocess
+      begin
+        PTY.spawn(cmd) do |stdin, _stdout, pid|
+          begin
+            # Do stuff with the output here. Just printing to show it works
+            stdin.each do |line|
+              print line
+              result << line
+            end
+            child_process = PTY.check(pid)
+          rescue Errno::EIO
+            puts 'Errno:EIO error, but this probably just means ' \
+                  'that the process has finished giving output'
+          end
+        end
+      rescue PTY::ChildExited
+        puts 'The child process exited!'
+      end
+      unless (child_process && child_process.success?)
+        exitstatus = child_process.exitstatus
+        puts "FAILED: #{child_process.pid} exited with status #{exitstatus.inspect} due to failed command #{cmd}"
+        exit exitstatus || 1
+      end
+      result
+    end
+
+    def bundle(ref)
+      system("rm -f Gemfile.lock")
+      # This is absolutely critical for bundling to work
+      Bundler.with_clean_env do
+        system("bundle check ||
+          bundle install --local ||
+          bundle install ||
+          bundle update")
+      end
+
+      # if $CHILD_STATUS
+      #   STDERR.puts "Bundle failed at: #{ref}, #{$CHILD_STATUS.exitstatus}" unless $CHILD_STATUS.success?
+      #   $CHILD_STATUS.success?
+      # else
+      #   false
+      # end
+    end
+  end
+  include ShellMethods
+  include RevisionMethods
+
+  def benchmark_refs(ref1: nil, ref2: nil, cmd:)
+    checking_out = false
+    ref0 = current_branch
+    ref1 ||= current_branch
+    ref2 ||= 'master'
+    p [ref0, ref1, ref2, current_revision]
+
+    run_benchmark_at_ref(cmd, ref1)
+    p [ref0, ref1, ref2, current_revision]
+    run_benchmark_at_ref(cmd, ref2)
+    p [ref0, ref1, ref2, current_revision]
+
+    checking_out = true
+    checkout_ref(ref0)
+  rescue Exception # rubocop:disable Lint/RescueException
+    STDERR.puts "[ERROR] #{$!.message}"
+    checkout_ref(ref0) unless checking_out
+    raise
+  end
+
+  def benchmark_revisions(ref1: nil, ref2: nil, cmd:)
+    checking_out = false
+    ref0 = current_branch
+    ref1 ||= current_branch
+    ref2 ||= 'master'
+
+    revisions(ref1, ref2).each do |rev|
+      STDERR.puts "Checking out: #{revision_description(rev)}"
+
+      run_benchmark_at_ref(cmd, rev)
+      clean_head
+    end
+    checking_out = true
+    checkout_ref(ref0)
+  rescue Exception # rubocop:disable Lint/RescueException
+    STDERR.puts "[ERROR]: #{$!.message}"
+    checkout_ref(ref0) unless checking_out
+    raise
+  end
+
+  def run_benchmark_at_ref(cmd, ref)
+    checkout_ref(ref)
+    run_benchmark(cmd, ref)
+  end
+
+  def run_benchmark(cmd, ref = nil)
+    ref ||= current_revision
+    bundle(ref) &&
+      benchmark_tests(cmd, ref)
+  end
+
+  def benchmark_tests(cmd, ref)
+    base = E_TMP_DIR
+    # cmd.sub('bin/bench', 'tmp/revision_runner/bench')
+    # bundle = Gem.bin('bunle'
+    # Bundler.with_clean_env(&block)
+
+    # cmd = Shellwords.shelljoin(cmd)
+    # cmd = "COMMIT_HASH=#{ref} BASE=#{base} bundle exec ruby  -rbenchmark/ips #{cmd}"
+    # Add vendoring benchmark/ips to load path
+
+    # CURRENT THINKING: IMPORTANT
+    # Pass into require statement as RUBYOPTS i.e. via env rather than command line argument
+    # otherwise, have a 'fast ams benchmarking' module that extends benchmarkings to add the 'ams'
+    # method but doesn't depend on benchmark-ips
+    options = {
+      commit_hash: ref,
+      base: base,
+      rubyopt: Shellwords.shellescape("-Ilib:#{source_stasher.gem_require_paths.join(':')}")
+    }
+    BenchmarkDriver.parse_argv_and_run(ARGV.dup, options)
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  benchmarking = BenchRegression.new
+
+  case ARGV[0]
+  when 'current'
+    # Run current branch only
+
+    # super simple command line parsing
+    args = ARGV.dup
+    _    = args.shift # remove 'current' from args
+    cmd  = args
+    benchmarking.run_benchmark(cmd)
+  when 'revisions'
+    # Runs on every revision
+
+    # super simple command line parsing
+    args = ARGV.dup
+    _         = args.shift
+    ref1      = args.shift # remove 'revisions' from args
+    ref2      = args.shift
+    cmd       = args
+    benchmarking.benchmark_revisions(ref1: ref1, ref2: ref2, cmd: cmd)
+  when 'vendor'
+    # Just prevents vendored files from being cleaned up
+    # at exit. (They are vendored at initialize.)
+    benchmarking.source_stasher.vendor = true
+  else
+    # Default: Compare current_branch to master
+    # Optionally: pass in two refs as args to `bin/bench_regression`
+    # TODO: Consider checking across more revisions, to automatically find problems.
+
+    # super simple command line parsing
+    args = ARGV.dup
+    ref1      = args.shift
+    ref2      = args.shift
+    cmd       = args
+    benchmarking.benchmark_refs(ref1: ref1, ref2: ref2, cmd: cmd)
+  end
+end

data/bin/serve_benchmark

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+set -e
+
+case "$1" in
+
+  start)
+  config="${CONFIG_RU:-test/benchmark/config.ru}"
+  bundle exec ruby -Ilib -S rackup "$config" --daemonize --pid tmp/benchmark_app.pid --warn --server webrick
+  until [ -f 'tmp/benchmark_app.pid' ]; do
+    sleep 0.1 # give it time to start.. I don't know a better way
+  done
+  cat tmp/benchmark_app.pid
+  true
+  ;;
+
+  stop)
+  if [ -f 'tmp/benchmark_app.pid' ]; then
+    kill -TERM $(cat tmp/benchmark_app.pid)
+  else
+    echo 'No pidfile'
+    false
+  fi
+  ;;
+
+  status)
+  if [ -f 'tmp/benchmark_app.pid' ]; then
+    kill -0 $(cat tmp/benchmark_app.pid)
+    [ "$?" -eq 0 ]
+  else
+    echo 'No pidfile'
+    false
+  fi
+  ;;
+
+  *)
+  echo "Usage: $0 [start|stop|status]"
+  ;;
+
+esac

data/docs/ARCHITECTURE.md

@@ -0,0 +1,126 @@
+[Back to Guides](README.md)
+
+This document focuses on architecture the 0.10.x version of ActiveModelSerializers. If you are interested in the architecture of the 0.8 or 0.9 versions,
+please refer to the [0.8 README](https://github.com/rails-api/active_model_serializers/blob/0-8-stable/README.md) or
+[0.9 README](https://github.com/rails-api/active_model_serializers/blob/0-9-stable/README.md).
+
+The original design is also available [here](https://github.com/rails-api/active_model_serializers/blob/d72b66d4c5355b0ff0a75a04895fcc4ea5b0c65e/README.textile).
+
+# ARCHITECTURE
+
+An **`ActiveModel::Serializer`** wraps a [serializable resource](https://github.com/rails/rails/blob/4-2-stable/activemodel/lib/active_model/serialization.rb)
+and exposes an `attributes` method, among a few others.
+It allows you to specify which attributes and associations should be represented in the serializatation of the resource.
+It requires an adapter to transform its attributes into a JSON document; it cannot be serialized itself.
+It may be useful to think of it as a
+[presenter](http://blog.steveklabnik.com/posts/2011-09-09-better-ruby-presenters).
+
+The **`ActiveModel::ArraySerializer`** represent a collection of resources as serializers
+and, if there is no serializer, primitives.
+
+The **`ActiveModel::Adapter`** describes the structure of the JSON document generated from a
+serializer. For example, the `Attributes` example represents each serializer as its
+unmodified attributes.  The `JsonApi` adapter represents the serializer as a [JSON
+API](http://jsonapi.org/) document.
+
+The **`ActiveModelSerializers::SerializableResource`** acts to coordinate the serializer(s) and adapter
+to an object that responds to `to_json`, and `as_json`.  It is used in the controller to
+encapsulate the serialization resource when rendered. However, it can also be used on its own
+to serialize a resource outside of a controller, as well.
+
+## Primitive handling
+
+Definitions: A primitive is usually a String or Array. There is no serializer
+defined for them; they will be serialized when the resource is converted to JSON (`as_json` or
+`to_json`).  (The below also applies for any object with no serializer.)
+
+ActiveModelSerializers doesn't handle primitives passed to `render json:` at all.
+
+However, when a primitive value is an attribute or in a collection,
+it is not modified.
+
+Internally, if no serializer can be found in the controller, the resource is not decorated by
+ActiveModelSerializers.
+
+If the collection serializer (ArraySerializer) cannot
+identify a serializer for a resource in its collection, it raises [`NoSerializerError`](https://github.com/rails-api/active_model_serializers/issues/1191#issuecomment-142327128)
+which is rescued in `ActiveModel::Serializer::Reflection#build_association` which sets
+the association value directly:
+
+```ruby
+reflection_options[:virtual_value] = association_value.try(:as_json) || association_value
+```
+
+(which is called by the adapter as `serializer.associations(*)`.)
+
+## How options are parsed
+
+High-level overview:
+
+- For a collection
+  - `:serializer` specifies the collection serializer and
+  - `:each_serializer` specifies the serializer for each resource in the collection.
+- For a single resource, the `:serializer` option is the resource serializer.
+- Options are partitioned in serializer options and adapter options.  Keys for adapter options are specified by
+    [`ADAPTER_OPTION_KEYS`](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/serializable_resource.rb#L5).
+    The remaining options are serializer options.
+
+Details:
+
+1. **ActionController::Serialization**
+  1. `serializable_resource = ActiveModelSerializers::SerializableResource.new(resource, options)`
+    1. `options` are partitioned into `adapter_opts` and everything else (`serializer_opts`).
+      The `adapter_opts`  keys are defined in `ActiveModelSerializers::SerializableResource::ADAPTER_OPTION_KEYS`.
+1. **ActiveModelSerializers::SerializableResource**
+  1. `if serializable_resource.serializer?` (there is a serializer for the resource, and an adapter is used.)
+    - Where `serializer?` is `use_adapter? && !!(serializer)`
+      - Where `use_adapter?`: 'True when no explicit adapter given, or explicit value is truthy (non-nil);
+        False when explicit adapter is falsy (nil or false)'
+      - Where `serializer`:
+        1. from explicit `:serializer` option, else
+        2. implicitly from resource `ActiveModel::Serializer.serializer_for(resource)`
+  1. A side-effect of checking `serializer` is:
+     - The `:serializer` option is removed from the serializer_opts hash
+     - If the `:each_serializer` option is present, it is removed from the serializer_opts hash and set as the `:serializer` option
+  1. The serializer and adapter are created as
+    1. `serializer_instance = serializer.new(resource, serializer_opts)`
+    2. `adapter_instance = ActiveModel::Serializer::Adapter.create(serializer_instance, adapter_opts)`
+1. **ActiveModel::Serializer::ArraySerializer#new**
+  1. If the `serializer_instance` was a `ArraySerializer` and the `:serializer` serializer_opts
+    is present, then [that serializer is passed into each resource](https://github.com/rails-api/active_model_serializers/blob/a54d237e2828fe6bab1ea5dfe6360d4ecc8214cd/lib/active_model/serializer/array_serializer.rb#L14-L16).
+1. **ActiveModel::Serializer#attributes** is used by the adapter to get the attributes for
+  resource as defined by the serializer.
+
+## What does a 'serializable resource' look like?
+
+- An `ActiveRecord::Base` object.
+- Any Ruby object that passes the
+  [Lint](http://www.rubydoc.info/github/rails-api/active_model_serializers/ActiveModel/Serializer/Lint/Tests)
+  [code](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model/serializer/lint.rb).
+
+ActiveModelSerializers provides a
+[`ActiveModelSerializers::Model`](https://github.com/rails-api/active_model_serializers/blob/master/lib/active_model_serializers/model.rb),
+which is a simple serializable PORO (Plain-Old Ruby Object).
+
+ActiveModelSerializers::Model may be used either as a template, or in production code.
+
+```ruby
+class MyModel < ActiveModelSerializers::Model
+  attr_accessor :id, :name, :level
+end
+```
+
+The default serializer for `MyModel` would be `MyModelSerializer` whether MyModel is an
+ActiveRecord::Base object or not.
+
+Outside of the controller the rules are **exactly** the same as for records. For example:
+
+```ruby
+render json: MyModel.new(level: 'awesome'), adapter: :json
+```
+
+would be serialized the same as
+
+```ruby
+ActiveModelSerializers::SerializableResource.new(MyModel.new(level: 'awesome'), adapter: :json).as_json
+```

data/docs/README.md

@@ -0,0 +1,40 @@
+# Docs - ActiveModel::Serializer 0.10.x
+
+This is the documentation of ActiveModelSerializers, it's focused on the **0.10.x version.**
+
+-----
+
+## General
+
+- [Getting Started](general/getting_started.md)
+- [Configuration Options](general/configuration_options.md)
+- [Serializers](general/serializers.md)
+- [Adapters](general/adapters.md)
+- [Rendering](general/rendering.md)
+- [Caching](general/caching.md)
+- [Logging](general/logging.md)
+- [Deserialization](general/deserialization.md)
+- [Instrumentation](general/instrumentation.md)
+- JSON API
+  - [Schema](jsonapi/schema.md)
+  - [Errors](jsonapi/errors.md)
+- [ARCHITECTURE](ARCHITECTURE.md)
+
+## How to
+
+- [How to add root key](howto/add_root_key.md)
+- [How to add pagination links](howto/add_pagination_links.md)
+- [Using ActiveModelSerializers Outside Of Controllers](howto/outside_controller_use.md)
+- [Testing ActiveModelSerializers](howto/test.md)
+- [Passing Arbitrary Options](howto/passing_arbitrary_options.md)
+- [How to serialize a Plain-Old Ruby Object (PORO)](howto/serialize_poro.md)
+
+## Integrations
+
+| Integration | Supported ActiveModelSerializers versions |  Gem name and/or link
+|----|-----|----
+| Ember.js | 0.9.x | [active-model-adapter](https://github.com/ember-data/active-model-adapter)
+| Ember.js | 0.10.x + |  [docs/integrations/ember-and-json-api.md](integrations/ember-and-json-api.md)
+| Grape | 0.10.x + | [docs/integrations/grape.md](integrations/grape.md)  |
+| Grape | 0.9.x | https://github.com/jrhe/grape-active_model_serializers/ |
+| Sinatra | 0.9.x | https://github.com/SauloSilva/sinatra-active-model-serializers/

data/docs/STYLE.md

@@ -0,0 +1,58 @@
+# STYLE
+
+## Code and comments
+
+- We are actively working to identify tasks under the label [**Good for New
+  Contributors**](https://github.com/rails-api/active_model_serializers/labels/Good%20for%20New%20Contributors).
+  - [Changelog
+      Missing](https://github.com/rails-api/active_model_serializers/issues?q=label%3A%22Changelog+Missing%22+is%3Aclosed) is
+    an easy way to help out.
+
+- [Fix a bug](https://github.com/rails-api/active_model_serializers/labels/Ready%20for%20PR).
+  - Ready for PR - A well defined bug, needs someone to PR a fix.
+  - Bug - Anything that is broken.
+  - Regression - A bug that did not exist in previous versions and isn't a new feature (applied in tandem with Bug).
+  - Performance - A performance related issue. We could track this as a bug, but usually these would have slightly lower priority than standard bugs.
+
+- [Develop new features](https://github.com/rails-api/active_model_serializers/labels/Feature).
+
+- [Improve code quality](https://codeclimate.com/github/rails-api/active_model_serializers/code?sort=smell_count&sort_direction=desc).
+
+- [Improve amount of code exercised by tests](https://codeclimate.com/github/rails-api/active_model_serializers/coverage?sort=covered_percent&sort_direction=asc).
+
+- [Fix RuboCop (Style) TODOS](https://github.com/rails-api/active_model_serializers/blob/master/.rubocop_todo.yml).
+  - Delete and offsense, run `rake rubocop` (or possibly `rake rubocop:auto_correct`),
+    and [submit a PR](CONTRIBUTING.md#submitting-a-pull-request-pr).
+
+- We are also encouraging comments to substantial changes (larger than bugfixes and simple features) under an
+  "RFC" (Request for Comments) process before we start active development.
+   Look for the [**RFC**](https://github.com/rails-api/active_model_serializers/labels/RFC) label.
+
+
+## Pull requests
+
+- If the tests pass and the pull request looks good, a maintainer will merge it.
+- If the pull request needs to be changed,
+  - you can change it by updating the branch you generated the pull request from
+    - either by adding more commits, or
+    - by force pushing to it
+  - A maintainer can make any changes themselves and manually merge the code in.
+
+## Commit messages
+
+- [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
+- [http://stopwritingramblingcommitmessages.com/](http://stopwritingramblingcommitmessages.com/)
+- [ThoughtBot style guide](https://github.com/thoughtbot/guides/tree/master/style#git)
+
+#### About Pull Requests (PR's)
+
+- [Using Pull Requests](https://help.github.com/articles/using-pull-requests)
+- [Github pull requests made easy](http://www.element84.com/github-pull-requests-made-easy.html)
+- [Exercism Git Workflow](http://help.exercism.io/git-workflow.html).
+- [Level up your Git](http://rakeroutes.com/blog/deliberate-git/)
+- [All Your Open Source Code Are Belong To Us](http://www.benjaminfleischer.com/2013/07/30/all-your-open-source-code-are-belong-to-us/)
+
+## Issue Labeling
+
+ActiveModelSerializers uses a subset of [StandardIssueLabels](https://github.com/wagenet/StandardIssueLabels) for Github Issues. You can [see our labels here](https://github.com/rails-api/active_model_serializers/labels).
+