terrain 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d37822d50c6e00a4b0cfb6720ef147eef776554c
-  data.tar.gz: fa979a9c65f39f0f36101126c8c4ffab1ee583ea
+  metadata.gz: 35b20c85da62fa29911c7f66fd6c3152dd138d21
+  data.tar.gz: 16e76c904d30e761b3667f0ae0c135fad8b7529c
 SHA512:
-  metadata.gz: b783ca61aaf45f49ffe57c99a110dccdaba51bdf562edaf678c1eb3069d84ebd4ad12cac36a71d400afa071d7c26f4e491153bcc2beccb11e0ca8ea2ee616b45
-  data.tar.gz: 559f5adc616c79de489abe36483534c5b9c437d3939f6f45145e4543e4ff8bcc9408ffc7d3c0751a37187988aa917ec0a9d9bdd45bf778b7653c8a798d0f207f
+  metadata.gz: 42432a6d37702385300c453a526620951a797acfaeaece1f17b81546fb9b041921fb1ae5f452bd37892d5bccb2d6ec71a0037a811c250896f9e28558705f9fe2
+  data.tar.gz: 89b74868b62563bec9d303e926632559ee79a4d65d5759020d650b6cb9d35ca70e085f05d4d186017f94d457d9dad9956797bede36615216277ba59b3f7f8251

data/.gitignore

@@ -1 +1,2 @@
 Gemfile.lock
+*.gem

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 2.1.0
+  - 2.2.3
+  - 2.3.0

data/Gemfile

@@ -6,5 +6,6 @@ gem 'airborne'
 gem 'factory_girl'
 gem 'faker'
 gem 'rails'
+gem 'rake'
 gem 'rspec-rails'
 gem 'sqlite3'

data/README.md

@@ -1,11 +1,8 @@
 # Terrain
 
-Opinionated toolkit for building CRUD APIs with Rails
+[![Build Status](https://travis-ci.org/scttnlsn/terrain.png?branch=master)](https://travis-ci.org/scttnlsn/terrain)
 
-* error handling
-* basic CRUD
-* serialization via
-* authorization via [Pundit](https://github.com/elabs/pundit)
+Opinionated toolkit for building CRUD APIs with Rails
 
 ## Install
 
@@ -17,6 +14,18 @@ gem 'terrain'
 
 ## Usage
 
+* [Error handling](#error-handling)
+* [Resources](#resources)
+  * [Authorization](#authorization)
+  * [Serialization](#serialization)
+  * [Querying](#querying)
+    * [Filtering](#filtering)
+    * [Ordering](#ordering)
+    * [Pagination](#pagination)
+    * [Relationships](#relationships)
+  * [CRUD operations](#crud-operations)
+* [Config](#config)
+
 ### Error handling
 
 ```ruby
@@ -39,7 +48,8 @@ JSON responses are of the form:
 {
   "error": {
     "key": "type_of_error",
-    "message": "Localized error message"
+    "message": "Localized error message",
+    "details": "Optional details"
   }
 }
 ```
@@ -55,7 +65,7 @@ class ExampleController < ApplicationController
   private
 
   def my_error
-    error_response(:type_of_error, 500)
+    error_response(:type_of_error, 500, { some: :details })
   end
 end
 ```
@@ -84,11 +94,75 @@ via [ActiveModelSerializers](https://github.com/rails-api/active_model_serialize
 
 #### Querying
 
-* `include` - This corresponds to the `ActiveModelSerializers` include option and embeds the given relationships in the response.  Relationships are also preloaded according to the given string.  If omitted then no relationships will be included or embedded in the response.
+Records of a given resource are queried by requesting the `index` action.
+
+##### Filtering
+
+Queries are scoped to the results returned from the `resource_scope` method.  By default this returns all records, however, you can override it to further filter the results (i.e. based on query params, nested route params, etc.):
+
+```ruby
+class ExampleController < ApplicationController
+  include Terrain::Resource
+
+  resource Example, permit: [:foo, :bar, :baz]
+
+  private
+
+  def resource_scope
+    scope = super
+    scope = scope.where(foo: params[:foo]) if params[:foo].present?
+    scope
+  end
+end
+```
+
+##### Ordering
+
+You can pass an `order` param to reorder the response records.  Specify a comma-separated list of fields and prefix the field with a `-` for descending order:
+
+```ruby
+# corresponds to Example.order('foo', 'bar desc')
+get :index, order: 'foo,-bar'
+```
+
+##### Pagination
+
+To request a range of records, specify the range in an HTTP header:
+
+```ruby
+# Request the first 10 records
+get :index, {}, { 'Range' => '0-9' }
+```
+
+All responses include a `Content-Range` header that specifies the exact range returned as well as a total count of records.  i.e.
+
+```
+Content-Range: 0-9/100
+```
+
+You can also pass open ended ranges such as `10-` (i.e. skip the first 10 records).
+
+##### Relationships
+
+No model relationships are serialized in the response by default.  To specify the set of relationships to be embedded in the response, pass a comma-separated list of relationships in the `include` param.
+
+As an example, suppose we're querying for posts which each have many tags and belong to an author.  We could embed those relationships with the following `include` param:
+
+```ruby
+get :index, include: 'author,tags'
+```
+
+Suppose now that the author also has a profile relationship.  We could include the author, author profile and tags by passing:
+
+```ruby
+get :index, include: 'author.profile,tags'
+```
+
+Included relationships are automatically preloaded via the ActiveRecord `includes` method.  The `include` param is also supported in `show` actions.
 
 #### CRUD operations
 
-You may need an action to perform additional steps beyond simple persistence.  There are hooks for each CRUD operation (shown below with their default implementation):
+You may need an action to perform additional steps beyond simple persistence.  There are methods for performing CRUD operations that can be overridden (shown below with their default implementation):
 
 ```ruby
 class ExampleController < ApplicationController
@@ -112,3 +186,12 @@ class ExampleController < ApplicationController
   end
 end
 ```
+
+### Config
+
+```ruby
+Terrain.configure do |config|
+  # Maximum number of records returned
+  config.max_records = Float::INFINITY
+end
+```

data/Rakefile

@@ -0,0 +1,5 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/terrain/config.rb

@@ -0,0 +1,9 @@
+module Terrain
+  class Config
+    attr_accessor :max_records
+
+    def max_records
+      @max_records || Float::INFINITY
+    end
+  end
+end

data/lib/terrain/errors.rb

@@ -1,3 +1,5 @@
+require 'terrain/page'
+
 module Terrain
   module Errors
     extend ActiveSupport::Concern
@@ -9,8 +11,25 @@ module Terrain
       rescue_from 'ActionController::RoutingError', with: :route_not_found
       rescue_from 'ActiveRecord::RecordInvalid', with: :record_invalid
 
+      rescue_from Terrain::Page::RangeError, with: :range_error
+
       private
 
+      def error_response(key = :server_error, status = 500, details = nil)
+        result = {
+          error: {
+            key: key,
+            message: I18n.t("terrain.errors.#{key}", request: request)
+          }
+        }
+
+        if details.present?
+          result[:error][:details] = details
+        end
+
+        render json: result, status: status
+      end
+
       def association_not_found
         error_response(:association_not_found, 400)
       end
@@ -31,19 +50,12 @@ module Terrain
         error_response(:route_not_found, 404)
       end
 
-      def record_invalid
-        error_response(:record_invalid, 422)
+      def record_invalid(error)
+        error_response(:record_invalid, 422, error.record.errors.to_hash)
       end
 
-      def error_response(key = :server_error, status = 500)
-        result = {
-          error: {
-            key: key,
-            message: I18n.t("terrain.errors.#{key}", request: request)
-          }
-        }
-
-        render json: result, status: status
+      def range_error
+        error_response(:range_error, 416)
       end
     end
   end

data/lib/terrain/page.rb

@@ -0,0 +1,63 @@
+module Terrain
+  class Page
+    class RangeError < StandardError; end
+
+    RANGE_REGEX = /^(?<from>[0-9]*)-(?<to>[0-9]*)$/
+
+    attr_reader :scope, :range
+
+    def initialize(scope, range = nil)
+      @scope = scope
+      @range = range
+    end
+
+    def bounds
+      @bounds ||= begin
+        if range.present?
+          if match
+            raise RangeError if from > to
+            [from, to]
+          else
+            raise RangeError
+          end
+        else
+          [0, count - 1]
+        end
+      end
+    end
+
+    def count
+      @count ||= scope.count
+    end
+
+    def records
+      from, to = bounds
+      limit = [to - from + 1, Terrain.config.max_records].min
+      @records ||= scope.offset(from).limit(limit)
+    end
+
+    def content_range
+      if count > 0
+        from, to = bounds
+        to = [to, from + records.count - 1].min
+        "#{from}-#{to}/#{count}"
+      else
+        '*/0'
+      end
+    end
+
+    private
+
+    def match
+      range.match(RANGE_REGEX)
+    end
+
+    def from
+      match && match[:from].present? ? match[:from].to_i : 0
+    end
+
+    def to
+      match && match[:to].present? ? match[:to].to_i : (count - 1)
+    end
+  end
+end

data/lib/terrain/resource.rb

@@ -1,6 +1,8 @@
 require 'active_model_serializers'
 require 'pundit'
 
+require 'terrain/page'
+
 module Terrain
   module Resource
     extend ActiveSupport::Concern
@@ -19,7 +21,13 @@ module Terrain
 
     module Actions
       def index
-        render json: preloaded_resource.all
+        scope = order(resource_scope)
+
+        range = request.headers['Range']
+        page = Terrain::Page.new(scope, range)
+
+        headers['Content-Range'] = page.content_range
+        render json: page.records, include: (params[:include] || [])
       end
 
       def create
@@ -88,6 +96,29 @@ module Terrain
         end
       end
 
+      def order(scope)
+        if params[:order].present?
+          order = params[:order].gsub(/ /, '').split(',').map do |field|
+            direction = 'asc'
+
+            if field[0] == '-'
+              direction = 'desc'
+              field = field[1..-1]
+            end
+
+            "#{field} #{direction}"
+          end
+
+          scope = scope.order(order)
+        end
+
+        scope
+      end
+
+      def resource_scope
+        preloaded_resource.all
+      end
+
       def load_record
         preloaded_resource.find(params[:id])
       end

data/lib/terrain.rb

@@ -1,4 +1,17 @@
 require 'active_support'
 
+require 'terrain/config'
 require 'terrain/errors'
 require 'terrain/resource'
+
+module Terrain
+  extend self
+
+  def config
+    @config ||= Config.new
+  end
+
+  def configure
+    yield config
+  end
+end

data/spec/spec_helper.rb

@@ -43,7 +43,7 @@ module Helpers
   def serialize(value, options = {})
     options[:include] ||= []
     if value.respond_to?(:each)
-      ActiveModel::Serializer::CollectionSerializer.new(value, options).as_json
+      value.map { |item| serialize(item, options) }
     else
       ActiveModelSerializers::SerializableResource.new(value, options).as_json.symbolize_keys
     end

data/spec/terrain/errors_spec.rb

@@ -59,16 +59,36 @@ describe 'Terrain::Errors', type: :controller do
     it { expect_json('error.key', 'route_not_found') }
   end
 
-  context 'route not found' do
+  context 'range error' do
+    controller do
+      def index
+        raise Terrain::Page::RangeError
+      end
+    end
+
+    it { expect(response.status).to eq 416 }
+    it { expect_json_types(error: :object) }
+    it { expect_json_types('error.message', :string) }
+    it { expect_json('error.key', 'range_error') }
+  end
+
+  context 'record invalid' do
+    let(:record) { Example.new }
+
     controller do
       def index
-        raise ActiveRecord::RecordInvalid, Example.new
+        record = Example.new
+        record.valid?
+        raise ActiveRecord::RecordInvalid, record
       end
     end
 
+    before { record.valid? }
+
     it { expect(response.status).to eq 422 }
     it { expect_json_types(error: :object) }
     it { expect_json_types('error.message', :string) }
     it { expect_json('error.key', 'record_invalid') }
+    it { expect_json('error.details', record.errors.to_hash) }
   end
 end

data/spec/terrain/page_spec.rb

@@ -0,0 +1,101 @@
+require 'spec_helper'
+
+describe Terrain::Page do
+  let!(:records) { create_list(:example, 10) }
+  let(:scope) { Example.all }
+  let(:empty_scope) { Example.where('1 = 0') }
+  let(:range) { '0-4' }
+  let(:page) { described_class.new(scope, range) }
+
+  describe '#bounds' do
+    subject { page.bounds }
+
+    it { is_expected.to eq [0, 4] }
+
+    context 'with empty range' do
+      let(:range) { '5-5' }
+
+      it { is_expected.to eq [5, 5] }
+    end
+
+    context 'with no upper bound' do
+      let(:range) { '5-' }
+
+      it { is_expected.to eq [5, 9] }
+    end
+
+    context 'with no lower bound' do
+      let(:range) { '-5' }
+
+      it { is_expected.to eq [0, 5] }
+    end
+
+    context 'with invalid range' do
+      let(:range) { '3-2' }
+
+      it { expect { subject }.to raise_error described_class::RangeError }
+    end
+
+    context 'with invalid upper bound' do
+      let(:range) { '5-x' }
+
+      it { expect { subject }.to raise_error described_class::RangeError }
+    end
+  end
+
+  describe '#count' do
+    subject { page.count }
+
+    it { is_expected.to eq 10 }
+
+    context 'with no records' do
+      let(:scope) { empty_scope }
+
+      it { is_expected.to eq 0 }
+    end
+  end
+
+  describe '#records' do
+    subject { page.records }
+
+    it { is_expected.to eq records[0..4] }
+
+    context 'with fewer records than requested range' do
+      let(:range) { '5-14' }
+
+      it { is_expected.to eq records[5..9] }
+    end
+
+    context 'with max records configured' do
+      before { Terrain.config.max_records = 3 }
+      after { Terrain.config.max_records = nil }
+
+      it { is_expected.to eq records[0..2] }
+    end
+  end
+
+  describe '#content_range' do
+    subject { page.content_range }
+
+    it { is_expected.to eq '0-4/10' }
+
+    context 'with fewer records than requested range' do
+      let(:range) { '5-14' }
+
+      it { is_expected.to eq '5-9/10' }
+    end
+
+    context 'with max records configured' do
+      before { Terrain.config.max_records = 3 }
+      after { Terrain.config.max_records = nil }
+
+      it { is_expected.to eq '0-2/10' }
+    end
+
+    context 'with no records' do
+      let(:scope) { empty_scope }
+
+      it { is_expected.to eq '*/0' }
+    end
+  end
+end

data/spec/terrain/resource_spec.rb

@@ -8,7 +8,7 @@ describe 'Terrain::Resource', type: :controller do
   end
 
   describe '#index' do
-    let!(:examples) { create_list(:example, 10) }
+    let!(:records) { create_list(:example, 10) }
 
     it 'responds with 200 status' do
       get :index
@@ -17,7 +17,105 @@ describe 'Terrain::Resource', type: :controller do
 
     it 'responds with serialized records' do
       get :index
-      expect(response.body).to eq serialize(Example.all).to_json
+      expect(response.body).to eq serialize(records).to_json
+    end
+
+    it 'responds with Content-Range header' do
+      get :index
+      expect(response.headers['Content-Range']).to eq Terrain::Page.new(Example.all).content_range
+    end
+
+    context 'filtered' do
+      let(:record) { records.first }
+
+      before do
+        record.foo = 'test'
+        record.save!
+      end
+
+      controller do
+        resource Example
+
+        def resource_scope
+          super.where(foo: params[:foo])
+        end
+      end
+
+      it 'responds with filtered records' do
+        get :index, foo: 'test'
+        expect(response.body).to eq serialize([record]).to_json
+      end
+    end
+
+    context 'ordered' do
+      let(:params) { ActionController::Parameters.new(order: 'foo') }
+
+      it 'responds with ordered records' do
+        get :index, params
+        expect(response.body).to eq serialize(Example.order('foo asc')).to_json
+      end
+
+      context 'descending' do
+        let(:params) { ActionController::Parameters.new(order: '-foo') }
+
+        it 'responds with ordered records' do
+          get :index, params
+          expect(response.body).to eq serialize(Example.order('foo desc')).to_json
+        end
+      end
+
+      context 'multiple sort columns' do
+        let(:params) { ActionController::Parameters.new(order: ' - foo , bar  ') }
+
+        it 'responds with ordered records' do
+          get :index, params
+          expect(response.body).to eq serialize(Example.order('foo desc', 'bar asc')).to_json
+        end
+      end
+    end
+
+    context 'paged' do
+      before { request.headers['Range'] = '0-4' }
+
+      it 'responds with requested records' do
+        get :index
+        expect(response.body).to eq serialize(records[0..4]).to_json
+      end
+
+      it 'responds with Content-Range header' do
+        get :index
+        expect(response.headers['Content-Range']).to eq Terrain::Page.new(Example.all, '0-4').content_range
+      end
+    end
+
+    context 'with relations' do
+      before do
+        records.each do |record|
+          create_list(:widget, 3, example: record)
+        end
+      end
+
+      it 'does not include relations in serialized record' do
+        get :index
+        expect(response.body).to eq serialize(records, include: []).to_json
+      end
+
+      context 'with valid include' do
+        let(:params) { ActionController::Parameters.new(include: 'widgets') }
+
+        it 'includes relations in serialized record' do
+          get :index, params
+          expect(response.body).to eq serialize(records, include: ['widgets']).to_json
+        end
+      end
+
+      context 'with invalid include' do
+        let(:params) { ActionController::Parameters.new(include: 'widgets,wrong') }
+
+        it 'raises error' do
+          expect { get :index, params }.to raise_error ActiveRecord::AssociationNotFoundError
+        end
+      end
     end
   end
 

data/terrain.gemspec

@@ -3,7 +3,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |gem|
   gem.name          = 'terrain'
-  gem.version       = '0.0.1'
+  gem.version       = '0.0.2'
   gem.summary       = 'Terrain'
   gem.description   = ''
   gem.license       = 'MIT'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: terrain
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Scott Nelson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-05-04 00:00:00.000000000 Z
+date: 2016-05-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -60,10 +60,14 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".travis.yml"
 - Gemfile
 - README.md
+- Rakefile
 - lib/terrain.rb
+- lib/terrain/config.rb
 - lib/terrain/errors.rb
+- lib/terrain/page.rb
 - lib/terrain/resource.rb
 - spec/spec_helper.rb
 - spec/support/example.rb
@@ -73,6 +77,7 @@ files:
 - spec/support/widget.rb
 - spec/support/widget_factory.rb
 - spec/terrain/errors_spec.rb
+- spec/terrain/page_spec.rb
 - spec/terrain/resource_spec.rb
 - terrain.gemspec
 homepage: https://github.com/scttnlsn/terrain
@@ -108,4 +113,5 @@ test_files:
 - spec/support/widget.rb
 - spec/support/widget_factory.rb
 - spec/terrain/errors_spec.rb
+- spec/terrain/page_spec.rb
 - spec/terrain/resource_spec.rb