onsi 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 240457c28d5920df4c1ece3e02958683cb4ce64880d62c04508b4d61f6f209c4
-  data.tar.gz: 7cf5164177f088a50d759c1bbb0a5d71f50c8c02196583391d5d5ea3733d2b23
+  metadata.gz: ed92bde9b8d7540e7d542621101fedc2cb414aaa07d24c751d57d7b4454b0bcb
+  data.tar.gz: 441c0cd6376b4bcc6c086acb0cbec596fed03f0a190a8096e8dac639be4a28d9
 SHA512:
-  metadata.gz: ce09111ef7c6b0f5f61fae71fd58c922650aa800f17ac6910805537be0c5f2f9a9b13991ea4c98887baf206fb2ccde9a3ae324e371d01a1d61b7ce9a063eff20
-  data.tar.gz: fd0da8ddb1f5a11be31a8f78acefd751e1ef020a0c3cbdc3eb2c3b92a53dc60888b7d317906de77fdf75468651a37fcb313b833db2676841b63826e4ea1284e9
+  metadata.gz: b1b31fa4f17aad3767d5f4f2b46bf92e52ff6bd9ec7343ab4e742796d41f6791f5944b07378ec3dfd16d11b2b1caca07608fea9ad3dcb911b1a89318d8be15cd
+  data.tar.gz: 4e0e591bc4fea1df9aeedc73b6f558a12e7a41b42f65a780eff24784bad73c709731af923e1fd97d0346295ff911b66584cd11e74584071f6f0bffbbef176aef

data/.rubocop.yml

@@ -19,6 +19,11 @@ Metrics/ParameterLists:
 Metrics/CyclomaticComplexity:
   Max: 10
 
+Metrics/BlockLength:
+  Enabled: true
+  Exclude:
+    - spec/**/*
+
 DotPosition:
   EnforcedStyle: leading
 
@@ -51,3 +56,6 @@ Style/RaiseArgs:
 
 Style/FrozenStringLiteralComment:
   Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    onsi (0.2.1)
+    onsi (0.3.0)
       rails (>= 5.0, < 6.0)
 
 GEM

data/README.md

@@ -1,8 +1,8 @@
 # Onsi
 
-Used to generate API responses from a rails App.
+Used to generate API responses from a Rails App.
 
-=================================================
+***
 
 [![CircleCI](https://circleci.com/gh/skylarsch/onsi.svg?style=svg)](https://circleci.com/gh/skylarsch/onsi)
 
@@ -10,3 +10,117 @@ Used to generate API responses from a rails App.
 
 [![Test Coverage](https://api.codeclimate.com/v1/badges/c3ee44371f7565f2709c/test_coverage)](https://codeclimate.com/github/skylarsch/onsi/test_coverage)
 
+### Install
+
+1. Add `gem 'onsi'` to your Gemfile
+
+2. `bundle install`
+
+## Getting Setup
+
+### Controllers
+
+`Onsi::Controller` handles rendering resources for you.
+
+```ruby
+class PeopleController < ApplicationController
+  include Onsi::Controller
+
+  # Optional. By default Onsi will render `:v1`
+  render_version :v2
+
+  def show
+    @person = Person.find(params[:id])
+    # You can pass an Object, Enumerable, or Onsi::Resource
+    # Whatever you pass, the object or each element in the collection *MUST*
+    # include `Onsi::Model`
+    render_resource @person
+  end
+end
+```
+
+### Models
+
+Used to define your API resources. Calling the class method `api_render` will
+allow you to begin setting up a version of your API. You're able to define as
+many API versions as you would like. The default rendered if nothing is
+specified in the `render_resource` method is `:v1`.
+
+```ruby
+class Person < ApplicationRecord
+  include Onsi::Model
+
+  api_render(:v1) do
+    # Passing the name of the attribute only will call that name as a method on
+    # the instance of the method.
+    attribute(:first_name)
+    attribute(:last_name)
+    # You can give attribute a block and it will be called on the object
+    # instance. This lets you rename or compute attributes
+    attribute(:full_name) { "#{first_name} #{last_name}" }
+
+    # Relationship requires a minimum of 2 parameters. The first is the name
+    # of the relationship in the rendered JSON. The second is the type.
+    # When fetching the value, Onsi will add `_id` and call that method on the
+    # object instance. e.g. `team_id` in this case.
+    relationship(:team, :team)
+
+    # Relationships can take a block that will be called on the object instance
+    # and the return value will be used as the ID
+    relationship(:primary_email, :email) { emails.where(primary: true).first.id }
+  end
+end
+```
+
+### Params
+
+`Onsi::Params` can be used to flatten params that come into the API.
+
+Calling `.parse` will give you an instance of `Onsi::Params` with whitelisted
+attributes & relationships. The first argument is the params from the controller.
+The second is an array of attributes and the third is an array of relationships.
+
+Calling `#flatten` will merge the attributes & relationships.
+
+```json
+{
+  "data": {
+    "type": "person",
+    "attributes": {
+      "first_name": "Skylar",
+      "last_name": "Schipper",
+      "bad_value": "'); DROP TABLE `people`; --"
+    },
+    "relationships": {
+      "team": {
+        "data": {
+          "type": "team",
+          "id": "1"
+        }
+      },
+      "unknown": {
+        "data": [
+          { "type": "foo", "id": "1" }
+        ]
+      }
+    }
+  }
+}
+```
+
+Flattened gives you:
+
+```ruby
+{ "first_name" => "Skylar", "last_name" => "Schipper", "team_id" => "1" }
+```
+
+```ruby
+class PeopleController < ApplicationController
+  include Onsi::Controller
+
+  def create
+    attributes = Onsi::Param.parse(params, [:first_name, :last_name], [:team])
+    render_resource Person.create!(attributes.flatten)
+  end
+end
+```

data/lib/onsi/error_responder.rb

@@ -0,0 +1,139 @@
+require 'active_support/concern'
+
+module Onsi
+  module ErrorResponder
+    extend ActiveSupport::Concern
+
+    included do
+      rescue_from StandardError,                         with: :render_error_500
+      rescue_from ActiveRecord::RecordNotFound,          with: :render_error_404
+      rescue_from ActiveRecord::RecordInvalid,           with: :render_error_422
+      rescue_from ActionController::ParameterMissing,    with: :respond_param_error_400
+      rescue_from Onsi::Params::MissingReqiredAttribute, with: :respond_missing_attr_error_400
+      rescue_from Onsi::Params::RelationshipNotFound,    with: :respond_missing_relationship_error_400
+      rescue_from Onsi::Errors::UnknownVersionError,     with: :respond_invalid_version_error_400
+    end
+
+    def render_error(response)
+      render(response.renderable)
+    end
+
+    def render_error_500(error)
+      notify_unhandled_exception(error)
+      response = ErrorResponse.new(500)
+      response.add(500, 'internal_server_error', meta: error_metadata(error))
+      render_error(response)
+    end
+
+    def render_error_404(_error)
+      response = ErrorResponse.new(404)
+      response.add(404, 'not_found')
+      render_error(response)
+    end
+
+    def render_error_422(error)
+      response = ErrorResponse.new(422)
+      error.record.errors.details.each do |name, details|
+        details.each do |info|
+          response.add(
+            422,
+            'validation_error',
+            title: "Validation Error: #{info[:error]}",
+            meta: info.merge(param: name)
+          )
+        end
+      end
+      render_error(response)
+    end
+
+    def respond_param_error_400(error)
+      response = ErrorResponse.new(400)
+      response.add(
+        400,
+        'missing_parameter',
+        meta: { param: error.param }
+      )
+      render_error(response)
+    end
+
+    def respond_missing_relationship_error_400(error)
+      response = ErrorResponse.new(400)
+      response.add(
+        400,
+        'missing_relationship',
+        meta: { param: error.key }
+      )
+      render_error(response)
+    end
+
+    def respond_invalid_version_error_400(error)
+      notify_unhandled_exception(error)
+      response = ErrorResponse.new(400)
+      response.add(
+        400,
+        'invalid_version',
+        details: "API version #{error.version} unsupported for #{error.klass.name.underscore}"
+      )
+      render_error(response)
+    end
+
+    def respond_missing_attr_error_400(error)
+      response = ErrorResponse.new(400)
+      response.add(
+        400,
+        'missing_attribute',
+        meta: {
+          attribute: error.attribute
+        }
+      )
+      render_error(response)
+    end
+
+    def notify_unhandled_exception(exception)
+      Rails.logger.error "Unhandled Exception `#{exception.class.name}: #{exception.message}`"
+    end
+
+    private
+
+    def error_metadata(error)
+      return nil unless Rails.configuration.consider_all_requests_local
+      {
+        exception: {
+          class: error.class.name,
+          message: error.message,
+          backtrace: error.backtrace
+        }
+      }
+    end
+  end
+
+  class ErrorResponse
+    attr_reader :status
+
+    def initialize(status)
+      @status = status
+      @errors = []
+    end
+
+    def add(status, code, title: nil, details: nil, meta: nil)
+      @errors << {}.tap do |err|
+        err[:status] = (status || @status).to_s
+        err[:code]   = code
+        err[:title]  = title      if title.present?
+        err[:detail] = details    if details.present?
+        err[:meta]   = Hash(meta) if meta.present?
+      end
+    end
+
+    def as_json
+      { errors: @errors.as_json }
+    end
+
+    def renderable
+      {
+        json:   as_json,
+        status: status
+      }
+    end
+  end
+end

data/lib/onsi/params.rb

@@ -9,6 +9,15 @@ module Onsi
       end
     end
 
+    class MissingReqiredAttribute < StandardError
+      attr_reader :attribute
+
+      def initialize(message, attr)
+        super(message)
+        @attribute = attr
+      end
+    end
+
     class << self
       def parse(params, attributes = [], relationships = [])
         data = params.require(:data)
@@ -63,6 +72,14 @@ module Onsi
       attributes.to_h.merge(relationships.to_h).with_indifferent_access
     end
 
+    def require(key)
+      value = attributes.to_h.with_indifferent_access[key]
+      if value.nil?
+        raise MissingReqiredAttribute.new("Missing attribute #{key}", key)
+      end
+      value
+    end
+
     def safe_fetch(key)
       yield(@relationships[key])
     rescue ActiveRecord::RecordNotFound

data/lib/onsi/version.rb

@@ -1,3 +1,3 @@
 module Onsi
-  VERSION = '0.2.1'.freeze
+  VERSION = '0.3.0'.freeze
 end

data/lib/onsi.rb

@@ -1,4 +1,5 @@
 require 'onsi/controller'
+require 'onsi/error_responder'
 require 'onsi/errors'
 require 'onsi/model'
 require 'onsi/params'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: onsi
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Skylar Schipper
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-05-14 00:00:00.000000000 Z
+date: 2018-05-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -164,6 +164,7 @@ files:
 - bin/setup
 - lib/onsi.rb
 - lib/onsi/controller.rb
+- lib/onsi/error_responder.rb
 - lib/onsi/errors.rb
 - lib/onsi/model.rb
 - lib/onsi/params.rb