erratum 0.0.1

data/lib/erratum/resource_naming.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+class   Erratum
+module  ResourceNaming
+  CONTROLLER_RESOURCE_NAME_PATTERN = /\A((.*?::)?.*?)(\w+)Controller\z/
+
+  module ClassMethods
+    def plural_resource_name
+      @plural_resource_name ||= name[CONTROLLER_RESOURCE_NAME_PATTERN, 3].
+                                underscore.
+                                pluralize.
+                                downcase
+    end
+
+    def singular_resource_name
+      @singular_resource_name ||= name[CONTROLLER_RESOURCE_NAME_PATTERN, 3].
+                                  underscore.
+                                  singularize.
+                                  downcase
+    end
+
+    def resource_class_name
+      @resource_class_name ||= singular_resource_name.
+                               camelize
+    end
+  end
+
+  def self.included(base)
+    base.extend ClassMethods
+  end
+end
+end

data/lib/erratum/utilities/string.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+class   Erratum
+module  Utilities
+class   String
+  def self.underscore(other)
+    word = other.to_s.gsub('::', '/')
+    word.gsub!(/(?:([A-Za-z\d])|^)(?=\b|[^a-z])/) do
+      "#{Regexp.last_match(1)}#{Regexp.last_match(1) && ''}"
+    end
+    word.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+    word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+    word.tr!('-', '_')
+    word.downcase!
+    word
+  end
+end
+end
+end

data/lib/erratum/verifiable_resource.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+require 'erratum/resource_naming'
+
+class   Erratum
+module  ResourceNaming
+  def self.included(base)
+    base.include ResourceNaming
+
+    base.before_action except: %i{index create} do
+      model = public_send(self.class.singular_resource_name)
+
+      resource_not_found_error = Erratum.build(
+        'ResourceNotFoundError',
+        resource_name: self.class.singular_resource_name,
+        resource_id:   [params[:id]],
+        action:        action_name,
+      )
+
+      fail resource_not_found_error unless model.persisted?
+    end
+  end
+end
+end

data/lib/erratum/version.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+class Erratum
+  VERSION = '0.0.1'
+end

data/lib/erratum.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+require 'erratum/configuration'
+require 'erratum/error'
+require 'erratum/errors/authorization_error'
+require 'erratum/errors/authorization_errors/forbidden_error'
+require 'erratum/errors/authentication_error'
+require 'erratum/errors/authentication_errors/duplicate_authentication_error'
+require 'erratum/errors/authentication_errors/invalid_token_error'
+require 'erratum/errors/authentication_errors/invalid_username_or_password_error'
+require 'erratum/errors/crud_error'
+require 'erratum/errors/crud_errors/association_error'
+require 'erratum/errors/crud_errors/resource_not_found_error'
+require 'erratum/errors/crud_errors/resource_persistence_error'
+require 'erratum/errors/request_errors/parameter_missing_error'
+require 'erratum/errors/request_errors/unpermitted_parameters_error'
+require 'erratum/rescuable_resource'
+require 'erratum/verifiable_resource'
+require 'erratum/version'
+
+class   Erratum
+  def self.fetch(error_type)
+    Object.const_get("Erratum::Errors::#{error_type}")
+  end
+
+  def self.build(error_type, overrides = {})
+    fetch(error_type).new(overrides)
+  end
+
+  def self.convert(original_error, overrides = {})
+    case original_error.class.name
+    when 'ActiveRecord::InvalidForeignKey'
+      fetch('AssociationError').convert(original_error, overrides)
+    when 'ActiveRecord::RecordNotFound'
+      fetch('ResourceNotFoundError').convert(original_error, overrides)
+    when 'ActiveRecord::RecordInvalid',
+         'ActiveRecord::RecordNotSaved'
+      fetch('ResourcePersistenceError').convert(original_error, overrides)
+    when 'ActionController::ParameterMissing',
+      fetch('ParameterMissingError').convert(original_error, overrides)
+    when 'ActionController::UnpermittedParameters'
+      fetch('UnpermittedParametersError').convert(original_error, overrides)
+    end
+  end
+
+  def self.raise(error_type, **args)
+    Kernel.fail build(error_type, **args)
+  end
+end

data/spec/lib/erratum/configuration_spec.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+require 'rspeckled'
+require 'erratum/configuration'
+
+class           Erratum
+RSpec.describe  Configuration, singletons: true do
+  it 'can set the url mappings' do
+    configuration = Configuration.instance
+    configuration.url_mappings = 'foobarbaz'
+
+    expect(configuration.url_mappings).to eql 'foobarbaz'
+  end
+
+  it 'can convert itself into a hash' do
+    configuration              = Configuration.instance
+    configuration.url_mappings = {
+      'external_documentation_urls'  => 'blah',
+      'developer_documentation_urls' => 'asdf',
+    }
+
+    expect(configuration.to_h).to eql(
+      external_documentation_urls:  'blah',
+      developer_documentation_urls: 'asdf',
+    )
+  end
+end
+end

data/spec/lib/erratum/error_spec.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+require 'rspeckled'
+require 'erratum/error'
+
+class CustomError < RuntimeError
+  include Erratum::Error
+end
+
+class           Erratum
+RSpec.describe  Error do
+  it 'can wrap an error with another error' do
+    original_error = RuntimeError.new('My Runtime Error Message')
+    wrapped_error  = CustomError.wrap(original_error)
+
+    expect(wrapped_error.class.name).to eql 'CustomError'
+  end
+
+  it 'can wrap the message of an error by identifying the original error type' do
+    original_error = RuntimeError.new('My Runtime Error Message')
+    wrapped_error  = CustomError.wrap(original_error)
+
+    expect(wrapped_error.message).to eql 'RuntimeError: My Runtime Error Message'
+  end
+
+  it 'can transfer the backtrace of the original error to the wrapped error' do
+    original_error = RuntimeError.new('My Runtime Error Message')
+    original_error.set_backtrace %w{foo bar baz}
+    wrapped_error = CustomError.wrap(original_error)
+
+    expect(wrapped_error.backtrace).to eql %w{foo bar baz}
+  end
+
+  it 'can have its message explicitly set when it is generated' do
+    error = CustomError.new(message: 'My Message')
+
+    expect(error.message).to eql 'My Message'
+  end
+
+  it 'can have its message explicitly set when it is generated' do
+    error = CustomError.new
+    allow(error).to receive(:detail).
+                    and_return('My Developer Message')
+
+    expect(error.message).to eql 'My Developer Message'
+  end
+
+  it 'can generate error data' do
+    custom_error = CustomError.new(
+      id:                          'identifier',
+      http_status:                 'flibbity',
+      code:                        'jibbit',
+      title:                       'roll dem bones and stones',
+      detail:                      'I cannot receive any satisfaction',
+      source:                      'But perhaps if I attempt it one more time, I can',
+      developer_documentation_url: 'asimof/jibbit?version=janky',
+      external_documentation_url:  'jinkies/87654321',
+    )
+
+    expect(custom_error.as_json).to eql(
+      errors: [
+                {
+                  id:     'identifier',
+                  links:  {
+                    about:         'jinkies/87654321',
+                    documentation: 'asimof/jibbit?version=janky',
+                  },
+                  status: 'flibbity',
+                  code:   'jibbit',
+                  title:  'roll dem bones and stones',
+                  detail: 'I cannot receive any satisfaction',
+                  source: 'But perhaps if I attempt it one more time, I can',
+                },
+              ],
+    )
+  end
+
+  it 'can extract configuration from the global config if it is not passed in',
+     singletons: Erratum::Configuration do
+
+    Erratum.configure do |config|
+      config.url_mappings = {
+        'external_documentation_urls'  => {
+          'jibbit' => 'http://example.com/edu',
+        },
+        'developer_documentation_urls' => {
+          'jibbit' => 'http://example.com/ddu',
+        },
+      }
+    end
+
+    custom_error = CustomError.new(
+      id:          'identifier',
+      http_status: 'flibbity',
+      code:        'jibbit',
+      title:       'roll dem bones and stones',
+      detail:      'I cannot receive any satisfaction',
+      source:      'But perhaps if I attempt it one more time, I can',
+    )
+
+    expect(custom_error.as_json).to eql(
+      errors: [
+                {
+                  id:     'identifier',
+                  links:  {
+                    about:         'http://example.com/edu',
+                    documentation: 'http://example.com/ddu',
+                  },
+                  status: 'flibbity',
+                  code:   'jibbit',
+                  title:  'roll dem bones and stones',
+                  detail: 'I cannot receive any satisfaction',
+                  source: 'But perhaps if I attempt it one more time, I can',
+                },
+              ],
+    )
+  end
+
+  it 'can override the global config if it is set, but an explicit value is passed in',
+     singletons: Erratum::Configuration do
+
+    Erratum.configure do |config|
+      config.url_mappings = {
+        'external_documentation_urls'  => {
+          'jibbit' => 'http://example.com/edu',
+        },
+        'developer_documentation_urls' => {
+          'jibbit' => 'http://example.com/ddu',
+        },
+      }
+    end
+
+    custom_error = CustomError.new(
+      id:                          'identifier',
+      http_status:                 'flibbity',
+      code:                        'jibbit',
+      title:                       'roll dem bones and stones',
+      detail:                      'I cannot receive any satisfaction',
+      source:                      'But perhaps if I attempt it one more time, I can',
+      developer_documentation_url: 'hasimof/jibbit?version=hanky',
+      external_documentation_url:  'hinkies/87654321',
+    )
+
+    expect(custom_error.as_json).to eql(
+      errors: [
+                {
+                  id:     'identifier',
+                  links:  {
+                    about:         'hinkies/87654321',
+                    documentation: 'hasimof/jibbit?version=hanky',
+                  },
+                  status: 'flibbity',
+                  code:   'jibbit',
+                  title:  'roll dem bones and stones',
+                  detail: 'I cannot receive any satisfaction',
+                  source: 'But perhaps if I attempt it one more time, I can',
+                },
+              ],
+    )
+  end
+
+  it 'can handle if it finds no URL mappings' do
+    custom_error = CustomError.new(
+      id:          'identifier',
+      http_status: 'flibbity',
+      code:        'jibbit',
+      title:       'roll dem bones and stones',
+      detail:      'I cannot receive any satisfaction',
+      source:      'But perhaps if I attempt it one more time, I can',
+    )
+
+    expect(custom_error.as_json).to eql(
+      errors: [
+                {
+                  id:     'identifier',
+                  links:  {
+                    about:         nil,
+                    documentation: nil,
+                  },
+                  status: 'flibbity',
+                  code:   'jibbit',
+                  title:  'roll dem bones and stones',
+                  detail: 'I cannot receive any satisfaction',
+                  source: 'But perhaps if I attempt it one more time, I can',
+                },
+              ],
+    )
+  end
+end
+end

data/spec/lib/erratum/errors/authentication_errors/duplicate_authentication_error_spec.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+require 'rspeckled'
+require 'erratum/errors/authentication_errors/duplicate_authentication_error'
+
+class           Erratum
+module          Errors
+RSpec.describe  DuplicateAuthenticationError do
+  let(:error) do
+    DuplicateAuthenticationError.new(provider:         'flibbity',
+                                     provider_user_id: '12345',
+                                     user_id:          '54321')
+  end
+
+  it 'has a status of 409' do
+    expect(error.http_status).to eql 409
+  end
+
+  it 'has a code' do
+    expect(error.code).to eql 'errors.duplicate_authentication_error'
+  end
+
+  it 'has a title' do
+    expect(error.title).to eql 'Duplicate Authentication'
+  end
+
+  it 'can output the detail' do
+    expect(error.detail).to eql '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
+
+  it 'can output the source' do
+    expect(error.source).to eql(
+              'provider'         => 'flibbity',
+              'provider_user_id' => '12345',
+              'user_id'          => '54321',
+    )
+  end
+end
+end
+end

data/spec/lib/erratum/errors/authentication_errors/invalid_token_error_spec.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+require 'rspeckled'
+require 'erratum/errors/authentication_errors/invalid_token_error'
+
+class           Erratum
+module          Errors
+RSpec.describe  InvalidTokenError do
+  let(:error) { InvalidTokenError.new }
+
+  it 'has a status of 401' do
+    expect(error.http_status).to eql 401
+  end
+
+  it 'has a code' do
+    expect(error.code).to eql 'errors.invalid_token_error'
+  end
+
+  it 'has a title' do
+    expect(error.title).to eql 'Invalid Token'
+  end
+
+  it 'can output the detail' do
+    expect(error.detail).to eql 'The token you attempted to use for this ' \
+                                           'request is invalid for this resource.  ' \
+                                           'Please double-check and try again.'
+  end
+
+  it 'can output the source' do
+    expect(error.source).to eql(token: '[FILTERED]')
+  end
+end
+end
+end

data/spec/lib/erratum/errors/authentication_errors/invalid_username_or_password_error_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+require 'rspeckled'
+require 'erratum/errors/authentication_errors/invalid_username_or_password_error'
+
+class           Erratum
+module          Errors
+RSpec.describe  InvalidUsernameOrPasswordError do
+  let(:error) { InvalidUsernameOrPasswordError.new }
+
+  it 'has a status of 401' do
+    expect(error.http_status).to eql 401
+  end
+
+  it 'has a code' do
+    expect(error.code).to eql 'errors.invalid_username_or_password_error'
+  end
+
+  it 'has a title' do
+    expect(error.title).to eql 'Invalid Username/Password'
+  end
+
+  it 'can output the detail' do
+    expect(error.detail).to eql 'Either the username or password passed in ' \
+                                           'or this request is invalid.  Please ' \
+                                           'double-check and try again.'
+  end
+
+  it 'can output the source' do
+    error = InvalidUsernameOrPasswordError.new username: 'neo'
+
+    expect(error.source).to eql(username: 'neo', password: '[FILTERED]')
+  end
+end
+end
+end

data/spec/lib/erratum/errors/authorization_errors/forbidden_error_spec.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+require 'rspeckled'
+require 'erratum/errors/authorization_errors/forbidden_error'
+
+class           Erratum
+module          Errors
+RSpec.describe  ForbiddenError do
+  let(:error) { ForbiddenError.new }
+
+  it 'has a status of 403' do
+    expect(error.http_status).to eql 403
+  end
+
+  it 'has a code' do
+    expect(error.code).to eql 'errors.forbidden_error'
+  end
+
+  it 'has a title' do
+    expect(error.title).to eql 'Forbidden'
+  end
+
+  it 'can output the detail for actions affecting a specific resource' do
+    error = ForbiddenError.new(resource_name: 'resource',
+                               resource_id:   '123',
+                               action:        'show')
+
+    expect(error.detail).to eql \
+    'You do not have access to show the resource with ID 123. Providing a different ' \
+    'set of credentials may potentially allow you access to this resource.'
+  end
+
+  it 'can output the detail for actions affecting multiple resources' do
+    error = ForbiddenError.new(resource_name: 'resource',
+                               action:        'create')
+
+    expect(error.detail).to eql \
+    'You do not have access to create a resource. Providing a different ' \
+    'set of credentials may potentially allow you access to this resource.'
+  end
+
+  it 'can output the source' do
+    error = ForbiddenError.new(resource_name: 'resource',
+                               resource_id:   '123',
+                               action:        'show')
+
+    expect(error.source).to eql('resource_name' => 'resource',
+                                'resource_id'   => '123',
+                                'action'        => 'show')
+  end
+end
+end
+end

data/spec/lib/erratum/errors/crud_errors/association_error_spec.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+require 'rspeckled'
+require 'erratum/errors/crud_errors/association_error'
+require 'active_record/errors'
+
+class           Erratum
+module          Errors
+RSpec.describe  AssociationError do
+  let(:foreign_key_error) do
+    ActiveRecord::InvalidForeignKey.new('DETAIL:  Key (resource_id)=(123)')
+  end
+
+  it 'has a status of 422' do
+    error = AssociationError.new
+
+    expect(error.http_status).to eql 422
+  end
+
+  it 'has a code' do
+    error = AssociationError.new
+
+    expect(error.code).to eql 'errors.association_error'
+  end
+
+  it 'has a title' do
+    error = AssociationError.new
+
+    expect(error.title).to eql 'Association Error'
+  end
+
+  it 'includes the resource name and action in the detail' do
+    error = AssociationError.new association_name: 'dragon',
+                                 resource_name:    'Daenerys'
+
+    expect(error.detail).to eql 'The dragon that you ' \
+                                'attempted to associate with the Daenerys was ' \
+                                'not valid.'
+  end
+
+  it 'includes the resource name and action in the source' do
+    error = AssociationError.new association_name: 'dragon',
+                                 resource_name:    'Daenerys',
+                                 attributes:       'winter is coming',
+                                 association_id:   '123'
+
+    expect(error.source).to eql(
+      'Daenerys'  => 'winter is coming',
+      'dragon id' => '123',
+    )
+  end
+
+  it 'can convert an "ActiveRecord::InvalidForeignKey"' do
+    error = AssociationError.convert(foreign_key_error)
+
+    expect(error.resource_name).to    eql nil
+    expect(error.association_name).to eql 'resource'
+    expect(error.association_id).to   eql '123'
+  end
+
+  it 'can convert an "ActiveRecord::InvalidForeignKey" while overriding attributes' do
+    error = AssociationError.convert(foreign_key_error, resource_name: 'my_resource')
+
+    expect(error.resource_name).to    eql 'my_resource'
+    expect(error.association_name).to eql 'resource'
+    expect(error.association_id).to   eql '123'
+  end
+end
+end
+end

data/spec/lib/erratum/errors/crud_errors/resource_not_found_error_spec.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+require 'rspeckled'
+require 'erratum/errors/crud_errors/resource_not_found_error'
+require 'active_record/errors'
+
+class           Erratum
+module          Errors
+RSpec.describe  ResourceNotFoundError do
+  it 'has a status of 404' do
+    error = ResourceNotFoundError.new
+
+    expect(error.http_status).to eql 404
+  end
+
+  it 'has a code' do
+    error = ResourceNotFoundError.new
+
+    expect(error.code).to eql 'errors.resource_not_found_error'
+  end
+
+  it 'has a title' do
+    error = ResourceNotFoundError.new
+
+    expect(error.title).to eql 'Resource Not Found'
+  end
+
+  it 'includes the resource name and action in the detail' do
+    error = ResourceNotFoundError.new resource_name: 'dragon',
+                                      action:        'ride'
+
+    expect(error.detail).to eql 'The dragon you attempted ' \
+                                           'to ride for this request is either ' \
+                                           'not authorized for the authenticated user ' \
+                                           'or does not exist.'
+  end
+
+  it 'includes the resource name and action in the source' do
+    error = ResourceNotFoundError.new resource_name: 'dragon',
+                                      resource_id:   123
+
+    expect(error.source).to eql('dragon_id' => 123)
+  end
+
+  it 'can accept an array of IDs' do
+    error = ResourceNotFoundError.new resource_name: 'dragon',
+                                      resource_id:   %w{123 456}
+
+    expect(error.source).to eql('dragon_id' => %w{123 456})
+  end
+
+  it 'can convert an "ActiveRecord::RecordNotFound" with no IDs' do
+    record_not_found_error = ActiveRecord::RecordNotFound.new \
+                               "Couldn't find resource without an ID"
+    error                  = ResourceNotFoundError.convert(record_not_found_error)
+
+    expect(error.resource_name).to eql nil
+    expect(error.resource_id).to   eql []
+  end
+
+  it 'can convert an "ActiveRecord::RecordNotFound" with one ID' do
+    record_not_found_error = ActiveRecord::RecordNotFound.new \
+                               "Couldn't find resource with 'id'=123"
+    error                  = ResourceNotFoundError.convert(record_not_found_error)
+
+    expect(error.resource_name).to eql nil
+    expect(error.resource_id).to   eql %w{123}
+  end
+
+  it 'can convert an "ActiveRecord::RecordNotFound" with multiple IDs' do
+    record_not_found_error = ActiveRecord::RecordNotFound.new \
+                               "Couldn't find all resource with 'id': 123, 456, 789"
+    error                  = ResourceNotFoundError.convert(record_not_found_error)
+
+    expect(error.resource_name).to eql nil
+    expect(error.resource_id).to   eql %w{123 456 789}
+  end
+
+  it 'can convert an "ActiveRecord::RecordNotFound" while overriding attributes' do
+    record_not_found_error = ActiveRecord::RecordNotFound.new \
+                               "Couldn't find resource with 'id'=123"
+    error                  = ResourceNotFoundError.convert(record_not_found_error,
+                                                           resource_name: 'my_resource')
+
+    expect(error.resource_name).to eql 'my_resource'
+    expect(error.resource_id).to   eql %w{123}
+  end
+end
+end
+end