terrain 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: d37822d50c6e00a4b0cfb6720ef147eef776554c
+  data.tar.gz: fa979a9c65f39f0f36101126c8c4ffab1ee583ea
+SHA512:
+  metadata.gz: b783ca61aaf45f49ffe57c99a110dccdaba51bdf562edaf678c1eb3069d84ebd4ad12cac36a71d400afa071d7c26f4e491153bcc2beccb11e0ca8ea2ee616b45
+  data.tar.gz: 559f5adc616c79de489abe36483534c5b9c437d3939f6f45145e4543e4ff8bcc9408ffc7d3c0751a37187988aa917ec0a9d9bdd45bf778b7653c8a798d0f207f

data/.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'airborne'
+gem 'factory_girl'
+gem 'faker'
+gem 'rails'
+gem 'rspec-rails'
+gem 'sqlite3'

data/README.md

@@ -0,0 +1,114 @@
+# Terrain
+
+Opinionated toolkit for building CRUD APIs with Rails
+
+* error handling
+* basic CRUD
+* serialization via
+* authorization via [Pundit](https://github.com/elabs/pundit)
+
+## Install
+
+Add Terrain to your Gemfile:
+
+```ruby
+gem 'terrain'
+```
+
+## Usage
+
+### Error handling
+
+```ruby
+class ExampleController < ApplicationController
+  include Terrain::Errors
+end
+```
+
+Rescues the following errors:
+
+* `ActiveRecord::AssociationNotFoundError` (400)
+* `Pundit::NotAuthorizedError` (403)
+* `ActiveRecord::RecordNotFound` (404)
+* `ActionController::RoutingError` (404)
+* `ActiveRecord::RecordInvalid` (422)
+
+JSON responses are of the form:
+
+```json
+{
+  "error": {
+    "key": "type_of_error",
+    "message": "Localized error message"
+  }
+}
+```
+
+To rescue a custom error with a similar response:
+
+```ruby
+class ExampleController < ApplicationController
+  include Terrain::Errors
+
+  rescue_from MyError, with: :my_error
+
+  private
+
+  def my_error
+    error_response(:type_of_error, 500)
+  end
+end
+```
+
+### Resources
+
+Suppose you have an `Example` model with `foo`, `bar`, and `baz` columns.
+
+```ruby
+class ExampleController < ApplicationController
+  include Terrain::Resource
+
+  resource Example, permit: [:foo, :bar, :baz]
+end
+```
+
+This sets up the typical resourceful Rails controller actions.  Note that **you'll still need to setup corresponding routes**.
+
+#### Authorization
+
+Authorization is handled by [Pundit](https://github.com/elabs/pundit).  If the policy class for a given resource exists, each controller action calls the policy before proceeding with the operation.  Authorization expects a `current_user` controller method to exist (otherwise `nil` is used as the `pundit_user`).
+
+#### Serialization
+
+via [ActiveModelSerializers](https://github.com/rails-api/active_model_serializers)
+
+#### 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.
+
+#### 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):
+
+```ruby
+class ExampleController < ApplicationController
+  include Terrain::Resource
+
+  resource Example, permit: [:foo, :bar, :baz]
+
+  private
+
+  def create_record
+    resource.create!(permitted_params)
+  end
+
+  def update_record(record)
+    record.update_attributes!(permitted_params)
+    record
+  end
+
+  def destroy_record(record)
+    record.delete
+  end
+end
+```

data/lib/terrain/errors.rb

@@ -0,0 +1,50 @@
+module Terrain
+  module Errors
+    extend ActiveSupport::Concern
+
+    included do
+      rescue_from 'ActiveRecord::AssociationNotFoundError', with: :association_not_found
+      rescue_from 'Pundit::NotAuthorizedError', with: :unauthorized
+      rescue_from 'ActiveRecord::RecordNotFound', with: :record_not_found
+      rescue_from 'ActionController::RoutingError', with: :route_not_found
+      rescue_from 'ActiveRecord::RecordInvalid', with: :record_invalid
+
+      private
+
+      def association_not_found
+        error_response(:association_not_found, 400)
+      end
+
+      def unauthenticated
+        error_response(:unauthenticated, 401)
+      end
+
+      def unauthorized
+        error_response(:unauthorized, 403)
+      end
+
+      def record_not_found
+        error_response(:record_not_found, 404)
+      end
+
+      def route_not_found
+        error_response(:route_not_found, 404)
+      end
+
+      def record_invalid
+        error_response(:record_invalid, 422)
+      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
+      end
+    end
+  end
+end

data/lib/terrain/resource.rb

@@ -0,0 +1,109 @@
+require 'active_model_serializers'
+require 'pundit'
+
+module Terrain
+  module Resource
+    extend ActiveSupport::Concern
+
+    class_methods do
+      attr_accessor :permit
+
+      def resource(resource, options = {})
+        include Pundit
+        include Actions
+
+        @resource = resource
+        self.permit = options[:permit] || []
+      end
+    end
+
+    module Actions
+      def index
+        render json: preloaded_resource.all
+      end
+
+      def create
+        record = resource.new(permitted_params)
+        authorize_record(record)
+
+        render json: create_record, include: [], status: 201
+      end
+
+      def show
+        record = load_record
+        authorize_record(record)
+
+        render json: record, include: params[:include] || []
+      end
+
+      def update
+        record = load_record
+        authorize_record(record)
+
+        render json: update_record(record), include: []
+      end
+
+      def destroy
+        record = load_record
+        authorize_record(record)
+        destroy_record(record)
+
+        render nothing: true, status: 204
+      end
+
+      private
+
+      def resource
+        self.class.instance_variable_get('@resource')
+      end
+
+      def includes_hash
+        if params[:include].present?
+          ActiveModel::Serializer::IncludeTree::Parsing.include_string_to_hash(params[:include])
+        else
+          {}
+        end
+      end
+
+      def preloaded_resource
+        resource.includes(includes_hash)
+      end
+
+      def permitted_params
+        params.permit(self.class.permit)
+      end
+
+      def pundit_user
+        if defined?(current_user)
+          current_user
+        else
+          nil
+        end
+      end
+
+      def authorize_record(record)
+        finder = Pundit::PolicyFinder.new(record)
+        if finder.policy
+          authorize(record)
+        end
+      end
+
+      def load_record
+        preloaded_resource.find(params[:id])
+      end
+
+      def create_record
+        resource.create!(permitted_params)
+      end
+
+      def update_record(record)
+        record.update_attributes!(permitted_params)
+        record
+      end
+
+      def destroy_record(record)
+        record.delete
+      end
+    end
+  end
+end

data/lib/terrain.rb

@@ -0,0 +1,4 @@
+require 'active_support'
+
+require 'terrain/errors'
+require 'terrain/resource'

data/spec/spec_helper.rb

@@ -0,0 +1,68 @@
+ENV['RAILS_ENV'] = 'test'
+
+require 'terrain'
+
+require 'rails'
+require 'action_controller/railtie'
+require 'active_model_serializers'
+require 'active_model_serializers/railtie'
+require 'active_record'
+require 'airborne'
+require 'factory_girl'
+require 'faker'
+require 'rspec/rails'
+
+LOGGER = Logger.new('/dev/null')
+
+Rails.logger = LOGGER
+ActiveModelSerializers.logger = LOGGER
+ActiveRecord::Base.logger = LOGGER
+
+DATABASE = {
+  adapter: 'sqlite3',
+  database: ':memory:'
+}
+
+ActiveRecord::Migration.verbose = false
+ActiveRecord::Base.establish_connection(DATABASE)
+
+module Terrain
+  class Application < ::Rails::Application
+    def self.find_root(from)
+      Dir.pwd
+    end
+
+    config.eager_load = false
+    config.secret_key_base = 'secret'
+  end
+end
+
+Terrain::Application.initialize!
+
+module Helpers
+  def serialize(value, options = {})
+    options[:include] ||= []
+    if value.respond_to?(:each)
+      ActiveModel::Serializer::CollectionSerializer.new(value, options).as_json
+    else
+      ActiveModelSerializers::SerializableResource.new(value, options).as_json.symbolize_keys
+    end
+  end
+
+  def policy_double(methods)
+    Class.new(Struct.new(:user, :record)) do
+      methods.each do |name, value|
+        define_method(name) { value }
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.include Helpers
+  config.include FactoryGirl::Syntax::Methods
+
+  config.use_transactional_fixtures = true
+end
+
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |f| require f }

data/spec/support/example.rb

@@ -0,0 +1,5 @@
+class Example < ActiveRecord::Base
+  has_many :widgets
+  
+  validates :foo, presence: true
+end

data/spec/support/example_factory.rb

@@ -0,0 +1,7 @@
+FactoryGirl.define do
+  factory :example do
+    foo { Faker::Lorem.word }
+    bar { Faker::Lorem.word }
+    baz { Faker::Lorem.word }
+  end
+end

data/spec/support/example_serializer.rb

@@ -0,0 +1,4 @@
+class ExampleSerializer < ActiveModel::Serializer
+  attributes :foo, :bar, :baz
+  has_many :widgets
+end

data/spec/support/schema.rb

@@ -0,0 +1,13 @@
+ActiveRecord::Schema.define(version: 1) do
+  create_table :examples do |t|
+    t.string :foo, null: false
+    t.string :bar
+    t.string :baz
+    t.timestamps null: false
+  end
+
+  create_table :widgets do |t|
+    t.integer :example_id, null: false
+    t.timestamps null: false
+  end
+end

data/spec/support/widget.rb

@@ -0,0 +1,3 @@
+class Widget < ActiveRecord::Base
+  belongs_to :example
+end

data/spec/support/widget_factory.rb

@@ -0,0 +1,5 @@
+FactoryGirl.define do
+  factory :widget do
+    example
+  end
+end

data/spec/terrain/errors_spec.rb

@@ -0,0 +1,74 @@
+require 'spec_helper'
+
+describe 'Terrain::Errors', type: :controller do
+  controller do
+    include Terrain::Errors
+  end
+
+  before { get :index }
+
+  context 'association not found' do
+    controller do
+      def index
+        raise ActiveRecord::AssociationNotFoundError.new(nil, nil)
+      end
+    end
+
+    it { expect(response.status).to eq 400 }
+    it { expect_json_types(error: :object) }
+    it { expect_json_types('error.message', :string) }
+    it { expect_json('error.key', 'association_not_found') }
+  end
+
+  context 'unauthorized' do
+    controller do
+      def index
+        raise Pundit::NotAuthorizedError
+      end
+    end
+
+    it { expect(response.status).to eq 403 }
+    it { expect_json_types(error: :object) }
+    it { expect_json_types('error.message', :string) }
+    it { expect_json('error.key', 'unauthorized') }
+  end
+
+  context 'record not found' do
+    controller do
+      def index
+        raise ActiveRecord::RecordNotFound
+      end
+    end
+
+    it { expect(response.status).to eq 404 }
+    it { expect_json_types(error: :object) }
+    it { expect_json_types('error.message', :string) }
+    it { expect_json('error.key', 'record_not_found') }
+  end
+
+  context 'route not found' do
+    controller do
+      def index
+        raise ActionController::RoutingError, ''
+      end
+    end
+
+    it { expect(response.status).to eq 404 }
+    it { expect_json_types(error: :object) }
+    it { expect_json_types('error.message', :string) }
+    it { expect_json('error.key', 'route_not_found') }
+  end
+
+  context 'route not found' do
+    controller do
+      def index
+        raise ActiveRecord::RecordInvalid, Example.new
+      end
+    end
+
+    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') }
+  end
+end

data/spec/terrain/resource_spec.rb

@@ -0,0 +1,200 @@
+require 'spec_helper'
+
+describe 'Terrain::Resource', type: :controller do
+  controller do
+    include Terrain::Resource
+
+    resource Example, permit: [:foo, :bar, :baz]
+  end
+
+  describe '#index' do
+    let!(:examples) { create_list(:example, 10) }
+
+    it 'responds with 200 status' do
+      get :index
+      expect(response.status).to eq 200
+    end
+
+    it 'responds with serialized records' do
+      get :index
+      expect(response.body).to eq serialize(Example.all).to_json
+    end
+  end
+
+  describe '#create' do
+    let(:params) { ActionController::Parameters.new(attributes_for(:example)) }
+
+    it 'responds with 201 status' do
+      post :create, params
+      expect(response.status).to eq 201
+    end
+
+    it 'creates record' do
+      expect { post :create, params }.to change { Example.count }.by 1
+    end
+
+    it 'responds with serialized record' do
+      post :create, params
+      expect(response.body).to eq serialize(Example.last).to_json
+    end
+
+    context 'invalid params' do
+      let(:params) { ActionController::Parameters.new(attributes_for(:example, foo: nil)) }
+
+      it 'raises error' do
+        expect { post :create, params }.to raise_error ActiveRecord::RecordInvalid
+      end
+    end
+
+    context 'with failing policy' do
+      before do
+        allow_any_instance_of(Example).to receive(:policy_class) { policy_double(create?: false) }
+      end
+
+      it 'raises error' do
+        expect { post :create, params }.to raise_error Pundit::NotAuthorizedError
+      end
+    end
+  end
+
+  describe '#show' do
+    let!(:record) { create(:example) }
+    let(:params) { ActionController::Parameters.new(id: record.id) }
+
+    it 'responds with 200 status' do
+      get :show, params
+      expect(response.status).to eq 200
+    end
+
+    it 'responds with serialized record' do
+      get :show, params
+      expect(response.body).to eq serialize(record).to_json
+    end
+
+    context 'invalid ID' do
+      let(:params) { ActionController::Parameters.new(id: 999) }
+
+      it 'raises error' do
+        expect { get :show, params }.to raise_error ActiveRecord::RecordNotFound
+      end
+    end
+
+    context 'with failing policy' do
+      before do
+        allow_any_instance_of(Example).to receive(:policy_class) { policy_double(show?: false) }
+      end
+
+      it 'raises error' do
+        expect { get :show, params }.to raise_error Pundit::NotAuthorizedError
+      end
+    end
+
+    context 'with relations' do
+      let!(:widgets) { create_list(:widget, 3, example: record) }
+
+      it 'does not include relations in serialized record' do
+        get :show, params
+        expect(response.body).to eq serialize(record, include: []).to_json
+      end
+
+      context 'with valid include' do
+        let(:params) { ActionController::Parameters.new(id: record.id, include: 'widgets') }
+
+        it 'includes relations in serialized record' do
+          get :show, params
+          expect(response.body).to eq serialize(record, include: ['widgets']).to_json
+        end
+      end
+
+      context 'with invalid include' do
+        let(:params) { ActionController::Parameters.new(id: record.id, include: 'widgets,wrong') }
+
+        it 'raises error' do
+          expect { get :show, params }.to raise_error ActiveRecord::AssociationNotFoundError
+        end
+      end
+    end
+  end
+
+  describe '#update' do
+    let!(:record) { create(:example) }
+    let(:attrs) { attributes_for(:example) }
+    let(:params) { ActionController::Parameters.new(attrs.merge(id: record.id)) }
+
+    it 'responds with 200 status' do
+      patch :update, params
+      expect(response.status).to eq 200
+    end
+
+    it 'updates record' do
+      patch :update, params
+      record.reload
+      expect(record.foo).to eq params[:foo]
+      expect(record.bar).to eq params[:bar]
+      expect(record.baz).to eq params[:baz]
+    end
+
+    it 'responds with serialized record' do
+      patch :update, params
+      expect(response.body).to eq serialize(record.reload).to_json
+    end
+
+    context 'invalid params' do
+      let(:attrs) { attributes_for(:example, foo: nil) }
+
+      it 'raises error' do
+        expect { patch :update, params }.to raise_error ActiveRecord::RecordInvalid
+      end
+    end
+
+    context 'invalid ID' do
+      let(:params) { ActionController::Parameters.new(id: 999) }
+
+      it 'raises error' do
+        expect { patch :update, params }.to raise_error ActiveRecord::RecordNotFound
+      end
+    end
+
+    context 'with failing policy' do
+      before do
+        allow_any_instance_of(Example).to receive(:policy_class) { policy_double(update?: false) }
+      end
+
+      it 'raises error' do
+        expect { patch :update, params }.to raise_error Pundit::NotAuthorizedError
+      end
+    end
+  end
+
+  describe '#destroy' do
+    let!(:record) { create(:example) }
+    let(:params) { ActionController::Parameters.new(id: record.id) }
+
+    it 'responds with 204 status' do
+      delete :destroy, params
+      expect(response.status).to eq 204
+    end
+
+    it 'deletes record' do
+      expect { delete :destroy, params }.to change { Example.count }.by -1
+    end
+
+    context 'invalid ID' do
+      let(:params) { ActionController::Parameters.new(id: 999) }
+
+      it 'raises error' do
+        expect { patch :update, params }.to raise_error ActiveRecord::RecordNotFound
+      end
+    end
+
+    context 'with failing policy' do
+      before do
+        allow_any_instance_of(Example).to receive(:policy_class) { policy_double(destroy?: false) }
+      end
+
+      it 'raises error' do
+        expect { delete :destroy, params }.to raise_error Pundit::NotAuthorizedError
+      end
+    end
+  end
+end

data/terrain.gemspec

@@ -0,0 +1,24 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |gem|
+  gem.name          = 'terrain'
+  gem.version       = '0.0.1'
+  gem.summary       = 'Terrain'
+  gem.description   = ''
+  gem.license       = 'MIT'
+  gem.authors       = ['Scott Nelson']
+  gem.email         = 'scott@scottnelson.co'
+  gem.homepage      = 'https://github.com/scttnlsn/terrain'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+
+  gem.required_ruby_version = '>= 2.0.0'
+
+  gem.add_dependency 'activesupport', '>= 4.0'
+  gem.add_dependency 'pundit', '1.1.0'
+  gem.add_dependency 'active_model_serializers', '>= 0.10.0.rc5'
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: terrain
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Scott Nelson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-05-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: pundit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.1.0
+- !ruby/object:Gem::Dependency
+  name: active_model_serializers
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.10.0.rc5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.10.0.rc5
+description: ''
+email: scott@scottnelson.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- README.md
+- lib/terrain.rb
+- lib/terrain/errors.rb
+- lib/terrain/resource.rb
+- spec/spec_helper.rb
+- spec/support/example.rb
+- spec/support/example_factory.rb
+- spec/support/example_serializer.rb
+- spec/support/schema.rb
+- spec/support/widget.rb
+- spec/support/widget_factory.rb
+- spec/terrain/errors_spec.rb
+- spec/terrain/resource_spec.rb
+- terrain.gemspec
+homepage: https://github.com/scttnlsn/terrain
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Terrain
+test_files:
+- spec/spec_helper.rb
+- spec/support/example.rb
+- spec/support/example_factory.rb
+- spec/support/example_serializer.rb
+- spec/support/schema.rb
+- spec/support/widget.rb
+- spec/support/widget_factory.rb
+- spec/terrain/errors_spec.rb
+- spec/terrain/resource_spec.rb