erratum 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c87aeb2c02c44b93d2d11f4c3c253fe229b72c44
+  data.tar.gz: d596655b0085b9e0a22e1725235282a2c1f87964
+SHA512:
+  metadata.gz: 9afbb9199a4a7972ed0b0fea7ec56611ccb412bf504835eb58b1a102bcd3407a15add805c1bfbe1277dc9aa308256b2b1466eddbd9f00daf43aaef537e46966f
+  data.tar.gz: 7daab0272eeb312e81e663c792199d799e9511f596f9cde1f304c21659331b7d50b92acc38993d726f4c59507faffe414fc7192af72abbe3db4a1396c8c2aa52

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2016 The Grand Design
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,2 @@
+Erratum
+================================================================================

data/Rakefile

@@ -0,0 +1,2 @@
+# frozen_string_literal: true
+require 'bundler/gem_tasks'

data/lib/erratum/configuration.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+require 'singleton'
+
+class   Erratum
+  class Configuration
+    include Singleton
+
+    attr_accessor :url_mappings
+
+    def external_documentation_urls
+      @external_documentation_urls ||= url_mappings['external_documentation_urls']
+    end
+
+    def developer_documentation_urls
+      @developer_documentation_urls ||= url_mappings['developer_documentation_urls']
+    end
+
+    def to_h
+      {
+        external_documentation_urls:  external_documentation_urls,
+        developer_documentation_urls: developer_documentation_urls,
+      }
+    end
+
+    def url_mappings
+      @url_mappings ||= {
+        'external_documentation_urls'  => {},
+        'developer_documentation_urls' => {},
+      }
+    end
+  end
+
+  def configuration
+    Configuration.instance
+  end
+
+  def self.configure
+    yield configuration
+  end
+
+  def self.configuration
+    Configuration.instance
+  end
+end

data/lib/erratum/error.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+require 'json'
+require 'erratum/configuration'
+require 'erratum/utilities/string'
+
+class   Erratum
+module  Error
+  module ClassMethods
+    def wrap(other)
+      wrapped_error = new message: "#{other.class.name}: #{other.message}"
+      wrapped_error.set_backtrace other.backtrace
+      wrapped_error
+    end
+  end
+
+  attr_accessor :id,
+                :external_documentation_url,
+                :developer_documentation_url,
+                :http_status,
+                :code,
+                :title,
+                :detail,
+                :source,
+                :message
+
+  def initialize(**args)
+    args.each do |variable, value|
+      public_send("#{variable}=", value)
+    end
+  end
+
+  def as_json(_options = {})
+    {
+      errors: [
+                {
+                  id:     id,
+                  links:  {
+                    about:         external_documentation_url,
+                    documentation: developer_documentation_url,
+                  },
+                  status: http_status,
+                  code:   code,
+                  title:  title,
+                  detail: detail,
+                  source: source,
+                },
+              ],
+    }
+  end
+
+  def to_json(_options = {})
+    JSON.dump(as_json)
+  end
+
+  def id
+    @id ||= SecureRandom.uuid
+  end
+
+  def external_documentation_url
+    @external_documentation_url ||= configuration.external_documentation_urls[code]
+  end
+
+  def developer_documentation_url
+    @developer_documentation_url ||= configuration.developer_documentation_urls[code]
+  end
+
+  def http_status
+    @http_status ||= 500
+  end
+
+  alias status http_status
+
+  def code
+    @code ||= Erratum::Utilities::String.
+                underscore(self.class.name).
+                gsub(%r{\A[^/]+/}, '').
+                gsub(%r{/}, '.')
+  end
+
+  def title
+    @title ||= self.class.name
+  end
+
+  def detail
+    @detail ||= 'The server encountered an error.'
+  end
+
+  def source
+    @source ||= {}
+  end
+
+  def message
+    to_s
+  end
+
+  def to_s
+    @message || detail
+  end
+
+  def self.included(base)
+    base.extend ClassMethods
+  end
+
+  private
+
+  def configuration
+    Erratum.configuration
+  end
+end
+end

data/lib/erratum/errors/authentication_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+require 'erratum/error'
+
+class   Erratum
+module  Errors
+module  AuthenticationError
+end
+end
+end

data/lib/erratum/errors/authentication_errors/duplicate_authentication_error.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+require 'erratum/errors/authentication_error'
+
+class   Erratum
+module  Errors
+class   DuplicateAuthenticationError < RuntimeError
+  include Error
+  include AuthenticationError
+
+  attr_accessor :provider,
+                :provider_user_id,
+                :user_id
+
+  def http_status
+    409
+  end
+
+  def title
+    'Duplicate Authentication'
+  end
+
+  def detail
+    'The authentication you attempted to register has already been registered by ' \
+    'another user. We do not currently support allowing multiple users to be connected ' \
+    'to the same authentication.'
+  end
+
+  def source
+    {
+      'provider'         => provider,
+      'provider_user_id' => provider_user_id,
+      'user_id'          => user_id,
+    }
+  end
+end
+end
+end

data/lib/erratum/errors/authentication_errors/invalid_token_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+require 'erratum/errors/authentication_error'
+
+class   Erratum
+module  Errors
+class   InvalidTokenError < RuntimeError
+  include Error
+  include AuthenticationError
+
+  attr_accessor :authentication_token
+
+  def http_status
+    401
+  end
+
+  def title
+    'Invalid Token'
+  end
+
+  def detail
+    'The token you attempted to use for this request is invalid for this resource.  ' \
+    'Please double-check and try again.'
+  end
+
+  def source
+    { token: '[FILTERED]' }
+  end
+end
+end
+end

data/lib/erratum/errors/authentication_errors/invalid_username_or_password_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+require 'erratum/errors/authentication_error'
+
+class   Erratum
+module  Errors
+class   InvalidUsernameOrPasswordError < RuntimeError
+  include Error
+  include AuthenticationError
+
+  attr_accessor :username
+
+  def http_status
+    401
+  end
+
+  def title
+    'Invalid Username/Password'
+  end
+
+  def detail
+    'Either the username or password passed in or this request is invalid.  Please ' \
+    'double-check and try again.'
+  end
+
+  def source
+    { username: username, password: '[FILTERED]' }
+  end
+end
+end
+end

data/lib/erratum/errors/authorization_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+require 'erratum/error'
+
+class   Erratum
+module  Errors
+module  AuthorizationError
+end
+end
+end

data/lib/erratum/errors/authorization_errors/forbidden_error.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+require 'erratum/errors/authorization_error'
+
+class   Erratum
+module  Errors
+class   ForbiddenError < RuntimeError
+  include Error
+  include AuthorizationError
+
+  NON_SPECIFIC_RESOURCE_ACTIONS = %w{index create}.freeze
+
+  attr_accessor :resource_name,
+                :resource_id,
+                :action
+
+  def http_status
+    403
+  end
+
+  def title
+    'Forbidden'
+  end
+
+  def detail
+    detail_quantity = if NON_SPECIFIC_RESOURCE_ACTIONS.include? action.to_s
+                        "#{action} a #{resource_name}"
+                      else
+                        "#{action} the #{resource_name} with ID #{resource_id}"
+                      end
+
+    "You do not have access to #{detail_quantity}. Providing a different set of " \
+    "credentials may potentially allow you access to this resource."
+  end
+
+  def source
+    @source ||= {
+      'resource_name' => resource_name,
+      'resource_id'   => resource_id,
+      'action'        => @action,
+    }
+  end
+
+  def action
+    @action || 'access'
+  end
+end
+end
+end

data/lib/erratum/errors/crud_error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+class   Erratum
+module  Errors
+module  CrudError
+  attr_accessor :resource_name,
+                :action,
+                :resource_id
+
+  def initialize(resource_name: nil, action: nil, resource_id: nil, **args)
+    self.resource_name = resource_name
+    self.action        = action || 'persist'
+    self.resource_id   = resource_id
+
+    super(**args)
+  end
+
+  private
+
+  def resource_name_underscored
+    @resource_name_underscored ||= resource_name.gsub(/\s/, '_')
+  end
+end
+end
+end

data/lib/erratum/errors/crud_errors/association_error.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+require 'erratum/errors/crud_error'
+
+class   Erratum
+module  Errors
+class   AssociationError < RuntimeError
+  include Error
+  include CrudError
+
+  attr_accessor :association_name,
+                :association_id,
+                :attributes
+
+  def self.convert(original_error, overrides = {})
+    initialization_parameters = {}
+
+    case original_error.class.name
+    when 'ActiveRecord::InvalidForeignKey'
+      message_info_pattern = /DETAIL:  Key \((.*)_id\)=\(([a-f0-9\-]+)\)/
+      message_info         = original_error.
+                               message.
+                               match(message_info_pattern)[1..-1]
+
+      initialization_parameters = {
+        association_name: message_info[0],
+        association_id:   message_info[1],
+      }
+    end
+
+    new(initialization_parameters.merge(overrides))
+  end
+
+  def http_status
+    422
+  end
+
+  def title
+    'Association Error'
+  end
+
+  def detail
+    "The #{association_name} that you attempted to associate with " \
+    "the #{resource_name} was not valid."
+  end
+
+  def source
+    {
+      resource_name            => attributes,
+      "#{association_name} id" => association_id,
+    }
+  end
+end
+end
+end

data/lib/erratum/errors/crud_errors/resource_not_found_error.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+require 'erratum/errors/crud_error'
+
+class   Erratum
+module  Errors
+class   ResourceNotFoundError < RuntimeError
+  include Error
+  include CrudError
+
+  def self.convert(original_error, overrides = {})
+    initialization_parameters = {}
+
+    case original_error.class.name
+    when 'ActiveRecord::RecordNotFound'
+      initialization_parameters = {
+        resource_id: case original_error.message
+                     when /\ACouldn't find .* without an ID\z/
+                       []
+                     when /\ACouldn't find .* with \'.*\'=([a-f0-9\-]+)/
+                       [Regexp.last_match(1)]
+                     when /\ACouldn't find all .* with \'.*\': ((?:[a-f0-9\-]+(?:, )?)+)/
+                       Array(Regexp.last_match(1).split(', '))
+                     end,
+      }
+    end
+
+    new(initialization_parameters.merge(overrides))
+  end
+
+  def http_status
+    404
+  end
+
+  def title
+    'Resource Not Found'
+  end
+
+  def detail
+    "The #{resource_name} you attempted to #{action} for this request is either " \
+    "not authorized for the authenticated user or does not exist."
+  end
+
+  def source
+    { "#{resource_name_underscored}_id" => resource_id }
+  end
+
+  def action
+    @action || 'access'
+  end
+end
+end
+end

data/lib/erratum/errors/crud_errors/resource_persistence_error.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+require 'erratum/errors/crud_error'
+
+class   Erratum
+module  Errors
+class   ResourcePersistenceError < RuntimeError
+  include Error
+  include CrudError
+
+  attr_accessor :errors,
+                :attributes
+
+  def self.convert(original_error, overrides = {})
+    initialization_parameters = {}
+
+    case original_error.class.name
+    when 'ActiveRecord::RecordInvalid',
+         'ActiveRecord::RecordNotSaved'
+
+      initialization_parameters = {
+        attributes: original_error.record.attributes,
+        errors:     original_error.record.errors.full_messages,
+      }
+    end
+
+    new(initialization_parameters.merge(overrides))
+  end
+
+  def http_status
+    422
+  end
+
+  def title
+    'Resource Persistence Error'
+  end
+
+  def detail
+    "One or more of the attributes on the #{resource_name} you attempted " \
+    "to #{action} is invalid."
+  end
+
+  def source
+    {
+      'errors'     => errors,
+      'attributes' => attributes,
+    }
+  end
+end
+end
+end

data/lib/erratum/errors/request_errors/parameter_missing_error.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+class   Erratum
+module  Errors
+class   ParameterMissingError < RuntimeError
+  include Error
+  include CrudError
+
+  attr_accessor :parameter
+
+  def self.convert(original_error, overrides = {})
+    initialization_parameters = {}
+
+    case original_error.class.name
+    when 'ActionController::ParameterMissing'
+      initialization_parameters = {
+        parameter: original_error.param,
+      }
+    end
+
+    new(initialization_parameters.merge(overrides))
+  end
+
+  def http_status
+    400
+  end
+
+  def title
+    'Missing Parameter'
+  end
+
+  def detail
+    "When attempting to #{action} a #{resource_name}, '#{parameter}' is a " \
+    "required parameter."
+  end
+
+  def source
+    {
+      'required_parameter' => parameter,
+    }
+  end
+end
+end
+end

data/lib/erratum/errors/request_errors/unpermitted_parameters_error.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+class   Erratum
+module  Errors
+class   UnpermittedParametersError < RuntimeError
+  include Error
+  include CrudError
+
+  attr_accessor :parameters
+
+  def self.convert(original_error, overrides = {})
+    initialization_parameters = {}
+
+    case original_error.class.name
+    when 'ActionController::UnpermittedParameters'
+      initialization_parameters = {
+        parameters: Array(original_error.params),
+      }
+    end
+
+    new(initialization_parameters.merge(overrides))
+  end
+
+  def initialize(**attrs)
+    self.parameters = Array(attrs.delete(:parameters))
+
+    super(**attrs)
+  end
+
+  def http_status
+    400
+  end
+
+  def title
+    'Unpermitted Parameters'
+  end
+
+  def detail
+    "Attempting to #{action} a #{resource_name} with the following parameters is " \
+    "not allowed: #{parameters.join(', ')}"
+  end
+
+  def source
+    {
+      'unpermitted_parameters' => parameters,
+    }
+  end
+end
+end
+end

data/lib/erratum/rescuable_resource.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+require 'erratum/resource_naming'
+
+class   Erratum
+module  RescuableResource
+  def self.included(base)
+    base.include ResourceNaming
+
+    base.rescue_from 'ActiveRecord::RecordInvalid',
+                     'ActiveRecord::RecordNotSaved',
+                     'ActiveRecord::RecordNotFound',
+                     'ActiveRecord::InvalidForeignKey',
+                     'ActionController::ParameterMissing',
+                     'ActionController::UnpermittedParameters' do |exception|
+      erratum = Erratum.convert(exception,
+                                resource_name: self.class.singular_resource_name,
+                                action:        action_name)
+
+      render json:   erratum,
+             status: erratum.http_status
+    end
+
+    base.rescue_from 'Erratum::Error' do |exception|
+      render json:   exception,
+             status: exception.http_status
+    end
+  end
+end
+end